@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/_internal/shared/actions/action-registry.js

@@ -64,6 +64,73 @@ export function actionLabel(def) {
 // just establishes the shape + a few "obvious" actions that other Phase 5
 // flows can reference today.
 export const ACTIONS = {
+    /*
+     * D56 — self-serve ad bookings.
+     *
+     * 🛑 `book-ad-slot` carries a confirmation because it is a PURCHASE of a
+     * named month, and cancelling it does not free that month for re-sale —
+     * the booking document IS the availability lock and keeping it is
+     * deliberate. A control that spends money and cannot be undone by the
+     * person who clicked it is exactly what Rule #7's confirmation is for.
+     */
+    ADS: {
+        "book-ad-slot": {
+            iconKey: "create",
+            id: "ads.book-ad-slot",
+            label: "Book this slot",
+            ariaLabel: "Book this ad slot for the selected month",
+            description: "Reserves one placement for one month at the listed flat fee. The creative is reviewed by a person before it appears anywhere.",
+            kind: "primary",
+            permissions: ["user"],
+            confirmation: {
+                title: "Book this slot?",
+                body: "This reserves the placement for the whole month at the listed price. Cancelling later does not release the month for someone else to buy.",
+                confirmLabel: "Yes, book it",
+            },
+        },
+        "cancel-ad-booking": {
+            iconKey: "cancel",
+            id: "ads.cancel-ad-booking",
+            label: "Cancel booking",
+            ariaLabel: "Cancel this ad booking",
+            description: "Stops the creative running. 🛑 Does NOT free the month — the slot stays yours for the period you booked; releasing it is a separate admin act with a refund behind it.",
+            kind: "danger",
+            permissions: ["user"],
+            confirmation: {
+                title: "Cancel this booking?",
+                body: "Your ad stops running. The month is NOT released for another advertiser, and this does not issue a refund on its own.",
+                confirmLabel: "Yes, cancel",
+            },
+        },
+        "approve-ad-creative": {
+            iconKey: "verify",
+            id: "ads.approve-ad-creative",
+            label: "Approve creative",
+            ariaLabel: "Approve this ad creative so it can render",
+            description: "Clears the creative to render for its booked month. Approval is of THIS creative — an edit returns it to review.",
+            kind: "primary",
+            permissions: ["admin", "moderator"],
+            confirmation: {
+                title: "Approve this creative?",
+                body: "It will render on the public site for its booked month once the booking is paid.",
+                confirmLabel: "Yes, approve",
+            },
+        },
+        "reject-ad-creative": {
+            iconKey: "reject",
+            id: "ads.reject-ad-creative",
+            label: "Reject creative",
+            ariaLabel: "Reject this ad creative and tell the advertiser why",
+            description: "Sends it back with your note. A note is REQUIRED — without one the advertiser resubmits the same creative and you review it twice.",
+            kind: "danger",
+            permissions: ["admin", "moderator"],
+            confirmation: {
+                title: "Reject this creative?",
+                body: "The advertiser sees your note and can submit a new creative against the same booking. The slot stays theirs.",
+                confirmLabel: "Yes, reject",
+            },
+        },
+    },
     PRODUCT: {
         /*
          * The buyer-facing verbs below shipped long ago; the four CRUD entries
@@ -929,6 +996,36 @@ export const ACTIONS = {
             kind: "primary",
             permissions: ["seller", "admin"],
         },
+        "dispatch-custom": {
+            iconKey: "ship",
+            id: "store.dispatch-custom",
+            label: "Record dispatch",
+            ariaLabel: "Record a parcel you posted yourself",
+            description: "Record the carrier and tracking id for a parcel the seller posted themselves.",
+            kind: "primary",
+            permissions: ["seller", "admin"],
+        },
+        "dispatch-platform": {
+            iconKey: "ship",
+            id: "store.dispatch-platform",
+            label: "Book through the platform",
+            ariaLabel: "Book this parcel through the platform's courier account",
+            description: "Book a pickup on the platform's own carrier account. The tracking id comes back from the courier.",
+            kind: "primary",
+            permissions: ["seller", "admin"],
+            /*
+             * 🛑 Confirmed because it SPENDS MONEY and cannot be undone from this
+             * screen. A booking debits the platform's carrier wallet and schedules
+             * a real pickup; `bookShipment` then refuses a second attempt on the
+             * same order, so a mis-click is not a thing the seller can take back by
+             * pressing the button again.
+             */
+            confirmation: {
+                title: "Book this parcel through the platform?",
+                body: "A courier pickup will be scheduled at the address you picked and the cost charged to the platform's carrier account. This cannot be undone from here.",
+                confirmLabel: "Book pickup",
+            },
+        },
         "mark-installment-paid": {
             iconKey: "confirm",
             id: "store.mark-installment-paid",
@@ -1727,6 +1824,137 @@ export const ACTIONS = {
         },
     },
     ADMIN: {
+        /*
+         * ── Integration switches (12b) ──────────────────────────────────
+         *
+         * 🛑 The confirmation BODY is deliberately empty on `disable-integration`,
+         * and that is not an omission.
+         *
+         * `INTEGRATIONS[id].offConsequence` is the real body, and it differs per
+         * integration by design — "payments off" abandons in-flight payments,
+         * "support off" hides a contact route, "shipping off" selects a working
+         * manual path and stops nothing. A generic "are you sure?" here would
+         * flatten exactly the distinction that file exists to preserve, and a COPY
+         * of each consequence string would be a second place for it to drift from
+         * (Root Cause #42). `AdminIntegrationsView` composes the dialog body from
+         * the descriptor at render time.
+         *
+         * The registry still owns the label, the aria-label, the kind, and the fact
+         * that a confirmation is REQUIRED — which is what Rule #7 is about.
+         */
+        "enable-integration": {
+            iconKey: "approve",
+            id: "admin.enable-integration",
+            label: "Enable",
+            ariaLabel: "Enable this integration",
+            description: "Turn an integration on. Writes the authoritative settings field for it.",
+            kind: "primary",
+            permissions: ["admin"],
+        },
+        "update-pricing": {
+            iconKey: "save",
+            id: "admin.update-pricing",
+            label: "Save new rate",
+            ariaLabel: "Save the new rate",
+            description: "Change one platform rate from now on. Orders, invoices and payouts already recorded keep the rate they were charged at — a rate change never restates history.",
+            kind: "primary",
+            permissions: ["admin"],
+            /*
+             * 🛑 A confirmation even though `kind` is "primary" rather than "danger".
+             * The registry requires one for destructive actions; this one is here
+             * because the act is IRREVERSIBLE IN A WAY THAT DOES NOT LOOK IT — the
+             * rate moves forward only, so "undo" means a second change with a second
+             * audit row, and nothing restores what was charged in between.
+             */
+            confirmation: {
+                title: "Change this rate?",
+                body: "Every checkout from now on uses the new value. Past orders, invoices and payouts are untouched and keep the rate they were charged at.",
+                confirmLabel: "Change the rate",
+            },
+        },
+        "add-dispute-reason": {
+            iconKey: "create",
+            id: "admin.add-dispute-reason",
+            label: "Add reason",
+            ariaLabel: "Add a dispute reason",
+            description: "Add a reason buyers can pick when reporting a problem. The reason's KIND decides which gate it is subject to; the wording is yours.",
+            kind: "primary",
+            permissions: ["admin"],
+        },
+        "retire-dispute-reason": {
+            iconKey: "reject",
+            id: "admin.retire-dispute-reason",
+            label: "Retire",
+            ariaLabel: "Retire this dispute reason",
+            description: "Take a reason out of the buyer's picker. Never a delete — past disputes name it, and the order snapshots its label so history survives either way.",
+            kind: "danger",
+            permissions: ["admin"],
+            confirmation: {
+                title: "Retire this reason?",
+                /*
+                 * Names what retiring does NOT do, because that is the part an agent
+                 * is most likely to be unsure about and the reason this is not a
+                 * delete. A vague "are you sure" would invite exactly the hesitation
+                 * the schema's soft-retire design exists to remove.
+                 */
+                body: "Buyers will stop seeing it on the dispute form. Disputes already raised under it keep their wording, and you can put it back at any time.",
+                confirmLabel: "Retire it",
+                confirmKind: "danger",
+            },
+        },
+        "reactivate-dispute-reason": {
+            iconKey: "approve",
+            id: "admin.reactivate-dispute-reason",
+            label: "Reactivate",
+            ariaLabel: "Put this dispute reason back in the picker",
+            description: "Offer a retired reason to buyers again. The original author is kept.",
+            kind: "primary",
+            permissions: ["admin"],
+        },
+        "disable-integration": {
+            iconKey: "reject",
+            id: "admin.disable-integration",
+            label: "Disable",
+            ariaLabel: "Disable this integration",
+            description: "Turn an integration off. The consequence differs per integration and is stated on the row.",
+            kind: "danger",
+            permissions: ["admin"],
+            confirmation: {
+                title: "Switch this integration off?",
+                body: "",
+                confirmLabel: "Switch it off",
+                confirmKind: "danger",
+            },
+        },
+        "enable-all-integrations": {
+            iconKey: "approve",
+            id: "admin.enable-all-integrations",
+            label: "Enable all",
+            ariaLabel: "Enable every integration",
+            description: "Turn every integration on in a single write.",
+            kind: "secondary",
+            permissions: ["admin"],
+            confirmation: {
+                title: "Enable every integration?",
+                body: "Online payments, customer email, courier booking and the support surface will all be switched on. One write, one audit-log entry.",
+                confirmLabel: "Enable everything",
+            },
+        },
+        "disable-all-integrations": {
+            iconKey: "reject",
+            id: "admin.disable-all-integrations",
+            label: "Disable all",
+            ariaLabel: "Disable every integration",
+            description: "Turn every integration off in a single write.",
+            kind: "danger",
+            permissions: ["admin"],
+            confirmation: {
+                title: "Disable every integration?",
+                body: "This stops online payments, customer email and courier booking, and hides the buyer support surface. 🛑 Payments already in progress are abandoned — a buyer part-way through the gateway may be charged with no order placed. Staff email and open tickets stay workable. One write, one audit-log entry.",
+                confirmLabel: "Disable everything",
+                confirmKind: "danger",
+            },
+        },
         // ── Product moderation ─────────────────────────────────────────────────
         "approve-product": {
             iconKey: "approve",
@@ -1883,6 +2111,46 @@ export const ACTIONS = {
                 confirmKind: "danger",
             },
         },
+        /*
+         * D55 — the pre-order BALANCE's two review verdicts.
+         *
+         * 🛑 Deliberately separate from `verify-payment` / `reject-payment-fraud`
+         * above, which review the DEPOSIT. A pre-order's two payments are months
+         * apart, and the consequences do not match: rejecting a deposit proof
+         * cancels the order, restores stock and bans the account for 7 days,
+         * because the order had no legitimate basis. Rejecting a BALANCE proof on
+         * goods already made and allocated must do none of that — it asks for a
+         * better screenshot. Reusing the deposit's action would attach a 7-day
+         * ban to a blurry photo.
+         */
+        "verify-balance": {
+            iconKey: "verify",
+            id: "admin.verify-balance",
+            label: "Accept Balance",
+            ariaLabel: "Accept the pre-order balance payment proof",
+            description: "Confirms the pre-order balance was received. The order becomes shippable. Does NOT post a ledger entry — the sale was recognised in full at order creation.",
+            kind: "primary",
+            permissions: ["admin", "moderator"],
+            confirmation: {
+                title: "Accept the balance payment?",
+                body: "This records the remaining balance as received and clears the order to ship. Check the reference against your bank first.",
+                confirmLabel: "Yes, accept",
+            },
+        },
+        "reject-balance": {
+            iconKey: "reject",
+            id: "admin.reject-balance",
+            label: "Reject Balance Proof",
+            ariaLabel: "Reject the pre-order balance proof and ask the buyer to resend",
+            description: "Sends the proof back with your note. The buyer can submit again — no cancellation, no stock change, no ban: the goods are already made and allocated to them.",
+            kind: "secondary",
+            permissions: ["admin", "moderator"],
+            confirmation: {
+                title: "Reject this balance proof?",
+                body: "The buyer is told why and can send another. The order stays open and the item stays theirs.",
+                confirmLabel: "Reject and ask again",
+            },
+        },
         "verify-vendor": {
             iconKey: "verify",
             id: "admin.verify-vendor",
@@ -3256,6 +3524,34 @@ export const ACTIONS = {
                 confirmLabel: "Close ticket",
             },
         },
+        /*
+         * Raising a dispute on an order.
+         *
+         * Filed under SUPPORT rather than a new ORDER bucket: there is no such
+         * bucket, and a dispute's destination is a support investigation. A first
+         * draft of the form wrote `ACTIONS.ORDERS?.["raise-dispute"]`, where the
+         * optional chain would have silently resolved to `undefined` and rendered
+         * a button with no label, no aria-label and no confirmation — which is
+         * precisely what Rule #7 exists to stop.
+         *
+         * NO `confirmation`, deliberately. It is not destructive: nothing is
+         * cancelled, no money moves, and the action's own docstring says it "does
+         * not itself reverse payment/order status". A confirm dialog in front of
+         * "tell us something went wrong" adds friction to the one path a buyer
+         * with a problem needs to be able to take.
+         */
+        "raise-dispute": {
+            // `report`, which IS the Flag glyph (icon-registry.ts:133). `"flag"` is
+            // not a registered key — and because `iconKey` is typed `IconKey` rather
+            // than `string`, that would have been a compile error rather than the
+            // silent no-op it used to be.
+            iconKey: "report",
+            id: "support.raise-dispute",
+            label: "Report this",
+            ariaLabel: "Report a problem with this order",
+            description: "Raise a dispute on an order for support to investigate.",
+            kind: "primary",
+        },
     },
     TESTER: {
         "save-note": {

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,186 @@ 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.
+ */
+/** One order group's payable total, and whether its store takes points. */
+export interface PointsBase {
+    total: number;
+    accepted: boolean;
+}
+/** Everything one group contributes to its own payable total. */
+export interface PointsBaseParts {
+    /** Goods subtotal for the group, before any discount. */
+    goods: number;
+    couponDiscount: number;
+    shippingFee: number;
+    /** Gift wrap + shipment protection + any other per-store add-on. */
+    addonFee: number;
+    platformFee: number;
+    gstOnFee: number;
+    acceptsPoints: boolean;
+}
+/**
+ * The payable total a points allocation is measured against.
+ *
+ * 🛑 ONE implementation, because it was two. `POST /api/payment/create-order`
+ * and `verifyAndPlaceRazorpayOrderAction`'s amount guard each built this sum
+ * by hand, in the same shape, from the same six parts — and they are the
+ * *shown* figure and the *charged* figure for the same cart. Two hand-written
+ * copies of one money rule is Root Cause #75 exactly, and the failure mode is
+ * the worst kind: they only disagree on carts where the arithmetic differs, so
+ * nothing errors and the buyer is quoted one number and charged another.
+ *
+ * The coupon is floored at zero before the fees are added, never after — a
+ * discount larger than the goods must not eat the shipping and platform fee.
+ */
+export declare function pointsBaseForGroup(parts: PointsBaseParts): PointsBase;
+export declare function allocatePointsAcrossGroups(groups: readonly PointsBase[], 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