@mohasinac/appkit 4.53.0 → 4.53.2

package/dist/_internal/server/features/stores/tabs.d.ts

@@ -0,0 +1,30 @@
+import { isListingTypeEnabled } from "../../../shared/listing-types/feature-flags";
+import { type ListingTabCountResult } from "../products/listing-tab-counts";
+type SiteSettingsSnapshot = Parameters<typeof isListingTypeEnabled>[1];
+export interface StoreTabLink {
+    value: string;
+    label: string;
+    href: string;
+}
+export interface ResolvedStoreTabs {
+    /** Listing-type tabs with something in them, in `STORE_PAGE_TABS` order. */
+    dropdownTabs: StoreTabLink[];
+    /** Coupons (if any), Reviews (if any), About — always non-empty. */
+    tabs: StoreTabLink[];
+    /**
+     * Both numbers, because they answer different questions: `available` is what
+     * each tab badges, `total` is what decides whether the tab exists at all.
+     * See `ListingTabCountResult`.
+     */
+    listingCounts: ListingTabCountResult;
+    couponsCount: number;
+    reviewsCount: number;
+}
+export declare function resolveStoreTabs(storeSlug: string, storeId: string | undefined, settings: SiteSettingsSnapshot): Promise<ResolvedStoreTabs>;
+/**
+ * Where the bare `/stores/[slug]` route should land: the first listing-type
+ * tab holding anything, else Coupons, else Reviews, else About. `about` is
+ * always present in `tabs`, so this never falls through to nothing.
+ */
+export declare function getDefaultStoreTabPath(storeSlug: string, storeId: string | undefined, settings: SiteSettingsSnapshot): Promise<string>;
+export {};

package/dist/_internal/server/features/stores/tabs.js

@@ -0,0 +1,124 @@
+/*
+ * 🛑 Deliberately NO `"use server"`. That directive marks every export as a
+ * client-callable RPC endpoint, and these are not — they are read helpers
+ * invoked from a Server Component (`StoreDetailLayoutView`) and a server
+ * page (`/stores/[slug]`). Declaring it anyway also obliges every export to
+ * return `ActionResult<T>` (`audit-server-action-envelope`), which would
+ * wrap a path string in an envelope nobody unwraps. The sibling helpers
+ * this file sits beside — `adapters.ts`, `denormalize.ts` and
+ * `listing-tab-counts.ts`, which it calls — carry no directive either.
+ *
+ * WHY: `StoreDetailLayoutView`'s nav bar and the bare `/stores/[slug]`
+ *      redirect both need "which tabs does this store actually have
+ *      something in, and in what order". Before this file the redirect
+ *      didn't ask the question at all — it always sent a visitor to
+ *      `/products`, even for a store with zero products (and nothing else),
+ *      landing on a tab that isn't even in the nav bar. Computing the answer
+ *      twice (once per caller) is exactly the duplicated-predicate shape
+ *      Root Cause #73 warns about, so it lives in one place.
+ * WHAT: `resolveStoreTabs` — every visible tab for a store, in priority
+ *       order (listing types in `STORE_PAGE_TABS` order, then Coupons, then
+ *       Reviews, then About last). `getDefaultStoreTabPath` picks the first
+ *       one — the correct landing page for a store with no products.
+ */
+import { sieveAnd, sieveFilter, SIEVE_OP } from "../../../../utils/sieve-builder.js";
+import { couponsRepository, reviewRepository } from "../../../../repositories/index.js";
+import { ROUTES } from "../../../../next/routing/route-map.js";
+import { STORE_PAGE_TABS } from "../../../../features/products/constants/listing-tabs.js";
+import { isListingTypeEnabled, isCategoryTypeEnabled } from "../../../shared/listing-types/feature-flags.js";
+import { pluginFor } from "../../../shared/listing-types/_registry.js";
+import { listingTabCounts, } from "../products/listing-tab-counts.js";
+function tabLabel(base, count) {
+    if (!count)
+        return base;
+    return `${base} (${count.toLocaleString()})`;
+}
+/**
+ * tabSlug -> route builder. Mirrors `ROUTES.PUBLIC.STORE_*` exactly.
+ *
+ * 🛑 `spares` was missing here until this file was added, which meant
+ * `visibleStoreTabs` could include a tab this map had no builder for the
+ * moment a store's spares count went above zero — `STORE_LISTING_HREF[tab.id]`
+ * would resolve to `undefined`, and calling it as a function would throw.
+ * `/stores/[storeSlug]/spares/page.tsx` is a real route; the href map just
+ * never named it.
+ */
+const STORE_LISTING_HREF = {
+    products: (slug) => String(ROUTES.PUBLIC.STORE_PRODUCTS(slug)),
+    auctions: (slug) => String(ROUTES.PUBLIC.STORE_AUCTIONS(slug)),
+    "pre-orders": (slug) => String(ROUTES.PUBLIC.STORE_PRE_ORDERS(slug)),
+    "prize-draws": (slug) => String(ROUTES.PUBLIC.STORE_PRIZE_DRAWS(slug)),
+    bundles: (slug) => String(ROUTES.PUBLIC.STORE_BUNDLES(slug)),
+    classifieds: (slug) => String(ROUTES.PUBLIC.STORE_CLASSIFIEDS(slug)),
+    "digital-codes": (slug) => String(ROUTES.PUBLIC.STORE_DIGITAL_CODES(slug)),
+    live: (slug) => String(ROUTES.PUBLIC.STORE_LIVE(slug)),
+    // Combined art + stickers, mirroring the public /art page. This used to
+    // point at STORE_PRODUCTS, which filters to `standard` — so the tab showed
+    // a real non-zero count and landed on a page with none of those items.
+    art: (slug) => String(ROUTES.PUBLIC.STORE_ART(slug)),
+    spares: (slug) => String(ROUTES.PUBLIC.STORE_SPARES(slug)),
+};
+export async function resolveStoreTabs(storeSlug, storeId, settings) {
+    const [listingCounts, couponsCount, reviewsCount] = storeId
+        ? await Promise.all([
+            listingTabCounts(STORE_PAGE_TABS, { storeId }),
+            // audit-public-test-data-ok: a COUNT of the store's own coupons, and
+            // `CouponDocument` carries no isTestData field — there is nothing to strip.
+            couponsRepository
+                .list({ filters: sieveAnd(sieveFilter("storeId", SIEVE_OP.EQ, storeId), sieveFilter("validity.isActive", SIEVE_OP.EQ, "true")), page: 1, pageSize: 1 })
+                .then((r) => r.total)
+                .catch(() => 0),
+            reviewRepository
+                .listAll({ filters: sieveAnd(sieveFilter("storeId", SIEVE_OP.EQ, storeId), sieveFilter("status", SIEVE_OP.EQ, "approved")), page: 1, pageSize: 1 })
+                .then((r) => r.total)
+                .catch(() => 0),
+        ])
+        : [{ available: {}, total: {} }, 0, 0];
+    const visibleStoreTabs = STORE_PAGE_TABS.filter((tab) => {
+        if (tab.id === "bundles") {
+            if (!isCategoryTypeEnabled("bundle", settings))
+                return false;
+        }
+        else if (tab.id === pluginFor("art").tabSlug) {
+            // Combined tab — visible if either underlying listing type is enabled.
+            if (!(isListingTypeEnabled("art", settings) || isListingTypeEnabled("stickers", settings)))
+                return false;
+        }
+        else if (tab.listingType) {
+            if (!isListingTypeEnabled(tab.listingType, settings))
+                return false;
+        }
+        // A store with zero items of a given listing type shouldn't offer a tab
+        // that leads to an empty page. `undefined` means the count query FAILED,
+        // not zero, so the tab stays visible rather than hiding real stock
+        // behind a swallowed error (Root Cause #59).
+        // TOTAL, not the badge: a tab whose rows have all ended still has an
+        // archive behind the Ended/All scopes, and hiding it would strand that.
+        const count = listingCounts.total[tab.id];
+        return count === undefined || count > 0;
+    });
+    const dropdownTabs = visibleStoreTabs.map((tab) => ({
+        value: tab.id,
+        label: tabLabel(tab.label, listingCounts.available[tab.id]),
+        href: STORE_LISTING_HREF[tab.id](storeSlug),
+    }));
+    const tabs = [
+        ...(couponsCount > 0
+            ? [{ value: "coupons", label: tabLabel("Coupons", couponsCount), href: String(ROUTES.PUBLIC.STORE_COUPONS(storeSlug)) }]
+            : []),
+        ...(reviewsCount > 0
+            ? [{ value: "reviews", label: tabLabel("Reviews", reviewsCount), href: String(ROUTES.PUBLIC.STORE_REVIEWS(storeSlug)) }]
+            : []),
+        { value: "about", label: "About", href: String(ROUTES.PUBLIC.STORE_ABOUT(storeSlug)) },
+    ];
+    return { dropdownTabs, tabs, listingCounts, couponsCount, reviewsCount };
+}
+/**
+ * Where the bare `/stores/[slug]` route should land: the first listing-type
+ * tab holding anything, else Coupons, else Reviews, else About. `about` is
+ * always present in `tabs`, so this never falls through to nothing.
+ */
+export async function getDefaultStoreTabPath(storeSlug, storeId, settings) {
+    const { dropdownTabs, tabs } = await resolveStoreTabs(storeSlug, storeId, settings);
+    return (dropdownTabs[0] ?? tabs[0]).href;
+}

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

@@ -1,12 +1,10 @@
 /** Default ListingCheckoutRule hook implementations. */
-import { STANDARD_MAX_QTY_PER_LINE } from "./_limits.js";
 export const DEFAULT_LISTING_RULE = {
     purchaseable: true,
     cartEligible: true,
     cartIneligibleHint: "This listing type cannot be added to the cart.",
     requiresShippingAddress: true,
     nonRefundable: false,
-    maxQuantityPerLine: STANDARD_MAX_QTY_PER_LINE,
     canMergeWithSameProduct: true,
     maxLinesPerOrder: Infinity,
     refundPolicy: { full: true, partial: true, partialGranularity: "item" },

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

@@ -28,5 +28,18 @@ export declare const PRIZE_DRAW_DURATION_DAYS_MIN = 1;
 export declare const PRIZE_DRAW_DURATION_DAYS_MAX = 15;
 /** Maximum qty per bundle purchase (bundles are always single-shot direct buys). */
 export declare const BUNDLE_MAX_QTY_PER_TX = 1;
-/** Standard / pre-order max qty per cart line (enforced at addToCart). */
+/**
+ * Max quantity on a single cart line.
+ *
+ * 🛑 It now IS the enforcement. It used to say "enforced at addToCart" while
+ * the actual limit was four hand-written `.max(99)` literals that never
+ * referenced it — so the constant was documentation nobody read and the rule
+ * was a magic number in four places. The cart schemas import it.
+ *
+ * Its other reader, `ListingCheckoutRule.maxQuantityPerLine`, was DELETED in
+ * the same change: that field was set by auction, offer and prize-draw and read
+ * by nothing at all, and it contradicted the feature it appeared to govern —
+ * prize-draw set it to 1 while `splitMultipleOrders` right beside it existed
+ * only to chunk a quantity of 7 into [3,3,1].
+ */
 export declare const STANDARD_MAX_QTY_PER_LINE = 99;

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

@@ -28,5 +28,18 @@ export const PRIZE_DRAW_DURATION_DAYS_MIN = 1;
 export const PRIZE_DRAW_DURATION_DAYS_MAX = 15;
 /** Maximum qty per bundle purchase (bundles are always single-shot direct buys). */
 export const BUNDLE_MAX_QTY_PER_TX = 1;
-/** Standard / pre-order max qty per cart line (enforced at addToCart). */
+/**
+ * Max quantity on a single cart line.
+ *
+ * 🛑 It now IS the enforcement. It used to say "enforced at addToCart" while
+ * the actual limit was four hand-written `.max(99)` literals that never
+ * referenced it — so the constant was documentation nobody read and the rule
+ * was a magic number in four places. The cart schemas import it.
+ *
+ * Its other reader, `ListingCheckoutRule.maxQuantityPerLine`, was DELETED in
+ * the same change: that field was set by auction, offer and prize-draw and read
+ * by nothing at all, and it contradicted the feature it appeared to govern —
+ * prize-draw set it to 1 while `splitMultipleOrders` right beside it existed
+ * only to chunk a quantity of 7 into [3,3,1].
+ */
 export const STANDARD_MAX_QTY_PER_LINE = 99;

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

@@ -20,6 +20,7 @@ import { digitalCodeRule } from "./digital-code.rule.js";
 import { liveRule } from "./live.rule.js";
 import { artRule } from "./art.rule.js";
 import { stickersRule } from "./stickers.rule.js";
+import { sparesRule } from "./spares.rule.js";
 export const CHECKOUT_RULES = {
     standard: standardRule,
     auction: auctionRule,
@@ -30,6 +31,7 @@ export const CHECKOUT_RULES = {
     live: liveRule,
     art: artRule,
     stickers: stickersRule,
+    spares: sparesRule,
 };
 export const CATEGORY_CHECKOUT_RULES = {
     bundle: bundleRule,

package/dist/_internal/shared/checkout/rules/auction.rule.js

@@ -4,7 +4,15 @@ export const auctionRule = {
     orderType: "auction",
     cartEligible: false, // bid-only; add-to-cart is blocked at the action layer
     cartIneligibleHint: "Place a bid on the auction page instead.",
-    maxQuantityPerLine: 1,
+    /*
+     * 🛑 cod + cash, NOT emi. An auction win is a committed sale of a unique lot:
+     * a buyer who never pays on delivery costs the seller the item and the
+     * auction both, and there is no second-highest bidder to fall back to once
+     * it has been marked sold. EMI is confirmed-at-order financing rather than a
+     * deferred payment, so it carries none of that risk and stays available.
+     */
+    blockedPaymentMethods: ["cod", "cash"],
+    blockedPaymentMessage: "An auction win cannot be paid for on delivery or in cash — the lot is one of a kind and is held for you from the moment the auction closes.",
     canMergeWithSameProduct: false,
     refundPolicy: { full: true, partial: false, partialGranularity: "none" },
     splitKey: (item) => `auction:${item.itemId}`,

package/dist/_internal/shared/checkout/rules/bundle.rule.js

@@ -3,4 +3,17 @@ export const bundleRule = {
     cartEligible: false, // direct-checkout-only; addBundleToCart has been removed
     orderType: "standard", // bundle orders resolve to standard orderType
     requiresShippingAddress: true,
+    /*
+     * 🛑 cod + cash, NOT emi. A bundle is priced BELOW the sum of its members —
+     * that discount is the whole product — so a no-show on delivery costs the
+     * seller several items at once, and the bundle has meanwhile been held out of
+     * every member's own availability. EMI is confirmed-at-order financing rather
+     * than a deferred payment, so it carries none of that and stays available.
+     *
+     * 🛑 Honoured by `assertPaymentMethodAllowed`, NOT by `runSyncPreflight` —
+     * which skips multi-member lines, and a bundle line is always one. A value
+     * here relying on preflight would be a silent no-op.
+     */
+    blockedPaymentMethods: ["cod", "cash"],
+    blockedPaymentMessage: "Bundles cannot be paid for on delivery or in cash — a bundle is priced below the sum of its parts and is reserved when you order.",
 };

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

@@ -1,5 +1,6 @@
 export type { ListingCheckoutRule, CategoryCheckoutRule, CartItemProductPair, OrderItemInput, RefundPolicy, } from "./types";
 export { CHECKOUT_RULES, CATEGORY_CHECKOUT_RULES, getListingRule, getCategoryRule, pickOrderType, getSplitKey, runSyncPreflight, } from "./_registry";
+export { assertPaymentMethodAllowed, blockedMethodsForCart, type BlockedMethod, } from "./payment-gate";
 export { CART_MAX_ITEMS, CHECKOUT_MAX_ORDERS_PER_TX, PRIZE_DRAW_MAX_REVEALS_PER_ORDER, PRIZE_DRAW_DURATION_DAYS_MIN, PRIZE_DRAW_DURATION_DAYS_MAX, BUNDLE_MAX_QTY_PER_TX, STANDARD_MAX_QTY_PER_LINE, } from "./_limits";
 export { standardRule } from "./standard.rule";
 export { auctionRule } from "./auction.rule";
@@ -12,3 +13,4 @@ export { digitalCodeRule } from "./digital-code.rule";
 export { liveRule } from "./live.rule";
 export { artRule } from "./art.rule";
 export { stickersRule } from "./stickers.rule";
+export { sparesRule } from "./spares.rule";

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

@@ -1,4 +1,12 @@
 export { CHECKOUT_RULES, CATEGORY_CHECKOUT_RULES, getListingRule, getCategoryRule, pickOrderType, getSplitKey, runSyncPreflight, } from "./_registry.js";
+/*
+ * The payment gate is a SEPARATE module from `_registry`, on purpose: it is the
+ * one rule check that cannot be expressed as a per-listing-type pass over
+ * single-member lines, which is all `runSyncPreflight` can see. Keeping them
+ * apart is what stops someone folding it back into preflight, where it would
+ * silently stop covering bundles and grouped lines.
+ */
+export { assertPaymentMethodAllowed, blockedMethodsForCart, } from "./payment-gate.js";
 export { CART_MAX_ITEMS, CHECKOUT_MAX_ORDERS_PER_TX, PRIZE_DRAW_MAX_REVEALS_PER_ORDER, PRIZE_DRAW_DURATION_DAYS_MIN, PRIZE_DRAW_DURATION_DAYS_MAX, BUNDLE_MAX_QTY_PER_TX, STANDARD_MAX_QTY_PER_LINE, } from "./_limits.js";
 // Individual rules — exported for tests and direct access.
 export { standardRule } from "./standard.rule.js";
@@ -12,3 +20,4 @@ export { digitalCodeRule } from "./digital-code.rule.js";
 export { liveRule } from "./live.rule.js";
 export { artRule } from "./art.rule.js";
 export { stickersRule } from "./stickers.rule.js";
+export { sparesRule } from "./spares.rule.js";

package/dist/_internal/shared/checkout/rules/offer.rule.js

@@ -2,7 +2,6 @@ import { DEFAULT_LISTING_RULE } from "./_defaults.js";
 export const offerRule = {
     ...DEFAULT_LISTING_RULE,
     orderType: "offer",
-    maxQuantityPerLine: 1,
     canMergeWithSameProduct: false,
     refundPolicy: { full: true, partial: false, partialGranularity: "none" },
     splitKey: (item) => `offer:${item.itemId}`,

package/dist/_internal/shared/checkout/rules/payment-gate.d.ts

@@ -0,0 +1,26 @@
+import type { CartItemDocument } from "../../../../features/cart/schemas/firestore";
+import type { ProductDocument } from "../../../../features/products/schemas/firestore";
+import { type CheckoutPaymentMethod } from "../../features/checkout/config";
+/** Why one method is unavailable, and which listing said so. */
+export interface BlockedMethod {
+    /** The listing's own wording when it has one, else a generated sentence. */
+    message: string;
+    /** For logs and for the generated wording. */
+    label: string;
+}
+/**
+ * Which methods this cart forbids.
+ *
+ * Returned rather than thrown so the same answer can also DISABLE a payment
+ * control — one source for the refusal and the affordance, instead of a
+ * client-side guess that drifts from the server.
+ */
+export declare function blockedMethodsForCart(items: readonly CartItemDocument[], productById: ReadonlyMap<string, ProductDocument>): Map<CheckoutPaymentMethod, BlockedMethod>;
+/**
+ * Throw when the chosen method is forbidden by anything in the cart.
+ *
+ * One error, not one per offending line: a buyer changes the payment method
+ * once, and listing every blocked item would be a wall of text about a single
+ * decision.
+ */
+export declare function assertPaymentMethodAllowed(items: readonly CartItemDocument[], productById: ReadonlyMap<string, ProductDocument>, paymentMethod: CheckoutPaymentMethod | undefined): void;

package/dist/_internal/shared/checkout/rules/payment-gate.js

@@ -0,0 +1,133 @@
+/*
+ * WHY: Some listings must not be bought with a pay-later method. An auction win
+ *      or a bundle is a committed sale — a buyer who never pays on delivery
+ *      costs the seller the lot, and for a unique auction lot there is no
+ *      second-highest bidder to fall back on once it is marked sold. The rule
+ *      registry has a field for this (`blockedPaymentMethods`) and nothing
+ *      reachable enforced it for every line.
+ * WHAT: One cart-wide payment check, run BEFORE the transaction.
+ *
+ * 🛑 `runSyncPreflight` STRUCTURALLY CANNOT DO THIS, and that is not a bug in
+ * preflight. It does `if (isMultiMemberLine(pair.item)) continue;` for a good
+ * reason: a bundle or grouped line's own `listingType` describes the WRAPPER,
+ * not its members, so a per-type rule applied there would be applied to the
+ * wrong thing. Both of its call sites repeat the skip independently, and the
+ * online path additionally reduces each line to `getCartItemMemberIds(item)[0]`
+ * — its FIRST member only. So a `blockedPaymentMethods` set on `bundleRule` and
+ * left to preflight would be a silent no-op: the field would be set, reviewed,
+ * and never read.
+ *
+ * This resolves every line to ALL its members, so a grouped line containing one
+ * blocked listing is caught.
+ *
+ * 🛑 IT RUNS OUTSIDE THE TRANSACTION. Preflight is invoked inside the
+ * transaction callback, so a payment-method rejection there spends a full
+ * transaction attempt to produce an answer that depends on nothing the
+ * transaction reads.
+ *
+ * EXPORTS: assertPaymentMethodAllowed, blockedMethodsForCart
+ *
+ * @tag domain:checkout
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:server/features/checkout
+ * @tag sideEffects:none
+ */
+import { ValidationError } from "../../../../errors/index.js";
+import { CHECKOUT_PAYMENT_METHODS, } from "../../features/checkout/config.js";
+import { getCartItemMemberIds } from "../line-members.js";
+import { getCategoryRule, getListingRule } from "./_registry.js";
+/**
+ * Which methods this cart forbids.
+ *
+ * Returned rather than thrown so the same answer can also DISABLE a payment
+ * control — one source for the refusal and the affordance, instead of a
+ * client-side guess that drifts from the server.
+ */
+export function blockedMethodsForCart(items, productById) {
+    const blocked = new Map();
+    const claim = (methods, label, message) => {
+        for (const m of methods ?? []) {
+            // First claimant wins, so the message names a real listing rather than
+            // whichever happened to be last in the cart.
+            if (blocked.has(m))
+                continue;
+            blocked.set(m, {
+                label,
+                message: message ??
+                    `"${label}" cannot be paid for with ${PAYMENT_METHOD_LABEL[m] ?? m}.`,
+            });
+        }
+    };
+    for (const item of items) {
+        /*
+         * A bundle's restriction lives on its CategoryCheckoutRule, not on any
+         * listing type — its members are ordinary products whose own types would
+         * otherwise answer for it. Checked first for that reason.
+         */
+        if (item.bundleCategorySlug) {
+            const rule = getCategoryRule("bundle");
+            claim(rule?.blockedPaymentMethods, item.groupTitle ?? item.productTitle ?? "this bundle", rule?.blockedPaymentMessage);
+        }
+        /*
+         * EVERY member, not the first. `getCartItemMemberIds` returns the line's
+         * own product for a plain line and all members for a bundle or group, so
+         * one blocked member blocks the line.
+         */
+        for (const productId of getCartItemMemberIds(item)) {
+            const product = productById.get(productId);
+            /*
+             * An unresolved member is NOT treated as unrestricted here. It is left to
+             * the stock and existence checks that already run on the same cart and
+             * fail loudly — inventing a payment refusal for a missing product would
+             * report the wrong problem.
+             */
+            if (!product)
+                continue;
+            const type = (product.listingType ?? "standard");
+            const rule = getListingRule(type);
+            claim(rule.blockedPaymentMethods, product.title ?? type, rule.blockedPaymentMessage);
+        }
+    }
+    return blocked;
+}
+/** Human wording for the generated message. */
+const PAYMENT_METHOD_LABEL = {
+    cod: "cash on delivery",
+    cash: "cash on pickup",
+    emi: "EMI",
+    online: "online payment",
+    upi_manual: "manual bank/UPI transfer",
+};
+/**
+ * Throw when the chosen method is forbidden by anything in the cart.
+ *
+ * One error, not one per offending line: a buyer changes the payment method
+ * once, and listing every blocked item would be a wall of text about a single
+ * decision.
+ */
+export function assertPaymentMethodAllowed(items, productById, paymentMethod) {
+    if (!paymentMethod)
+        return;
+    /*
+     * 🛑 `admin_bypass` is exempt, deliberately. It exists so an admin can reach
+     * an order state without a real payment, is gated by a site-settings flag
+     * plus an admin role, and logs every use. Blocking it would make the one tool
+     * for testing these flows unable to test them.
+     */
+    if (paymentMethod === "admin_bypass")
+        return;
+    const blocked = blockedMethodsForCart(items, productById);
+    const offender = blocked.get(paymentMethod);
+    if (!offender)
+        return;
+    /*
+     * The methods that remain, derived from the union rather than a second list —
+     * a seventh payment method must not quietly go unmentioned here.
+     */
+    const allowed = CHECKOUT_PAYMENT_METHODS.filter((m) => m !== "admin_bypass" && !blocked.has(m)).map((m) => PAYMENT_METHOD_LABEL[m] ?? m);
+    throw Object.assign(new ValidationError(allowed.length > 0
+        ? `${offender.message} Available instead: ${allowed.join(", ")}.`
+        : `${offender.message} Nothing in this cart's combination can be paid for — remove the item and buy it on its own.`), { code: "PAYMENT_METHOD_BLOCKED" });
+}

package/dist/_internal/shared/checkout/rules/prize-draw.rule.js

@@ -10,15 +10,26 @@ import { PRIZE_DRAW_MAX_REVEALS_PER_ORDER } from "./_limits.js";
  * "admin_bypass" stays usable for QA regardless.
  */
 const PRIZE_DRAW_BLOCKED_PAYMENT_METHODS = ["cod", "cash", "emi"];
+/**
+ * The refusal, kept VERBATIM when this check moved out of `preflightChecks`
+ * into `assertPaymentMethodAllowed`.
+ *
+ * 🛑 The gate can generate a correct sentence on its own, and a generated one
+ * would have been a regression here: this wording names the REASON (winner
+ * assignment waits on confirmed payment) rather than just the refusal, and the
+ * reason is the thing a buyer needs in order to pick a different method rather
+ * than abandon the entry.
+ */
+const PRIZE_DRAW_BLOCKED_PAYMENT_MESSAGE = "Prize-draw entries can only be paid by manual bank/UPI transfer or PhonePe — cash on delivery and EMI are not available for this listing type.";
 export const prizeDrawRule = {
     ...DEFAULT_LISTING_RULE,
     orderType: "prize-draw",
     nonRefundable: true,
-    maxQuantityPerLine: 1,
     canMergeWithSameProduct: false,
     maxLinesPerOrder: PRIZE_DRAW_MAX_REVEALS_PER_ORDER,
     refundPolicy: { full: false, partial: false, partialGranularity: "none" },
     blockedPaymentMethods: PRIZE_DRAW_BLOCKED_PAYMENT_METHODS,
+    blockedPaymentMessage: PRIZE_DRAW_BLOCKED_PAYMENT_MESSAGE,
     splitKey: (item) => `prize-draw:${item.itemId}`,
     /**
      * Slice a high-quantity prize-draw entry into chunks of
@@ -43,13 +54,23 @@ export const prizeDrawRule = {
         }
         return chunks;
     },
-    preflightChecks: (pairs, paymentMethod) => {
-        if (paymentMethod && PRIZE_DRAW_BLOCKED_PAYMENT_METHODS.includes(paymentMethod)) {
-            const hasPrizeDraw = pairs.some((p) => p.product.listingType === "prize-draw");
-            if (hasPrizeDraw) {
-                throw Object.assign(new ValidationError("Prize-draw entries can only be paid by manual bank/UPI transfer or PhonePe — cash on delivery and EMI are not available for this listing type."), { code: "PRIZE_DRAW_PAYMENT_METHOD_BLOCKED" });
-            }
-        }
+    preflightChecks: (pairs) => {
+        /*
+         * The payment-method check USED to live here and is now in
+         * `assertPaymentMethodAllowed`, which runs cart-wide before the
+         * transaction.
+         *
+         * 🛑 This is not a tidy-up. The copy here could only ever see
+         * single-member lines — `runSyncPreflight` skips a bundle or grouped line,
+         * and its online call site reduces each line to its FIRST member — so a
+         * prize-draw entry reachable through a grouped selection was never
+         * checked. Re-adding a copy here would be a second answer to one question
+         * (Root Cause #75), and the one that is easier to find is the one that
+         * cannot see every line.
+         *
+         * `blockedPaymentMethods` + `blockedPaymentMessage` on this rule are what
+         * the gate reads, so the wording is unchanged.
+         */
         for (const { item, product } of pairs) {
             if (product.listingType !== "prize-draw")
                 continue;

package/dist/_internal/shared/checkout/rules/spares.rule.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Spares listing rule — one component off a disassembled item, standard-like
+ * checkout.
+ *
+ * No bespoke behaviour: cart/order grouping, stock decrement and refund policy
+ * all follow the standard defaults, and `pluginFor()` carries everything that
+ * differs (badge, browse route, seller form fields).
+ *
+ * 🛑 `orderType: "standard"` is deliberate rather than lazy. A new `OrderType`
+ * member fans out into the order-status tabs, the order filters and the
+ * splitter's own keys — and buys nothing here, because a spare is fulfilled,
+ * refunded and reported exactly like any other physical item. A buyer looking
+ * at their orders wants "the attack ring I bought", not a separate tab for it.
+ */
+import type { ListingCheckoutRule } from "./types";
+export declare const sparesRule: ListingCheckoutRule;

package/dist/_internal/shared/checkout/rules/spares.rule.js

@@ -0,0 +1,5 @@
+import { DEFAULT_LISTING_RULE } from "./_defaults.js";
+export const sparesRule = {
+    ...DEFAULT_LISTING_RULE,
+    orderType: "standard",
+};

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

@@ -62,8 +62,6 @@ export interface ListingCheckoutRule {
      * Set true for prize-draw entries.
      */
     nonRefundable: boolean;
-    /** Hard qty cap per single cart line. Auction/offer/prize-draw-per-line = 1. */
-    maxQuantityPerLine: number;
     /**
      * When false the checkout pipeline issues one order per cart line (even when
      * multiple lines share the same product).  Auctions and offers set this to
@@ -83,8 +81,20 @@ export interface ListingCheckoutRule {
      * all methods allowed. Prize-draw blocks cod/cash/emi — winner assignment
      * depends on the order's payment actually being confirmed, which those
      * deferred-payment methods don't guarantee.
+     *
+     * 🛑 Enforced by `assertPaymentMethodAllowed`, NOT by `runSyncPreflight`. A
+     * rule may only trust preflight for a single-member line; a type that can
+     * appear inside a bundle or a grouped selection is skipped there entirely.
+     * The gate runs over every member of every line, once, before the
+     * transaction.
      */
     blockedPaymentMethods?: CheckoutPaymentMethod[];
+    /**
+     * The refusal, in this type's own words. Optional — the gate generates a
+     * correct sentence without it. Supply one when the REASON is worth saying,
+     * as prize-draw's does.
+     */
+    blockedPaymentMessage?: string;
     /**
      * Return the grouping key used by the order splitter. Items with the same
      * key land in the same OrderGroup and produce one order document.
@@ -150,4 +160,18 @@ export interface CategoryCheckoutRule {
     cartEligible: boolean;
     orderType: OrderType;
     requiresShippingAddress: boolean;
+    /**
+     * Payment methods this category cannot be paid with.
+     *
+     * 🛑 NOT enforced by `runSyncPreflight`. That function skips multi-member
+     * lines by design, and a bundle is always one — so a value here would be set,
+     * reviewed, and never read. `assertPaymentMethodAllowed` is what honours it,
+     * and it runs cart-wide before the transaction.
+     */
+    blockedPaymentMethods?: CheckoutPaymentMethod[];
+    /**
+     * The refusal, in this category's own words. Optional — the gate generates a
+     * correct sentence without it. Supply one when the REASON is worth saying.
+     */
+    blockedPaymentMessage?: string;
 }