@mohasinac/appkit 4.11.1 → 4.11.3

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

@@ -1,36 +1,105 @@
-import { bidRepository, orderRepository, productRepository, } from "../../../../repositories";
+import { bidRepository, cartRepository, productRepository, storeRepository, } from "../../../../repositories";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
 import { AUCTION_MESSAGES } from "../handlers/messages";
+import { ROUTES } from "../../../../next/routing/route-map";
+import { CART_LANE } from "../../../shared/checkout/lanes";
+/**
+ * How long the winner has to pay before the locked cart line lapses. Mirrors
+ * the accepted-offer window so both locked lanes behave the same.
+ */
+const AUCTION_CHECKOUT_WINDOW_MS = 48 * 60 * 60 * 1000;
+/** Deep link the winner straight into the auction checkout lane. */
+const AUCTION_CHECKOUT_URL = `${String(ROUTES.USER.CHECKOUT)}?lane=${CART_LANE.AUCTION}`;
 async function settleAuction(ctx, product) {
     const activeBids = await bidRepository.getActiveByProduct(product.id);
-    const batch = ctx.db.batch();
     if (activeBids.length === 0) {
+        const batch = ctx.db.batch();
         productRepository.updateStatusInBatch(batch, product.id, "archived");
         await batch.commit();
         ctx.logger.info(AUCTION_MESSAGES.NO_BIDS_LOG(product.id));
         return;
     }
     const [winnerEntry, ...loserEntries] = activeBids;
+    // Reserve price. It exists on the product, is editable by the seller, is
+    // shown in both dashboards, and the buyer guide promises bids below it don't
+    // win — but settlement awarded activeBids[0] unconditionally until
+    // 2026-08-21. A below-reserve auction ends with NO winner.
+    const reserve = product.reservePrice;
+    if (typeof reserve === "number" && reserve > 0 && winnerEntry.data.bidAmount < reserve) {
+        const batch = ctx.db.batch();
+        activeBids.forEach(({ ref }) => bidRepository.markLost(batch, ref));
+        productRepository.updateStatusInBatch(batch, product.id, "archived");
+        await batch.commit();
+        const reserveStore = product.storeId
+            ? await storeRepository.findById(product.storeId).catch(() => null)
+            : null;
+        if (reserveStore?.ownerId) {
+            await sendNotification({
+                userId: reserveStore.ownerId,
+                type: "auction_ended",
+                priority: "normal",
+                title: AUCTION_MESSAGES.RESERVE_NOT_MET_TITLE,
+                message: AUCTION_MESSAGES.RESERVE_NOT_MET_MESSAGE(product.title, winnerEntry.data.currency, winnerEntry.data.bidAmount, reserve),
+                relatedId: product.id,
+                relatedType: "product",
+            });
+        }
+        await Promise.allSettled(activeBids.slice(0, 50).map(({ data: bid }) => sendNotification({
+            userId: bid.userId,
+            type: "bid_lost",
+            priority: "normal",
+            title: AUCTION_MESSAGES.LOST_TITLE,
+            message: AUCTION_MESSAGES.RESERVE_NOT_MET_BIDDER_MESSAGE(product.title),
+            relatedId: product.id,
+            relatedType: "product",
+        })));
+        ctx.logger.info(`Auction ${product.id} ended below reserve — no winner`, {
+            highestBid: winnerEntry.data.bidAmount,
+            reservePrice: reserve,
+        });
+        return;
+    }
+    const batch = ctx.db.batch();
     bidRepository.markWon(batch, winnerEntry.ref);
     loserEntries.forEach(({ ref }) => bidRepository.markLost(batch, ref));
-    const orderRef = orderRepository.createFromAuction(batch, {
-        productId: product.id,
-        productTitle: product.title,
-        userId: winnerEntry.data.userId,
-        userName: winnerEntry.data.userName,
-        userEmail: winnerEntry.data.userEmail,
-        storeId: product.storeId,
-        amount: winnerEntry.data.bidAmount,
-        currency: winnerEntry.data.currency,
-        auctionProductId: product.id,
-    });
-    // Two-axis model: mark as sold without changing publish status
+    // Two-axis model: mark as sold without changing publish status.
     batch.update(ctx.db.collection("products").doc(product.id), {
         isSold: true,
         availableQuantity: 0,
     });
     await batch.commit();
-    // Fan-out notifications after batch commits.
+    // The win becomes a LOCKED CART LINE, not an order.
+    //
+    // Settlement used to call `orderRepository.createFromAuction`, which wrote a
+    // document that was not an OrderDocument at all — flat productId/userId/
+    // unitPrice, no items[], no buyerId, no paymentMethod, no shippingAddress,
+    // and a Firestore auto-ID instead of the `order-…` semantic id. No orders UI
+    // could render it and the manual-payment panel returned null for it, so an
+    // auction winner had literally no way to pay, anywhere in the product.
+    //
+    // Routing the win through the cart instead means the winner goes through the
+    // ONE checkout that already knows how to collect an address, charge a payment
+    // method, run the high-value OTP, split per store and produce a real order.
+    // Auctions stay `canAddToCart: false` for user-initiated adds — this writes
+    // through the repository directly, the same deliberate bypass `checkoutOffer`
+    // uses for accepted offers.
+    await cartRepository.addItem(winnerEntry.data.userId, {
+        productId: product.id,
+        productTitle: product.title,
+        productImage: product.mainImage ?? "",
+        price: winnerEntry.data.bidAmount,
+        currency: winnerEntry.data.currency,
+        quantity: 1,
+        storeId: product.storeId,
+        storeName: product.storeName ?? "",
+        listingType: "auction",
+        isAuctionWin: true,
+        auctionId: product.id,
+        bidId: winnerEntry.data.id,
+        lockedPrice: winnerEntry.data.bidAmount,
+        checkoutDeadline: new Date(ctx.now.getTime() + AUCTION_CHECKOUT_WINDOW_MS),
+        locked: true,
+    });
     await sendNotification({
         userId: winnerEntry.data.userId,
         type: "bid_won",
@@ -39,6 +108,10 @@ async function settleAuction(ctx, product) {
         message: AUCTION_MESSAGES.WON_MESSAGE(product.title, winnerEntry.data.currency, winnerEntry.data.bidAmount),
         relatedId: product.id,
         relatedType: "product",
+        // Previously the winner's notification linked back to the product page and
+        // carried no CTA — the one place it should never send them.
+        actionUrl: AUCTION_CHECKOUT_URL,
+        actionLabel: AUCTION_MESSAGES.WON_ACTION_LABEL,
     });
     await Promise.allSettled(loserEntries.slice(0, 50).map(({ data: bid }) => sendNotification({
         userId: bid.userId,
@@ -53,7 +126,7 @@ async function settleAuction(ctx, product) {
         winner: winnerEntry.data.userId,
         winningBid: winnerEntry.data.bidAmount,
         losersCount: loserEntries.length,
-        orderId: orderRef.id,
+        bidId: winnerEntry.data.id,
     });
 }
 export async function runAuctionSettlement(ctx) {

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

@@ -1,5 +1,5 @@
 import { normalizeError } from "../../../../errors/normalize";
-import { offerRepository } from "../../../../repositories";
+import { bidRepository, cartRepository, offerRepository } from "../../../../repositories";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
 export async function runOfferExpiry(ctx) {
     ctx.logger.info("Starting offer expiry sweep");
@@ -11,11 +11,15 @@ export async function runOfferExpiry(ctx) {
         ctx.logger.error("Failed to query expired offers", err);
         throw err;
     }
+    // NOTE: no early return here. This job sweeps three distinct things and the
+    // other two (accepted-past-deadline offers, unpaid auction wins) must still
+    // run when there happen to be no expired pending/countered offers.
     if (expiredOffers.length === 0) {
-        ctx.logger.info("No expired offers found");
-        return;
+        ctx.logger.info("No expired pending/countered offers found");
+    }
+    else {
+        ctx.logger.info(`Found ${expiredOffers.length} expired offer(s) to process`);
     }
-    ctx.logger.info(`Found ${expiredOffers.length} expired offer(s) to process`);
     const expiredIds = [];
     for (const offer of expiredOffers) {
         try {
@@ -46,8 +50,116 @@ export async function runOfferExpiry(ctx) {
             throw err;
         }
     }
+    await expireAcceptedPastCheckoutDeadline(ctx);
+    await lapseUnpaidAuctionWins(ctx);
     ctx.logger.info("Offer expiry complete", {
         processed: expiredIds.length,
         skipped: expiredOffers.length - expiredIds.length,
     });
 }
+/**
+ * The second half of the sweep, missing until 2026-08-21.
+ *
+ * `findExpiredActive` only looks at pending/countered offers past `expiresAt`.
+ * An offer the seller ACCEPTED but the buyer never paid for stayed "accepted"
+ * forever: its locked price remained claimable long after the 48h checkout
+ * window the buyer was shown, and the seller had no way to take the listing
+ * back. This lapses those offers and clears the matching locked cart lines, so
+ * the lane gate stops blocking a buyer on an offer that is no longer live.
+ */
+async function expireAcceptedPastCheckoutDeadline(ctx) {
+    let stale;
+    try {
+        stale = await offerRepository.findExpiredAccepted(ctx.now);
+    }
+    catch (err) {
+        void normalizeError(err);
+        ctx.logger.error("Failed to query accepted-but-unpaid offers", err);
+        return;
+    }
+    if (stale.length === 0)
+        return;
+    ctx.logger.info(`Found ${stale.length} accepted offer(s) past their checkout deadline`);
+    const ids = [];
+    for (const offer of stale) {
+        try {
+            // Drop the locked cart line first — leaving it behind would keep the
+            // buyer's offer lane non-empty and block their standard checkout on an
+            // offer they can no longer act on.
+            await cartRepository.removeItemsByOfferId(offer.buyerUid, offer.id);
+            ids.push(offer.id);
+            await sendNotification({
+                userId: offer.buyerUid,
+                type: "offer_expired",
+                priority: "normal",
+                title: "Accepted offer expired",
+                message: `The checkout window for your accepted offer on "${offer.productTitle}" has closed. You can make a new offer if it's still listed.`,
+                relatedId: offer.id,
+                relatedType: "offer",
+            });
+        }
+        catch (err) {
+            void normalizeError(err);
+            ctx.logger.warn(`Failed to lapse accepted offer ${offer.id}`, {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    if (ids.length > 0) {
+        try {
+            await offerRepository.expireMany(ids);
+        }
+        catch (err) {
+            void normalizeError(err);
+            ctx.logger.error("Failed to batch-expire accepted offers", err);
+        }
+    }
+}
+/**
+ * A won auction the buyer never paid for.
+ *
+ * Folded into this job rather than given its own scheduled function: both are
+ * "a locked cart line whose claim has lapsed", they want the same cadence, and
+ * Cloud Scheduler bills per registered job (see CLAUDE.md's Firebase budget
+ * table — 27 jobs is already an accepted, documented cost).
+ *
+ * The listing is NOT silently relisted. A forfeited win is a seller decision
+ * (relist, offer to the runner-up, or ban the non-payer), so this clears the
+ * line, marks the bid forfeited, and notifies both sides.
+ */
+async function lapseUnpaidAuctionWins(ctx) {
+    let stale;
+    try {
+        stale = await cartRepository.findExpiredLockedLines(ctx.now);
+    }
+    catch (err) {
+        void normalizeError(err);
+        ctx.logger.error("Failed to scan for expired locked cart lines", err);
+        return;
+    }
+    const auctionLines = stale.filter(({ item }) => item.bidId && item.isAuctionWin);
+    if (auctionLines.length === 0)
+        return;
+    ctx.logger.info(`Found ${auctionLines.length} unpaid auction win(s) past deadline`);
+    for (const { userId, item } of auctionLines) {
+        try {
+            await cartRepository.removeItemsByBidId(userId, item.bidId);
+            await bidRepository.markForfeited(item.bidId);
+            await sendNotification({
+                userId,
+                type: "auction_ended",
+                priority: "high",
+                title: "Auction win forfeited",
+                message: `You didn't complete payment for "${item.productTitle}" in time, so the win has been forfeited. Repeated non-payment can restrict your account.`,
+                relatedId: item.auctionId ?? item.productId,
+                relatedType: "product",
+            });
+        }
+        catch (err) {
+            void normalizeError(err);
+            ctx.logger.warn(`Failed to lapse auction win ${item.bidId}`, {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+}

package/dist/_internal/server/jobs/core/testerSandboxCleanup.d.ts

@@ -1,5 +1,5 @@
 import type { JobContext } from "../runtime/types";
-export declare const SANDBOX_COLLECTIONS: readonly ["categories", "stores", "products", "blogPosts", "events"];
+export declare const SANDBOX_COLLECTIONS: readonly ["categories", "stores", "products", "blogPosts", "events", "offers"];
 export interface TesterSandboxCleanupOptions {
     /** true = wipe every isTestData:true doc regardless of testDataExpiresAt (manual force-purge). */
     force?: boolean;

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

@@ -3,7 +3,10 @@ import { BID_FIELDS } from "../../../../constants/field-names";
 // Exported so testerSandboxRefresh.ts (the every-4h revert+prune job) reuses
 // the exact same collection scope instead of redefining it — one source of
 // truth for "what counts as sandbox scope."
-export const SANDBOX_COLLECTIONS = ["categories", "stores", "products", "blogPosts", "events"];
+// Keep in sync with testerSandboxRefresh.ts's SEED_BY_COLLECTION — the daily
+// TTL cleanup and the 4-hourly revert+prune must agree on what "sandbox" means
+// (CLAUDE.md § Tester QA standards #3).
+export const SANDBOX_COLLECTIONS = ["categories", "stores", "products", "blogPosts", "events", "offers"];
 const BID_CHUNK_SIZE = 30; // Firestore `in` query cap
 export async function runTesterSandboxCleanup(ctx, opts = {}) {
     const cutoff = opts.force ? null : new Date();

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

@@ -8,6 +8,7 @@ import { storesTesterSeedData } from "../../../../features/tester/seed-data/stor
 import { productsTesterSeedData } from "../../../../features/tester/seed-data/products-tester-seed-data";
 import { blogTesterSeedData } from "../../../../features/tester/seed-data/blog-tester-seed-data";
 import { eventsTesterSeedData } from "../../../../features/tester/seed-data/events-tester-seed-data";
+import { offersTesterSeedData } from "../../../../features/tester/seed-data/offers-tester-seed-data";
 import { bidsTesterSeedData } from "../../../../features/tester/seed-data/bids-tester-seed-data";
 const SEED_BY_COLLECTION = {
     categories: categoriesTesterSeedData,
@@ -15,6 +16,7 @@ const SEED_BY_COLLECTION = {
     products: productsTesterSeedData,
     blogPosts: blogTesterSeedData,
     events: eventsTesterSeedData,
+    offers: offersTesterSeedData,
 };
 const BID_CHUNK_SIZE = 30; // Firestore `in` query cap
 /**

package/dist/_internal/server/jobs/handlers/_helpers.js

@@ -2,6 +2,7 @@
  * Shared helpers for job handlers.
  */
 import { getAdminRealtimeDb } from "../../../../providers/db-firebase";
+import { PRODUCT_FIELDS } from "../../../../constants/field-names";
 import { BATCH_LIMIT } from "./messages";
 /** Batch-delete document refs, respecting Firestore's 500-write batch limit. */
 export async function batchDelete(ctx, refs) {
@@ -23,7 +24,9 @@ export { getAdminRealtimeDb };
  * only the ones past testDataExpiresAt (the scheduled 7-day sweep).
  */
 export async function getTestDataRefs(db, collection, cutoff) {
-    let q = db.collection(collection).where("isTestData", "==", true);
+    let q = db
+        .collection(collection)
+        .where(PRODUCT_FIELDS.IS_TEST_DATA, "==", true);
     if (cutoff)
         q = q.where("testDataExpiresAt", "<=", cutoff);
     const snap = await q.limit(200).get();

package/dist/_internal/server/jobs/handlers/messages.d.ts

@@ -10,6 +10,11 @@ export declare const AUCTION_MESSAGES: {
     LOST_TITLE: string;
     LOST_MESSAGE: (productTitle: string) => string;
     NO_BIDS_LOG: (productId: string) => string;
+    /** CTA on the winner's notification — links into the auction checkout lane. */
+    WON_ACTION_LABEL: string;
+    RESERVE_NOT_MET_TITLE: string;
+    RESERVE_NOT_MET_MESSAGE: (productTitle: string, currency: string, highestBid: number, reservePrice: number) => string;
+    RESERVE_NOT_MET_BIDDER_MESSAGE: (productTitle: string) => string;
 };
 export declare const BID_MESSAGES: {
     OUTBID_TITLE: string;

package/dist/_internal/server/jobs/handlers/messages.js

@@ -10,6 +10,11 @@ export const AUCTION_MESSAGES = {
     LOST_TITLE: "Auction ended",
     LOST_MESSAGE: (productTitle) => `The auction for "${productTitle}" has ended. You were outbid.`,
     NO_BIDS_LOG: (productId) => `Auction ${productId} ended with no bids`,
+    /** CTA on the winner's notification — links into the auction checkout lane. */
+    WON_ACTION_LABEL: "Pay now",
+    RESERVE_NOT_MET_TITLE: "Auction ended below reserve",
+    RESERVE_NOT_MET_MESSAGE: (productTitle, currency, highestBid, reservePrice) => `"${productTitle}" ended at ${currency} ${highestBid}, below your reserve of ${currency} ${reservePrice}. No winner was declared and the listing was archived.`,
+    RESERVE_NOT_MET_BIDDER_MESSAGE: (productTitle) => `The auction for "${productTitle}" ended without meeting the seller's reserve price, so it did not sell.`,
 };
 export const BID_MESSAGES = {
     OUTBID_TITLE: "You've been outbid",

package/dist/_internal/shared/checkout/lanes.d.ts

@@ -0,0 +1,41 @@
+export declare const CART_LANE: {
+    readonly AUCTION: "auction";
+    readonly OFFER: "offer";
+    readonly STANDARD: "standard";
+};
+export type CartLane = (typeof CART_LANE)[keyof typeof CART_LANE];
+/**
+ * Highest obligation first. An auction win is a completed sale the buyer already
+ * committed to by bidding; an accepted offer is a price the seller has held for
+ * them on a clock; ordinary cart items carry no commitment at all.
+ */
+export declare const CART_LANE_PRIORITY: readonly CartLane[];
+export declare const CART_LANE_LABELS: Record<CartLane, string>;
+/** The two lanes whose price is fixed outside the listing. */
+export declare function isLockedLane(lane: CartLane): boolean;
+/** Minimal shape this module needs — works on cart documents and client rows alike. */
+export interface LaneAssignable {
+    isAuctionWin?: boolean;
+    isOffer?: boolean;
+    offerId?: string;
+    bidId?: string;
+}
+export declare function laneOf(item: LaneAssignable): CartLane;
+export declare function laneItems<T extends LaneAssignable>(items: readonly T[], lane: CartLane): T[];
+export declare function laneCounts(items: readonly LaneAssignable[]): Record<CartLane, number>;
+/**
+ * The one lane the buyer may check out right now, or null for an empty cart.
+ */
+export declare function activeLane(items: readonly LaneAssignable[]): CartLane | null;
+export declare function isLaneCheckoutable(items: readonly LaneAssignable[], lane: CartLane): boolean;
+/**
+ * Why `lane` can't be checked out right now — null when it can.
+ * Phrased for the buyer, naming the lane that's blocking and what to do.
+ */
+export declare function laneBlockReason(items: readonly LaneAssignable[], lane: CartLane): string | null;
+/**
+ * Whether a NEW item may be added to the cart at all. While a higher-obligation
+ * lane is pending, adding more shopping would let the buyer keep deferring the
+ * thing they already committed to.
+ */
+export declare function canAddNewItems(items: readonly LaneAssignable[]): boolean;

package/dist/_internal/shared/checkout/lanes.js

@@ -0,0 +1,106 @@
+/*
+ * WHY: A cart can hold three kinds of line with three different obligations — a
+ *      won auction (you owe it), an accepted offer (you negotiated it, at a
+ *      locked price, on a deadline), and ordinary shopping. Mixing them into one
+ *      total lets a buyer settle a ₹200 sticker while a ₹30,000 auction win they
+ *      already committed to sits unpaid, and makes every total ambiguous.
+ * WHAT: The lane model — a derived (never stored) partition of the cart, with a
+ *       strict priority order. Exactly one lane is checkout-able at a time: the
+ *       highest-priority non-empty one. Lower lanes stay visible but disabled,
+ *       and while a higher lane is pending nothing new may be added to the cart.
+ *
+ * Derived on purpose. A stored `lane` mirror field would drift the first time a
+ * write path forgot it (CLAUDE.md Root Cause #42), exactly as the manual-payment
+ * queue state is derived rather than stored.
+ *
+ * EXPORTS:
+ *   CartLane, CART_LANE_PRIORITY, CART_LANE_LABELS, laneOf, activeLane,
+ *   laneItems, laneCounts, isLaneCheckoutable, laneBlockReason, isLockedLane
+ *
+ * @tag domain:checkout,cart
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:CartRouteClient,CheckoutRouteClient,cart-actions,order-splitter,checkout/actions
+ * @tag sideEffects:none
+ */
+export const CART_LANE = {
+    AUCTION: "auction",
+    OFFER: "offer",
+    STANDARD: "standard",
+};
+/**
+ * Highest obligation first. An auction win is a completed sale the buyer already
+ * committed to by bidding; an accepted offer is a price the seller has held for
+ * them on a clock; ordinary cart items carry no commitment at all.
+ */
+export const CART_LANE_PRIORITY = [
+    CART_LANE.AUCTION,
+    CART_LANE.OFFER,
+    CART_LANE.STANDARD,
+];
+export const CART_LANE_LABELS = {
+    auction: "Auction wins",
+    offer: "Accepted offers",
+    standard: "Cart",
+};
+/** The two lanes whose price is fixed outside the listing. */
+export function isLockedLane(lane) {
+    return lane === CART_LANE.AUCTION || lane === CART_LANE.OFFER;
+}
+export function laneOf(item) {
+    if (item.isAuctionWin || item.bidId)
+        return CART_LANE.AUCTION;
+    if (item.isOffer || item.offerId)
+        return CART_LANE.OFFER;
+    return CART_LANE.STANDARD;
+}
+export function laneItems(items, lane) {
+    return items.filter((i) => laneOf(i) === lane);
+}
+export function laneCounts(items) {
+    const counts = { auction: 0, offer: 0, standard: 0 };
+    for (const item of items)
+        counts[laneOf(item)] += 1;
+    return counts;
+}
+/**
+ * The one lane the buyer may check out right now, or null for an empty cart.
+ */
+export function activeLane(items) {
+    const counts = laneCounts(items);
+    return CART_LANE_PRIORITY.find((lane) => counts[lane] > 0) ?? null;
+}
+export function isLaneCheckoutable(items, lane) {
+    return activeLane(items) === lane;
+}
+/**
+ * Why `lane` can't be checked out right now — null when it can.
+ * Phrased for the buyer, naming the lane that's blocking and what to do.
+ */
+export function laneBlockReason(items, lane) {
+    const active = activeLane(items);
+    if (active === lane)
+        return null;
+    const counts = laneCounts(items);
+    if (counts[lane] === 0)
+        return "There's nothing in this tab yet.";
+    if (active === CART_LANE.AUCTION) {
+        const n = counts.auction;
+        return `Settle your ${n} won auction${n === 1 ? "" : "s"} first — auction wins are already committed purchases.`;
+    }
+    if (active === CART_LANE.OFFER) {
+        const n = counts.offer;
+        return `Complete your ${n} accepted offer${n === 1 ? "" : "s"} first — the agreed price is only held for a limited time.`;
+    }
+    return "This tab can't be checked out right now.";
+}
+/**
+ * Whether a NEW item may be added to the cart at all. While a higher-obligation
+ * lane is pending, adding more shopping would let the buyer keep deferring the
+ * thing they already committed to.
+ */
+export function canAddNewItems(items) {
+    const active = activeLane(items);
+    return active === null || active === CART_LANE.STANDARD;
+}

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

@@ -6,6 +6,25 @@
  */
 import type { CartItemDocument } from "../../../features/cart/schemas/firestore";
 import type { ProductDocument } from "../../../features/products/schemas/firestore";
+/**
+ * The single source of truth for "what do we charge for this line".
+ *
+ * Three cases, in priority order:
+ *
+ *  1. **A locked price** — an accepted offer or a won auction. `lockedPrice` is
+ *     the negotiated/won amount and it OVERRIDES the current listing price, which
+ *     is the whole point of the negotiation. Until 2026-08-21 none of the five
+ *     copies of this function looked at `lockedPrice`, so an accepted offer was
+ *     billed at the seller's listed price while the cart UI displayed the agreed
+ *     one (`item.lockedPrice ?? item.price`) — the buyer saw ₹X and paid ₹Y.
+ *  2. **A bundle line** (SB-UNI-5 2026-05-13) — `item.price` is the bundle price
+ *     locked at add-time.
+ *  3. **Everything else** — the live Firestore price, so a stale cart-cached
+ *     price is never charged on a COD/UPI order.
+ *
+ * `product` may be null for a locked line whose listing has since been archived;
+ * the locked price is still owed, so that case must not dereference `product`.
+ */
 export declare function unitPriceFor(item: CartItemDocument, product: ProductDocument | null): number;
 /**
  * P-6 — pre-order groups charge each product's own `preOrderDepositPercent`

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

@@ -1,11 +1,35 @@
 import { roundRupees } from "../../../utils/number.formatter";
-// 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.
+/**
+ * The single source of truth for "what do we charge for this line".
+ *
+ * Three cases, in priority order:
+ *
+ *  1. **A locked price** — an accepted offer or a won auction. `lockedPrice` is
+ *     the negotiated/won amount and it OVERRIDES the current listing price, which
+ *     is the whole point of the negotiation. Until 2026-08-21 none of the five
+ *     copies of this function looked at `lockedPrice`, so an accepted offer was
+ *     billed at the seller's listed price while the cart UI displayed the agreed
+ *     one (`item.lockedPrice ?? item.price`) — the buyer saw ₹X and paid ₹Y.
+ *  2. **A bundle line** (SB-UNI-5 2026-05-13) — `item.price` is the bundle price
+ *     locked at add-time.
+ *  3. **Everything else** — the live Firestore price, so a stale cart-cached
+ *     price is never charged on a COD/UPI order.
+ *
+ * `product` may be null for a locked line whose listing has since been archived;
+ * the locked price is still owed, so that case must not dereference `product`.
+ */
 export function unitPriceFor(item, product) {
-    return item.bundleCategorySlug && item.bundleProductIds?.length
-        ? item.price
-        : product.price;
+    if (typeof item.lockedPrice === "number" && item.lockedPrice > 0) {
+        return item.lockedPrice;
+    }
+    if (item.bundleCategorySlug && item.bundleProductIds?.length) {
+        return item.price;
+    }
+    // Null-safe fallback: one of the four call sites this replaced (the cart
+    // summary/preview path) already guarded with `product?.price ?? item.price`,
+    // and collapsing onto a non-null assertion would have regressed it into a
+    // crash whenever a cart line outlives its listing.
+    return product?.price ?? item.price;
 }
 /**
  * P-6 — pre-order groups charge each product's own `preOrderDepositPercent`