@mohasinac/appkit 4.59.0 → 4.60.0

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

@@ -98,6 +98,48 @@ export declare function isLaneCheckoutable(items: readonly LaneAssignable[], lan
  * selection" means "the lane on screen" and can mean nothing else.
  */
 export declare function defaultCheckoutItems<T extends LaneAssignable>(items: readonly T[]): T[];
+/**
+ * THE item set a checkout charges for and settles. One definition, both paths.
+ *
+ * ## 🛑 D40: the captured item set was not the settled item set, in TWO ways
+ *
+ * Measured, because the plan recorded only the first half:
+ *
+ * | | capture (`/api/payment/create-order`) | settle (gateway path) |
+ * |---|---|---|
+ * | with a selection | the selected items, **any lane** | **the active lane**, selection IGNORED |
+ * | with no selection | **the whole cart, every lane** | the active lane only |
+ *
+ * The first row is the one the plan describes: deselect half the cart, pay for
+ * half, receive orders for the whole lane — the buyer gets goods they did not
+ * pay for and the seller's stock leaves without payment.
+ *
+ * 🛑 **The second row is worse and was not recorded anywhere: the buyer is
+ * OVERCHARGED.** With no explicit selection the capture route billed
+ * `cart.items` — every lane — while settle created orders for the active lane
+ * only. And multi-lane carts are not an edge case: `defaultCheckoutItems`' own
+ * docstring above says they "are what the lane model produces", because
+ * `auctionSettlement` pushes a won auction into whatever is already in the
+ * cart. So a buyer with a won auction and ordinary items in the cart was
+ * charged for both and received orders for one.
+ *
+ * ## The rule
+ *
+ * **Active lane first, then the selection as a filter within it.** Not the
+ * other way round, and not selection-instead-of-lane:
+ *
+ * - The lane invariant is non-negotiable — `assertCheckoutLane` refuses any
+ *   settle whose items are not the active lane, so a selection spanning lanes
+ *   could be charged and then never settled. That is the D64 class (money
+ *   taken, no order).
+ * - An empty intersection is a REFUSAL, not a silent widening. A selection
+ *   naming only off-lane items means the buyer is looking at something the
+ *   server will not sell them, and falling back to the whole lane would charge
+ *   them for items they deliberately unticked.
+ */
+export declare function resolveCheckoutItems<T extends LaneAssignable & {
+    itemId: string;
+}>(items: readonly T[], selectedItemIds?: readonly string[] | null): T[];
 /**
  * Why `lane` can't be checked out right now — null when it can.
  * Phrased for the buyer, naming the lane that's blocking and what to do.

package/dist/_internal/shared/checkout/lanes.js

@@ -156,6 +156,52 @@ export function defaultCheckoutItems(items) {
     const active = activeLane(items);
     return active ? laneItems(items, active) : [...items];
 }
+/**
+ * THE item set a checkout charges for and settles. One definition, both paths.
+ *
+ * ## 🛑 D40: the captured item set was not the settled item set, in TWO ways
+ *
+ * Measured, because the plan recorded only the first half:
+ *
+ * | | capture (`/api/payment/create-order`) | settle (gateway path) |
+ * |---|---|---|
+ * | with a selection | the selected items, **any lane** | **the active lane**, selection IGNORED |
+ * | with no selection | **the whole cart, every lane** | the active lane only |
+ *
+ * The first row is the one the plan describes: deselect half the cart, pay for
+ * half, receive orders for the whole lane — the buyer gets goods they did not
+ * pay for and the seller's stock leaves without payment.
+ *
+ * 🛑 **The second row is worse and was not recorded anywhere: the buyer is
+ * OVERCHARGED.** With no explicit selection the capture route billed
+ * `cart.items` — every lane — while settle created orders for the active lane
+ * only. And multi-lane carts are not an edge case: `defaultCheckoutItems`' own
+ * docstring above says they "are what the lane model produces", because
+ * `auctionSettlement` pushes a won auction into whatever is already in the
+ * cart. So a buyer with a won auction and ordinary items in the cart was
+ * charged for both and received orders for one.
+ *
+ * ## The rule
+ *
+ * **Active lane first, then the selection as a filter within it.** Not the
+ * other way round, and not selection-instead-of-lane:
+ *
+ * - The lane invariant is non-negotiable — `assertCheckoutLane` refuses any
+ *   settle whose items are not the active lane, so a selection spanning lanes
+ *   could be charged and then never settled. That is the D64 class (money
+ *   taken, no order).
+ * - An empty intersection is a REFUSAL, not a silent widening. A selection
+ *   naming only off-lane items means the buyer is looking at something the
+ *   server will not sell them, and falling back to the whole lane would charge
+ *   them for items they deliberately unticked.
+ */
+export function resolveCheckoutItems(items, selectedItemIds) {
+    const inLane = defaultCheckoutItems(items);
+    if (!selectedItemIds?.length)
+        return inLane;
+    const selected = new Set(selectedItemIds);
+    return inLane.filter((item) => selected.has(item.itemId));
+}
 /**
  * Why `lane` can't be checked out right now — null when it can.
  * Phrased for the buyer, naming the lane that's blocking and what to do.

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

@@ -111,7 +111,64 @@ export declare function lineTaxComponentsFor(item: CartItemDocument, productById
  * one and not the other — here that would mean quoting one tax figure and
  * charging another.
  */
-export declare function sumGroupGst(items: readonly CartItemDocument[], productById: Map<string, ProductDocument | null>, intraState: boolean): GroupGstSummary;
+export declare function sumGroupGst(items: readonly CartItemDocument[], productById: Map<string, ProductDocument | null>, intraState: boolean, 
+/**
+ * G1 — the group's coupon discount, in decimal rupees. **Reduces the taxable
+ * value**, prorated across the group's tax slices.
+ *
+ * 🛑 WHY THIS PARAMETER EXISTS. Without it the tax was backed out of the
+ * UNDISCOUNTED gross, so on a ₹1,000 item @18% with a ₹200 coupon the order
+ * recorded taxable ₹847.46 + GST ₹152.54 = ₹1,000 while the buyer paid ₹800
+ * for the goods. **₹30.51 of tax recorded on money that was never
+ * collected** — remitted by us, on every discounted order.
+ *
+ * A discount shown on the invoice generally reduces the value of supply
+ * under s.15(3)(a) CGST Act, so the post-discount base is both the honest
+ * figure and the lower liability. 🛑 This changes what we remit and is a CA
+ * question, not a code preference; it is implemented because it was decided,
+ * and it is flagged in the plan's standing-risk section for review.
+ *
+ * Optional, defaulting to 0, so the behaviour is unchanged for any caller
+ * that does not pass it — a REQUIRED parameter would have been better at
+ * forcing every call site to answer, but three of the four callers compute
+ * the discount after the tax today and the reorder is riskier than the
+ * default. `audit-checkout-total-parity` is what will catch an omission.
+ */
+couponDiscount?: number, 
+/**
+ * G5 — the group's TAXABLE ancillary charges, in decimal rupees: shipping,
+ * COD handling, gift wrap, shipment protection, sale protection.
+ *
+ * 🛑 These used to enter the order total as BARE ADDENDS carrying no tax at
+ * all. Delivery and handling are generally part of a composite supply and
+ * taxable at the rate of the principal supply, so a ₹100 shipping line on an
+ * 18% order was collected with ~₹15.25 of embedded tax that we declared
+ * nowhere.
+ *
+ * ── THE MECHANISM DIVERGES FROM THE PLAN, DELIBERATELY ──────────────────
+ *
+ * The plan recorded G5 as "raises buyer totals slightly", i.e. tax ADDED on
+ * top of each fee. That is the right reading for a tax-exclusive system and
+ * this one is not: `calculateGstInclusive`'s own header states "**Every
+ * price in this system is tax-inclusive**", and the product JSON-LD
+ * publicly asserts `valueAddedTaxIncluded: true`.
+ *
+ * So the fees are treated INCLUSIVE, exactly like goods:
+ *
+ *   · the buyer pays the configured ₹100 — **no total changes, no silent
+ *     re-pricing of every order**
+ *   · ₹15.25 of it is recognised as GST and remitted
+ *   · `taxableAmount` and `gstAmount` rise; the amount collected does not
+ *
+ * Adding tax on top instead would mix two conventions inside one total —
+ * which is the shape of the five-disagreeing-totals problem this phase
+ * exists to remove — and would make the published JSON-LD false. Flagged
+ * rather than silently chosen; it is still part of the CA conversation.
+ *
+ * Taxed at the PRINCIPAL rate, derived from the group's own goods (see
+ * below), because an ancillary charge follows the supply it is ancillary to.
+ */
+taxableFees?: number): GroupGstSummary;
 /** One rate's rollup within an order group — what Rule 46 asks an invoice to show. */
 export interface GstRateSlice {
     gstRate: number;
@@ -235,6 +292,97 @@ export declare function ordersGoodsValue(orders: readonly PayableOrderLike[]): n
 export declare function orderTaxableValue(order: PayableOrderLike): number;
 /** Sum of `orderTaxableValue` across orders — the payout base for a batch. */
 export declare function ordersTaxableValue(orders: readonly PayableOrderLike[]): number;
+/** The subset `orderShippingReimbursement` reads. */
+export interface ReimbursableOrderLike {
+    platformBookedShipment?: boolean;
+    shippingReimbursement?: {
+        approvedAmount?: number;
+    };
+    shippingReconciliation?: {
+        reimbursable?: number;
+    };
+}
+/**
+ * Postage the seller is owed back on one order — **D45, and it is NOT revenue.**
+ *
+ * ## Why this is a separate term from the taxable value
+ *
+ * `orderTaxableValue` above is deliberately goods-only, and that stays true:
+ * shipping is not a sale and must never be grossed into the figure GST is
+ * backed out of. A reimbursement is a **cost being refunded**, so it is added
+ * AFTER the taxable value rather than folded into it — which also means it
+ * carries no commission, because commissioning a seller's postage would be
+ * charging them for the privilege of posting a parcel.
+ *
+ * ## 🛑 It reads `approvedAmount`, and absence means NOT YET DECIDED
+ *
+ * The self-shipped branch pays what an admin approved, never what the seller
+ * declared: *"the only approved amount will be given to them."* An absent
+ * `approvedAmount` therefore returns 0 — and that is "nothing is payable yet",
+ * not "nothing is owed". The distinction matters because a payout batch built
+ * before approval must not silently settle the order at zero postage and leave
+ * the seller with no later claim; the quiet-period invariant is what holds the
+ * order back until the reimbursement is decided.
+ *
+ * ## 🛑 Shiprocket-booked parcels get NOTHING, gated on the booking
+ *
+ * We paid that courier. The gate is `platformBookedShipment`, a fact about how
+ * the shipment was created — never "does a receipt exist", which a seller
+ * supplies and could therefore supply for a parcel they did not pay for.
+ *
+ * ## The quoted branch pays `reimbursable` from the reconciliation
+ *
+ * On an order that went through the courier picker, `reconcileOrderShipping`
+ * has already computed `min(spent, charged)` at dispatch and stored it. No
+ * approval step there: the seller declared a spend against a quote the buyer
+ * chose, which is its own evidence, and the cap does the rest.
+ *
+ * Either way **the platform nets exactly zero on shipping** — the seller is
+ * made whole up to what the buyer paid, and any saving goes to the buyer as
+ * points.
+ */
+export declare function orderShippingReimbursement(order: ReimbursableOrderLike): number;
+/**
+ * Points this order issued, which the STORE funds.
+ *
+ * ## 🛑 A DEDUCTION, and never a clawback
+ *
+ * Owner, 2026-10-21: *"so stores bear it"*, framed as *"like a sale discount
+ * for getting a repeat customer — you get to pay few loss."* So the earn is a
+ * discount expense the seller absorbs, and it comes off their payout.
+ *
+ * That works as a simple deduction — with no ledger, no clawback and no
+ * negative balance — only because of an ordering guarantee worth stating
+ * explicitly, since I had it backwards in the plan for a while:
+ *
+ * ```
+ * delivered → completion (points issued) → order-complete closes
+ *           → payout-release unblocks → payout computed → payout settled
+ * ```
+ *
+ * `payout-release` is `blockedBy: ["order-complete", …]`, so the payout gate
+ * opens BECAUSE the order completed — and completion is the same event that
+ * issues the points. The award is therefore **always strictly before** the
+ * payout is computed, by construction rather than by timing luck. I had
+ * recorded this as "the buyer's fast path RELEASES the payout early, so the
+ * absorption may happen after the money has left", which would have required
+ * a `sellerLedger` debit against a future payout. The fast path *unblocks*;
+ * it does not release. One planned mechanism deleted rather than built.
+ *
+ * Reads `pointsAwarded` off the order rather than recomputing a percentage:
+ * the figure must be what was actually credited, and the goods value may have
+ * changed since (a partial cancellation) — recomputing would deduct an amount
+ * the buyer never received.
+ */
+export declare function orderPointsFunded(order: {
+    pointsAwarded?: number;
+}): number;
+/** Sum of `orderPointsFunded` across a batch. */
+export declare function ordersPointsFunded(orders: readonly {
+    pointsAwarded?: number;
+}[]): number;
+/** Sum of `orderShippingReimbursement` across a batch. */
+export declare function ordersShippingReimbursement(orders: readonly ReimbursableOrderLike[]): 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

@@ -146,7 +146,64 @@ productById) {
 export function sumGroupGst(items, 
 /* `| null` to match `lineTaxComponentsFor` and `lineTotalFor` — see the note
  * there. The consumer's create-order route holds an honestly-nullable map. */
-productById, intraState) {
+productById, intraState, 
+/**
+ * G1 — the group's coupon discount, in decimal rupees. **Reduces the taxable
+ * value**, prorated across the group's tax slices.
+ *
+ * 🛑 WHY THIS PARAMETER EXISTS. Without it the tax was backed out of the
+ * UNDISCOUNTED gross, so on a ₹1,000 item @18% with a ₹200 coupon the order
+ * recorded taxable ₹847.46 + GST ₹152.54 = ₹1,000 while the buyer paid ₹800
+ * for the goods. **₹30.51 of tax recorded on money that was never
+ * collected** — remitted by us, on every discounted order.
+ *
+ * A discount shown on the invoice generally reduces the value of supply
+ * under s.15(3)(a) CGST Act, so the post-discount base is both the honest
+ * figure and the lower liability. 🛑 This changes what we remit and is a CA
+ * question, not a code preference; it is implemented because it was decided,
+ * and it is flagged in the plan's standing-risk section for review.
+ *
+ * Optional, defaulting to 0, so the behaviour is unchanged for any caller
+ * that does not pass it — a REQUIRED parameter would have been better at
+ * forcing every call site to answer, but three of the four callers compute
+ * the discount after the tax today and the reorder is riskier than the
+ * default. `audit-checkout-total-parity` is what will catch an omission.
+ */
+couponDiscount = 0, 
+/**
+ * G5 — the group's TAXABLE ancillary charges, in decimal rupees: shipping,
+ * COD handling, gift wrap, shipment protection, sale protection.
+ *
+ * 🛑 These used to enter the order total as BARE ADDENDS carrying no tax at
+ * all. Delivery and handling are generally part of a composite supply and
+ * taxable at the rate of the principal supply, so a ₹100 shipping line on an
+ * 18% order was collected with ~₹15.25 of embedded tax that we declared
+ * nowhere.
+ *
+ * ── THE MECHANISM DIVERGES FROM THE PLAN, DELIBERATELY ──────────────────
+ *
+ * The plan recorded G5 as "raises buyer totals slightly", i.e. tax ADDED on
+ * top of each fee. That is the right reading for a tax-exclusive system and
+ * this one is not: `calculateGstInclusive`'s own header states "**Every
+ * price in this system is tax-inclusive**", and the product JSON-LD
+ * publicly asserts `valueAddedTaxIncluded: true`.
+ *
+ * So the fees are treated INCLUSIVE, exactly like goods:
+ *
+ *   · the buyer pays the configured ₹100 — **no total changes, no silent
+ *     re-pricing of every order**
+ *   · ₹15.25 of it is recognised as GST and remitted
+ *   · `taxableAmount` and `gstAmount` rise; the amount collected does not
+ *
+ * Adding tax on top instead would mix two conventions inside one total —
+ * which is the shape of the five-disagreeing-totals problem this phase
+ * exists to remove — and would make the published JSON-LD false. Flagged
+ * rather than silently chosen; it is still part of the CA conversation.
+ *
+ * Taxed at the PRINCIPAL rate, derived from the group's own goods (see
+ * below), because an ancillary charge follows the supply it is ancillary to.
+ */
+taxableFees = 0) {
     let taxableAmount = 0;
     let exemptAmount = 0;
     let cgst = 0;
@@ -154,8 +211,35 @@ productById, intraState) {
     let igst = 0;
     let gstAmount = 0;
     const byRate = new Map();
-    for (const item of items) {
-        for (const slice of lineTaxComponentsFor(item, productById)) {
+    /*
+     * ── G1: apply the discount to the slice GROSSES before backing tax out ───
+     *
+     * Collected up front rather than taxed inline, because a discount is a
+     * property of the GROUP and has to be spread across its slices before any
+     * one of them can be taxed. Three properties matter:
+     *
+     *   1. **Prorated by gross share**, including exempt slices. A coupon on a
+     *      mixed 0%/18% group reduces both proportionally; excluding the exempt
+     *      slice would concentrate the whole discount on the taxed one and
+     *      under-report the tax.
+     *   2. **`allocateAcrossMembers` for the split**, not per-slice
+     *      multiplication. It pushes the rounding remainder onto the last slice
+     *      so the parts sum to EXACTLY the discounted gross — which is the
+     *      invariant that keeps the invoice reconciling against the amount
+     *      charged. Independent `× (1 − d/total)` roundings do not.
+     *   3. **Clamped at zero.** A discount exceeding the group total (possible
+     *      on a free-item promotion) must not produce negative taxable values.
+     */
+    const rawSlices = items.flatMap((item) => lineTaxComponentsFor(item, productById));
+    const grossTotal = rawSlices.reduce((s, sl) => s + sl.taxable, 0);
+    const discount = Math.min(Math.max(0, couponDiscount), grossTotal);
+    const discountedGross = grossTotal - discount;
+    const sliceGross = discount > 0 && grossTotal > 0
+        ? allocateAcrossMembers(discountedGross, rawSlices.map((sl) => sl.taxable))
+        : rawSlices.map((sl) => sl.taxable);
+    for (const [i, raw] of rawSlices.entries()) {
+        const slice = { ...raw, taxable: sliceGross[i] ?? raw.taxable };
+        {
             /*
              * 🛑 A 0%-rated slice is EXEMPT, not absent. It was `continue`d
              * entirely, so `order.taxableAmount` excluded exempt goods while
@@ -222,6 +306,62 @@ productById, intraState) {
             }
         }
     }
+    /*
+     * ── G5: the ancillary charges, taxed at the PRINCIPAL rate ──────────────
+     *
+     * A composite supply is taxed at the rate of its principal supply, and the
+     * principal supply here is the goods — shipping, handling, gift wrap and the
+     * protections exist only because the goods are being supplied.
+     *
+     * 🛑 "Principal rate" is the rate of the HIGHEST-VALUE taxable component,
+     * not the highest rate and not an average. On a mixed 5% + 18% group the
+     * principal supply is whichever dominates by value, so a cart of mostly-5%
+     * goods carries its shipping at 5%. Taking the highest RATE would
+     * over-collect on exactly the carts where the 18% item is a minor add-on;
+     * averaging would invent a rate that exists in no schedule and cannot appear
+     * on a Rule 46 invoice.
+     *
+     * 🛑 A group whose goods are entirely EXEMPT (0%) taxes its fees at 0% too —
+     * `principalRate` stays null, so the fee lands in `exemptAmount`. Ancillary
+     * to an exempt supply is exempt; defaulting to 18% there would tax delivery
+     * on a zero-rated order.
+     */
+    if (taxableFees > 0) {
+        let principalRate = null;
+        let principalValue = 0;
+        for (const slice of byRate.values()) {
+            if (slice.taxableAmount > principalValue) {
+                principalValue = slice.taxableAmount;
+                principalRate = slice.gstRate;
+            }
+        }
+        if (principalRate === null) {
+            // No taxed goods in this group — the fee follows them and is exempt.
+            exemptAmount += taxableFees;
+        }
+        else {
+            // INCLUSIVE, like every other price in this system: the configured fee
+            // is what the buyer pays and the tax is backed out of it.
+            const f = calculateGstInclusive(principalRate, intraState, taxableFees);
+            taxableAmount += f.taxableAmount;
+            cgst += f.cgst;
+            sgst += f.sgst;
+            igst += f.igst;
+            gstAmount += f.gstAmount;
+            // Folded into the principal rate's existing bucket rather than given its
+            // own: on the invoice these are part of one taxable supply at one rate,
+            // and a separate line at the same rate would not reconcile against the
+            // Rule 46 per-rate summary.
+            const prev = byRate.get(principalRate);
+            if (prev) {
+                prev.taxableAmount = roundRupees(prev.taxableAmount + f.taxableAmount);
+                prev.cgst = roundRupees(prev.cgst + f.cgst);
+                prev.sgst = roundRupees(prev.sgst + f.sgst);
+                prev.igst = roundRupees(prev.igst + f.igst);
+                prev.gstAmount = roundRupees(prev.gstAmount + f.gstAmount);
+            }
+        }
+    }
     return {
         taxableAmount: roundRupees(taxableAmount),
         exemptAmount: roundRupees(exemptAmount),
@@ -353,6 +493,114 @@ export function orderTaxableValue(order) {
 export function ordersTaxableValue(orders) {
     return roundRupees(orders.reduce((sum, o) => sum + orderTaxableValue(o), 0));
 }
+/**
+ * Postage the seller is owed back on one order — **D45, and it is NOT revenue.**
+ *
+ * ## Why this is a separate term from the taxable value
+ *
+ * `orderTaxableValue` above is deliberately goods-only, and that stays true:
+ * shipping is not a sale and must never be grossed into the figure GST is
+ * backed out of. A reimbursement is a **cost being refunded**, so it is added
+ * AFTER the taxable value rather than folded into it — which also means it
+ * carries no commission, because commissioning a seller's postage would be
+ * charging them for the privilege of posting a parcel.
+ *
+ * ## 🛑 It reads `approvedAmount`, and absence means NOT YET DECIDED
+ *
+ * The self-shipped branch pays what an admin approved, never what the seller
+ * declared: *"the only approved amount will be given to them."* An absent
+ * `approvedAmount` therefore returns 0 — and that is "nothing is payable yet",
+ * not "nothing is owed". The distinction matters because a payout batch built
+ * before approval must not silently settle the order at zero postage and leave
+ * the seller with no later claim; the quiet-period invariant is what holds the
+ * order back until the reimbursement is decided.
+ *
+ * ## 🛑 Shiprocket-booked parcels get NOTHING, gated on the booking
+ *
+ * We paid that courier. The gate is `platformBookedShipment`, a fact about how
+ * the shipment was created — never "does a receipt exist", which a seller
+ * supplies and could therefore supply for a parcel they did not pay for.
+ *
+ * ## The quoted branch pays `reimbursable` from the reconciliation
+ *
+ * On an order that went through the courier picker, `reconcileOrderShipping`
+ * has already computed `min(spent, charged)` at dispatch and stored it. No
+ * approval step there: the seller declared a spend against a quote the buyer
+ * chose, which is its own evidence, and the cap does the rest.
+ *
+ * Either way **the platform nets exactly zero on shipping** — the seller is
+ * made whole up to what the buyer paid, and any saving goes to the buyer as
+ * points.
+ */
+export function orderShippingReimbursement(order) {
+    if (order.platformBookedShipment === true)
+        return 0;
+    /*
+     * The self-shipped branch first: an approved amount is an explicit human
+     * decision and outranks the dispatch-time computation, which on this branch
+     * would not exist anyway.
+     */
+    const approved = order.shippingReimbursement?.approvedAmount;
+    if (typeof approved === "number" && Number.isFinite(approved)) {
+        return roundRupees(Math.max(0, approved));
+    }
+    const reimbursable = order.shippingReconciliation?.reimbursable;
+    if (typeof reimbursable === "number" && Number.isFinite(reimbursable)) {
+        return roundRupees(Math.max(0, reimbursable));
+    }
+    /*
+     * No reconciliation and no approval. Zero, and deliberately silent: an order
+     * dispatched before this feature existed has neither field, and warning on
+     * every one of those would make the log useless for the cases that matter.
+     */
+    return 0;
+}
+/**
+ * Points this order issued, which the STORE funds.
+ *
+ * ## 🛑 A DEDUCTION, and never a clawback
+ *
+ * Owner, 2026-10-21: *"so stores bear it"*, framed as *"like a sale discount
+ * for getting a repeat customer — you get to pay few loss."* So the earn is a
+ * discount expense the seller absorbs, and it comes off their payout.
+ *
+ * That works as a simple deduction — with no ledger, no clawback and no
+ * negative balance — only because of an ordering guarantee worth stating
+ * explicitly, since I had it backwards in the plan for a while:
+ *
+ * ```
+ * delivered → completion (points issued) → order-complete closes
+ *           → payout-release unblocks → payout computed → payout settled
+ * ```
+ *
+ * `payout-release` is `blockedBy: ["order-complete", …]`, so the payout gate
+ * opens BECAUSE the order completed — and completion is the same event that
+ * issues the points. The award is therefore **always strictly before** the
+ * payout is computed, by construction rather than by timing luck. I had
+ * recorded this as "the buyer's fast path RELEASES the payout early, so the
+ * absorption may happen after the money has left", which would have required
+ * a `sellerLedger` debit against a future payout. The fast path *unblocks*;
+ * it does not release. One planned mechanism deleted rather than built.
+ *
+ * Reads `pointsAwarded` off the order rather than recomputing a percentage:
+ * the figure must be what was actually credited, and the goods value may have
+ * changed since (a partial cancellation) — recomputing would deduct an amount
+ * the buyer never received.
+ */
+export function orderPointsFunded(order) {
+    const awarded = order.pointsAwarded;
+    return typeof awarded === "number" && Number.isFinite(awarded)
+        ? roundRupees(Math.max(0, awarded))
+        : 0;
+}
+/** Sum of `orderPointsFunded` across a batch. */
+export function ordersPointsFunded(orders) {
+    return roundRupees(orders.reduce((sum, o) => sum + orderPointsFunded(o), 0));
+}
+/** Sum of `orderShippingReimbursement` across a batch. */
+export function ordersShippingReimbursement(orders) {
+    return roundRupees(orders.reduce((sum, o) => sum + orderShippingReimbursement(o), 0));
+}
 /**
  * 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

@@ -0,0 +1,116 @@
+/**
+ * How much of an order can still be refunded, and what is withheld.
+ *
+ * ONE owner for two numbers that were previously computed four different ways
+ * and disagreed with each other and with the money actually moved.
+ *
+ * WHY:
+ *
+ * · **D1** — the over-refund guard compared `amount > order.totalPrice`, i.e.
+ *   against the ORDER TOTAL rather than the remaining balance, while its own
+ *   docstring promised "≤ remaining refundable amount". So ₹500 and then
+ *   another ₹500 both passed on a ₹600 order: **₹1,000 refunded, two real
+ *   gateway calls, both successful.**
+ *
+ * · **D3** — `isFull` was `amount >= order.totalPrice`, so a split refund
+ *   (₹300 + ₹200 of ₹500) never reached `status: "refunded"` and the order
+ *   stayed fully refundable forever.
+ *
+ * · **D32** — the platform fee is non-refundable by policy, and the only code
+ *   implementing that withheld ~10x too much (see `platformFeeWithheld`).
+ */
+/**
+ * Half a paisa. The tolerance exists because these are IEEE-754 sums of 2dp
+ * components: `0.1 + 0.2 > 0.3` is TRUE in floating point, so an exact
+ * comparison would reject a legitimate final refund that exactly exhausts the
+ * balance. Half a paisa is below the smallest representable money unit, so it
+ * cannot admit a real over-refund.
+ */
+export declare const MONEY_EPSILON = 0.005;
+/** The subset of an order this module needs. Keeps it testable and pure. */
+export interface RefundableOrderLike {
+    totalPrice: number;
+    platformFee?: number;
+    platformFeeGst?: number;
+    refunds?: ReadonlyArray<{
+        amount: number;
+        status?: string;
+    }>;
+}
+/**
+ * The platform fee actually withheld on a refund: the amount CHARGED, never a
+ * recomputed percentage.
+ *
+ * 🛑 This replaces the single worst money defect found in the audit (D32).
+ * `previewCancellationRefund` did:
+ *
+ *     const effectiveRate = platformFeePercent * (1 + gstPercent / 100);
+ *     const feeDeducted   = (grossRefund * effectiveRate) / 100;
+ *
+ * — a PERCENTAGE OF THE REFUND, which ignores `commissions.platformFeeMax`
+ * (default **₹10**) entirely and ignores `order.platformFee`, the amount that
+ * was actually collected and is stored on the order. On a ₹5,000 order at 2% +
+ * 18% GST it deducted **₹118** from a buyer who had paid **₹11.80** — keeping
+ * roughly ₹106 of their goods money and labelling it a platform fee. The
+ * overcharge grows with order value, so it is largest exactly where it is most
+ * noticeable.
+ *
+ * `platformFeeGst` is read from the order and only DERIVED for rows written
+ * before that field existed (2026-10-21). The derivation takes `gstPercent`
+ * from the caller rather than reading settings itself, so this stays pure and
+ * so a caller cannot accidentally reach for today's rate when the order is
+ * from last year — which is the mistake the whole function exists to undo.
+ */
+export declare function platformFeeWithheld(order: Pick<RefundableOrderLike, "platformFee" | "platformFeeGst">, 
+/** Only consulted for legacy orders with no stored `platformFeeGst`. */
+legacyGstPercent?: number): number;
+/**
+ * The ceiling every refund is measured against.
+ *
+ * 🛑 `totalPrice − platformFeeWithheld`, NOT `totalPrice`. The platform fee is
+ * non-refundable in every scenario — a decided policy, and one the product
+ * already states: `REFUND_COPY.request.acknowledgments[2]` tells the buyer
+ * "platform fees may be non-recoverable".
+ *
+ * This correction matters twice over. Phase 1's cumulative cap has to compare
+ * against THIS, or a refund can exceed what the buyer is owed; and `isFull`
+ * 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.
+ */
+export declare function refundableBase(order: RefundableOrderLike, legacyGstPercent?: number): number;
+/**
+ * Sum of refunds that have COMMITTED money, i.e. everything not `failed`.
+ *
+ * 🛑 A `reserved` entry counts. The two-phase write reserves before calling the
+ * provider and settles after, so between those two points the money may well
+ * have left — excluding reserved entries would let a concurrent request refund
+ * against a balance that is already spoken for, which is the TOCTOU the
+ * reservation exists to close. A `failed` entry releases its reservation by
+ * being skipped here, which is why no explicit release step is needed.
+ *
+ * `status` is optional on `OrderRefundEvent`: rows written before the
+ * two-phase scheme have none, and those are all committed refunds, so a
+ * missing status must count.
+ */
+export declare function committedRefundTotal(order: RefundableOrderLike): number;
+export interface RefundCapacity {
+    /** `totalPrice` less the non-refundable platform fee. */
+    base: number;
+    /** Already committed (processed or reserved). */
+    committed: number;
+    /** `base − committed`, floored at zero. */
+    remaining: number;
+    /** The non-refundable amount, for disclosure to the buyer. */
+    withheld: number;
+}
+/** Everything a caller needs to decide and to EXPLAIN a refund decision. */
+export declare function refundCapacity(order: RefundableOrderLike, legacyGstPercent?: number): RefundCapacity;
+/**
+ * Would this refund exhaust the refundable base?
+ *
+ * Measured against `base`, not `totalPrice` — see `refundableBase`. The
+ * epsilon makes an exactly-exhausting refund count as full rather than
+ * leaving a sub-paisa residue that keeps the order refundable forever.
+ */
+export declare function wouldBeFullRefund(order: RefundableOrderLike, amount: number, legacyGstPercent?: number): boolean;