@mohasinac/appkit 4.62.0 → 4.62.1

package/dist/_internal/shared/checkout/coupon-discount.d.ts

@@ -32,12 +32,54 @@ export interface GroupCouponDiscountResult {
     appliedDiscounts: {
         code: string;
         couponId?: string;
+        /**
+         * 🛑 This is NOT `CouponType`, and the two are easy to confuse now that
+         * both live in this file. This one records WHERE the discount came from —
+         * a coupon the buyer typed, a deal, or an automatic rule — and it is what
+         * the order document stores in `appliedDiscounts[]`.
+         *
+         * `CartAppliedCoupon.type` is the coupon's own kind (`percentage`,
+         * `points_earn`, …) and is what the loop below skips on. Reading one where
+         * the other is meant would compile cleanly and be wrong: every value of
+         * this union is absent from that one, so the `points_earn` skip would
+         * never fire and a points coupon would discount the order.
+         */
         type: "coupon" | "deal" | "auto";
         discountAmount: number;
         scope?: "admin" | "seller";
         storeId?: string;
     }[];
 }
+/**
+ * What the CART-level call returns: the same totals, plus the per-group
+ * breakdown.
+ *
+ * 🛑 A separate interface rather than one optional field on the result above.
+ * `computeGroupCouponDiscount` scores ONE group, so it has no per-group list
+ * to report and never will — giving it an empty `perGroup` would be a value
+ * that type-checks and means nothing, and the capture route's points tender
+ * reads this array positionally. A caller that gets `[]` where it expected one
+ * entry per group apportions every point against group zero.
+ */
+export interface CartCouponDiscountResult extends GroupCouponDiscountResult {
+    /**
+     * The per-group discount, in the order the groups were passed.
+     *
+     * 🛑 Surfaced rather than aggregated-and-forgotten. It was already being
+     * computed inside the loop below and then summed away — the same shape as
+     * `CheckoutPricingPreviewStore`'s per-store fees, which existed only as an
+     * aggregate until a seller card needed them.
+     *
+     * The caller that needs it is the capture route's points tender: the
+     * per-group base includes that group's own discount, and re-deriving it
+     * there would be a second copy of the apportionment rule (Root Cause #75) on
+     * the one path D37 proves gets left behind.
+     */
+    perGroup: {
+        storeId: string | undefined;
+        couponDiscount: number;
+    }[];
+}
 /**
  * Prorates every buyer-applied coupon against one seller-group's total.
  *
@@ -70,4 +112,4 @@ export declare function computeCartCouponDiscount(appliedCoupons: CartAppliedCou
         itemId: string;
         lineTotal: number;
     }[];
-}[]): GroupCouponDiscountResult;
+}[]): CartCouponDiscountResult;

package/dist/_internal/shared/checkout/coupon-discount.js

@@ -42,6 +42,20 @@ export function computeGroupCouponDiscount(appliedCoupons, groupLines, groupTota
     let couponDiscount = 0;
     const appliedDiscounts = [];
     for (const coupon of appliedCoupons) {
+        /*
+         * 🛑 D51 — a `points_earn` coupon DISCOUNTS NOTHING. It awards points on
+         * the post-discount amount paid, and it carries `pointsPercent` rather than
+         * a discount value.
+         *
+         * Skipped here rather than relied on to carry `discountAmount: 0`. The
+         * apply route writes whatever `validateCouponForCart` returned, and a
+         * points coupon that ever came back with a non-zero `discountAmount` —
+         * through a mis-seeded `discount.value`, or an admin editing a coupon's
+         * type after creation — would silently discount the order AND award points.
+         * A type check cannot be bypassed by bad data; a zero cannot be relied on.
+         */
+        if (coupon.type === "points_earn")
+            continue;
         let couponGroupDiscount = 0;
         const isSellerScoped = coupon.scope === "seller" && coupon.storeId;
         if (isSellerScoped) {
@@ -93,11 +107,22 @@ export function computeCartCouponDiscount(appliedCoupons, groups) {
     const cartSubtotal = groups.reduce((sum, g) => sum + g.lines.reduce((s, l) => s + l.lineTotal, 0), 0);
     let couponDiscount = 0;
     const appliedDiscounts = [];
+    const perGroup = [];
     for (const group of groups) {
         const groupTotal = group.lines.reduce((s, l) => s + l.lineTotal, 0);
         const res = computeGroupCouponDiscount(appliedCoupons, group.lines, groupTotal, cartSubtotal, group.storeId);
         couponDiscount += res.couponDiscount;
         appliedDiscounts.push(...res.appliedDiscounts);
+        /*
+         * 🛑 NOT rounded here, and the aggregate below IS. Rounding each group
+         * then summing can differ from summing then rounding by a paisa per group,
+         * and the aggregate is what the gateway captures — so the group figures
+         * stay raw and the caller rounds its own composed base once, exactly as
+         * `createOrderForGroup` does with a single `roundRupees` on `orderTotal`
+         * (D42). A rounded-then-summed discount is how a total ends up a paisa
+         * short of its own lines.
+         */
+        perGroup.push({ storeId: group.storeId, couponDiscount: res.couponDiscount });
     }
-    return { couponDiscount: roundRupees(couponDiscount), appliedDiscounts };
+    return { couponDiscount: roundRupees(couponDiscount), appliedDiscounts, perGroup };
 }

package/dist/_internal/shared/checkout/order-math.d.ts

@@ -377,12 +377,157 @@ export declare function orderShippingReimbursement(order: ReimbursableOrderLike)
 export declare function orderPointsFunded(order: {
     pointsAwarded?: number;
 }): number;
+/**
+ * Points this order CONSUMED, which the accepting store also funds (D46/D47).
+ *
+ * Decision 3's other end. The earn above is borne by the originating store;
+ * the redemption is absorbed by the store that agreed to accept points
+ * (`StoreDocument.acceptsPoints`, defaulting to NOT accepted precisely so no
+ * seller is enrolled in funding discounts they never agreed to). The platform
+ * funds neither end.
+ *
+ * Reads `pointsApplied` off the order for the same reason the earn reads
+ * `pointsAwarded`: it must be what was actually spent. Recomputing the cap from
+ * today's total would deduct a figure the buyer never received the benefit of —
+ * and on a partially-cancelled order the total has moved.
+ */
+export declare function orderPointsRedeemed(order: {
+    pointsApplied?: number;
+}): number;
 /** Sum of `orderPointsFunded` across a batch. */
 export declare function ordersPointsFunded(orders: readonly {
     pointsAwarded?: number;
 }[]): number;
+/**
+ * Everything the store funds through the points programme, for one batch:
+ * points ISSUED on these orders plus points SPENT on them.
+ *
+ * ## 🛑 One figure, because they are one obligation
+ *
+ * Both ends are seller-funded (decisions 3 and 17) and both are deducted from
+ * the same payout at the same moment, so splitting them across two parameters
+ * of `computePayoutDeduction` would be two chances for a call site to pass one
+ * and forget the other — and a payout that deducts the earn but not the
+ * redemption is short by exactly the amount nobody noticed.
+ *
+ * 🛑 This helper exists because `ordersPointsFunded` had **ZERO consumers**
+ * from the day it was written — the earn deduction was built, documented at
+ * length, and never passed to the function it was built for, so every payout
+ * since has quietly been funded by the platform. That is the dead-field
+ * pattern (Rule: every declared field has both a writer and a reader) occurring
+ * inside the work that catalogues it. Wiring the combined figure at all four
+ * call sites is what closes it.
+ */
+export declare function ordersPointsBorneByStore(orders: readonly {
+    pointsAwarded?: number;
+    pointsApplied?: number;
+}[]): number;
 /** Sum of `orderShippingReimbursement` across a batch. */
 export declare function ordersShippingReimbursement(orders: readonly ReimbursableOrderLike[]): number;
+/**
+ * How many points may be spent on ONE order group, and what is left to charge.
+ *
+ * ## 🛑 A PIPELINE STAGE, after the final rounding — never a post-order debit
+ *
+ * This is the whole lesson of D46. The deleted code redeemed points AFTER the
+ * orders existed and the gateway had captured `orderTotal`, so a successful
+ * redemption took points from a buyer who had just paid full price: nothing in
+ * the pipeline knew about the spend, so nothing reduced the charge.
+ *
+ * So the tender is a STAGE. `amountDue = orderTotal − pointsApplied` is
+ * computed here, and `amountDue` is what the gateway captures and what the
+ * post-capture guard compares. A sixth way for the captured amount to diverge
+ * from the recorded total is the D37/D38/D40 family; this is how it is avoided.
+ *
+ * ## 🛑 Applied AFTER rounding, deliberately
+ *
+ * `orderTotal` is rounded ONCE at the end of its own nine-term sum (D42).
+ * Folding points in before that rounding would put a discount inside the sum
+ * being rounded, so the figure shown to the buyer and the figure captured could
+ * differ by a paisa. They must be provably equal, which is why `amountDue` is
+ * derived here and never recomputed at the gateway.
+ *
+ * ## Per order group, because the ACCEPTING STORE absorbs it
+ *
+ * Decision 3: a redeemed point reduces THAT store's payout for THAT order. A
+ * cart spanning an accepting and a non-accepting store must not pool the
+ * discount — each group gets its own cap and its own figure. That is the same
+ * granularity `splitCartIntoOrderGroups` and `allocateCheckoutFees` already
+ * use, and its absence is what caused Root Cause #65's per-store
+ * multiplication bug.
+ *
+ * ## All-or-nothing, and the remainder STAYS
+ *
+ * Owner's rule: *"if use point it is all and then the balance is returned if
+ * excess"*. There is no requested amount — the balance is spent down as far as
+ * the cap allows, and whatever will not fit is simply not spent. It stays in
+ * the ledger for a later order; nothing is forfeited, and no caller can ask for
+ * a partial spend.
+ *
+ * 🛑 The 50% cap is not optional, and removing it was explicitly declined.
+ * `POINTS_MAX_REDEMPTION_PERCENT` exists because a ₹0 order breaks the gateway
+ * (a ₹0 Razorpay order is not a thing) and because a balance that can settle a
+ * whole purchase behaves like the stored value the points schema is written to
+ * avoid.
+ */
+export declare function resolvePointsTender(input: {
+    /** The group's FINAL rounded total. */
+    orderTotal: number;
+    /** The buyer's live balance, in points (1 point = ₹1). */
+    balance: number;
+    /** Whether this group's store accepts points. */
+    accepted: boolean;
+    /** Whether the buyer ticked the cart's `useAllPoints`. */
+    optedIn: boolean;
+}): {
+    pointsApplied: number;
+    amountDue: number;
+};
+/**
+ * Draw one balance down across a checkout's order groups, in group order.
+ *
+ * ## Why this exists rather than each caller looping
+ *
+ * The tender is applied PER GROUP (decision 3 — the accepting store absorbs
+ * its own redemption), so "how many points does this checkout use" is a
+ * sequential draw-down, not a single `min`. Four surfaces need the same answer
+ * and must not each write the loop:
+ *
+ * | surface | why it needs the total |
+ * |---|---|
+ * | `previewCheckoutPricing` | the figure shown to the buyer |
+ * | `POST /api/payment/create-order` | the figure CAPTURED |
+ * | the post-capture guard | the figure compared |
+ * | the two order paths | the per-group figure recorded |
+ *
+ * D37 is the record of what happens when one of those four is left out: the
+ * coupon discount reached three of them and not the capture route, so the
+ * buyer was shown one number, charged another, and the order recorded the
+ * first — invisible in our own data because the guard was one-sided.
+ *
+ * 🛑 The order paths deliberately do NOT call this. They apply
+ * `resolvePointsTender` to their own group as they create it, drawing down a
+ * shared remainder — which is the same function applied in the same order, so
+ * the sum is identical by construction. Making them call this instead would
+ * mean computing every group's final total before creating any of them, which
+ * is a restructure of two 200-line functions for an answer they already have.
+ *
+ * ## The cap is per group, and the ORDER of the groups therefore matters
+ *
+ * A balance smaller than the whole checkout's 50% allowance is consumed by the
+ * earliest groups. That is arbitrary but it must be *consistently* arbitrary:
+ * every caller iterates `orderGroups` in the order `splitCartIntoOrderGroups`
+ * produced, so all four agree. Sorting differently anywhere would make the
+ * shown and charged figures diverge on exactly the carts where the balance is
+ * tight.
+ */
+export declare function allocatePointsAcrossGroups(groups: readonly {
+    total: number;
+    accepted: boolean;
+}[], balance: number, optedIn: boolean): {
+    perGroup: number[];
+    pointsApplied: number;
+};
 /**
  * P-6 — pre-order groups charge each product's own `preOrderDepositPercent`
  * (falling back to the generic COD deposit % when a product doesn't have one

package/dist/_internal/shared/checkout/order-math.js

@@ -1,5 +1,13 @@
 import { roundRupees } from "../../../utils/number.formatter.js";
 import { calculateGstInclusive, taxableFromInclusive } from "../fees/calculator.js";
+/*
+ * Points: the CAP arithmetic only. `maxRedeemablePoints` lives beside
+ * `POINTS_MAX_REDEMPTION_PERCENT`, which is the constant that defines it, so
+ * importing it here keeps one owner for the rule rather than a second copy of
+ * the percentage (Root Cause #75). This file stays pure — the points SCHEMA is
+ * plain data with no Firestore import.
+ */
+import { maxRedeemablePoints } from "../../../features/points/schemas/firestore.js";
 /**
  * The single source of truth for "what do we charge for ONE COPY of this line".
  *
@@ -593,14 +601,179 @@ export function orderPointsFunded(order) {
         ? roundRupees(Math.max(0, awarded))
         : 0;
 }
+/**
+ * Points this order CONSUMED, which the accepting store also funds (D46/D47).
+ *
+ * Decision 3's other end. The earn above is borne by the originating store;
+ * the redemption is absorbed by the store that agreed to accept points
+ * (`StoreDocument.acceptsPoints`, defaulting to NOT accepted precisely so no
+ * seller is enrolled in funding discounts they never agreed to). The platform
+ * funds neither end.
+ *
+ * Reads `pointsApplied` off the order for the same reason the earn reads
+ * `pointsAwarded`: it must be what was actually spent. Recomputing the cap from
+ * today's total would deduct a figure the buyer never received the benefit of —
+ * and on a partially-cancelled order the total has moved.
+ */
+export function orderPointsRedeemed(order) {
+    const applied = order.pointsApplied;
+    return typeof applied === "number" && Number.isFinite(applied)
+        ? roundRupees(Math.max(0, applied))
+        : 0;
+}
 /** Sum of `orderPointsFunded` across a batch. */
 export function ordersPointsFunded(orders) {
     return roundRupees(orders.reduce((sum, o) => sum + orderPointsFunded(o), 0));
 }
+/**
+ * Everything the store funds through the points programme, for one batch:
+ * points ISSUED on these orders plus points SPENT on them.
+ *
+ * ## 🛑 One figure, because they are one obligation
+ *
+ * Both ends are seller-funded (decisions 3 and 17) and both are deducted from
+ * the same payout at the same moment, so splitting them across two parameters
+ * of `computePayoutDeduction` would be two chances for a call site to pass one
+ * and forget the other — and a payout that deducts the earn but not the
+ * redemption is short by exactly the amount nobody noticed.
+ *
+ * 🛑 This helper exists because `ordersPointsFunded` had **ZERO consumers**
+ * from the day it was written — the earn deduction was built, documented at
+ * length, and never passed to the function it was built for, so every payout
+ * since has quietly been funded by the platform. That is the dead-field
+ * pattern (Rule: every declared field has both a writer and a reader) occurring
+ * inside the work that catalogues it. Wiring the combined figure at all four
+ * call sites is what closes it.
+ */
+export function ordersPointsBorneByStore(orders) {
+    return roundRupees(orders.reduce((sum, o) => sum + orderPointsFunded(o) + orderPointsRedeemed(o), 0));
+}
 /** Sum of `orderShippingReimbursement` across a batch. */
 export function ordersShippingReimbursement(orders) {
     return roundRupees(orders.reduce((sum, o) => sum + orderShippingReimbursement(o), 0));
 }
+/**
+ * How many points may be spent on ONE order group, and what is left to charge.
+ *
+ * ## 🛑 A PIPELINE STAGE, after the final rounding — never a post-order debit
+ *
+ * This is the whole lesson of D46. The deleted code redeemed points AFTER the
+ * orders existed and the gateway had captured `orderTotal`, so a successful
+ * redemption took points from a buyer who had just paid full price: nothing in
+ * the pipeline knew about the spend, so nothing reduced the charge.
+ *
+ * So the tender is a STAGE. `amountDue = orderTotal − pointsApplied` is
+ * computed here, and `amountDue` is what the gateway captures and what the
+ * post-capture guard compares. A sixth way for the captured amount to diverge
+ * from the recorded total is the D37/D38/D40 family; this is how it is avoided.
+ *
+ * ## 🛑 Applied AFTER rounding, deliberately
+ *
+ * `orderTotal` is rounded ONCE at the end of its own nine-term sum (D42).
+ * Folding points in before that rounding would put a discount inside the sum
+ * being rounded, so the figure shown to the buyer and the figure captured could
+ * differ by a paisa. They must be provably equal, which is why `amountDue` is
+ * derived here and never recomputed at the gateway.
+ *
+ * ## Per order group, because the ACCEPTING STORE absorbs it
+ *
+ * Decision 3: a redeemed point reduces THAT store's payout for THAT order. A
+ * cart spanning an accepting and a non-accepting store must not pool the
+ * discount — each group gets its own cap and its own figure. That is the same
+ * granularity `splitCartIntoOrderGroups` and `allocateCheckoutFees` already
+ * use, and its absence is what caused Root Cause #65's per-store
+ * multiplication bug.
+ *
+ * ## All-or-nothing, and the remainder STAYS
+ *
+ * Owner's rule: *"if use point it is all and then the balance is returned if
+ * excess"*. There is no requested amount — the balance is spent down as far as
+ * the cap allows, and whatever will not fit is simply not spent. It stays in
+ * the ledger for a later order; nothing is forfeited, and no caller can ask for
+ * a partial spend.
+ *
+ * 🛑 The 50% cap is not optional, and removing it was explicitly declined.
+ * `POINTS_MAX_REDEMPTION_PERCENT` exists because a ₹0 order breaks the gateway
+ * (a ₹0 Razorpay order is not a thing) and because a balance that can settle a
+ * whole purchase behaves like the stored value the points schema is written to
+ * avoid.
+ */
+export function resolvePointsTender(input) {
+    const total = roundRupees(Math.max(0, input.orderTotal));
+    if (!input.optedIn || !input.accepted)
+        return { pointsApplied: 0, amountDue: total };
+    const balance = Math.floor(Math.max(0, input.balance));
+    if (!Number.isFinite(balance) || balance <= 0)
+        return { pointsApplied: 0, amountDue: total };
+    /*
+     * `maxRedeemablePoints` owns the cap arithmetic — it floors to whole points
+     * and applies `POINTS_MAX_REDEMPTION_PERCENT`. Re-deriving the percentage
+     * here would be a second copy of a money rule (Root Cause #75), and the one
+     * place it already lives sits beside the constant that defines it.
+     */
+    const pointsApplied = maxRedeemablePoints(total, balance);
+    return { pointsApplied, amountDue: roundRupees(total - pointsApplied) };
+}
+/**
+ * Draw one balance down across a checkout's order groups, in group order.
+ *
+ * ## Why this exists rather than each caller looping
+ *
+ * The tender is applied PER GROUP (decision 3 — the accepting store absorbs
+ * its own redemption), so "how many points does this checkout use" is a
+ * sequential draw-down, not a single `min`. Four surfaces need the same answer
+ * and must not each write the loop:
+ *
+ * | surface | why it needs the total |
+ * |---|---|
+ * | `previewCheckoutPricing` | the figure shown to the buyer |
+ * | `POST /api/payment/create-order` | the figure CAPTURED |
+ * | the post-capture guard | the figure compared |
+ * | the two order paths | the per-group figure recorded |
+ *
+ * D37 is the record of what happens when one of those four is left out: the
+ * coupon discount reached three of them and not the capture route, so the
+ * buyer was shown one number, charged another, and the order recorded the
+ * first — invisible in our own data because the guard was one-sided.
+ *
+ * 🛑 The order paths deliberately do NOT call this. They apply
+ * `resolvePointsTender` to their own group as they create it, drawing down a
+ * shared remainder — which is the same function applied in the same order, so
+ * the sum is identical by construction. Making them call this instead would
+ * mean computing every group's final total before creating any of them, which
+ * is a restructure of two 200-line functions for an answer they already have.
+ *
+ * ## The cap is per group, and the ORDER of the groups therefore matters
+ *
+ * A balance smaller than the whole checkout's 50% allowance is consumed by the
+ * earliest groups. That is arbitrary but it must be *consistently* arbitrary:
+ * every caller iterates `orderGroups` in the order `splitCartIntoOrderGroups`
+ * produced, so all four agree. Sorting differently anywhere would make the
+ * shown and charged figures diverge on exactly the carts where the balance is
+ * tight.
+ */
+export function allocatePointsAcrossGroups(groups, balance, optedIn) {
+    const perGroup = groups.map(() => 0);
+    if (!optedIn)
+        return { perGroup, pointsApplied: 0 };
+    let remaining = Math.floor(Math.max(0, balance));
+    if (!Number.isFinite(remaining) || remaining <= 0)
+        return { perGroup, pointsApplied: 0 };
+    let applied = 0;
+    for (let i = 0; i < groups.length; i += 1) {
+        const g = groups[i];
+        const { pointsApplied } = resolvePointsTender({
+            orderTotal: g.total,
+            balance: g.accepted ? remaining : 0,
+            accepted: g.accepted,
+            optedIn: true,
+        });
+        perGroup[i] = pointsApplied;
+        remaining -= pointsApplied;
+        applied += pointsApplied;
+    }
+    return { perGroup, pointsApplied: applied };
+}
 /**
  * P-6 — pre-order groups charge each product's own `preOrderDepositPercent`
  * (falling back to the generic COD deposit % when a product doesn't have one

package/dist/_internal/shared/checkout/refundable-base.d.ts

@@ -36,6 +36,21 @@ export interface RefundableOrderLike {
         amount: number;
         status?: string;
     }>;
+    /**
+     * D46/D47 — points applied at checkout, in points (1 point = ₹1).
+     *
+     * 🛑 Subtracted from the refundable base, because **a refund can only return
+     * money that was collected.** On a ₹1,000 order settled with 250 points the
+     * card was charged ₹750; refunding the full base would hand the buyer ₹1,000
+     * and then `reverseRedemptionForOrder` would hand back 250 points on top —
+     * ₹250 of real money created out of a discount.
+     *
+     * The points themselves come back as POINTS, never as cash. That is not a
+     * stylistic choice: `pointsLedger`'s header states it as a legal boundary,
+     * because paying a balance out in rupees is what makes it stored value, which
+     * in India is PPI territory with RBI authorisation attached.
+     */
+    pointsApplied?: number;
 }
 /**
  * The platform fee actually withheld on a refund: the amount CHARGED, never a
@@ -77,6 +92,16 @@ legacyGstPercent?: number): number;
  * has to compare against THIS, or the largest possible refund is strictly less
  * than `totalPrice` and **an order can never reach `status: "refunded"`** —
  * which is what the old `amount >= totalPrice` test guaranteed.
+ *
+ * 🛑 And `pointsApplied` comes off too (D46/D47). A refund returns MONEY, and
+ * the money collected was `totalPrice − pointsApplied`; the points go back
+ * through `reverseRedemptionForOrder` as points. Leaving them in the base would
+ * refund them twice — once in rupees here and once in points there — which is
+ * the one way this feature could manufacture real money from a discount.
+ *
+ * Absent means zero, so every order written before the tender existed is
+ * unaffected, and `isFull` still reaches the exhausted state on them exactly as
+ * before.
  */
 export declare function refundableBase(order: RefundableOrderLike, legacyGstPercent?: number): number;
 /**

package/dist/_internal/shared/checkout/refundable-base.js

@@ -75,9 +75,21 @@ legacyGstPercent) {
  * has to compare against THIS, or the largest possible refund is strictly less
  * than `totalPrice` and **an order can never reach `status: "refunded"`** —
  * which is what the old `amount >= totalPrice` test guaranteed.
+ *
+ * 🛑 And `pointsApplied` comes off too (D46/D47). A refund returns MONEY, and
+ * the money collected was `totalPrice − pointsApplied`; the points go back
+ * through `reverseRedemptionForOrder` as points. Leaving them in the base would
+ * refund them twice — once in rupees here and once in points there — which is
+ * the one way this feature could manufacture real money from a discount.
+ *
+ * Absent means zero, so every order written before the tender existed is
+ * unaffected, and `isFull` still reaches the exhausted state on them exactly as
+ * before.
  */
 export function refundableBase(order, legacyGstPercent) {
-    return roundRupees(Math.max(0, order.totalPrice - platformFeeWithheld(order, legacyGstPercent)));
+    return roundRupees(Math.max(0, order.totalPrice -
+        platformFeeWithheld(order, legacyGstPercent) -
+        Math.max(0, order.pointsApplied ?? 0)));
 }
 /**
  * Sum of refunds that have COMMITTED money, i.e. everything not `failed`.

package/dist/_internal/shared/checkout/split.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Group-purchase contribution splits — the ONE owner of the invariant.
+ *
+ * A coordinator divides what a grouped line costs among its members. They may
+ * type absolute amounts or percentages, and the total may come out at or ABOVE
+ * the landed cost; the excess belongs to the seller.
+ *
+ * ## The invariant
+ *
+ * ```
+ * landedCost = goods + shipping + fees + add-ons        (per order group)
+ *
+ * contribution(member) = percent × landedCost   OR   a typed amount
+ * require:  Σ(contributions) ≥ landedCost
+ * surplus:  Σ(contributions) − landedCost
+ * ```
+ *
+ * Percentages summing above 100% and typed amounts summing above the landed
+ * cost are **the same case**, so one rule covers both and there is no
+ * mode-specific branch to get wrong.
+ *
+ * ## Why the surplus becomes `lockedPrice`
+ *
+ * `unitPriceFor` already honours `lockedPrice` ahead of everything else — that
+ * is how an accepted offer BELOW list is charged correctly. An agreed total
+ * ABOVE list is the same mechanism in the other direction, so GST is charged on
+ * what was actually paid, the payout base rises by the surplus,
+ * `refundableBase` ceilings at the agreed amount, and the invoice needs no new
+ * line. No new money term anywhere.
+ */
+/** A member's share, as the coordinator expressed it. */
+export interface SplitContribution {
+    productId: string;
+    /** `"percent"` reads `percent`; `"amount"` reads `amount`. */
+    splitMode: "amount" | "percent";
+    /** 0–100. Required when `splitMode === "percent"`. */
+    percent?: number;
+    /** Decimal rupees. Required when `splitMode === "amount"`. */
+    amount?: number;
+}
+export interface SplitResolution {
+    /** Per member, in input order, after rounding. */
+    resolved: Array<{
+        productId: string;
+        amount: number;
+    }>;
+    /** What the members together put in. */
+    contributed: number;
+    /** `contributed − landedCost`, never negative (see `shortfall`). */
+    surplus: number;
+    /** `landedCost − contributed` when the split is short, else 0. */
+    shortfall: number;
+    /** The invariant holds. A caller must refuse to commit when false. */
+    valid: boolean;
+}
+/**
+ * Resolve contributions against a landed cost.
+ *
+ * Pure. No I/O, no clock — the landed cost is computed by the caller from the
+ * order group it already has.
+ *
+ * 🛑 ROUNDS ONCE, at the end of each member's amount, and then puts the
+ * ROUNDING REMAINDER on the last member. Rounding each percentage
+ * independently and summing is how a 3-way 33.33% split charges a rupee less
+ * than the agreed total and the surplus silently goes negative — the same
+ * remainder discipline `allocateAcrossMembers` uses for bundle tax.
+ */
+export declare function resolveSplit(contributions: readonly SplitContribution[], landedCost: number): SplitResolution;
+/**
+ * The price to lock on the line, given the goods subtotal and a surplus.
+ *
+ * ## 🛑 THE TRAP THIS FUNCTION EXISTS TO PREVENT
+ *
+ * The percentage BASE is the landed cost — goods **plus shipping plus fees** —
+ * because that is what the coordinator is really dividing. But `lockedPrice` is
+ * the GOODS price of the line: the checkout adds shipping, the platform fee,
+ * GST and the add-ons on top of it, independently.
+ *
+ * So locking the landed cost would charge shipping and every fee **TWICE** —
+ * once inside `lockedPrice` and once again as the checkout's own terms. The
+ * surplus rides on the goods price alone.
+ *
+ * That is the whole reason this is a named function rather than an expression
+ * at a call site: `goods + surplus` and `landedCost + surplus` are both
+ * plausible-looking one-liners and only one of them is a correct charge.
+ */
+export declare function lockedPriceWithSurplus(goodsSubtotal: number, surplus: number): number;