@mohasinac/appkit 4.58.0 → 4.60.0

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

@@ -0,0 +1,103 @@
+/**
+ * How a buyer-applied coupon splits across the sellers in one cart.
+ *
+ * WHY THIS MOVED HERE (2026-10-21): the implementation was module-private
+ * inside `_internal/server/features/checkout/actions.ts`, where three order
+ * paths could reach it and the **gateway capture route could not**.
+ *
+ * 🛑 So `/api/payment/create-order` — the one place that decides what the
+ * buyer's card is actually charged — had NO COUPON TERM ANYWHERE IN THE FILE.
+ * Measured: zero occurrences of "coupon" or "discount", and
+ *
+ *     rawTotal = subtotalRs + platformFee + gstOnFee + addonFees + shippingFee
+ *
+ * while `createOrderForGroup` (COD/UPI), `previewCheckoutPricing` and
+ * `createRazorpayGroupOrder` all compute `max(0, total − couponDiscount) + …`.
+ *
+ * The consequence is a live overcharge on every coupon order paid by card: the
+ * preview shows ₹X−discount, the gateway captures ₹X, and the order records
+ * ₹X−discount. And it is invisible in our own data, because the post-capture
+ * amount guard is ONE-SIDED (`paid < expected − 1`), so an over-capture never
+ * trips it. Nothing in the system disagreed with itself; only the buyer's card
+ * statement did.
+ *
+ * `_internal/shared/` rather than `_internal/server/` because this is pure
+ * arithmetic with no Firestore reach, and because `_internal/shared` is the
+ * only one of the three a consumer route can be served from. It is the first
+ * increment of the single-pipeline extraction.
+ */
+import { roundRupees } from "../../../utils/number.formatter.js";
+/**
+ * Prorates every buyer-applied coupon against one seller-group's total.
+ *
+ * Pure — no side effects. Usage-accumulator bookkeeping is layered on by the
+ * callers that actually place an order, which is what lets the preview and the
+ * capture route call this without recording a redemption.
+ *
+ * A seller-scoped coupon applies only to its own store's group; an admin
+ * coupon prorates across every group by `groupTotal / cartSubtotal`. Clamped
+ * to the group total at the end, so a coupon can never make a group negative.
+ */
+export function computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, storeId) {
+    let couponDiscount = 0;
+    const appliedDiscounts = [];
+    for (const coupon of appliedCoupons) {
+        let couponGroupDiscount = 0;
+        const isSellerScoped = coupon.scope === "seller" && coupon.storeId;
+        if (isSellerScoped) {
+            if (coupon.storeId !== storeId)
+                continue;
+            if (coupon.applicableItemIds?.length) {
+                const eligibleTotal = groupLines
+                    .filter((l) => coupon.applicableItemIds.includes(l.itemId))
+                    .reduce((s, l) => s + l.lineTotal, 0);
+                couponGroupDiscount =
+                    eligibleTotal > 0
+                        ? Math.min(roundRupees((eligibleTotal / groupTotal) * coupon.discountAmount), eligibleTotal)
+                        : 0;
+            }
+            else {
+                couponGroupDiscount = Math.min(coupon.discountAmount, groupTotal);
+            }
+        }
+        else if (cartSubtotal > 0) {
+            couponGroupDiscount = Math.min(roundRupees((groupTotal / cartSubtotal) * coupon.discountAmount), groupTotal);
+        }
+        if (couponGroupDiscount > 0) {
+            couponDiscount += couponGroupDiscount;
+            appliedDiscounts.push({
+                code: coupon.code,
+                couponId: coupon.couponId,
+                type: "coupon",
+                discountAmount: couponGroupDiscount,
+                scope: coupon.scope,
+                storeId: coupon.storeId,
+            });
+        }
+    }
+    couponDiscount = Math.min(couponDiscount, groupTotal);
+    return { couponDiscount, appliedDiscounts };
+}
+/**
+ * The whole cart's discount, summed over its seller-groups.
+ *
+ * 🛑 This exists so a caller holding only a cart-wide subtotal cannot be
+ * tempted to apply a coupon to it directly. Doing so is wrong in two ways that
+ * cancel out on a single-seller cart and diverge on a multi-seller one: a
+ * seller-scoped coupon would be applied to other sellers' items, and the
+ * per-group clamp (`min(discount, groupTotal)`) would not bind. The capture
+ * route holds exactly that shape, which is how it ended up with no discount at
+ * all rather than a wrong one.
+ */
+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 = [];
+    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);
+    }
+    return { couponDiscount: roundRupees(couponDiscount), appliedDiscounts };
+}

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