@mohasinac/appkit 4.56.0 → 4.58.0

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.56.0",
-  "head": "a2d85e72b5cac1f1a55ae7386f661b293eccd704",
+  "version": "4.58.0",
+  "head": "978d9ef892ec5d3ef08a87c7f040877faf3c5daa",
   "branch": "main",
-  "dirty": true,
-  "builtAt": "2026-10-20T16:58:51.945Z"
+  "dirty": false,
+  "builtAt": "2026-10-20T20:29:00.050Z"
 }

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

@@ -0,0 +1,44 @@
+import { type BeyDocument, type BeyProductDocument } from "../../../../features/beys/schemas/firestore";
+/**
+ * One bey, by slug.
+ *
+ * 🛑 A DIRECT DOC READ — `id === slug`, so this needs no query, no index and
+ * no scan. That is the whole reason the id is the slug.
+ */
+export declare const getBeyBySlug: (slug: string) => Promise<BeyDocument | null>;
+/**
+ * The bey(s) paired with a category leaf — the inverse of `BeyDocument.categoryId`.
+ *
+ * 🛑 ONE INDEXED EQUALITY, no composite index, which is the same shape
+ * `getCompositionsForCategory` uses for the parts side of this exact job. A
+ * single-field `==` is served by Firestore's automatic index, so this adds no
+ * index to declare and no deploy to wait on.
+ *
+ * 🛑 NOT `.limit(1)`, and that is measured rather than cautious. 1,880 beys
+ * carry a `categoryId` across 1,858 distinct leaves — so **22 leaves pair with
+ * TWO beys**, which are the vendor pairs (a Takara-Tomy release and its Hasbro
+ * equivalent merged onto one taxonomy leaf). `limit(1)` would render one of
+ * them and silently drop the other on 22 pages, with nothing to indicate a
+ * second existed. The cap is small and the extra rows are the point.
+ *
+ * Fails OPEN to an empty list for the same reason as below: a category page
+ * missing its reference link is a worse page, a category page that throws is no
+ * page at all.
+ */
+export declare const getBeysForCategory: (categoryId: string) => Promise<BeyDocument[]>;
+/**
+ * The products that ship a bey.
+ *
+ * 🛑 A QUERY, unlike `getModelsUsingPart`'s `getAll`, and the difference is a
+ * real asymmetry in the data rather than an inconsistency: a part row carries
+ * `usedBy` so its models are ids already in hand, whereas the product→bey edge
+ * lives on the PRODUCT (`assortment[].beyId`). A bey has no stored list of the
+ * products containing it.
+ *
+ * So this is one `array-contains` over a denormalised id array, bounded at 12.
+ * 🛑 It needs `assortmentBeyIds` on the product — a flat array of the ids
+ * inside `assortment[]`, because Firestore cannot `array-contains` on a field
+ * nested inside objects in an array. Until the seed carries that field this
+ * returns [] and says so, rather than running a scan.
+ */
+export declare const getProductsContainingBey: (beyId: string) => Promise<BeyProductDocument[]>;

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

@@ -0,0 +1,107 @@
+/**
+ * Reads for the public bey surfaces.
+ *
+ * 🛑 Wrapped in `React.cache` because a page and its `generateMetadata` share
+ * the call — and the NARROWEST shared call is what gets cached, not whatever
+ * is convenient to export. `React.cache` memoises per argument list, so two
+ * call sites passing different arguments get two entries and dedupe nothing
+ * (the `getStoreBySlug(slug)` vs `getStoreBySlug(slug, viewer)` trap).
+ */
+import { cache } from "react";
+import { BEYS_COLLECTION, BEY_PRODUCTS_COLLECTION, } from "../../../../features/beys/schemas/firestore.js";
+import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { BEY_FIELDS } from "../../../../constants/field-names.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+/**
+ * One bey, by slug.
+ *
+ * 🛑 A DIRECT DOC READ — `id === slug`, so this needs no query, no index and
+ * no scan. That is the whole reason the id is the slug.
+ */
+export const getBeyBySlug = cache(async (slug) => {
+    try {
+        const snap = await getAdminDb().collection(BEYS_COLLECTION).doc(slug).get();
+        return snap.exists ? { id: snap.id, ...snap.data() } : null;
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        serverLogger.warn("getBeyBySlug failed", { slug, error: e.message });
+        return null;
+    }
+});
+/**
+ * The bey(s) paired with a category leaf — the inverse of `BeyDocument.categoryId`.
+ *
+ * 🛑 ONE INDEXED EQUALITY, no composite index, which is the same shape
+ * `getCompositionsForCategory` uses for the parts side of this exact job. A
+ * single-field `==` is served by Firestore's automatic index, so this adds no
+ * index to declare and no deploy to wait on.
+ *
+ * 🛑 NOT `.limit(1)`, and that is measured rather than cautious. 1,880 beys
+ * carry a `categoryId` across 1,858 distinct leaves — so **22 leaves pair with
+ * TWO beys**, which are the vendor pairs (a Takara-Tomy release and its Hasbro
+ * equivalent merged onto one taxonomy leaf). `limit(1)` would render one of
+ * them and silently drop the other on 22 pages, with nothing to indicate a
+ * second existed. The cap is small and the extra rows are the point.
+ *
+ * Fails OPEN to an empty list for the same reason as below: a category page
+ * missing its reference link is a worse page, a category page that throws is no
+ * page at all.
+ */
+export const getBeysForCategory = cache(async (categoryId) => {
+    try {
+        const snap = await getAdminDb()
+            .collection(BEYS_COLLECTION)
+            .where(BEY_FIELDS.CATEGORY_ID, "==", categoryId)
+            .limit(4)
+            .get();
+        return snap.docs.map((d) => ({ id: d.id, ...d.data() }));
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        serverLogger.warn("getBeysForCategory failed", { categoryId, error: e.message });
+        return [];
+    }
+});
+/**
+ * The products that ship a bey.
+ *
+ * 🛑 A QUERY, unlike `getModelsUsingPart`'s `getAll`, and the difference is a
+ * real asymmetry in the data rather than an inconsistency: a part row carries
+ * `usedBy` so its models are ids already in hand, whereas the product→bey edge
+ * lives on the PRODUCT (`assortment[].beyId`). A bey has no stored list of the
+ * products containing it.
+ *
+ * So this is one `array-contains` over a denormalised id array, bounded at 12.
+ * 🛑 It needs `assortmentBeyIds` on the product — a flat array of the ids
+ * inside `assortment[]`, because Firestore cannot `array-contains` on a field
+ * nested inside objects in an array. Until the seed carries that field this
+ * returns [] and says so, rather than running a scan.
+ */
+export const getProductsContainingBey = cache(async (beyId) => {
+    try {
+        const snap = await getAdminDb()
+            .collection(BEY_PRODUCTS_COLLECTION)
+            .where("assortmentBeyIds", "array-contains", beyId)
+            .limit(12)
+            .get();
+        return snap.docs.map((d) => ({ id: d.id, ...d.data() }));
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        /*
+         * Fails OPEN to an empty list. A missing composite index throws
+         * `FAILED_PRECONDITION`, and the right outcome is a bey page without its
+         * "found in" section rather than a broken page — the caller wraps this in
+         * `safeRead` as well, so the degradation is recorded rather than silent.
+         *
+         * 🛑 `normalizeError` is the FIRST statement on purpose. It was below
+         * this comment, which put it outside audit-catch-normalize's proximity
+         * window — so the audit correctly reported it as missing even though the
+         * call was right there. Comment after the call, never before it.
+         */
+        serverLogger.warn("getProductsContainingBey failed", { beyId, error: e.message });
+        return [];
+    }
+});

package/dist/_internal/server/features/beys/og.d.ts

@@ -0,0 +1,42 @@
+/**
+ * OG card for `/beys/{slug}`.
+ *
+ * ── 🛑 NO IMAGE FETCHES, FOR THE REASON THE PARTS CARDS DO NOT EITHER ─────
+ *
+ * Beys DO have photographs — 1,903 of 1,988 — so this is a deliberate refusal
+ * rather than a gap. The project was suspended for **Fast Origin Transfer at
+ * 5.25× its allowance** (52.52 GB against 10 GB), traced to render-time image
+ * proxying (Root Cause #104). 1,988 bey routes with one remote fetch each, on
+ * a crawler sweep, is precisely the amplification that was just removed. Type
+ * on a gradient costs one lambda and nothing else.
+ *
+ * ── 🛑 NO MONEY ON THE CANVAS ─────────────────────────────────────────────
+ *
+ * All eight money-bearing OG renderers were stripped, and the rule is stated
+ * in CLAUDE.md: an OG image is a public image URL with the amount burned into
+ * the pixels, so no sign-in gate reaches it and no paywall markup describes
+ * it. 1,309 beys carry a price in the research data and none of it appears
+ * here.
+ *
+ * `audit-guest-price-leak`'s R1 blocks a `₹` in any `og.tsx`, so this is
+ * mechanically enforced rather than left to discipline.
+ */
+import type { ReactElement } from "react";
+import type { BeyDocument } from "../../../../features/beys/schemas/firestore";
+/**
+ * One bey's card.
+ *
+ * 🛑 EVERY CLAUSE IS CONDITIONAL, because the coverage genuinely varies: 93%
+ * of beys have a mass but only 248 state it directly, and `system` is on 94%
+ * while `type` and `spinDirection` are lower. A card reading "0 g" or an empty
+ * separator would be a claim the data does not support — the same reason the
+ * parts card builds its detail line by filtering.
+ *
+ * 🛑 The mass is marked `≈` when it was SUMMED from the parts rather than
+ * stated, which is the same honesty the detail page applies. A derived figure
+ * printed as an exact one is the single easiest way for this dataset to start
+ * lying.
+ */
+export declare function renderBeyOg(bey: BeyDocument | null | undefined, opts: {
+    siteName: string;
+}): ReactElement;

package/dist/_internal/server/features/beys/og.js

@@ -0,0 +1,89 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const BG = "#0f172a";
+const GRADIENT = "linear-gradient(135deg, #0f172a 0%, #1e293b 100%)";
+const MUTED = "#94a3b8";
+const ACCENT = "#5eead4";
+/*
+ * 🛑 A COPY of the parts shell, not an import, and that is a considered
+ * choice rather than laziness.
+ *
+ * The Duplication Decision Framework's Rule of Three says extract on the
+ * THIRD copy, not the second — "two copies is observation; three is a
+ * pattern". There are now exactly two OG shells of this shape. Lifting it to
+ * a shared module today would also put a third consumer between every OG
+ * renderer and its layout for no behavioural gain.
+ *
+ * When a third appears, extract then. The constants above are duplicated for
+ * the same reason and in the same breath.
+ */
+function shell(eyebrow, title, detail, siteName) {
+    return (_jsxs("div", { style: {
+            display: "flex",
+            width: "100%",
+            height: "100%",
+            background: BG,
+            fontFamily: "sans-serif",
+            position: "relative",
+            overflow: "hidden",
+            alignItems: "center",
+            justifyContent: "center",
+        }, children: [_jsx("div", { style: { position: "absolute", inset: 0, background: GRADIENT } }), _jsxs("div", { style: {
+                    position: "relative",
+                    display: "flex",
+                    flexDirection: "column",
+                    alignItems: "center",
+                    gap: 24,
+                    padding: "60px",
+                    textAlign: "center",
+                }, children: [_jsx("div", { style: {
+                            fontSize: 20,
+                            color: ACCENT,
+                            fontWeight: 600,
+                            letterSpacing: 3,
+                            textTransform: "uppercase",
+                        }, children: eyebrow }), _jsx("div", { style: {
+                            fontSize: title.length > 34 ? 56 : 76,
+                            color: "#ffffff",
+                            fontWeight: 700,
+                            lineHeight: 1.1,
+                        }, children: title }), detail && _jsx("div", { style: { fontSize: 28, color: MUTED }, children: detail }), _jsx("div", { style: { fontSize: 20, color: MUTED, marginTop: 8 }, children: siteName })] })] }));
+}
+/**
+ * One bey's card.
+ *
+ * 🛑 EVERY CLAUSE IS CONDITIONAL, because the coverage genuinely varies: 93%
+ * of beys have a mass but only 248 state it directly, and `system` is on 94%
+ * while `type` and `spinDirection` are lower. A card reading "0 g" or an empty
+ * separator would be a claim the data does not support — the same reason the
+ * parts card builds its detail line by filtering.
+ *
+ * 🛑 The mass is marked `≈` when it was SUMMED from the parts rather than
+ * stated, which is the same honesty the detail page applies. A derived figure
+ * printed as an exact one is the single easiest way for this dataset to start
+ * lying.
+ */
+export function renderBeyOg(bey, opts) {
+    if (!bey)
+        return shell("Beyblades", "Beyblade database", "", opts.siteName);
+    const statedMass = typeof bey.weightG === "number" ? bey.weightG : null;
+    const summedMass = typeof bey.weightGFromParts === "number" ? bey.weightGFromParts : null;
+    const mass = statedMass !== null
+        ? `${statedMass} g`
+        : summedMass !== null
+            ? `≈ ${Math.round(summedMass * 10) / 10} g`
+            : null;
+    const bits = [
+        bey.type ? `${bey.type} type` : null,
+        bey.spinDirection ?? null,
+        mass,
+        bey.composition?.length ? `${bey.composition.length} parts` : null,
+    ].filter((b) => b !== null);
+    /*
+     * The eyebrow is the SYSTEM (Hybrid Wheel System, Burst Ultimate…) because
+     * that is the one line a collector uses to place a bey in time, and it is
+     * present on 94% of them. `series` is the fallback and "Beyblade" the floor
+     * — never an empty eyebrow, which reads as a broken template.
+     */
+    const eyebrow = bey.system ?? bey.series ?? "Beyblade";
+    return shell(eyebrow, bey.name, bits.join("  ·  "), opts.siteName);
+}

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

@@ -1,3 +1,4 @@
+import { type SelectedShippingQuote } from "../../../shared/shipping/quote";
 import { type StoreShippingPolicy } from "../../../shared/features/shipping/mode";
 import { type CartLane } from "../../../shared/checkout/lanes";
 import type { OutOfStockPolicy } from "../../../../features/orders/schemas/index";
@@ -12,6 +13,36 @@ export interface CreateCheckoutOrderInput {
     paymentMethod: CheckoutPaymentMethod;
     /** Required when paymentMethod === "emi" — the buyer's chosen tenure (2–6 months). */
     emiTenureMonths?: number;
+    /**
+     * The courier the buyer picked at checkout, with the ₹50-rounded rate they
+     * were shown.
+     *
+     * 🛑 OPTIONAL, and its absence is meaningful: a cart whose carrier quote
+     * failed, a digital-only cart, or any caller written before the picker
+     * existed falls back to `resolveShippingCost` exactly as before. Absence is
+     * what makes reconciliation skip the order as "no-quote" rather than
+     * measuring a seller's spend against a figure nobody was charged.
+     *
+     * 🛑 `chargedRate` is TRUSTED from the client, and that is a deliberate,
+     * bounded decision rather than an oversight. It is re-derived server-side
+     * through `roundShippingUp` before it is billed, so a tampered value can
+     * only ever be a different carrier rate rounded the same way — the gap
+     * worth closing is re-quoting the carrier at order time, which costs an
+     * outbound call on the payment path and is tracked separately.
+     */
+    selectedShippingQuote?: SelectedShippingQuote;
+    /**
+     * Points the buyer chose to spend on this checkout. 1 point = ₹1.
+     *
+     * 🛑 Requested, never trusted. The server re-reads the balance, re-applies
+     * the 50% cap against the real cart total, and spends the LESSER of the two
+     * — a client that asks for more than it holds gets its request trimmed, not
+     * an error, because the honest reading of "spend 500 when you have 300" is a
+     * stale page rather than an attack. `pointsRepository.redeem` then re-checks
+     * the balance a third time inside its own transaction, which is the check
+     * that actually prevents a negative balance under concurrency.
+     */
+    pointsToRedeem?: number;
     notes?: string;
     excludedProductIds?: string[];
     /** When true this is an admin test order — OTP consent is pre-granted and the order is created paid/processing. */

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

@@ -12,6 +12,9 @@ import { roundRupees } from "../../../../utils/number.formatter.js";
 import { ApiError, ValidationError, NotFoundError, ERROR_MESSAGES } from "../../../../errors/index.js";
 import { ORDER_FIELDS } from "../../../../constants/field-names.js";
 import { serverLogger } from "../../../../monitoring/index.js";
+import { roundShippingUp, } from "../../../shared/shipping/quote.js";
+import { pointsRepository } from "../../../../features/points/repository/points.repository.js";
+import { maxRedeemablePoints } from "../../../../features/points/schemas/firestore.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";
@@ -490,7 +493,7 @@ function dispatchOrderConfirmationEmails(emailsToSend) {
  * so the caller can accumulate the checkout-wide `total`.
  */
 async function createOrderForGroup(group, orderType, ctx) {
-    const { paymentMethod, emiTenureMonths, emiSettings, commissions, appliedCoupons, cartSubtotal, couponUsageAccumulator, uid, userName, userEmail, shippingAddress, notes, adminBypass, adminBypassBy, adminBatchId, orderIds, emailsToSend, outOfStockPolicy, droppedItems, buyerState, gstSettings, siteContactUpiVpa, storeAddons, platformFeeByStore, } = ctx;
+    const { paymentMethod, emiTenureMonths, emiSettings, commissions, appliedCoupons, cartSubtotal, couponUsageAccumulator, uid, userName, userEmail, shippingAddress, notes, adminBypass, adminBypassBy, adminBatchId, orderIds, emailsToSend, outOfStockPolicy, droppedItems, buyerState, gstSettings, siteContactUpiVpa, storeAddons, platformFeeByStore, selectedShippingQuote, } = ctx;
     const firstItem = group[0].item;
     const firstProduct = group[0].product;
     // Add-ons are this store's choice, not the cart's — see OrderGroupContext.
@@ -507,7 +510,25 @@ async function createOrderForGroup(group, orderType, ctx) {
         return expandCartLineToOrderRows(item, product, ctx.productById).map((baseLine) => itemRule.decorateOrderItem(baseLine, product));
     });
     const totalQuantity = group.reduce((sum, { item }) => sum + item.quantity, 0);
-    const { shippingFee, storeOwnerId, storeEmiEnabled, storeState, storeProtections, storeTaxIdentity } = await resolveShippingCost(firstItem.storeId);
+    const { shippingFee: resolvedShippingFee, storeOwnerId, storeEmiEnabled, storeState, storeProtections, storeTaxIdentity } = await resolveShippingCost(firstItem.storeId);
+    /*
+     * 🛑 The buyer's quote WINS over the seller's configured rate, and it is
+     * re-rounded here rather than trusted as sent.
+     *
+     * `roundShippingUp` is idempotent, so re-applying it to an honest value is a
+     * no-op; applied to a tampered one it forces the result back onto a ₹50 step.
+     * That bounds what a forged `chargedRate` can be to "some carrier rate,
+     * correctly rounded" rather than an arbitrary number.
+     *
+     * Applied to the FIRST group only — see the field's note on OrderGroupContext.
+     * A cart spanning sellers must not be charged the same parcel rate twice.
+     */
+    const isFirstGroup = ctx.orderIds.length === 0;
+    const shippingFee = selectedShippingQuote && isFirstGroup
+        ? roundShippingUp(selectedShippingQuote.chargedRate)
+        : selectedShippingQuote
+            ? 0
+            : resolvedShippingFee;
     /*
      * Who issues this invoice — the seller if they have their own GSTIN, the
      * platform otherwise. ONE function decides, and it is the only place that
@@ -678,6 +699,16 @@ async function createOrderForGroup(group, orderType, ctx) {
         // are "auction". Written ONCE here and never recomputed: the auction and
         // offer documents it summarises are mutable and eventually archived.
         sourceContext,
+        /*
+         * Frozen onto the order so reconciliation has a charged figure to measure
+         * the seller's real postage against. Only on the group that actually
+         * carries the shipping fee — a later group in a multi-seller cart is
+         * charged ₹0 shipping, so recording a quote there would invite a credit
+         * against money that group never collected.
+         */
+        selectedShippingQuote: selectedShippingQuote && isFirstGroup
+            ? { ...selectedShippingQuote, chargedRate: shippingFee }
+            : undefined,
         offerId: firstItem.offerId ?? undefined,
         // Distinguishes a Buy Now purchase from a settled auction win. Both are
         // orderType "auction"; only this one gets the 24h admin-review window.
@@ -1139,12 +1170,53 @@ export async function createCheckoutOrderAction(input) {
         siteContactUpiVpa: siteSettings?.contact?.upiVpa,
         storeAddons: cart.storeAddons,
         platformFeeByStore,
+        selectedShippingQuote: input.selectedShippingQuote,
         productById: checkoutProductById,
     };
     for (const { items: group, orderType } of orderGroups) {
         total += await createOrderForGroup(group, orderType, groupCtx);
     }
     await flushCouponUsageAccumulator(couponUsageAccumulator, uid);
+    /*
+     * Spend points AFTER the orders exist.
+     *
+     * 🛑 This ordering is the whole safety argument. Redeeming first and then
+     * failing to create an order would debit a buyer for something they never
+     * received, and points have no refund path that does not need a human. This
+     * way the worst case is an order placed at full price with the balance
+     * intact — recoverable, and visible to the buyer, who still has their
+     * points.
+     *
+     * The amount is re-derived server-side against the real total rather than
+     * taken from the request; `maxRedeemablePoints` applies the 50% cap, and
+     * `redeem` re-checks the balance inside its own transaction.
+     */
+    if (input.pointsToRedeem && input.pointsToRedeem > 0 && orderIds.length > 0) {
+        try {
+            const balance = await pointsRepository.getBalance(uid);
+            const spend = maxRedeemablePoints(total, Math.min(balance, input.pointsToRedeem));
+            if (spend > 0) {
+                await pointsRepository.redeem({
+                    userId: uid,
+                    points: spend,
+                    orderId: orderIds[0],
+                    description: `Redeemed on ${orderIds[0]}`,
+                });
+            }
+        }
+        catch (err) {
+            /*
+             * A failed redemption must not fail a placed order. The buyer keeps the
+             * points and paid full price — the strictly safer side of this trade.
+             */
+            const normalized = normalizeError(err);
+            serverLogger.error("points redemption failed after order creation", {
+                uid,
+                orderId: orderIds[0],
+                message: normalized.message,
+            });
+        }
+    }
     dispatchOrderConfirmationEmails(emailsToSend);
     serverLogger.info(`createCheckoutOrderAction: ${orderIds.length} order(s) placed for uid=${uid}` +
         (unavailable.length > 0 ? ` (${unavailable.length} item(s) unavailable)` : ""));
@@ -1572,7 +1644,7 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
     // 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, storeState, storeTaxIdentity } = await resolveShippingCost(firstItem.storeId);
+    const { shippingFee, storeOwnerId, storeState, storeTaxIdentity, storeProtections } = await resolveShippingCost(firstItem.storeId);
     /*
      * Same supplier-of-record rule as `createOrderForGroup`, through the same
      * function. This path (PhonePe verify / webhook) is the SECOND place an
@@ -1608,7 +1680,44 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
     const addons = storeAddons?.[firstItem.storeId] ?? {};
     const giftWrapFee = computeGiftWrapFee(addons.giftWrapAddon ?? false, commissionRates);
     const giftWrapMessage = addons.giftWrapMessage;
-    const shipmentProtectionFee = computeShipmentProtectionFee(groupTotal, addons.shipmentProtectionAddon ?? false, commissionRates);
+    /*
+     * 🛑 `computeProtectionFees`, not a bare `computeShipmentProtectionFee`.
+     *
+     * This path hand-rolled the shipment fee and computed NO sale-protection fee
+     * at all, which was wrong twice over:
+     *
+     *  1. **Sale protection was never charged here.** Razorpay's create-order
+     *     route DOES charge it (it calls `computeProtectionFees`), so the amount
+     *     captured and the amount this function records on the order disagreed
+     *     by the fee — and the platform absorbs the unconditional refund that
+     *     fee exists to pay for. See `computeSaleProtectionFee`.
+     *  2. **The C5e tiers were skipped.** The bare helper tests only "did the
+     *     buyer tick it" and the site-wide master switch, so shipment protection
+     *     could be billed on a seller who never agreed to back it, or on a
+     *     final-sale item where it cannot apply.
+     *
+     * Latent rather than live when written — `payment.phonepeEnabled` is false
+     * and the one live store has `supportsSaleProtection` unset — but both of
+     * those are a settings toggle away, and an under-charge that appears the
+     * moment a flag flips is worse than one that is visible now.
+     */
+    const groupHasFinalSale = group.some(({ product }) => product?.finalSale === true);
+    const { shippingProtectionFee: shipmentProtectionFee, saleProtectionFee } = computeProtectionFees({
+        subtotal: groupTotal,
+        selected: {
+            shipping: addons.shipmentProtectionAddon ?? false,
+            sale: addons.saleProtectionAddon ?? false,
+        },
+        tiers: {
+            platformShipping: commissionRates.shipmentProtectionFeeEnabled === true,
+            platformSale: commissionRates.saleProtectionFeeEnabled === true,
+            sellerShipping: storeProtections.shipping,
+            sellerSale: storeProtections.sale,
+            finalSale: groupHasFinalSale,
+        },
+        shippingFee: (s, sel) => computeShipmentProtectionFee(s, sel, commissionRates),
+        saleFee: (s, sel) => computeSaleProtectionFee(s, sel, commissionRates),
+    });
     /*
      * P-8 GST — now wired through this path. C0c defect 1.
      *
@@ -1641,7 +1750,7 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
     /* Product GST is not a term — prices are tax-inclusive, so it is already
      * inside `groupTotal`. Matches the COD/UPI path exactly; `platformFeeGst`
      * stays because that is GST on our fee, charged on top. */
-    const orderTotal = Math.max(0, groupTotal - couponDiscount) + shippingFee + giftWrapFee + shipmentProtectionFee + platformFee + platformFeeGst;
+    const orderTotal = Math.max(0, groupTotal - couponDiscount) + shippingFee + giftWrapFee + shipmentProtectionFee + saleProtectionFee + platformFee + platformFeeGst;
     // S-SBUNI-RULES 2026-05-13 — order-item decoration via rule registry.
     // Same expansion as the COD/UPI path. This was a THIRD hand-rolled copy of
     // the price rule (`isBundle ? item.price : product.price`) that — like the
@@ -1730,6 +1839,9 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
         giftWrapMessage: giftWrapFee > 0 ? giftWrapMessage?.slice(0, 500) : undefined,
         shipmentProtectionAddon: shipmentProtectionFee > 0 ? true : undefined,
         shipmentProtectionFee: shipmentProtectionFee > 0 ? shipmentProtectionFee : undefined,
+        // Recorded as well as charged — an order that collects a protection fee
+        // without a record of it cannot be reconciled against a later claim.
+        saleProtectionFee: saleProtectionFee > 0 ? saleProtectionFee : undefined,
         /*
          * The tax breakdown, matching `createOrderForGroup` field for field.
          * This path recorded NONE of it before C0c defect 1 — so an online order

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

@@ -46,3 +46,33 @@ export declare function adminRejectPaymentAsFraudAction(orderId: string, note: s
  * payment/order status — surfaces to the admin queue for investigation.
  */
 export declare function raiseOrderDisputeAction(orderId: string, reason: string): Promise<ActionResult<void>>;
+/**
+ * A buyer submits payment for ONE of their own EMI instalments.
+ *
+ * 🛑 Why this exists at all: there was no buyer-side route. The only writer
+ * was the seller's `markEmiInstallmentPaid`, so a buyer on an EMI plan could
+ * not pay an instalment — they waited for the seller to record it. The
+ * schema had anticipated them all along (`EmiInstallment.transactionId` and
+ * `.proofUrl` are documented as "buyer-uploaded"), which is the tell that the
+ * surface, not the model, was missing.
+ *
+ * 🛑 **ANY unpaid instalment, at ANY time — deliberately unbounded.** There is
+ * no due-date check and none should be added. A buyer who wants to clear the
+ * plan early is reducing our exposure, not breaking a rule, and the dueDate is
+ * the date we will CHASE them on, never the first date they may pay. Paying
+ * ahead also keeps `emiComplete` honest: that flag is what
+ * `assertEmiShippable` reads, so early settlement should be able to release a
+ * shipment early rather than waiting out a calendar.
+ *
+ * It mirrors the manual-payment model rather than inventing a second one: the
+ * buyer supplies a UTR and a proof, the seller or an admin confirms. The
+ * status therefore moves to `pending` review here, NOT to `paid` — a buyer
+ * must never be able to mark their own money received. `markEmiInstallmentPaid`
+ * stays the only writer of `paid`, and so stays the only way `emiComplete`
+ * can flip.
+ */
+export declare function submitEmiInstallmentPaymentAction(orderId: string, input: {
+    installmentIndex: number;
+    transactionId: string;
+    proofUrl?: string;
+}): Promise<ActionResult<void>>;