@mohasinac/appkit 4.11.0 → 4.11.2

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

@@ -13,10 +13,12 @@ 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 } from "../../../shared/checkout/order-math";
+import { computePreOrderDepositAmount, 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";
+import { assertCheckoutLane, assertLockedLinesStillValid, finalizeLockedLines, } from "./locked-lines";
+import { activeLane, laneOf } from "../../../shared/checkout/lanes";
 import { computeCodHandlingFee, computeWhatsAppNotifyFee, computeGiftWrapFee, computeShipmentProtectionFee, } from "../../../shared/fees/calculator";
 import { getAdminDb, getAdminRealtimeDb, RTDB_PATHS, } from "../../../../providers/db-firebase";
 import { PRODUCT_COLLECTION, PRODUCT_CODES_SUBCOLLECTION } from "../../../../features/products/schemas/firestore";
@@ -272,14 +274,6 @@ function dispatchOrderConfirmationEmails(emailsToSend) {
         return;
     Promise.all(emailsToSend.map((e) => sendOrderConfirmationEmail(e))).catch((err) => serverLogger.error("Order confirmation email error:", err));
 }
-// SB-UNI-5 2026-05-13 — bundle cart-lines use item.price (locked bundle price
-// at add-time); regular lines use product.price (current Firestore). Prevents
-// stale cart-cached prices from being charged on COD/UPI orders.
-function unitPriceFor(item, product) {
-    return item.bundleCategorySlug && item.bundleProductIds?.length
-        ? item.price
-        : product.price;
-}
 /**
  * Places one order for one seller-group of the checkout cart — fee math
  * (COD deposit/handling, EMI schedule), coupon apportionment, order-doc
@@ -461,6 +455,11 @@ async function createOrderForGroup(group, orderType, ctx) {
         ...extraOrderFields,
     });
     orderIds.push(order.id);
+    // Close the loop on any locked line this order settled: flip the offer to
+    // "paid" (its terminal status had NO server-side writer before 2026-08-21,
+    // so an accepted offer could be re-added and re-ordered) and back-link the
+    // winning bid to the order it became.
+    await finalizeLockedLines(group.map(({ item }) => item), order.id);
     // SB-UNI-N — claim a digital code for digital-code orders (fire-and-forget,
     // order is already persisted so a claim failure is logged, not thrown).
     if ((group[0]?.product?.listingType ?? "standard") === "digital-code") {
@@ -541,6 +540,9 @@ export async function createCheckoutOrderAction(input) {
     if (cartItems.length === 0) {
         throw new ValidationError(ERROR_MESSAGES.CHECKOUT.CART_EMPTY);
     }
+    // Lane priority + locked-line revalidation, before any money math runs.
+    assertCheckoutLane(cart.items, cartItems);
+    await assertLockedLinesStillValid(cartItems, uid);
     // Tier PP — OTP gate for high-value checkouts. Evaluated against the
     // WHOLE checkout batch's total (not each resulting per-seller order),
     // otherwise a buyer could dodge it by splitting a big cart across
@@ -780,7 +782,12 @@ export async function previewCheckoutPricing(input) {
     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)));
+    const previewLane = activeLane(cart.items ?? []);
+    const cartItems = (cart.items ?? []).filter((item) => !excludedSet.has(item.productId) &&
+        (!selectedSet || selectedSet.has(item.itemId)) &&
+        // A preview never throws — it just shows the lane the buyer can actually
+        // check out, matching what the checkout page's active tab displays.
+        (!previewLane || laneOf(item) === previewLane));
     if (cartItems.length === 0)
         return EMPTY_PRICING_PREVIEW;
     // Best-effort product lookup — a preview never throws on a since-unpublished
@@ -795,7 +802,6 @@ export async function previewCheckoutPricing(input) {
         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);
@@ -971,12 +977,6 @@ async function refundDroppedItemsForRazorpayCheckout(input) {
  */
 async function createRazorpayGroupOrder(group, orderType, ctx) {
     const { appliedCoupons, cartSubtotal, platformFeePercent, gstPercent, whatsappNotifyFee, giftWrapFee, giftWrapMessage, shipmentProtectionAddon, siteSettings, uid, userName, userEmail, razorpay_order_id, razorpay_payment_id, razorpay_signature, shippingAddress, notes, outOfStockPolicy, unavailablePaid, orderIds, emailsToSend, } = ctx;
-    // SB-UNI-5 2026-05-13 — bundle cart-lines use item.price (locked bundle
-    // price); regular lines use product.price. The helper keeps the math
-    // local to this block.
-    const unitPriceFor = (item, product) => item.bundleCategorySlug && item.bundleProductIds?.length
-        ? item.price
-        : product.price;
     const firstItem = group[0].item;
     const groupTotal = group.reduce((sum, { item, product }) => sum + unitPriceFor(item, product) * item.quantity, 0);
     // Reuses the same store/seller lookup as the COD/UPI path above instead
@@ -1089,6 +1089,11 @@ async function createRazorpayGroupOrder(group, orderType, ctx) {
         ...extraOrderFields,
     });
     orderIds.push(order.id);
+    // Close the loop on any locked line this order settled: flip the offer to
+    // "paid" (its terminal status had NO server-side writer before 2026-08-21,
+    // so an accepted offer could be re-added and re-ordered) and back-link the
+    // winning bid to the order it became.
+    await finalizeLockedLines(group.map(({ item }) => item), order.id);
     // SB-UNI-N — claim a digital code for digital-code orders (fire-and-forget,
     // order is already persisted so a claim failure is logged, not thrown).
     if ((group[0]?.product?.listingType ?? "standard") === "digital-code") {
@@ -1150,6 +1155,11 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
     if (!cart.items || cart.items.length === 0) {
         throw new ValidationError(ERROR_MESSAGES.CHECKOUT.CART_EMPTY);
     }
+    // Same lane priority + locked-line revalidation the manual/COD path runs.
+    // The Razorpay path settles the whole cart (no selectedItemIds), so the
+    // "selected" set is the cart itself.
+    assertCheckoutLane(cart.items, cart.items);
+    await assertLockedLinesStillValid(cart.items, uid);
     const isDigitalCartRazorpay = cartIsDigitalOnly(cart.items);
     let shippingAddress;
     let resolvedAddressRzp = null;
@@ -1281,12 +1291,6 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
     const orderIds = [];
     let total = 0;
     const emailsToSend = [];
-    // SB-UNI-5 2026-05-13 — bundle cart-lines use item.price (locked bundle
-    // price); regular lines use product.price. The helper keeps the math
-    // local to this block.
-    const unitPriceFor = (item, product) => item.bundleCategorySlug && item.bundleProductIds?.length
-        ? item.price
-        : product.price;
     const cartSubtotal = orderGroups.reduce((s, { items: g }) => s +
         g.reduce((gs, { item, product }) => gs + unitPriceFor(item, product) * item.quantity, 0), 0);
     for (const { items: group, orderType } of orderGroups) {

package/dist/_internal/server/features/checkout/locked-lines.d.ts

@@ -0,0 +1,30 @@
+import type { CartItemDocument } from "../../../../features/cart/schemas/firestore";
+/**
+ * Refuse a checkout that isn't the cart's active lane.
+ *
+ * The client scopes its selection to one lane's tab, but a selection is just a
+ * list of item ids in a request body — nothing stopped a caller from checking
+ * out their ₹200 standard items while a ₹30,000 auction win they already
+ * committed to sat unpaid. Priority is enforced here, on the server, over the
+ * WHOLE cart, not over the caller-supplied subset.
+ */
+export declare function assertCheckoutLane(allCartItems: readonly CartItemDocument[], selectedItems: readonly CartItemDocument[]): void;
+/** Error code the client maps to a lane-aware message. */
+export declare const CHECKOUT_LANE_BLOCKED = "CHECKOUT_LANE_BLOCKED";
+/**
+ * Re-validate every locked line immediately before the order is written.
+ *
+ * `checkoutOffer()` already checks status/deadline/stock when the line is ADDED
+ * to the cart, but nothing re-checked at order time — so a buyer could add an
+ * accepted offer, wait out the 48h window, and still be charged the locked
+ * price. Throws on the first invalid line; the caller's transaction aborts.
+ */
+export declare function assertLockedLinesStillValid(items: readonly CartItemDocument[], buyerUid: string): Promise<void>;
+/**
+ * Close the loop after the order exists.
+ *
+ * Best-effort by design: the order is already persisted and paid-for, so a
+ * failure here must be logged rather than thrown — losing the back-link is a
+ * bookkeeping problem, refusing a completed order is a customer-facing one.
+ */
+export declare function finalizeLockedLines(items: readonly CartItemDocument[], orderId: string): Promise<void>;

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

@@ -0,0 +1,116 @@
+/*
+ * WHY: A "locked line" is a cart line whose price was fixed outside the listing —
+ *      an accepted offer or a won auction. Two things were missing before
+ *      2026-08-21: the offer/bid was never re-checked at ORDER time (only at
+ *      add-to-cart time, so a line could sit in the cart past its deadline and
+ *      still check out), and nothing ever closed the loop afterwards — the
+ *      offer stayed "accepted" forever and could be re-added and re-ordered,
+ *      and a won bid had no link to the order it became.
+ * WHAT: `assertLockedLinesStillValid` (pre-order-creation guard) and
+ *       `finalizeLockedLines` (post-order-creation close-out). Both are called
+ *       from every order-creation path so the manual/COD and Razorpay flows
+ *       cannot diverge.
+ *
+ * EXPORTS:
+ *   assertLockedLinesStillValid, finalizeLockedLines
+ *
+ * @tag domain:checkout,offers,auctions
+ * @tag layer:server-action
+ * @tag pattern:none
+ * @tag access:server-only
+ * @tag consumers:checkout/actions.ts
+ * @tag sideEffects:firestore-write
+ */
+import { offerRepository } from "../../../../features/seller/repository/offer.repository";
+import { bidRepository } from "../../../../repositories";
+import { OfferStatusValues } from "../../../../features/seller/schemas";
+import { ValidationError } from "../../../../errors";
+import { serverLogger } from "../../../../monitoring/server-logger";
+import { normalizeError } from "../../../../errors/normalize";
+import { activeLane, laneOf, laneBlockReason } from "../../../shared/checkout/lanes";
+/**
+ * Refuse a checkout that isn't the cart's active lane.
+ *
+ * The client scopes its selection to one lane's tab, but a selection is just a
+ * list of item ids in a request body — nothing stopped a caller from checking
+ * out their ₹200 standard items while a ₹30,000 auction win they already
+ * committed to sat unpaid. Priority is enforced here, on the server, over the
+ * WHOLE cart, not over the caller-supplied subset.
+ */
+export function assertCheckoutLane(allCartItems, selectedItems) {
+    const active = activeLane(allCartItems);
+    if (!active)
+        return;
+    const offLane = selectedItems.filter((item) => laneOf(item) !== active);
+    if (offLane.length === 0)
+        return;
+    throw new ValidationError(laneBlockReason(allCartItems, laneOf(offLane[0])) ??
+        "Please complete your outstanding items first.", { code: CHECKOUT_LANE_BLOCKED });
+}
+/** Error code the client maps to a lane-aware message. */
+export const CHECKOUT_LANE_BLOCKED = "CHECKOUT_LANE_BLOCKED";
+/**
+ * Re-validate every locked line immediately before the order is written.
+ *
+ * `checkoutOffer()` already checks status/deadline/stock when the line is ADDED
+ * to the cart, but nothing re-checked at order time — so a buyer could add an
+ * accepted offer, wait out the 48h window, and still be charged the locked
+ * price. Throws on the first invalid line; the caller's transaction aborts.
+ */
+export async function assertLockedLinesStillValid(items, buyerUid) {
+    const now = new Date();
+    for (const item of items) {
+        if (!item.offerId)
+            continue;
+        const offer = await offerRepository.findById(item.offerId);
+        if (!offer) {
+            throw new ValidationError("The offer for one of your items no longer exists. Remove it and try again.");
+        }
+        if (offer.buyerUid !== buyerUid) {
+            throw new ValidationError("This offer belongs to a different account.");
+        }
+        if (offer.status !== OfferStatusValues.ACCEPTED) {
+            throw new ValidationError(offer.status === OfferStatusValues.PAID
+                ? "This offer has already been used for an order."
+                : "This offer is no longer accepted. Remove it from your cart and make a new offer.");
+        }
+        if (offer.checkoutDeadline && now > offer.checkoutDeadline) {
+            throw new ValidationError("The checkout window for this accepted offer has expired. Please make a new offer.");
+        }
+    }
+}
+/**
+ * Close the loop after the order exists.
+ *
+ * Best-effort by design: the order is already persisted and paid-for, so a
+ * failure here must be logged rather than thrown — losing the back-link is a
+ * bookkeeping problem, refusing a completed order is a customer-facing one.
+ */
+export async function finalizeLockedLines(items, orderId) {
+    for (const item of items) {
+        if (item.offerId) {
+            try {
+                await offerRepository.markPaid(item.offerId, orderId);
+            }
+            catch (err) {
+                void normalizeError(err);
+                serverLogger.error("finalizeLockedLines: markPaid failed", {
+                    offerId: item.offerId,
+                    orderId,
+                });
+            }
+        }
+        if (item.bidId) {
+            try {
+                await bidRepository.attachOrder(item.bidId, orderId);
+            }
+            catch (err) {
+                void normalizeError(err);
+                serverLogger.error("finalizeLockedLines: attachOrder failed", {
+                    bidId: item.bidId,
+                    orderId,
+                });
+            }
+        }
+    }
+}

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

@@ -1,3 +1,5 @@
+import { toProductItem } from "../../../shared/features/products/to-product-item";
+export { toProductItem };
 import type { ProductDocument } from "../../../../features/products/schemas/firestore";
 import type { ListingType } from "../../../../features/products/types";
 import type { ProductItem } from "../../../../features/products/types";
@@ -26,8 +28,6 @@ export interface RelatedItemsResult {
     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

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

@@ -1,4 +1,9 @@
 import { cache } from "react";
+// Imported (not just re-exported) because this module calls it internally.
+// It lives in _internal/shared so `"use client"` components can import it
+// without dragging this file's firebase-admin chain into the client bundle.
+import { toProductItem } from "../../../shared/features/products/to-product-item";
+export { toProductItem };
 import { productRepository } from "../../../../repositories";
 import { reviewRepository } from "../../../../repositories";
 import { getAdminDb } from "../../../../providers/db-firebase";
@@ -94,29 +99,6 @@ export async function listSitemapProducts() {
 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

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

@@ -1,4 +1,5 @@
 export { getProductForDetail, getReviewsForProduct, listSitemapProducts, type SitemapProduct, computeRelatedItems, toProductItem, toReview, getReviewItemsForProduct, type RelatedItemsResult, } from "./data";
+export { listPublicProducts, parsePublicProductParams, PUBLIC_PRODUCT_MAX_PAGE_SIZE, type PublicProductListInput, type PublicProductListResult, type PublicProductListOptions, type PublicProductExecutor, type PublicProductQuery, type ExecutorResult, } from "./list-public";
 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,5 @@
 export { getProductForDetail, getReviewsForProduct, listSitemapProducts, computeRelatedItems, toProductItem, toReview, getReviewItemsForProduct, } from "./data";
+export { listPublicProducts, parsePublicProductParams, PUBLIC_PRODUCT_MAX_PAGE_SIZE, } from "./list-public";
 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/list-public.d.ts

@@ -0,0 +1,111 @@
+import type { JsonValue } from "../../../../schemas/types";
+/** Vercel Hobby Fluid Compute ceiling (CLAUDE.md Rule #6) — never fetch more at once. */
+export declare const PUBLIC_PRODUCT_MAX_PAGE_SIZE = 50;
+/**
+ * A product document as it comes back from either executor. Deliberately
+ * `JsonValue`-shaped rather than `ProductDocument`: the upstream listingProcessor
+ * Function returns already-serialised rows, and this module only ever reads a
+ * handful of scalar fields off them (stockQuantity, listingType, the sort key).
+ */
+type Row = Record<string, JsonValue>;
+export interface PublicProductListInput {
+    /**
+     * Listing types this page spans. Emitted as one pipe-joined OR-group, which
+     * the Firebase Sieve adapter upgrades to a `.where(…, "in", …)` query.
+     */
+    listingTypes?: readonly string[];
+    q?: string;
+    category?: string;
+    brand?: string;
+    /** Pipe-joined multi-select (`new|used`) — emitted as an OR-group, never as AND. */
+    condition?: string;
+    storeId?: string;
+    status?: string;
+    minPrice?: string;
+    maxPrice?: string;
+    minBid?: string;
+    maxBid?: string;
+    featured?: boolean;
+    isPromoted?: boolean;
+    freeShipping?: boolean;
+    isPartOfBundle?: boolean;
+    features?: readonly string[];
+    preOrderProductionStatus?: string;
+    prizeRevealStatus?: string;
+    /** Hide sold-out rows. Applied in memory — never pushed into Firestore. */
+    inStock?: boolean;
+    dateFrom?: string;
+    dateTo?: string;
+    /** Pre-validated raw Sieve string (callers must safelist fields themselves). */
+    rawFilters?: string | null;
+    page?: number;
+    pageSize?: number;
+    sorts?: string;
+    cursor?: string | null;
+}
+export interface PublicProductListResult {
+    items: Row[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+    hasMore: boolean;
+    cursor: string | null;
+    /** The Sieve string actually sent to Firestore — surfaced for debugging. */
+    filters: string;
+    sorts: string;
+}
+export interface PublicProductQuery {
+    filters: string;
+    sorts: string;
+    page: number;
+    pageSize: number;
+    cursor?: string | null;
+}
+export interface ExecutorResult {
+    items: unknown[];
+    total: number;
+    page: number;
+    totalPages: number;
+    hasMore: boolean;
+    cursor?: string | null;
+}
+/**
+ * How the query actually runs. Defaults to `productRepository.list`. The consumer
+ * route overrides this to prefer the colocated `listingProcessor` Function and fall
+ * back to the repository — the seam exists so that preference never has to be
+ * duplicated into appkit, which has no access to the consumer's env.
+ */
+export type PublicProductExecutor = (query: PublicProductQuery) => Promise<ExecutorResult>;
+export interface PublicProductListOptions {
+    executor?: PublicProductExecutor;
+    /**
+     * When supplied, rows whose `listingType` is not in this set are stripped after
+     * the fetch. Callers that can read siteSettings pass `enabledListingTypes(...)`.
+     */
+    enabledListingTypes?: ReadonlySet<string>;
+}
+/**
+ * Read the shared public-listing query params. SSR views hand in Next's
+ * `searchParams` record; the API route hands in `url.searchParams`. Both produce
+ * the same typed input, which is the whole point — the two paths cannot drift.
+ */
+export declare function parsePublicProductParams(params: URLSearchParams | Record<string, string | string[] | undefined>, defaults?: {
+    listingTypes?: readonly string[];
+    pageSize?: number;
+    sorts?: string;
+    /**
+     * Public browse pages hide sold-out rows until the user flips "Show sold".
+     * The API route leaves this off so non-browse callers (related items,
+     * homepage sections) keep their current behaviour.
+     */
+    hideSoldByDefault?: boolean;
+    /**
+     * Auctions / pre-orders hide already-ended rows until "Show ended" is on,
+     * by defaulting `dateFrom` to now. Must mirror the paired client listing
+     * component exactly or the SSR paint and the refetch disagree.
+     */
+    hideEndedByDefault?: boolean;
+}): PublicProductListInput;
+export declare function listPublicProducts(input: PublicProductListInput, opts?: PublicProductListOptions): Promise<PublicProductListResult | null>;
+export {};