@mohasinac/appkit 4.23.0 → 4.24.0

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

@@ -15,6 +15,7 @@
 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 { getDefaultCurrency } from "../../../../core/baseline-resolver";
 export async function addBundleToCartAction(userId, bundleSlug) {
     if (!userId)
@@ -32,6 +33,12 @@ export async function addBundleToCartAction(userId, bundleSlug) {
     if (!bundle.bundlePrice || bundle.bundlePrice < 1) {
         throw new ValidationError("Bundle price is not configured");
     }
+    // Bundles bypass `addItemToCart`'s capability gate deliberately (a bundle's
+    // `listingType: "standard"` is a lie told to satisfy it — `bundleRule` is
+    // `cartEligible: false`). The LANE gate is not optional though, and this path
+    // silently skipped it: a buyer with an unpaid auction win could keep shopping
+    // by adding bundles.
+    await assertCanAddNewItems(userId);
     await cartRepository.addItem(userId, {
         productId: bundle.id,
         productTitle: bundle.name,

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

@@ -14,7 +14,7 @@ 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, unitPriceFor } from "../../../shared/checkout/order-math";
+import { computePreOrderDepositAmount, lineTotalFor, 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";
@@ -374,7 +374,7 @@ async function createOrderForGroup(group, orderType, ctx) {
     // Add-ons are this store's choice, not the cart's — see OrderGroupContext.
     const { whatsappNotifyAddon = false, giftWrapAddon = false, giftWrapMessage, shipmentProtectionAddon = false, } = storeAddons?.[firstItem.storeId] ?? {};
     const { platformFee = 0, gstOnFee: platformFeeGst = 0 } = platformFeeByStore.get(firstItem.storeId) ?? {};
-    const groupTotal = group.reduce((sum, { item, product }) => sum + unitPriceFor(item, product) * item.quantity, 0);
+    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 }) => {
         const lt = (product.listingType ?? "standard");
@@ -415,7 +415,7 @@ async function createOrderForGroup(group, orderType, ctx) {
         let taxableAmount = 0;
         let gstAmount = 0;
         for (const { item, product } of group) {
-            const lineTotal = unitPriceFor(item, product) * item.quantity;
+            const lineTotal = lineTotalFor(item, product);
             const rate = product.gstRate ?? 0;
             if (rate > 0) {
                 taxableAmount += lineTotal;
@@ -774,8 +774,16 @@ export async function createCheckoutOrderAction(input) {
                 }
             }
             if (availableItems.length > 0) {
-                const orderedProductIds = new Set(availableItems.map((a) => a.item.productId));
-                const remainingCartItems = cart.items.filter((ci) => !orderedProductIds.has(ci.productId));
+                // Clear by LINE identity, not by productId. `itemId` is what uniquely
+                // identifies a line; `productId` is not unique across lines and is not
+                // even a product id on a bundle/group line (it points at the bundle
+                // category, or at the group parent — which is itself purchasable). So
+                // matching on it deleted every OTHER line that happened to share the
+                // value: a loose "Set" parent sitting beside a group line built from
+                // that same group, or two lines of one product, both vanished when only
+                // one was ordered.
+                const orderedItemIds = new Set(availableItems.map((a) => a.item.itemId));
+                const remainingCartItems = cart.items.filter((ci) => !orderedItemIds.has(ci.itemId));
                 const cartRef = db.collection(CART_COLLECTION).doc(uid);
                 tx.set(cartRef, {
                     items: remainingCartItems,
@@ -818,13 +826,13 @@ export async function createCheckoutOrderAction(input) {
     const orderIds = [];
     let total = 0;
     const emailsToSend = [];
-    const cartSubtotal = orderGroups.reduce((s, { items: g }) => s + g.reduce((gs, { item, product }) => gs + unitPriceFor(item, product) * item.quantity, 0), 0);
+    const cartSubtotal = orderGroups.reduce((s, { items: g }) => s + g.reduce((gs, { item, product }) => gs + lineTotalFor(item, product), 0), 0);
     const couponUsageAccumulator = new Map();
     // One commission on one transaction, capped, then apportioned across the
     // orders this cart splits into — see allocateCheckoutFees.
     const platformFeeByStore = allocateCheckoutFees(orderGroups.map(({ items: g }) => [
         g[0].item.storeId,
-        g.reduce((sum, { item, product }) => sum + unitPriceFor(item, product) * item.quantity, 0),
+        g.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0),
     ]), computeCheckoutFees(cartSubtotal, commissions));
     const groupCtx = {
         paymentMethod,
@@ -922,7 +930,7 @@ export async function previewCheckoutPricing(input) {
     }
     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 cartSubtotal = orderGroups.reduce((s, { items: g }) => s + g.reduce((gs, { item, product }) => gs + lineTotalFor(item, product), 0), 0);
     // Same re-validation the real order placement runs, so the preview never
     // shows a discount the order won't actually honour.
     const { coupons: appliedCoupons } = await revalidateAppliedCoupons(cart.appliedCoupons ?? [], checks, uid);
@@ -932,7 +940,7 @@ export async function previewCheckoutPricing(input) {
     const stores = [];
     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 groupTotal = group.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0);
         const { shippingFee: groupShippingFee, storeState } = await resolveShippingCost(firstItem.storeId);
         // Add-ons are per store, read off the cart document — the same entry
         // createOrderForGroup will read when the order is actually placed.
@@ -948,13 +956,13 @@ export async function previewCheckoutPricing(input) {
         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 lineTotal = lineTotalFor(item, product);
                 const rate = product?.gstRate ?? 0;
                 if (rate > 0)
                     groupGstAmount += calculateGst(rate, intraState, lineTotal).gstAmount;
             }
         }
-        const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: unitPriceFor(item, product) * item.quantity }));
+        const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: lineTotalFor(item, product) }));
         const { couponDiscount: groupCouponDiscount } = computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, firstItem.storeId);
         stores.push({
             storeId: firstItem.storeId,
@@ -1131,12 +1139,12 @@ async function refundDroppedItemsForRazorpayCheckout(input) {
 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 firstItem = group[0].item;
-    const groupTotal = group.reduce((sum, { item, product }) => sum + unitPriceFor(item, product) * item.quantity, 0);
+    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
     // of re-implementing it inline — was two sequential findById calls per
     // seller group here, duplicated from resolveShippingCost.
     const { shippingFee, storeOwnerId } = await resolveShippingCost(firstItem.storeId);
-    const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: unitPriceFor(item, product) * item.quantity }));
+    const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: lineTotalFor(item, product) }));
     const { couponDiscount, appliedDiscounts } = computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, firstItem.storeId);
     // Mirrors createOrderForGroup — without this the online-payment path wrote
     // the discount onto the order but never incremented usage.currentUsage or
@@ -1469,7 +1477,7 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
         const expectedAddonFees = expectedShippingGroups.reduce((sum, g) => {
             const storeId = g.items[0].item.storeId;
             const addons = cart.storeAddons?.[storeId] ?? {};
-            const groupSubtotal = g.items.reduce((gs, { item, product }) => gs + unitPriceFor(item, product) * item.quantity, 0);
+            const groupSubtotal = g.items.reduce((gs, { item, product }) => gs + lineTotalFor(item, product), 0);
             return (sum +
                 computeWhatsAppNotifyFee(addons.whatsappNotifyAddon ?? false, commissionRates) +
                 computeGiftWrapFee(addons.giftWrapAddon ?? false, commissionRates) +
@@ -1501,12 +1509,12 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
     let total = 0;
     const emailsToSend = [];
     const cartSubtotal = orderGroups.reduce((s, { items: g }) => s +
-        g.reduce((gs, { item, product }) => gs + unitPriceFor(item, product) * item.quantity, 0), 0);
+        g.reduce((gs, { item, product }) => gs + lineTotalFor(item, product), 0), 0);
     const couponUsageAccumulator = new Map();
     // Same single capped commission + pro-rata split as the COD/UPI path.
     const platformFeeByStore = allocateCheckoutFees(orderGroups.map(({ items: g }) => [
         g[0].item.storeId,
-        g.reduce((sum, { item, product }) => sum + unitPriceFor(item, product) * item.quantity, 0),
+        g.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0),
     ]), computeCheckoutFees(cartSubtotal, siteSettings?.commissions ?? CHECKOUT_DEFAULT_COMMISSIONS));
     for (const { items: group, orderType } of orderGroups) {
         total += await createRazorpayGroupOrder(group, orderType, {

package/dist/_internal/shared/actions/action-registry.js

@@ -2412,6 +2412,47 @@ export const ACTIONS = {
             description: "Navigate back from the cart to the product catalogue.",
             kind: "ghost",
         },
+        "add-group-to-cart": {
+            iconKey: "cart",
+            id: "cart.add-group-to-cart",
+            label: "Add selected to cart",
+            ariaLabel: "Add the selected group items to the cart as one line",
+            description: "Add a buyer-assembled selection of group members to the cart as a SINGLE line, rather than one line per product.",
+            kind: "primary",
+        },
+        "add-bundle-to-cart": {
+            iconKey: "cart",
+            id: "cart.add-bundle-to-cart",
+            label: "Add to cart",
+            ariaLabel: "Add this bundle to the cart",
+            description: "Add a whole bundle to the cart. Bundles are all-or-nothing — the quantity is the number of COPIES of the bundle.",
+            kind: "primary",
+        },
+        "remove-group-member": {
+            iconKey: "delete",
+            id: "cart.remove-group-member",
+            label: "Remove",
+            ariaLabel: "Remove this item from the group line",
+            description: "Drop one member out of a grouped cart line. Ghost rather than danger on purpose: it reuses the cart's existing undo affordance, and Rule #7.4's mandatory-confirmation requirement applies to destructive actions.",
+            kind: "ghost",
+        },
+        // No iconKey — these two exist only to keep the stepper's accessible names
+        // in the registry rather than hard-coded in the primitive. The glyphs are
+        // the literal "+" / "−" characters.
+        "increase-quantity": {
+            id: "cart.increase-quantity",
+            label: "+",
+            ariaLabel: "Increase quantity",
+            description: "Default accessible name for QuantityStepper's increment control.",
+            kind: "ghost",
+        },
+        "decrease-quantity": {
+            id: "cart.decrease-quantity",
+            label: "−",
+            ariaLabel: "Decrease quantity",
+            description: "Default accessible name for QuantityStepper's decrement control.",
+            kind: "ghost",
+        },
     },
     CHECKOUT: {
         "place-order": {

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

@@ -7,9 +7,9 @@
 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".
+ * The single source of truth for "what do we charge for ONE COPY of this line".
  *
- * Three cases, in priority order:
+ * Four 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
@@ -17,15 +17,33 @@ import type { ProductDocument } from "../../../features/products/schemas/firesto
  *     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
+ *  2. **A multi-member line** — the sum of its members' own snapshotted prices,
+ *     weighted by each member's per-copy quantity. A `"group"` line pins
+ *     `item.quantity` to 1, so this is both the unit price and the line total;
+ *     see the invariant on `CartLineMember`.
+ *  3. **A legacy bundle line** (SB-UNI-5 2026-05-13) — written before
+ *     `groupMembers` existed. `item.price` is the bundle price locked at
+ *     add-time.
+ *  4. **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`.
+ *
+ * 🛑 Do not hand-roll this rule at a call site. It has been re-derived by hand
+ * six times, and the two copies that lived in the consumer repo
+ * (`src/app/api/payment/create-order/route.ts`) each reproduced the bundle
+ * branch while silently omitting case 1 — so Razorpay captured the LIST price
+ * for an accepted offer while the cart displayed the negotiated one. Call
+ * `lineTotalFor` and let this function stay the only definition.
  */
 export declare function unitPriceFor(item: CartItemDocument, product: ProductDocument | null): number;
+/**
+ * What this line contributes to a subtotal: one copy's price × the number of
+ * copies. THE call site should use this rather than multiplying `unitPriceFor`
+ * itself — that multiplication is where the six hand-rolled copies diverged.
+ */
+export declare function lineTotalFor(item: CartItemDocument, product: ProductDocument | null): number;
 /**
  * P-6 — pre-order groups charge each product's own `preOrderDepositPercent`
  * (falling back to the generic COD deposit % when a product doesn't have one

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

@@ -1,8 +1,8 @@
 import { roundRupees } from "../../../utils/number.formatter";
 /**
- * The single source of truth for "what do we charge for this line".
+ * The single source of truth for "what do we charge for ONE COPY of this line".
  *
- * Three cases, in priority order:
+ * Four 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
@@ -10,18 +10,33 @@ import { roundRupees } from "../../../utils/number.formatter";
  *     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
+ *  2. **A multi-member line** — the sum of its members' own snapshotted prices,
+ *     weighted by each member's per-copy quantity. A `"group"` line pins
+ *     `item.quantity` to 1, so this is both the unit price and the line total;
+ *     see the invariant on `CartLineMember`.
+ *  3. **A legacy bundle line** (SB-UNI-5 2026-05-13) — written before
+ *     `groupMembers` existed. `item.price` is the bundle price locked at
+ *     add-time.
+ *  4. **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`.
+ *
+ * 🛑 Do not hand-roll this rule at a call site. It has been re-derived by hand
+ * six times, and the two copies that lived in the consumer repo
+ * (`src/app/api/payment/create-order/route.ts`) each reproduced the bundle
+ * branch while silently omitting case 1 — so Razorpay captured the LIST price
+ * for an accepted offer while the cart displayed the negotiated one. Call
+ * `lineTotalFor` and let this function stay the only definition.
  */
 export function unitPriceFor(item, product) {
     if (typeof item.lockedPrice === "number" && item.lockedPrice > 0) {
         return item.lockedPrice;
     }
+    if (item.groupMembers?.length) {
+        return roundRupees(item.groupMembers.reduce((sum, m) => sum + m.unitPrice * m.quantity, 0));
+    }
     if (item.bundleCategorySlug && item.bundleProductIds?.length) {
         return item.price;
     }
@@ -31,6 +46,14 @@ export function unitPriceFor(item, product) {
     // crash whenever a cart line outlives its listing.
     return product?.price ?? item.price;
 }
+/**
+ * What this line contributes to a subtotal: one copy's price × the number of
+ * copies. THE call site should use this rather than multiplying `unitPriceFor`
+ * itself — that multiplication is where the six hand-rolled copies diverged.
+ */
+export function lineTotalFor(item, product) {
+    return unitPriceFor(item, product) * item.quantity;
+}
 /**
  * P-6 — pre-order groups charge each product's own `preOrderDepositPercent`
  * (falling back to the generic COD deposit % when a product doesn't have one
@@ -41,7 +64,7 @@ export function unitPriceFor(item, product) {
  */
 export function computePreOrderDepositAmount(group, defaultDepositPercent) {
     const raw = group.reduce((sum, { item, product }) => {
-        const lineTotal = unitPriceFor(item, product) * item.quantity;
+        const lineTotal = lineTotalFor(item, product);
         const pct = product.preOrderDepositPercent ?? defaultDepositPercent;
         return sum + lineTotal * (pct / 100); // audit-money-units-ok: percentage divisor, not paise
     }, 0);

package/dist/_internal/shared/checkout/rules/_limits.d.ts

@@ -1,6 +1,16 @@
 /** Checkout window / capacity constants — single source of truth. */
-/** Maximum distinct line items in one cart (hard cap, already enforced at addToCart). */
-export declare const CART_MAX_ITEMS = 50;
+/**
+ * Maximum distinct line items in one cart (hard cap, enforced at every
+ * add-to-cart entry point).
+ *
+ * Re-exported, not re-declared. This value existed as three independent `= 50`
+ * literals — here, in `constants/limits.ts`, and in
+ * `_internal/shared/features/cart/config.ts` — with nothing tying them
+ * together, so raising the cap in one place would have left two silently
+ * disagreeing. `constants/limits.ts` is a dependency-free leaf module, so this
+ * costs no import chain.
+ */
+export { CART_MAX_ITEMS } from "../../../../constants/limits";
 /**
  * Maximum number of order documents that can be created in one checkout
  * transaction.  If the cart produces more groups than this the checkout is

package/dist/_internal/shared/checkout/rules/_limits.js

@@ -1,6 +1,16 @@
 /** Checkout window / capacity constants — single source of truth. */
-/** Maximum distinct line items in one cart (hard cap, already enforced at addToCart). */
-export const CART_MAX_ITEMS = 50;
+/**
+ * Maximum distinct line items in one cart (hard cap, enforced at every
+ * add-to-cart entry point).
+ *
+ * Re-exported, not re-declared. This value existed as three independent `= 50`
+ * literals — here, in `constants/limits.ts`, and in
+ * `_internal/shared/features/cart/config.ts` — with nothing tying them
+ * together, so raising the cap in one place would have left two silently
+ * disagreeing. `constants/limits.ts` is a dependency-free leaf module, so this
+ * costs no import chain.
+ */
+export { CART_MAX_ITEMS } from "../../../../constants/limits";
 /**
  * Maximum number of order documents that can be created in one checkout
  * transaction.  If the cart produces more groups than this the checkout is

package/dist/_internal/shared/features/cart/config.d.ts

@@ -1,3 +1,4 @@
-export declare const CART_MAX_ITEMS = 50;
+/** Re-exported from the single declaration — see `constants/limits.ts`. */
+export { CART_MAX_ITEMS } from "../../../../constants/limits";
 export declare const CART_SESSION_TTL_DAYS = 30;
 export declare const CART_GUEST_STORAGE_KEY = "appkit:cart";

package/dist/_internal/shared/features/cart/config.js

@@ -1,3 +1,4 @@
-export const CART_MAX_ITEMS = 50;
+/** Re-exported from the single declaration — see `constants/limits.ts`. */
+export { CART_MAX_ITEMS } from "../../../../constants/limits";
 export const CART_SESSION_TTL_DAYS = 30;
 export const CART_GUEST_STORAGE_KEY = "appkit:cart";

package/dist/_internal/shared/features/cart/schema.d.ts

@@ -22,9 +22,9 @@ export declare const addToCartSchema: z.ZodObject<{
     productId: string;
     productTitle: string;
     productImage: string;
+    isOffer?: boolean | undefined;
     offerId?: string | undefined;
     lockedPrice?: number | undefined;
-    isOffer?: boolean | undefined;
 }, {
     storeId: string;
     price: number;
@@ -35,9 +35,9 @@ export declare const addToCartSchema: z.ZodObject<{
     storeName?: string | undefined;
     quantity?: number | undefined;
     productImage?: string | undefined;
+    isOffer?: boolean | undefined;
     offerId?: string | undefined;
     lockedPrice?: number | undefined;
-    isOffer?: boolean | undefined;
 }>;
 export declare const updateCartItemSchema: z.ZodObject<{
     productId: z.ZodString;
@@ -80,9 +80,9 @@ export declare const mergeGuestCartSchema: z.ZodObject<{
         productId: string;
         productTitle: string;
         productImage: string;
+        isOffer?: boolean | undefined;
         offerId?: string | undefined;
         lockedPrice?: number | undefined;
-        isOffer?: boolean | undefined;
     }, {
         storeId: string;
         price: number;
@@ -93,9 +93,9 @@ export declare const mergeGuestCartSchema: z.ZodObject<{
         storeName?: string | undefined;
         quantity?: number | undefined;
         productImage?: string | undefined;
+        isOffer?: boolean | undefined;
         offerId?: string | undefined;
         lockedPrice?: number | undefined;
-        isOffer?: boolean | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     guestItems: {
@@ -108,9 +108,9 @@ export declare const mergeGuestCartSchema: z.ZodObject<{
         productId: string;
         productTitle: string;
         productImage: string;
+        isOffer?: boolean | undefined;
         offerId?: string | undefined;
         lockedPrice?: number | undefined;
-        isOffer?: boolean | undefined;
     }[];
 }, {
     guestItems: {
@@ -123,9 +123,9 @@ export declare const mergeGuestCartSchema: z.ZodObject<{
         storeName?: string | undefined;
         quantity?: number | undefined;
         productImage?: string | undefined;
+        isOffer?: boolean | undefined;
         offerId?: string | undefined;
         lockedPrice?: number | undefined;
-        isOffer?: boolean | undefined;
     }[];
 }>;
 /**

package/dist/_internal/shared/features/notifications/action-url.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Where does a notification LAND?
+ *
+ * ## The problem this solves
+ *
+ * `actionUrl` was set by **5 of 40** `sendNotification()` call sites, so the
+ * other 35 arrived in the bell as text with nothing to click. Every writer
+ * that did set one hand-wrote the path, which is the same drift the ROUTES
+ * map exists to prevent.
+ *
+ * Worse, the destination is **role-dependent**: an offer notification sent to
+ * the buyer belongs at `/user/offers`, the same event sent to the seller at
+ * `/store/offers`, and an admin escalation at `/admin/offers`. A per-writer
+ * literal cannot express that, so writers that guessed a single path sent
+ * half their recipients somewhere they have no permission to be.
+ *
+ * ## Honest fallbacks, not invented pages
+ *
+ * `bid`, `offer` and `review` still have **no per-record page in any role** —
+ * W8 fixed those dead-end listings with a detail MODAL, not a route. So this
+ * resolver points them at the list the record lives in. That is a real,
+ * permitted, useful destination; fabricating `/user/bids/{id}` would produce
+ * a 404 and `audit-nav-page-wiring` would (correctly) fail on the ROUTES key.
+ *
+ * When those pages are built, change the entry here and all 40 call sites
+ * follow. That is the whole point of the indirection.
+ */
+import type { NotificationRelatedType } from "../../../../features/admin/schemas/firestore";
+/**
+ * Which portal the recipient reads this in.
+ *
+ * Deliberately NOT the `role` string off the session: a seller is also a
+ * buyer, and which portal a notification belongs to is a property of the
+ * EVENT, not of the person. The order-shipped notification goes to the buyer
+ * in `/user`, and the same shipment's payout notification goes to the same
+ * human in `/store`.
+ */
+export type NotificationAudience = "buyer" | "seller" | "admin";
+/**
+ * Resolve the page a notification should open.
+ *
+ * Returns `undefined` when there is genuinely nowhere to go — a `promotion`
+ * or a `welcome` has no record behind it — so the caller renders a plain,
+ * non-clickable row rather than a link to the dashboard the user is already
+ * looking at.
+ */
+export declare function resolveNotificationActionUrl(relatedType: NotificationRelatedType | undefined, relatedId: string | undefined, audience: NotificationAudience): string | undefined;

package/dist/_internal/shared/features/notifications/action-url.js

@@ -0,0 +1,111 @@
+/**
+ * Where does a notification LAND?
+ *
+ * ## The problem this solves
+ *
+ * `actionUrl` was set by **5 of 40** `sendNotification()` call sites, so the
+ * other 35 arrived in the bell as text with nothing to click. Every writer
+ * that did set one hand-wrote the path, which is the same drift the ROUTES
+ * map exists to prevent.
+ *
+ * Worse, the destination is **role-dependent**: an offer notification sent to
+ * the buyer belongs at `/user/offers`, the same event sent to the seller at
+ * `/store/offers`, and an admin escalation at `/admin/offers`. A per-writer
+ * literal cannot express that, so writers that guessed a single path sent
+ * half their recipients somewhere they have no permission to be.
+ *
+ * ## Honest fallbacks, not invented pages
+ *
+ * `bid`, `offer` and `review` still have **no per-record page in any role** —
+ * W8 fixed those dead-end listings with a detail MODAL, not a route. So this
+ * resolver points them at the list the record lives in. That is a real,
+ * permitted, useful destination; fabricating `/user/bids/{id}` would produce
+ * a 404 and `audit-nav-page-wiring` would (correctly) fail on the ROUTES key.
+ *
+ * When those pages are built, change the entry here and all 40 call sites
+ * follow. That is the whole point of the indirection.
+ */
+import { ROUTES } from "../../../../next/routing/route-map";
+/**
+ * Resolve the page a notification should open.
+ *
+ * Returns `undefined` when there is genuinely nowhere to go — a `promotion`
+ * or a `welcome` has no record behind it — so the caller renders a plain,
+ * non-clickable row rather than a link to the dashboard the user is already
+ * looking at.
+ */
+export function resolveNotificationActionUrl(relatedType, relatedId, audience) {
+    if (!relatedType || !relatedId)
+        return undefined;
+    switch (relatedType) {
+        case "order":
+            return audience === "admin"
+                ? String(ROUTES.ADMIN.ORDER_DETAIL(relatedId))
+                : audience === "seller"
+                    ? String(ROUTES.STORE.ORDER_DETAIL(relatedId))
+                    : String(ROUTES.USER.ORDER_DETAIL(relatedId));
+        case "product":
+            // The public listing page — the one destination that is the same for
+            // everyone, because a product page is public.
+            return String(ROUTES.PUBLIC.PRODUCT_DETAIL(relatedId));
+        // ── List-level, because no per-record page exists in ANY role ─────────
+        // W8 gave these listings a detail modal rather than a route. Linking the
+        // list is honest; a fabricated `/…/{id}` would 404.
+        case "bid":
+            return audience === "admin"
+                ? String(ROUTES.ADMIN.BIDS)
+                : audience === "seller"
+                    ? String(ROUTES.STORE.BIDS)
+                    : String(ROUTES.USER.BIDS);
+        case "offer":
+            return audience === "admin"
+                ? String(ROUTES.ADMIN.OFFERS)
+                : audience === "seller"
+                    ? String(ROUTES.STORE.OFFERS)
+                    : String(ROUTES.USER.OFFERS);
+        case "review":
+            // The public review page exists; the admin/seller sides are modals.
+            return String(ROUTES.PUBLIC.REVIEW_DETAIL(relatedId));
+        case "blog":
+            return String(ROUTES.BLOG.ARTICLE(relatedId));
+        case "user":
+            // Only an admin has a per-user page. A user notified ABOUT themselves
+            // (a ban, a role change) belongs on their own account hub, not on a
+            // page they cannot open.
+            return audience === "admin"
+                ? String(ROUTES.ADMIN.USER_DETAIL(relatedId))
+                : String(ROUTES.USER.PROFILE);
+        case "support_ticket":
+            return audience === "admin"
+                ? String(ROUTES.ADMIN.SUPPORT_TICKET_BY_ID(relatedId))
+                : String(ROUTES.USER.SUPPORT_TICKET(relatedId));
+        case "scammer":
+            // Admin-only surface — the public scam registry is browsed, not
+            // notified about.
+            return audience === "admin" ? String(ROUTES.ADMIN.SCAMMER_BY_ID(relatedId)) : undefined;
+        case "catalogueItem":
+            // The owner edits it; an admin reviews it from the approvals queue,
+            // which is a list because approval is a queue-shaped job.
+            return audience === "admin"
+                ? String(ROUTES.ADMIN.CATALOGUE_APPROVALS)
+                : String(ROUTES.USER.CATALOGUE_EDIT(relatedId));
+        case "payout":
+            return audience === "admin"
+                ? String(ROUTES.ADMIN.PAYOUT_DETAIL(relatedId))
+                : String(ROUTES.STORE.PAYOUT_DETAIL(relatedId));
+        case "store":
+            return audience === "admin"
+                ? String(ROUTES.ADMIN.STORE_DETAIL(relatedId))
+                : String(ROUTES.STORE.DASHBOARD);
+        default: {
+            /*
+             * Exhaustiveness. A new `relatedType` cannot compile without an answer
+             * to "where does this land", which is precisely the check that was
+             * missing when `catalogueItem` was smuggled in behind an `as never`.
+             */
+            const _exhaustive = relatedType;
+            void _exhaustive;
+            return undefined;
+        }
+    }
+}