@mohasinac/appkit 4.55.0-next.0 → 4.56.0

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.55.0-next.0",
-  "head": "549abc780f1aa0e87661e86d9c76718bfe3d6cb0",
-  "branch": "feat/mohasinac-site",
+  "version": "4.56.0",
+  "head": "a2d85e72b5cac1f1a55ae7386f661b293eccd704",
+  "branch": "main",
   "dirty": true,
-  "builtAt": "2026-10-20T12:44:38.195Z"
+  "builtAt": "2026-10-20T16:58:51.945Z"
 }

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

@@ -105,6 +105,18 @@ export interface CheckoutPricingPreviewInput {
      * is currently gated off.
      */
     lane?: CartLane;
+    /**
+     * The chosen EMI tenure, when `paymentMethod` is `"emi"`.
+     *
+     * 🛑 REQUIRED for an EMI preview to be truthful. The surcharge is
+     * `principalRemaining × surchargePercentPerMonth × tenureMonths`, so it
+     * cannot be derived from the cart alone — and without it this function
+     * returned a total that `createOrderForGroup` then exceeded by exactly that
+     * amount. Unlike the add-ons below, the tenure is NOT on the cart document:
+     * it is picked on the payment step and belongs to the order, so it has to
+     * travel with the request.
+     */
+    emiTenureMonths?: number;
 }
 /** One store's slice of the preview — what that seller's order will cost. */
 export interface CheckoutPricingPreviewStore {
@@ -116,6 +128,14 @@ export interface CheckoutPricingPreviewStore {
     giftWrapFee: number;
     shipmentProtectionFee: number;
     saleProtectionFee: number;
+    /**
+     * EMI surcharge for THIS seller, when the buyer is previewing an EMI order.
+     *
+     * Per store because `computeEmiSchedule` takes a SELLER subtotal — the
+     * financed principal is per order, not per cart, so a cart-wide figure
+     * would not match any order written.
+     */
+    emiSurcharge: number;
     gstAmount: number;
     couponDiscount: number;
     total: number;
@@ -147,6 +167,8 @@ export interface CheckoutPricingPreview {
     giftWrapFee: number;
     shipmentProtectionFee: number;
     saleProtectionFee: number;
+    /** Total EMI surcharge across sellers. Zero unless previewing an EMI order. */
+    emiSurcharge: number;
     gstAmount: number;
     couponDiscount: number;
     /** Buyer-facing platform commission, capped, charged once for this checkout. */

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

@@ -15,6 +15,8 @@ import { serverLogger } from "../../../../monitoring/index.js";
 import { unitOfWork, adminNotificationsRepository, siteSettingsRepository, userRepository, storeRepository, couponsRepository, claimedCouponsRepository, addressesRepository, productRepository, } from "../../../../repositories/index.js";
 import { isIntraStateSupply } from "../../../shared/fees/calculator.js";
 import { computePreOrderDepositAmount, lineTotalFor, sumGroupGst, unitPriceFor, } from "../../../shared/checkout/order-math.js";
+import { COD_MAX_ORDER_VALUE_FALLBACK } from "../../../../features/admin/schemas/firestore.js";
+import { CHECKOUT_ERROR_CODES } from "../../../../errors/error-codes.js";
 import { failedCheckoutRepository } from "../../../../features/checkout/repository/failed-checkout.repository.js";
 import { sendOrderConfirmationEmail } from "../../../../features/contact/server.js";
 import { splitCartIntoOrderGroups } from "../../../../features/orders/index.js";
@@ -42,7 +44,7 @@ import { verifyPaymentSignature as verifyRazorpayPaymentSignature } from "../../
 import { resolveKeys } from "../../../../core/integration-keys.js";
 import { paiseToRupees } from "../../../../core/money.js";
 import { CHECKOUT_DEFAULT_COMMISSIONS, CHECKOUT_DEFAULT_EMI_SETTINGS } from "../../../shared/features/checkout/config.js";
-import { checkEmiEligibility, computeEmiSchedule } from "../../../shared/features/emi/schedule.js";
+import { checkEmiEligibility, computeBuyerEmiQuote, computeEmiSchedule } from "../../../shared/features/emi/schedule.js";
 import { formatShippingAddress } from "./data.js";
 import { enforceMaxPerUserForCart } from "./prize-bundle-gates.js";
 import { getListingRule, runSyncPreflight, assertPaymentMethodAllowed, } from "../../../shared/checkout/rules/index.js";
@@ -870,6 +872,39 @@ export async function createCheckoutOrderAction(input) {
             }
         }
     }
+    /*
+     * COD value cap — the SERVER half of the gate.
+     *
+     * 🛑 The checkout UI already disables the COD option above the cap and says
+     * why. That is an affordance, not enforcement: this action is reachable by
+     * POST with `paymentMethod: "cod"` regardless of what the page rendered, and
+     * the whole point of the cap is the cash exposure on a refusal at the door.
+     * A limit enforced only in the browser is not a limit (Root Cause #46 — a
+     * field the schema accepts but the handler never verifies).
+     *
+     * Measured against the WHOLE checkout batch for the same reason the OTP gate
+     * above is: per-seller orders are a split of one cart, so capping each one
+     * would let a buyer clear a ₹3,000 limit with a ₹9,000 cart across three
+     * sellers. Same `cartItems` reduction, deliberately not shared with the OTP
+     * block — that one skips COD entirely, so the two can never be one test.
+     *
+     * `>` not `>=`: the setting is a maximum, so a cart exactly at the cap is
+     * allowed. The client comparison is spelled the same way.
+     */
+    if (!adminBypass && paymentMethod === "cod") {
+        const codMax = siteSettings?.payment?.codMaxOrderValue;
+        const effectiveCodMax = typeof codMax === "number" ? codMax : COD_MAX_ORDER_VALUE_FALLBACK;
+        const cartTotalForCodCheck = cartItems.reduce((sum, item) => sum + item.price * item.quantity, 0);
+        if (cartTotalForCodCheck > effectiveCodMax) {
+            failedCheckoutRepository
+                .logCheckout(uid, "cod_over_limit", "Cart exceeds the COD value cap", {
+                addressId: addressId ?? "",
+                paymentMethod,
+            })
+                .catch(() => undefined);
+            throw new ApiError(400, CHECKOUT_ERROR_CODES.COD_LIMIT_EXCEEDED);
+        }
+    }
     const isDigitalCart = cartIsDigitalOnly(cartItems);
     let shippingAddress;
     let resolvedAddress = null;
@@ -1137,6 +1172,7 @@ const EMPTY_PRICING_PREVIEW = {
     giftWrapFee: 0,
     shipmentProtectionFee: 0,
     saleProtectionFee: 0,
+    emiSurcharge: 0,
     gstAmount: 0,
     couponDiscount: 0,
     platformFee: 0,
@@ -1154,7 +1190,7 @@ const EMPTY_PRICING_PREVIEW = {
  * stock, creates an order, or writes coupon usage.
  */
 export async function previewCheckoutPricing(input) {
-    const { userId: uid, addressId, paymentMethod, excludedProductIds = [], lane, } = input;
+    const { userId: uid, addressId, paymentMethod, excludedProductIds = [], lane, emiTenureMonths, } = input;
     const siteSettings = await siteSettingsRepository.getSingleton();
     const commissions = siteSettings?.commissions ?? CHECKOUT_DEFAULT_COMMISSIONS;
     const cart = await unitOfWork.carts.getOrCreate(uid);
@@ -1207,7 +1243,7 @@ export async function previewCheckoutPricing(input) {
     for (const { items: group } of orderGroups) {
         const firstItem = group[0].item;
         const groupTotal = group.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0);
-        const { shippingFee: groupShippingFee, storeState, storeProtections } = await resolveShippingCost(firstItem.storeId);
+        const { shippingFee: groupShippingFee, storeState, storeProtections, storeEmiEnabled } = 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.
         const addons = cart.storeAddons?.[firstItem.storeId] ?? {};
@@ -1215,6 +1251,36 @@ export async function previewCheckoutPricing(input) {
         // ever charged for literal "cod" (pay the courier), never upi_manual or
         // cash (both pre-paid via UPI/bank transfer before dispatch).
         const groupCodHandlingFee = paymentMethod === "cod" ? computeCodHandlingFee(groupTotal, commissions) : 0;
+        /*
+         * 🛑 The EMI surcharge is a TERM OF THE TOTAL, and it was missing here
+         * while `createOrderForGroup` added it — a shown-vs-charged drift of
+         * exactly the kind this function exists to prevent.
+         *
+         * Measured on the live settings (tokenPercent 10, surchargePercentPerMonth
+         * 1) against the ₹20,000 listing: token ₹2,000, financed ₹18,000, so the
+         * surcharge is ₹360 at the default 2-month tenure and ₹1,080 at 6. The
+         * Order Summary showed ₹20,011.80 either way, and the order recorded up to
+         * ₹1,080 more. Worse, the EMI panel beside it already displayed
+         * instalments computed WITH the surcharge, so the page disagreed with
+         * itself.
+         *
+         * `computeBuyerEmiQuote`, never `computeEmiSchedule`: the latter also
+         * returns the platform/seller split of the surcharge, which is our
+         * commercial arrangement with the seller and has no business reaching a
+         * browser (see § "Buyer-facing fees").
+         *
+         * Eligibility is deliberately NOT enforced here. A preview that threw
+         * would blank the Order Summary; `createOrderForGroup` still refuses an
+         * ineligible EMI order, which is where refusing belongs. An ineligible
+         * cart simply previews no surcharge, because the tenure never applies.
+         */
+        let groupEmiSurcharge = 0;
+        if (paymentMethod === "emi" && emiTenureMonths && siteSettings?.emi) {
+            const emiSettings = siteSettings.emi;
+            if (checkEmiEligibility(groupTotal, storeEmiEnabled, emiSettings).eligible) {
+                groupEmiSurcharge = computeBuyerEmiQuote(groupTotal, emiTenureMonths, emiSettings).surchargeAmount;
+            }
+        }
         const groupGiftWrapFee = computeGiftWrapFee(addons.giftWrapAddon ?? false, commissions);
         /*
          * C5e — the same three tiers `createOrderForGroup` enforces, so the figure
@@ -1267,6 +1333,7 @@ export async function previewCheckoutPricing(input) {
             subtotal: groupTotal,
             shippingFee: groupShippingFee,
             codHandlingFee: groupCodHandlingFee,
+            emiSurcharge: groupEmiSurcharge,
             giftWrapFee: groupGiftWrapFee,
             shipmentProtectionFee: groupShipmentProtectionFee,
             saleProtectionFee: groupSaleProtectionFee,
@@ -1284,6 +1351,7 @@ export async function previewCheckoutPricing(input) {
             total: Math.max(0, groupTotal - groupCouponDiscount) +
                 groupShippingFee +
                 groupCodHandlingFee +
+                groupEmiSurcharge +
                 groupGiftWrapFee +
                 groupShipmentProtectionFee +
                 groupSaleProtectionFee,
@@ -1295,6 +1363,7 @@ export async function previewCheckoutPricing(input) {
     const sum = (pick) => stores.reduce((acc, s) => acc + pick(s), 0);
     const shippingFee = sum((s) => s.shippingFee);
     const codHandlingFee = sum((s) => s.codHandlingFee);
+    const emiSurcharge = sum((s) => s.emiSurcharge);
     const giftWrapFeeTotal = sum((s) => s.giftWrapFee);
     const shipmentProtectionFeeTotal = sum((s) => s.shipmentProtectionFee);
     const saleProtectionFeeTotal = sum((s) => s.saleProtectionFee);
@@ -1303,19 +1372,45 @@ export async function previewCheckoutPricing(input) {
     // One capped commission for the whole checkout, on every payment method —
     // deliberately not per store, so it is not added to the per-store rows above.
     const { platformFee, gstOnFee } = computeCheckoutFees(cartSubtotal, commissions);
+    /*
+     * 🛑 `gstAmount` is NOT a term, and leaving it in was a shown-vs-charged
+     * drift waiting on a settings flag.
+     *
+     * The per-store `total` above already excludes it, and its own field comment
+     * says so in capitals ("Deliberately NOT added to `total` below"). The
+     * CART-level total here added it anyway, so the two disagreed with each
+     * other and the cart-level one disagreed with `createOrderForGroup`, whose
+     * `orderTotal` excludes product GST for the reason set out there: prices are
+     * tax-INCLUSIVE, so the tax is already inside `cartSubtotal` and adding it
+     * charges it twice.
+     *
+     * It has never fired, which is the only reason it survived: `gstAmount` is
+     * computed solely when `siteSettings.gst.enabled` is true, and that is
+     * deliberately false until a real GSTIN is registered (see the seed's note —
+     * `/api/admin/site` refuses to enable it without a valid check digit). So on
+     * the day someone enters a registration, every cart would have quietly
+     * quoted ~5% more than the order it previews. Measured on the live ₹20,000
+     * listing (gstRate 5, HSN 95030020): the preview would have read ₹952.38
+     * over the amount charged.
+     *
+     * `gstOnFee` IS a term, and the asymmetry is the same one `createOrderForGroup`
+     * documents: that is GST on OUR commission, billed on top of the fee, not
+     * tax on the goods.
+     */
     const total = Math.max(0, cartSubtotal - couponDiscount) +
         shippingFee +
         codHandlingFee +
+        emiSurcharge +
         giftWrapFeeTotal +
         shipmentProtectionFeeTotal +
         saleProtectionFeeTotal +
         platformFee +
-        gstOnFee +
-        gstAmount;
+        gstOnFee;
     return {
         subtotal: cartSubtotal,
         shippingFee,
         codHandlingFee,
+        emiSurcharge,
         giftWrapFee: giftWrapFeeTotal,
         shipmentProtectionFee: shipmentProtectionFeeTotal,
         saleProtectionFee: saleProtectionFeeTotal,

package/dist/_internal/server/features/shipping/reconcile.d.ts

@@ -0,0 +1,28 @@
+import { type ActualShipmentCost } from "../../../shared/shipping/quote";
+export interface ReconcileShippingResult {
+    /** `null` when there was nothing to reconcile — see the reasons below. */
+    outcome: "credited" | "seller-absorbed" | "exact" | null;
+    sellerAbsorbs: number;
+    buyerPoints: number;
+    /** Why nothing happened, when `outcome` is null. For logs and the UI. */
+    skipped?: "no-quote" | "already-reconciled" | "no-buyer";
+}
+/**
+ * 🛑 IDEMPOTENT, and the guard is `order.shippingReconciliation` being unset.
+ *
+ * Crediting points is an APPEND to a ledger. Appends do not deduplicate
+ * themselves, so a dispatch action that fired twice — a double-clicked button,
+ * a retried job, a webhook delivered again — would pay the buyer twice, and
+ * nothing downstream could distinguish that from two genuine savings. The
+ * reconciliation record is written in the same step as the credit precisely so
+ * it can be the key.
+ *
+ * It deliberately does NOT use a transaction spanning the order and the
+ * ledger: `pointsRepository.append` already runs its own transaction over the
+ * ledger and the balance mirror, and nesting would mean reading the order
+ * inside it for no added safety. The residual risk is a crash between the
+ * credit and the order write, which leaves a credited buyer and an order that
+ * looks unreconciled — recoverable, and strictly better than the alternative
+ * ordering, which would mark the order done and then fail to pay.
+ */
+export declare function reconcileOrderShipping(orderId: string, actual: ActualShipmentCost): Promise<ReconcileShippingResult>;

package/dist/_internal/server/features/shipping/reconcile.js

@@ -0,0 +1,93 @@
+/**
+ * Close the loop on one order's shipping: compare what the buyer was charged
+ * with what the seller actually spent, and credit the difference as points.
+ *
+ * Called from the seller's dispatch path, once the real postage is known.
+ */
+import { orderRepository } from "../../../../features/orders/repository/orders.repository.js";
+import { pointsRepository } from "../../../../features/points/repository/points.repository.js";
+import { reconcileShipping, } from "../../../shared/shipping/quote.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+/**
+ * 🛑 IDEMPOTENT, and the guard is `order.shippingReconciliation` being unset.
+ *
+ * Crediting points is an APPEND to a ledger. Appends do not deduplicate
+ * themselves, so a dispatch action that fired twice — a double-clicked button,
+ * a retried job, a webhook delivered again — would pay the buyer twice, and
+ * nothing downstream could distinguish that from two genuine savings. The
+ * reconciliation record is written in the same step as the credit precisely so
+ * it can be the key.
+ *
+ * It deliberately does NOT use a transaction spanning the order and the
+ * ledger: `pointsRepository.append` already runs its own transaction over the
+ * ledger and the balance mirror, and nesting would mean reading the order
+ * inside it for no added safety. The residual risk is a crash between the
+ * credit and the order write, which leaves a credited buyer and an order that
+ * looks unreconciled — recoverable, and strictly better than the alternative
+ * ordering, which would mark the order done and then fail to pay.
+ */
+export async function reconcileOrderShipping(orderId, actual) {
+    const order = await orderRepository.findById(orderId);
+    if (!order) {
+        return { outcome: null, sellerAbsorbs: 0, buyerPoints: 0, skipped: "no-quote" };
+    }
+    /*
+     * No quote means this order never went through the courier picker — a
+     * manually-shipped seller, or an order placed before the feature. There is
+     * no charged figure to measure against, so there is nothing to reconcile.
+     * Inventing one from the flat `shippingFee` would compare the buyer's spend
+     * against a number that was never a courier quote.
+     */
+    if (!order.selectedShippingQuote) {
+        return { outcome: null, sellerAbsorbs: 0, buyerPoints: 0, skipped: "no-quote" };
+    }
+    if (order.shippingReconciliation) {
+        return {
+            outcome: null,
+            sellerAbsorbs: order.shippingReconciliation.sellerAbsorbs,
+            buyerPoints: order.shippingReconciliation.buyerPoints,
+            skipped: "already-reconciled",
+        };
+    }
+    const result = reconcileShipping(order.selectedShippingQuote, actual);
+    const buyerUid = order.userId;
+    if (result.buyerPoints > 0) {
+        if (!buyerUid) {
+            /*
+             * A credit with nobody to credit. Recorded rather than thrown: the
+             * parcel has shipped and the seller's dispatch must not fail because we
+             * cannot find the buyer — but this is a real data fault and has to be
+             * loud enough to find.
+             */
+            serverLogger.error("shipping reconciliation has points but no buyer", {
+                orderId,
+                buyerPoints: result.buyerPoints,
+            });
+            return { outcome: null, sellerAbsorbs: 0, buyerPoints: 0, skipped: "no-buyer" };
+        }
+        await pointsRepository.append({
+            userId: buyerUid,
+            kind: "shipping_saving",
+            amount: result.buyerPoints,
+            orderId,
+            /*
+             * Names both couriers and both figures, because "53 points" on its own
+             * is unexplainable six weeks later — and this string is written once and
+             * never re-derived, so it stays true of the moment it describes even if
+             * the order is edited afterwards.
+             */
+            description: `Shipping saving on ${orderId}: charged ₹${order.selectedShippingQuote.chargedRate} ` +
+                `for ${order.selectedShippingQuote.courierName}, shipped ₹${actual.actualRate} ` +
+                `via ${actual.courierName}.`,
+        });
+    }
+    await orderRepository.update(orderId, {
+        actualShipmentCost: actual,
+        shippingReconciliation: { ...result, reconciledAt: new Date() },
+    });
+    return {
+        outcome: result.buyerPoints > 0 ? "credited" : result.sellerAbsorbs > 0 ? "seller-absorbed" : "exact",
+        sellerAbsorbs: result.sellerAbsorbs,
+        buyerPoints: result.buyerPoints,
+    };
+}

package/dist/_internal/shared/config/schema.d.ts

@@ -89,6 +89,12 @@ export interface AppkitBrandConfig {
     name: string;
     /** Short / abbreviated name, e.g. "LT" */
     shortName?: string;
+    /**
+     * Standalone lockup line under the homepage hero logo, e.g. "Let It Rip
+     * India". Not `name`: that one is a sentence ingredient ("Why Buyers Trust
+     * {name}") and this one stands alone, so they are spelled differently.
+     */
+    heroCaption?: string;
     /** One-line brand description used in meta tags and footers */
     description?: string;
     /** Tagline shown in footer / about sections */

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

@@ -4,7 +4,7 @@ export declare const CHECKOUT_DEFAULT_COMMISSIONS: {
     readonly minimumTransactionFee: 0;
     readonly platformFeeMax: 10;
     readonly codDepositPercent: 10;
-    readonly codHandlingFeeMin: 200;
+    readonly codHandlingFeeCap: 200;
     readonly codHandlingFeePercent: 10;
     readonly giftWrapFeeEnabled: true;
     readonly giftWrapFee: 49;

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

@@ -8,7 +8,7 @@ export const CHECKOUT_DEFAULT_COMMISSIONS = {
     minimumTransactionFee: 0,
     platformFeeMax: 10,
     codDepositPercent: 10,
-    codHandlingFeeMin: 200,
+    codHandlingFeeCap: 200,
     codHandlingFeePercent: 10,
     // Mirrors the SiteSettingsDocument defaults, which enable every add-on.
     // Consequence of the mirror: if the settings read fails, an add-on already

package/dist/_internal/shared/features/site-settings/fees.d.ts

@@ -35,7 +35,7 @@ export interface BuyerFacingFees {
     saleProtectionFeeEnabled?: boolean;
     saleProtectionFeePercent?: number;
     saleProtectionFeeMin?: number;
-    codHandlingFeeMin?: number;
+    codHandlingFeeCap?: number;
     codHandlingFeePercent?: number;
     codDepositPercent?: number;
 }

package/dist/_internal/shared/features/site-settings/fees.js

@@ -21,7 +21,7 @@ export function toBuyerFacingFees(commissions) {
         saleProtectionFeeEnabled: commissions.saleProtectionFeeEnabled,
         saleProtectionFeePercent: commissions.saleProtectionFeePercent,
         saleProtectionFeeMin: commissions.saleProtectionFeeMin,
-        codHandlingFeeMin: commissions.codHandlingFeeMin,
+        codHandlingFeeCap: commissions.codHandlingFeeCap,
         codHandlingFeePercent: commissions.codHandlingFeePercent,
         codDepositPercent: commissions.codDepositPercent,
     };

package/dist/_internal/shared/fees/calculator.d.ts

@@ -75,12 +75,44 @@ export interface PayoutDeduction {
 }
 export declare function computePayoutDeduction(grossAmount: number, commissions: FeeCommissionRates): PayoutDeduction;
 export interface CodHandlingFeeRates {
-    /** Optional so existing `siteSettings` documents saved before this field existed don't produce NaN — falls back to ₹200. */
-    codHandlingFeeMin?: number;
+    /**
+     * Rupee CEILING on the COD handling fee. Optional so a `siteSettings`
+     * document saved before this field existed does not produce NaN — falls
+     * back to ₹200.
+     */ codHandlingFeeCap?: number;
     /** Optional for the same reason — falls back to 10%. */
     codHandlingFeePercent?: number;
 }
-/** COD handling fee charged to the buyer: max(fixed floor, subtotal × percent). */
+/**
+ * COD handling fee charged to the buyer: **min(subtotal × percent, cap)**.
+ *
+ * 🛑 The ₹200 is a CEILING, and it used to be applied as a FLOOR
+ * (`Math.max(min, percentFee)`) by a field called `codHandlingFeeMin`. The
+ * percentage then ran away on anything expensive: a ₹20,000 listing was
+ * charged **₹2,000** of "handling", which is not what handling a parcel costs
+ * — it is a tenth of the order. Measured on the live settings document
+ * (`codHandlingFeeMin: 200`, `codHandlingFeePercent: 10`) in the cart, and the
+ * figure was real: the buyer was quoted ₹22,011.80 on a ₹20,000 item.
+ *
+ * 🛑 What the fee IS, which is what makes the cap the correct shape: it is a
+ * TOKEN covering our cost of having shipped a parcel for free when the buyer
+ * does not pay on delivery. That cost is a courier's return leg — it scales
+ * with the parcel, not with the price of what is inside it. A ₹20,000 top and
+ * a ₹2,000 one cost the same to send back, so a fee that is 10× larger on the
+ * first is not recovering a cost, it is a surcharge on being expensive.
+ *
+ * The percentage survives because it is right at the small end — ₹150 of
+ * handling on a ₹300 order would exceed half the order — so the rule is "10%,
+ * but never more than ₹200". Below ₹2,000 the percentage binds; above it the
+ * cap does.
+ *
+ * The field was RENAMED rather than reinterpreted. A `…Min` read as a maximum
+ * is Root Cause #51's shape — a label describing the reverse of what the code
+ * does — and the next person to read the settings document would have had no
+ * way to tell. A live document carrying the old key now falls through to
+ * `DEFAULT_COD_HANDLING_FEE_CAP`, which is the same ₹200, so the rename
+ * changes no number on its own.
+ */
 export declare function computeCodHandlingFee(subtotal: number, rates: CodHandlingFeeRates): number;
 export interface GiftWrapFeeRates {
     /** Admin master toggle — the addon isn't charged (even if the buyer selected it) unless this is true. */

package/dist/_internal/shared/fees/calculator.js

@@ -73,14 +73,44 @@ export function computePayoutDeduction(grossAmount, commissions) {
     const netAmount = Math.max(0, roundRupees(grossAmount - totalDeduction));
     return { platformFee, gatewayFee, gstOnFee, totalDeduction, netAmount };
 }
-const DEFAULT_COD_HANDLING_FEE_MIN = 200;
+/** Buyer-facing COD handling ceiling, in decimal rupees. */
+const DEFAULT_COD_HANDLING_FEE_CAP = 200;
 const DEFAULT_COD_HANDLING_FEE_PERCENT = 10;
-/** COD handling fee charged to the buyer: max(fixed floor, subtotal × percent). */
+/**
+ * COD handling fee charged to the buyer: **min(subtotal × percent, cap)**.
+ *
+ * 🛑 The ₹200 is a CEILING, and it used to be applied as a FLOOR
+ * (`Math.max(min, percentFee)`) by a field called `codHandlingFeeMin`. The
+ * percentage then ran away on anything expensive: a ₹20,000 listing was
+ * charged **₹2,000** of "handling", which is not what handling a parcel costs
+ * — it is a tenth of the order. Measured on the live settings document
+ * (`codHandlingFeeMin: 200`, `codHandlingFeePercent: 10`) in the cart, and the
+ * figure was real: the buyer was quoted ₹22,011.80 on a ₹20,000 item.
+ *
+ * 🛑 What the fee IS, which is what makes the cap the correct shape: it is a
+ * TOKEN covering our cost of having shipped a parcel for free when the buyer
+ * does not pay on delivery. That cost is a courier's return leg — it scales
+ * with the parcel, not with the price of what is inside it. A ₹20,000 top and
+ * a ₹2,000 one cost the same to send back, so a fee that is 10× larger on the
+ * first is not recovering a cost, it is a surcharge on being expensive.
+ *
+ * The percentage survives because it is right at the small end — ₹150 of
+ * handling on a ₹300 order would exceed half the order — so the rule is "10%,
+ * but never more than ₹200". Below ₹2,000 the percentage binds; above it the
+ * cap does.
+ *
+ * The field was RENAMED rather than reinterpreted. A `…Min` read as a maximum
+ * is Root Cause #51's shape — a label describing the reverse of what the code
+ * does — and the next person to read the settings document would have had no
+ * way to tell. A live document carrying the old key now falls through to
+ * `DEFAULT_COD_HANDLING_FEE_CAP`, which is the same ₹200, so the rename
+ * changes no number on its own.
+ */
 export function computeCodHandlingFee(subtotal, rates) {
-    const min = rates.codHandlingFeeMin ?? DEFAULT_COD_HANDLING_FEE_MIN;
+    const cap = rates.codHandlingFeeCap ?? DEFAULT_COD_HANDLING_FEE_CAP;
     const percent = rates.codHandlingFeePercent ?? DEFAULT_COD_HANDLING_FEE_PERCENT;
     const percentFee = roundRupees(subtotal * (percent / 100));
-    return Math.max(min, percentFee);
+    return Math.min(percentFee, cap);
 }
 const DEFAULT_GIFT_WRAP_FEE = 49;
 /** Flat gift-wrap addon fee — charged only when the buyer opted in AND the admin has the addon enabled. */

package/dist/_internal/shared/listing-types/route-gating.d.ts

@@ -0,0 +1,56 @@
+/**
+ * "Does this href lead somewhere the site has switched off?"
+ *
+ * ## Why this exists
+ *
+ * `listings.listingTypes` already hides a disabled type everywhere the type is
+ * named — the nav, the `/products` chips, the admin tabs, the homepage
+ * SECTIONS (`HOMEPAGE_SECTION_LISTING_TYPE` in `MarketplaceHomepageView`). But
+ * a lot of this site's merchandising is free-text content that names a
+ * destination by URL and never mentions a listing type at all: a carousel
+ * slide's overlay button, a card's CTA, a promo-grid tile.
+ *
+ * Measured 2026-10-20 with `auction: false` live: the homepage hero carousel
+ * still shipped a "Live auctions / Place a bid before the timer runs out"
+ * CARD linking to `/auctions`, and a whole `slide-beyblade-auction` slide
+ * whose overlay read "Win it at your price". Both are authored content, so no
+ * type-keyed gate could see them — the only thing that identifies them is
+ * where they point.
+ *
+ * ## The rule, and the one case that makes it non-obvious
+ *
+ * A href is disabled when EVERY listing type that claims its route is
+ * disabled. Not "any" — `art` and `stickers` share `/art`, so a site that
+ * sells art but not stickers must keep `/art` reachable. Treating one disabled
+ * claimant as enough would silently delete a working destination.
+ *
+ * ## What it deliberately does NOT match
+ *
+ * Editorial pages that merely have a type's name in the path — `/help/auctions`,
+ * `/how-auctions-work`, `/seller-guide/prize-draws`. None of them starts with
+ * `/auctions`, so prefix matching excludes them for free, and that is correct:
+ * an explainer about auctions is still honest reading when auctions are off.
+ * A substring test would have eaten all three.
+ *
+ * Store tabs (`/stores/{slug}/auctions`) are also out of scope — those are
+ * resolved by `resolveStoreTabs`, which owns its own visibility, and a second
+ * owner is how a mirror drifts (Root Cause #42).
+ */
+import type { ListingType } from "../../../features/products/types/index";
+interface ListingFlagSnapshot {
+    listings?: {
+        listingTypes?: Partial<Record<ListingType, boolean>>;
+    };
+}
+/**
+ * `true` when `href` points at a listing type's browse page (or any page
+ * beneath it) and every type that browses there is disabled.
+ *
+ * Fails OPEN on anything it cannot classify: an unknown path, an external URL
+ * or a missing settings document all return `false`. A settings read that
+ * errored must not strip working destinations out of the homepage — the same
+ * reasoning as the suggestions endpoint's TTL cache and `src/proxy.ts`'s
+ * disabled-routes gate.
+ */
+export declare function isDisabledListingHref(href: string | undefined | null, settings: ListingFlagSnapshot | null | undefined): boolean;
+export {};