@mohasinac/appkit 4.62.1 → 4.63.0

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

@@ -12,7 +12,20 @@ export interface CreateCheckoutOrderInput {
     /** Required for physical carts; omitted for digital-code-only carts (no shipping). */
     addressId?: string;
     paymentMethod: CheckoutPaymentMethod;
-    /** Required when paymentMethod === "emi" — the buyer's chosen tenure (2–6 months). */
+    /**
+     * LEGACY ONLY. The instalment plan lives on `CartDocument.emiPlan`, written
+     * by `PUT /api/cart/emi`, because the online path needs the same answer in
+     * two separate requests (see that field's own note). This is honoured solely
+     * for a tab opened before 2026-10-22, which posts `paymentMethod: "emi"`
+     * plus a tenure here and has nothing on the cart — and it is ignored
+     * whenever the cart carries a plan, so a client can never re-price a quote
+     * the server has already issued.
+     *
+     * 🛑 "Pay in instalments" is an opt-in ON THE ORDER, orthogonal to the
+     * tender: the token is collected by whichever payment method the buyer
+     * picked. `resolveEmiChoice` is the one expression both axes resolve
+     * through, and `emiTenderFor` maps the legacy `"emi"` tender.
+     */
     emiTenureMonths?: number;
     /**
      * The courier the buyer picked at checkout, with the ₹50-rounded rate they
@@ -188,15 +201,21 @@ export interface CheckoutPricingPreviewInput {
      */
     lane?: CartLane;
     /**
-     * The chosen EMI tenure, when `paymentMethod` is `"emi"`.
+     * LEGACY ONLY — see `CreateCheckoutOrderInput.emiTenureMonths`.
      *
-     * 🛑 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.
+     * 🛑 The plan is read off `CartDocument.emiPlan`, so the preview and the
+     * order resolve it from the same durable value. This docstring used to argue
+     * the opposite — *"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"* — and that reasoning is what left the ONLINE path unable to
+     * agree with itself, because `/api/payment/create-order` decides the capture
+     * amount in one request and `/api/payment/verify` writes the order in
+     * another. A request body cannot be read by both.
+     *
+     * The surcharge is `principalRemaining × surchargePercentPerMonth ×
+     * tenureMonths`, so it genuinely cannot be derived from the cart ITEMS
+     * alone — which is why the tenure had to become part of the cart DOCUMENT
+     * rather than part of the request.
      */
     emiTenureMonths?: number;
 }
@@ -210,6 +229,15 @@ export interface CheckoutPricingPreviewStore {
     giftWrapFee: number;
     shipmentProtectionFee: number;
     saleProtectionFee: number;
+    /**
+     * How much of this seller's total is DEFERRED into instalments — the
+     * financed principal plus its surcharge. Zero unless instalments are on.
+     *
+     * 🛑 Not a discount and not a fee. `total` stays the full value of the
+     * supply (it is what the invoice declares and what a refund measures
+     * against); this is the slice of it that is not collected today.
+     */
+    emiDeferred: number;
     /**
      * EMI surcharge for THIS seller, when the buyer is previewing an EMI order.
      *
@@ -271,6 +299,12 @@ export interface CheckoutPricingPreview {
     saleProtectionFee: number;
     /** Total EMI surcharge across sellers. Zero unless previewing an EMI order. */
     emiSurcharge: number;
+    /**
+     * Total DEFERRED into instalments across sellers. Zero unless instalments
+     * are on. `total − pointsApplied − emiDeferred` is `amountDue` — what the
+     * buyer pays today.
+     */
+    emiDeferred: number;
     gstAmount: number;
     couponDiscount: number;
     /** Buyer-facing platform commission, capped, charged once for this checkout. */
@@ -300,8 +334,14 @@ export interface CheckoutPricingPreview {
      *
      * 🛑 THIS is the parity figure. The capture route and the post-capture guard
      * must both use it, or points become a sixth way the captured amount diverges
-     * from the recorded order (D37/D38/D40). Equal to `total` whenever no points
-     * are applied, so every existing reader of `total` stays correct.
+     * from the recorded order (D37/D38/D40). Equal to `total` whenever neither
+     * points nor instalments apply, so every existing reader of `total` stays
+     * correct.
+     *
+     * 🛑 Instalments reduce it too, via `amountDueNow` — the same expression the
+     * two order writers use. An EMI buyer pays the TOKEN today; quoting the full
+     * total here is what made the manual-payment page ask for the whole amount
+     * while scheduling instalments for the same money.
      */
     amountDue: number;
     /**