@mohasinac/appkit 4.62.0 → 4.63.0

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

@@ -1,5 +1,6 @@
 import { type SelectedShippingQuote } from "../../../shared/shipping/quote";
 import { type StoreShippingPolicy } from "../../../shared/features/shipping/mode";
+import { type SharedPurchaseRates } from "../../../shared/features/shipping/shared-purchase";
 import { type CartLane } from "../../../shared/checkout/lanes";
 import type { OutOfStockPolicy } from "../../../../features/orders/schemas/index";
 import { type CheckoutPaymentMethod } from "../../../shared/features/checkout/config";
@@ -11,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
@@ -132,6 +146,33 @@ opts?: {
         shipping: boolean;
         sale: boolean;
     };
+    /**
+     * Decision 22 — does this seller accept buyer points as part-payment?
+     *
+     * Here for the same reason as `storeProtections` directly above: the store
+     * document is already in hand, and the accepting store ABSORBS the
+     * redemption against its own payout, so this is a liability flag and absence
+     * resolves to `false` exactly once, here.
+     *
+     * 🛑 Resolved through `storeAcceptsPoints()`, never a bare field read — the
+     * platform's own storefront always accepts and that is decided in code
+     * rather than by a seeded flag somebody can switch off.
+     */
+    acceptsPoints: boolean;
+    /**
+     * S5a — the shared-purchase rates, from the store read this function already
+     * performs.
+     *
+     * Returned RAW rather than as a quote, for the same reason
+     * `storeTaxIdentity` is: the decision (how many destinations, and therefore
+     * what it costs) belongs to the caller that knows the lines. This function
+     * resolves per-store facts.
+     *
+     * 🛑 `undefined` on a fee is preserved and NOT defaulted to 0 — a seller who
+     * opted in without pricing it has not agreed to do it free. `quoteSharedPurchase`
+     * reports that as `unpriced` and the caller refuses.
+     */
+    sharedPurchaseRates: SharedPurchaseRates;
 }>;
 export interface DroppedCoupon {
     code: string;
@@ -160,15 +201,21 @@ export interface CheckoutPricingPreviewInput {
      */
     lane?: CartLane;
     /**
-     * The chosen EMI tenure, when `paymentMethod` is `"emi"`.
+     * LEGACY ONLY — see `CreateCheckoutOrderInput.emiTenureMonths`.
+     *
+     * 🛑 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.
      *
-     * 🛑 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 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;
 }
@@ -182,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.
      *
@@ -213,6 +269,26 @@ export interface CheckoutPricingPreviewStore {
     supportsSaleProtection: boolean;
     /** True when any of this store's priced lines is `finalSale`. */
     hasFinalSaleItem: boolean;
+    /**
+     * D46/D47 + decision 22 — does this seller accept points?
+     *
+     * Carried for the same reason as the two protection booleans directly above:
+     * the gate and the amount must be provably one decision rather than two that
+     * agree by discipline. A seller card can then say "points not accepted here"
+     * instead of the buyer wondering why their discount is smaller than their
+     * balance.
+     */
+    acceptsPoints: boolean;
+    /** Points applied to THIS store's order. Zero when it does not accept them. */
+    pointsApplied: number;
+    /**
+     * S5a — the shared-purchase fee for this store's order (handling + extra
+     * shipping legs). Zero on an ordinary single-destination order.
+     *
+     * 🛑 Surfaced because a coordinator commits against the preview, and the
+     * plan is explicit that these fees must be shown BEFORE they commit.
+     */
+    sharedPurchaseFee: number;
 }
 export interface CheckoutPricingPreview {
     subtotal: number;
@@ -223,13 +299,57 @@ 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. */
     platformFee: number;
     /** GST on the (capped) platform commission. */
     gstOnFee: number;
+    /**
+     * S5a — handling plus extra shipping legs, across every store in the cart.
+     *
+     * 🛑 A real additive charge, unlike the tax-inclusive `gstAmount`, so it is
+     * a term in `total` and belongs in the fee column.
+     */
+    sharedPurchaseFee: number;
     total: number;
+    /**
+     * D46/D47 — points applied across every accepting store in this checkout.
+     *
+     * 🛑 `total` stays the ORDER VALUE and is not reduced by this. `amountDue`
+     * below is what the buyer actually pays, and the two are deliberately both
+     * returned: the summary shows the full total, the discount line, and then the
+     * amount due, which is how a buyer can see what their points did. Collapsing
+     * them into one figure would hide the discount from the person who earned it.
+     */
+    pointsApplied: number;
+    /**
+     * What the gateway will be asked to capture: `total − pointsApplied`.
+     *
+     * 🛑 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 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;
+    /**
+     * The buyer's remaining points balance, for the cart's own copy ("you have
+     * N points"). Zero when they have not opted in — the preview does not read a
+     * balance it is not going to use.
+     */
+    pointsBalance: number;
     /**
      * Per-store breakdown, in group order. Every figure here was already being
      * computed inside the per-group loop and then discarded into an aggregate —