@mohasinac/appkit 4.58.0 → 4.60.0

package/dist/_internal/server/features/protection-claims/actions.js

@@ -0,0 +1,228 @@
+"use server";
+/**
+ * Filing and adjudicating a protection claim — the first callers
+ * `protectionAvailability()` and `adjudicateClaim()` have ever had.
+ *
+ * ## What was wrong (D11)
+ *
+ * We charge 2% (min ₹30) shipment protection and 3% (min ₹49) sale protection
+ * at four money sites. The decision logic, the custody state machine, the
+ * window constants and the order fields all existed with **zero callers**, and
+ * the refund path did not know the add-on existed. A FAQ promised *"we pursue
+ * the courier and refund you"* and *"refunded no questions asked"*.
+ *
+ * ## The two gates, and why both are server-side
+ *
+ * 1. **Did the buyer actually buy this cover?** Read off the ORDER's own
+ *    `shipmentProtectionFee` / `saleProtectionFee` — the amount charged — not
+ *    off the live store or the live settings. A seller must not be able to
+ *    withdraw cover after the sale, which is the same snapshot reasoning
+ *    `finalSale` uses on the refund path.
+ * 2. **Is the window still open?** The `claim-shipping` / `claim-sale`
+ *    obligations, derived from `deliveryDate` through
+ *    `PROTECTION_CLAIM_WINDOW_HOURS` (48h / 168h). One definition, shared with
+ *    the sweep that closes the window and earns the premium.
+ */
+import { wrapAction } from "../../../shared/types/action-result.js";
+import { requireRoleUser } from "../../../../providers/auth-firebase/helpers.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+import { ValidationError, NotFoundError } from "../../../../errors/index.js";
+import { orderRepository } from "../../../../features/orders/repository/orders.repository.js";
+import { protectionClaimsRepository } from "../../../../features/protection-claims/repository/protection-claims.repository.js";
+import { PROTECTION_CLAIM_DETAIL_MAX, PROTECTION_CLAIM_DETAIL_MIN, REASON_TO_KIND, createProtectionClaimId, } from "../../../../features/protection-claims/schemas/firestore.js";
+import { adjudicateClaim, SALE_PROTECTION_MAX_VALUE, } from "../../../shared/features/shipping/protections.js";
+import { deadlinesFor } from "../../../shared/obligations/deadlines.js";
+import { paymentCasesRepository } from "../../../../features/payment-cases/repository/payment-cases.repository.js";
+import { orderGoodsValue } from "../../../shared/checkout/order-math.js";
+/**
+ * File a claim as the buyer.
+ *
+ * 🛑 The COVER KIND is derived from the reason, never taken from the caller.
+ * `REASON_TO_KIND` maps transit failures to shipment cover and item failures
+ * to sale cover — because letting the buyer pick would let them file a
+ * non-delivery against the 7-day sale window after the 48-hour transit window
+ * had closed, which is the window rule defeated by a dropdown.
+ */
+export async function fileProtectionClaimAction(input) {
+    return wrapAction(async () => {
+        const user = await requireRoleUser(["user", "buyer", "seller", "admin"]);
+        const detail = input.detail?.trim() ?? "";
+        if (detail.length < PROTECTION_CLAIM_DETAIL_MIN) {
+            throw new ValidationError(`Please describe what happened in at least ${PROTECTION_CLAIM_DETAIL_MIN} characters — a claim with no account of the problem cannot be assessed.`);
+        }
+        if (detail.length > PROTECTION_CLAIM_DETAIL_MAX) {
+            throw new ValidationError(`Please keep the description under ${PROTECTION_CLAIM_DETAIL_MAX} characters.`);
+        }
+        const order = await orderRepository.findById(input.orderId);
+        if (!order)
+            throw new NotFoundError(`Order ${input.orderId} not found`);
+        if (order.userId !== user.uid) {
+            throw new ValidationError("You can only claim against your own order.");
+        }
+        const kind = REASON_TO_KIND[input.reason];
+        /*
+         * GATE 1 — did this order actually CARRY the cover?
+         *
+         * 🛑 Read off the order's own recorded fee, not the live store or the live
+         * settings. A seller flipping `supportsSaleProtection` off after the sale
+         * must not be able to withdraw cover the buyer paid for — the same
+         * reasoning `finalSale` uses on the refund path, and the same reason
+         * `OrderDocumentItem.finalSale` exists at all.
+         */
+        const feePaid = kind === "shipping" ? order.shipmentProtectionFee : order.saleProtectionFee;
+        if (!feePaid || feePaid <= 0) {
+            throw new ValidationError(kind === "shipping"
+                ? "This order does not carry shipment protection."
+                : "This order does not carry sale protection.");
+        }
+        /*
+         * GATE 2 — is the window still open?
+         *
+         * Derived from the obligation policy, so the buyer's form, the sweep that
+         * closes the window, and whatever page shows the deadline all read one
+         * definition.
+         *
+         * 🛑 No `deliveryDate` means the clock has not STARTED, which is not the
+         * same as closed — a parcel that never arrived is exactly what shipment
+         * cover is for, and refusing it for want of a delivery date would deny the
+         * claim the cover most exists for.
+         */
+        const obligationKind = kind === "shipping" ? "claim-shipping" : "claim-sale";
+        const window = deadlinesFor(order).find((d) => d.kind === obligationKind);
+        if (order.deliveryDate && window && window.dueAt.getTime() <= Date.now()) {
+            throw new ValidationError(`The ${kind === "shipping" ? "shipment" : "sale"} protection claim window for this order closed on ${window.dueAt.toLocaleDateString("en-IN")}.`);
+        }
+        /*
+         * The ceiling. `SALE_PROTECTION_MAX_VALUE` (₹25,000) is tested against what
+         * was PAID for the claimed goods, which is why `claimedAmount` is
+         * snapshotted at filing rather than recomputed later.
+         */
+        const claimedAmount = orderGoodsValue(order);
+        if (kind === "sale" && claimedAmount > SALE_PROTECTION_MAX_VALUE) {
+            throw new ValidationError(`Sale protection covers orders up to ₹${SALE_PROTECTION_MAX_VALUE.toLocaleString("en-IN")}. This order is above that, so the claim needs a human — please contact support.`);
+        }
+        const claim = await protectionClaimsRepository().file({
+            kind,
+            orderId: order.id,
+            storeId: order.storeId ?? "",
+            buyerId: user.uid,
+            reason: input.reason,
+            detail,
+            claimedAmount,
+            ...(input.itemIds?.length ? { itemIds: input.itemIds } : {}),
+            ...(input.evidenceUrls?.length ? { evidenceUrls: input.evidenceUrls } : {}),
+            ...(order.isTestData ? { isTestData: true } : {}),
+        });
+        /*
+         * Into the operator queue, because a claim is money at risk with a human
+         * decision attached — which is exactly what `paymentCases` is for. Keyed on
+         * the claim, so re-filing or a sweep re-observing it produces one case.
+         *
+         * Fire-and-forget: a queue write must never fail the buyer's claim.
+         */
+        void paymentCasesRepository()
+            .openOrObserve({
+            kind: "protection_claim",
+            subjectId: `claim:${claim.id}`,
+            severity: "warning",
+            title: `${kind === "shipping" ? "Shipment" : "Sale"} protection claim — ${order.id}`,
+            detail: [
+                `A buyer has claimed against protection cover they paid for.`,
+                "",
+                `Order: ${order.id}`,
+                `Store: ${order.storeId ?? "(none)"}`,
+                `Cover: ${kind} (fee paid: ${feePaid})`,
+                `Reason: ${input.reason}`,
+                `Claimed amount: ${claimedAmount}`,
+                "",
+                detail,
+                "",
+                `🛑 A PROTECTED claim is refunded unconditionally — the finding decides`,
+                `WHO PAYS, never whether the buyer is refunded. See adjudicateClaim.`,
+            ].join("\n"),
+            entityType: "order",
+            entityId: order.id,
+            amountAtRisk: claimedAmount,
+            orderIds: [order.id],
+        })
+            .catch((err) => {
+            void normalizeError(err);
+        });
+        serverLogger.warn("protection claim filed", {
+            claimId: claim.id,
+            orderId: order.id,
+            kind,
+            reason: input.reason,
+        });
+        return { claimId: claim.id };
+    });
+}
+/**
+ * Adjudicate as an admin or moderator.
+ *
+ * 🛑 THE FINDING DECIDES WHO PAYS, NEVER WHETHER A PROTECTED BUYER IS
+ * REFUNDED. `adjudicateClaim` encodes that and this action does not
+ * second-guess it: on protected cover a `change-of-mind` finding STILL refunds
+ * the buyer and moves the cost to the platform, raising a report — because the
+ * promise sold was unconditional, and the only honest enforcement against
+ * repeat abuse is withdrawing FUTURE eligibility, not denying this claim.
+ *
+ * 🛑 It records the decision and does NOT move money. The refund is
+ * `processRefundAction`'s job, with its own idempotency key — and keeping them
+ * apart means a claim that adjudicated but failed to refund leaves an `upheld`
+ * claim with no `refundId`, which is a findable state rather than a lost one.
+ */
+export async function adjudicateProtectionClaimAction(claimId, finding) {
+    return wrapAction(async () => {
+        const user = await requireRoleUser(["admin", "moderator"]);
+        const claim = await protectionClaimsRepository().findById(claimId);
+        if (!claim)
+            throw new NotFoundError(`Protection claim ${claimId} not found`);
+        if (claim.adjudicatedAt) {
+            throw new ValidationError("This claim has already been adjudicated.");
+        }
+        /*
+         * `protectedSale` is whether SALE cover was bought — the only tier
+         * `adjudicateClaim` branches on. A shipment claim is assessed on the
+         * finding alone, which is correct: transit cover is about the parcel
+         * arriving, and "the buyer changed their mind" is not a transit outcome.
+         */
+        const outcome = adjudicateClaim(claim.kind === "sale", finding);
+        await protectionClaimsRepository().adjudicate(claimId, {
+            finding,
+            outcome,
+            adjudicatedBy: user.uid,
+        });
+        serverLogger.warn("protection claim adjudicated", {
+            claimId,
+            finding,
+            refundBuyer: outcome.refundBuyer,
+            costBorneBy: outcome.costBorneBy,
+            raisesReport: outcome.raisesReport,
+        });
+        return { outcome };
+    });
+}
+/** A buyer's own claims, for their order detail page. */
+export async function getMyProtectionClaimsAction() {
+    return wrapAction(async () => {
+        const user = await requireRoleUser(["user", "buyer", "seller", "admin"]);
+        return protectionClaimsRepository().listForBuyer(user.uid);
+    });
+}
+/** Whether this order can be claimed against right now, for rendering the CTA. */
+export async function canClaimProtection(order, kind) {
+    const feePaid = kind === "shipping" ? order.shipmentProtectionFee : order.saleProtectionFee;
+    if (!feePaid || feePaid <= 0)
+        return { can: false, reason: "not-covered" };
+    const existing = await protectionClaimsRepository().findById(createProtectionClaimId(order.id, kind));
+    if (existing)
+        return { can: false, reason: "already-claimed" };
+    const obligationKind = kind === "shipping" ? "claim-shipping" : "claim-sale";
+    const window = deadlinesFor(order).find((d) => d.kind === obligationKind);
+    if (order.deliveryDate && window && window.dueAt.getTime() <= Date.now()) {
+        return { can: false, reason: "window-closed" };
+    }
+    return { can: true };
+}

package/dist/_internal/server/features/protection-claims/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * protection-claims — server surface.
+ *
+ * Narrow by design (Root Cause #18): the three actions a route calls, plus the
+ * CTA predicate a page needs. The repository is imported directly by anything
+ * that queries.
+ */
+export { fileProtectionClaimAction, adjudicateProtectionClaimAction, getMyProtectionClaimsAction, canClaimProtection, type FileProtectionClaimInput, } from "./actions";

package/dist/_internal/server/features/protection-claims/index.js

@@ -0,0 +1,8 @@
+/**
+ * protection-claims — server surface.
+ *
+ * Narrow by design (Root Cause #18): the three actions a route calls, plus the
+ * CTA predicate a page needs. The repository is imported directly by anything
+ * that queries.
+ */
+export { fileProtectionClaimAction, adjudicateProtectionClaimAction, getMyProtectionClaimsAction, canClaimProtection, } from "./actions.js";

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

@@ -20,6 +20,26 @@ export type ProcessRefundInput = {
     confirmIrrevocable: true;
     /** uid of the user processing the refund (admin / seller). */
     refundedBy: string;
+    /**
+     * 🛑 REQUIRED (D2). The caller's stable key for this logical refund.
+     *
+     * `refundId` used to be a server-side `randomUUID()` per call, which can
+     * never be idempotent: a double-clicked button minted two ids and issued
+     * **two real gateway refunds**. The entry id is now
+     * `sha256(idempotencyKey)`, so a retry reproduces the identical entry and
+     * the claim document refuses the second attempt.
+     *
+     * Required rather than optional ON PURPOSE — an optional key with a
+     * `randomUUID()` fallback is the old bug wearing a new name, and it would
+     * be reached by exactly the callers that forgot.
+     *
+     * What to pass: the submitting UI generates ONE uuid per form OPEN (so a
+     * double-click reuses it and a genuine second refund gets a new one);
+     * server-initiated paths use a NATURAL key — the out-of-stock auto-refund
+     * uses `oos_{merchantOrderId}`, which also makes it idempotent across
+     * checkout retries, a money fix in its own right.
+     */
+    idempotencyKey: string;
 } & ({
     method: "phonepe";
     /** The order's PhonePe merchantOrderId (order.paymentId) — PhonePe refunds are order-keyed, never payment-keyed. */

package/dist/_internal/server/features/refunds/actions.js

@@ -15,8 +15,16 @@ import { wrapAction } from "@mohasinac/appkit/server";
  *
  * Setting `contestable` to false is a side-effect of `orderRepository.postRefundEvent`.
  */
-import { randomUUID } from "crypto";
+/*
+ * `createHash`, not `randomUUID` — see `idempotencyKey` on the input type. A
+ * server-minted random id cannot be idempotent, which is what made a
+ * double-clicked button issue two real gateway refunds (D2).
+ */
+import { createHash } from "crypto";
 import { getProviders } from "../../../../contracts/registry.js";
+import { siteSettingsRepository } from "../../../../features/admin/repository/site-settings.repository.js";
+import { refundCapacity, wouldBeFullRefund, MONEY_EPSILON, } from "../../../shared/checkout/refundable-base.js";
+import { REFUND_CLAIMS_COLLECTION } from "../../../../features/orders/schemas/firestore.js";
 import { normalizeError } from "../../../../errors/normalize.js";
 import { rupeesToPaise } from "../../../../core/money.js";
 import { orderRepository } from "../../../../features/orders/repository/orders.repository.js";
@@ -86,8 +94,49 @@ export async function processRefundAction(input) {
             throw new NotFoundError(`Order ${input.orderId} not found`);
         if (input.amount <= 0)
             throw new ValidationError("Refund amount must be positive");
-        if (input.amount > order.totalPrice) {
-            throw new ValidationError("Refund amount exceeds order total");
+        /*
+         * One settings read, and only for the LEGACY case: orders written before
+         * `platformFeeGst` was persisted (2026-10-21) need their fee's GST
+         * derived, and deriving it from a rate we had to look up is still far
+         * better than D32's mistake of deriving the whole fee from a live
+         * percentage. Orders written after that date ignore this value entirely.
+         *
+         * Accepted cost: one read on an operator-initiated, rare action. The
+         * alternative — skipping it — would under-withhold on legacy orders,
+         * which sounds buyer-friendly but inflates `refundableBase`, so a
+         * "refund everything" would leave a residue and the order would never
+         * reach `status: "refunded"` (the D3 defect, reintroduced).
+         */
+        const siteSettings = await siteSettingsRepository.getSingleton().catch((err) => {
+            void normalizeError(err);
+            return null;
+        });
+        /*
+         * ── D1: the cap is the REMAINING balance, not the order total ────────
+         *
+         * This read `input.amount > order.totalPrice`, i.e. it compared each
+         * refund against the whole order — while the function's own docstring
+         * promised "≤ remaining refundable amount". So on a ₹600 order, ₹500 and
+         * then another ₹500 BOTH passed: ₹1,000 refunded, two real gateway
+         * calls, both successful.
+         *
+         * 🛑 The ceiling is `refundableBase`, not `totalPrice`: the platform fee
+         * is non-refundable by policy, which the product already tells the buyer
+         * (`REFUND_COPY.request.acknowledgments[2]`).
+         *
+         * This check is the EARLY, friendly one — it gives the operator a useful
+         * message before any provider call. It is NOT the authority: the real
+         * cap is re-evaluated inside `reserveRefund`'s transaction, because a
+         * check outside a transaction is TOCTOU and two concurrent requests
+         * could each see a clear cap and both proceed. That is exactly how the
+         * double refund above was reachable even with a correct comparison.
+         */
+        const capacity = refundCapacity(order, siteSettings?.commissions?.gstPercent);
+        if (input.amount > capacity.remaining + MONEY_EPSILON) {
+            throw new ValidationError(`Refund of ₹${input.amount.toFixed(2)} exceeds the ₹${capacity.remaining.toFixed(2)} still refundable on this order` +
+                (capacity.withheld > 0
+                    ? ` (₹${capacity.withheld.toFixed(2)} platform fee is non-refundable).`
+                    : "."));
         }
         // Guard: non-refundable orders (prize draws, bundles). A property of the
         // listing TYPE, decided by the platform — checked first because it
@@ -118,17 +167,72 @@ export async function processRefundAction(input) {
         // SB-UNI-N — digital-code refund gate: block if code is already claimed (revealed).
         const digitalCodeItems = (order.items ?? []).filter((i) => (i.listingType ?? "standard") === "digital-code");
         await assertDigitalCodesNotClaimed(input.orderId, digitalCodeItems);
-        const refundId = randomUUID();
+        /*
+         * ── D2: IDEMPOTENCY ──────────────────────────────────────────────────
+         *
+         * `const refundId = randomUUID()` was generated SERVER-SIDE, per call.
+         * A server-minted id can never be idempotent: a double-clicked button
+         * produced two different ids and therefore **two real gateway refunds**.
+         *
+         * The id is now derived from the caller's `idempotencyKey`, so a retry
+         * of the same logical request produces the identical entry. The client
+         * generates one key per form OPEN, so a double-click reuses it while a
+         * genuine second refund gets a new one.
+         *
+         * Truncated to 32 chars to stay comfortably inside a Firestore document
+         * id while keeping ~128 bits of the digest — collision risk is
+         * negligible and a collision degrades to "treated as a retry", which is
+         * the safe direction.
+         */
+        const refundId = createHash("sha256").update(input.idempotencyKey).digest("hex").slice(0, 32);
         const now = new Date();
-        let phonepeRefundId;
-        if (input.method === "phonepe") {
-            const payment = getProviders().payment;
-            if (!payment)
-                throw new ValidationError("Payment provider not configured");
-            const result = await payment.refund(input.phonepeOrderId, rupeesToPaise(input.amount));
-            phonepeRefundId = result.id;
+        /*
+         * The at-most-once gate, BEFORE any provider call. Same `.create()`
+         * fails-if-exists primitive the gateway order claim uses — the fourth
+         * use of it in this codebase.
+         *
+         * 🛑 Claimed first and released on nothing. A claim that outlives a
+         * crash is deliberate: it is what stops a retry from issuing a second
+         * provider call for a refund that may already have succeeded. An
+         * unsettled claim older than an hour is what the reconciler looks for
+         * (Phase 4 R3), and resolving it means READING the gateway, never
+         * guessing.
+         */
+        const claimRef = getAdminDb().collection(REFUND_CLAIMS_COLLECTION).doc(refundId);
+        try {
+            await claimRef.create({
+                orderId: input.orderId,
+                amount: input.amount,
+                state: "claimed",
+                claimedAt: now,
+                claimedBy: input.refundedBy,
+            });
+        }
+        catch (claimErr) {
+            void normalizeError(claimErr);
+            /*
+             * Already claimed. Return the WINNER's refundId as a SUCCESS, not an
+             * error — the refund either happened or is in flight, and an error
+             * here makes the operator click again, which is the behaviour this
+             * whole mechanism exists to stop.
+             */
+            serverLogger.info("refund: duplicate idempotency key — returning the existing refund", {
+                orderId: input.orderId,
+                refundId,
+            });
+            return { success: true, refundId };
         }
-        const isFull = input.amount >= order.totalPrice;
+        /*
+         * ── D3: `isFull` measured against the REFUNDABLE BASE ────────────────
+         *
+         * This was `input.amount >= order.totalPrice`, which is unreachable once
+         * the platform fee is withheld: the largest possible refund is strictly
+         * LESS than `totalPrice`, so an order could **never** reach
+         * `status: "refunded"` and stayed fully refundable forever. It also
+         * ignored prior partial refunds entirely — ₹300 then ₹200 of ₹500 left
+         * the order open.
+         */
+        const isFull = wouldBeFullRefund(order, input.amount, siteSettings?.commissions?.gstPercent);
         const event = {
             refundId,
             type: input.type,
@@ -144,7 +248,6 @@ export async function processRefundAction(input) {
                 : RETURN_REASON_LABEL[input.reasonCode],
             refundedAt: now,
             refundedBy: input.refundedBy,
-            ...(phonepeRefundId ? { phonepeRefundId } : {}),
             ...(input.method === "manual" && input.manualTransactionId
                 ? { manualTransactionId: input.manualTransactionId }
                 : {}),
@@ -155,11 +258,117 @@ export async function processRefundAction(input) {
                 }
                 : {}),
         };
-        await orderRepository.postRefundEvent(input.orderId, event, isFull);
+        /*
+         * ── D6: TWO-PHASE WRITE AROUND THE PROVIDER CALL ─────────────────────
+         *
+         * The old sequence was: call the gateway, then `postRefundEvent`, which
+         * does `findById` then `[...existing, event]`. Two problems.
+         *
+         * (a) The append is a read-then-write, so two concurrent refunds both
+         *     read the same array and the second **loses the first's event
+         *     entirely**.
+         * (b) A crash between the gateway call and the write leaves money gone
+         *     from the gateway and NO RECORD of it on our side — unrecoverable
+         *     without manually reading the provider.
+         *
+         * Reserve (transactional, cap enforced inside) → provider call (outside
+         * any transaction, because a transaction RETRIES its body and a retried
+         * network call is a second refund) → settle. This is the only ordering
+         * in which "money left and we do not know" is impossible: a crash now
+         * leaves a `reserved` entry plus an unsettled claim, which is a
+         * detectable, resolvable state.
+         */
+        await orderRepository.reserveRefund(input.orderId, event, {
+            refundableBase: capacity.base,
+            epsilon: MONEY_EPSILON,
+        });
+        let gatewayRefundId;
+        let gatewayName;
+        if (input.method === "phonepe") {
+            const payment = getProviders().payment;
+            if (!payment)
+                throw new ValidationError("Payment provider not configured");
+            try {
+                const result = await payment.refund(input.phonepeOrderId, rupeesToPaise(input.amount));
+                gatewayRefundId = result.id;
+                gatewayName = payment.name;
+            }
+            catch (providerErr) {
+                void normalizeError(providerErr);
+                /*
+                 * Release the reservation by settling it `failed`, so the amount
+                 * returns to the refundable balance — `committedRefundTotal` skips
+                 * failed entries, which is why no explicit release exists to forget.
+                 * Then rethrow: the operator must know the gateway refused.
+                 */
+                await orderRepository
+                    .settleRefund(input.orderId, refundId, {
+                    status: "failed",
+                    failureReason: providerErr instanceof Error ? providerErr.message : String(providerErr),
+                })
+                    .catch((settleErr) => {
+                    void normalizeError(settleErr);
+                    serverLogger.error("refund: could not mark a failed reservation — it will hold the balance until reconciled", {
+                        orderId: input.orderId,
+                        refundId,
+                    });
+                });
+                await claimRef
+                    .update({ state: "failed", settledAt: new Date() })
+                    .catch(() => { });
+                throw providerErr;
+            }
+        }
+        /*
+         * ── D7: the gateway id, recorded gateway-BLIND and provider-specific ──
+         *
+         * Razorpay's refund id used to be written to `phonepeRefundId`
+         * unconditionally (`phonepeRefundId = result.id`, no branch), while the
+         * declared `razorpayRefundId` was written by nothing — so a Razorpay
+         * refund existed in their dashboard with no way to tie it to ours.
+         *
+         * `gatewayRefundId` is what a reconciler reads and needs no knowledge of
+         * which provider ran. The provider-specific field is populated too, by
+         * the provider that actually produced the id, for an operator searching
+         * one dashboard.
+         */
+        await orderRepository.settleRefund(input.orderId, refundId, {
+            status: "processed",
+            ...(gatewayRefundId ? { gatewayRefundId } : {}),
+            ...(gatewayName ? { gateway: gatewayName } : {}),
+            providerFields: gatewayRefundId && gatewayName === "razorpay"
+                ? { razorpayRefundId: gatewayRefundId }
+                : gatewayRefundId
+                    ? { phonepeRefundId: gatewayRefundId }
+                    : {},
+        }, isFull);
+        await claimRef
+            .update({ state: "settled", settledAt: new Date() })
+            .catch((err) => {
+            void normalizeError(err);
+            // Harmless: the refund is recorded. An unsettled claim only means
+            // the reconciler will look at it once and find it already done.
+            serverLogger.warn("refund: claim not marked settled", { refundId });
+        });
         // SB-UNI-N — revoke any available (unclaimed) digital codes linked to this order.
         revokeAvailableDigitalCodes(input.orderId, digitalCodeItems);
-        // Fire-and-forget: deduct from the store's pending payout if one exists.
-        // Failure here must not roll back the already-posted refund event.
+        /*
+         * Clawback — deduct from the store's pending payout if one exists.
+         *
+         * 🛑 Still fire-and-forget on the FAILURE path, and that part is
+         * correct: the refund event is already posted and the buyer's money is
+         * already moving, so an accounting side effect must never roll it back.
+         *
+         * What changed on 2026-10-21 is that the RESULT is no longer discarded.
+         * This read `.catch(() => {})` with no `.then`, on the strength of the
+         * action's own docstring claiming an unrecovered clawback was "reflected
+         * in the next payout cycle" — which is false, verified: there is no
+         * seller ledger and each payout is computed fresh from a new batch of
+         * delivered orders, so the seller simply keeps money for goods that came
+         * back (D10). The action now records that case durably and returns a
+         * destination; this logs which one, so a refund and its clawback can be
+         * followed in one place.
+         */
         if (order.storeId) {
             applyRefundDeductionAction({
                 storeId: order.storeId,
@@ -169,7 +378,40 @@ export async function processRefundAction(input) {
                 // Same derived string the refund event records, so the payout
                 // deduction and the refund history read identically.
                 reason: event.reason,
-            }).catch(() => { });
+            })
+                .then((res) => {
+                if (!res.ok) {
+                    serverLogger.error("clawback action failed", {
+                        orderId: input.orderId,
+                        refundId,
+                    });
+                    return;
+                }
+                if (res.data.applied) {
+                    serverLogger.info("clawback netted off a pending payout", {
+                        orderId: input.orderId,
+                        payoutId: res.data.payoutId,
+                    });
+                }
+                else {
+                    /*
+                     * The seller has been paid for returned goods. Loud, because
+                     * there is no automatic recovery — `recordedAs` names the
+                     * durable row at /admin/maintenance/payment-rollbacks.
+                     */
+                    serverLogger.error("clawback UNRECOVERED — seller retains refunded amount", {
+                        orderId: input.orderId,
+                        storeId: res.data.storeId,
+                        amount: res.data.amount,
+                        reason: res.data.reason,
+                        recordedAs: res.data.recordedAs,
+                    });
+                }
+            })
+                .catch((clawbackErr) => {
+                void normalizeError(clawbackErr);
+                serverLogger.error("clawback threw", { orderId: input.orderId, refundId });
+            });
         }
         return { success: true, refundId };
     });

package/dist/_internal/server/features/refunds/capacity.d.ts

@@ -0,0 +1,29 @@
+/**
+ * How much of an order can still be refunded — the one server-side answer.
+ *
+ * `refundable-base.ts` is deliberately PURE: it takes `legacyGstPercent` as an
+ * argument rather than reading settings, so it stays testable and so a caller
+ * cannot accidentally apply today's GST rate to a historical order. That purity
+ * is right, and it leaves every server caller needing the same three lines to
+ * supply the argument.
+ *
+ * Three callers now need them — `cancelOrderWithRefund`, `obligationSweep`'s
+ * auto-refund branches, and `processRefundAction`'s own cap check — and three
+ * copies of a money calculation is Root Cause #75's exact shape. So the
+ * settings read lives here, once.
+ *
+ * 🛑 The read is for ONE case and it is not optional. Orders written before
+ * `platformFeeGst` was persisted (2026-10-21) carry no stored fee GST, so it
+ * has to be derived from the rate — and if two callers derive it differently,
+ * or one skips it, they disagree about the cap. The direction of that
+ * disagreement matters: skipping the GST INFLATES the refundable base, so a
+ * "refund everything" leaves a sub-rupee residue and the order can never reach
+ * `status: "refunded"` — which is D3, reintroduced by omission.
+ *
+ * A failed settings read degrades to `undefined`, which means legacy orders
+ * under-withhold rather than the whole refund failing. That is the safer
+ * direction for the buyer and it is visible: the residue shows up as an order
+ * stuck short of `refunded`, which R5 in `paymentReconcile` reports.
+ */
+import { type RefundCapacity, type RefundableOrderLike } from "../../../shared/checkout/refundable-base";
+export declare function resolveRefundCapacity(order: RefundableOrderLike): Promise<RefundCapacity>;

package/dist/_internal/server/features/refunds/capacity.js

@@ -0,0 +1,37 @@
+/**
+ * How much of an order can still be refunded — the one server-side answer.
+ *
+ * `refundable-base.ts` is deliberately PURE: it takes `legacyGstPercent` as an
+ * argument rather than reading settings, so it stays testable and so a caller
+ * cannot accidentally apply today's GST rate to a historical order. That purity
+ * is right, and it leaves every server caller needing the same three lines to
+ * supply the argument.
+ *
+ * Three callers now need them — `cancelOrderWithRefund`, `obligationSweep`'s
+ * auto-refund branches, and `processRefundAction`'s own cap check — and three
+ * copies of a money calculation is Root Cause #75's exact shape. So the
+ * settings read lives here, once.
+ *
+ * 🛑 The read is for ONE case and it is not optional. Orders written before
+ * `platformFeeGst` was persisted (2026-10-21) carry no stored fee GST, so it
+ * has to be derived from the rate — and if two callers derive it differently,
+ * or one skips it, they disagree about the cap. The direction of that
+ * disagreement matters: skipping the GST INFLATES the refundable base, so a
+ * "refund everything" leaves a sub-rupee residue and the order can never reach
+ * `status: "refunded"` — which is D3, reintroduced by omission.
+ *
+ * A failed settings read degrades to `undefined`, which means legacy orders
+ * under-withhold rather than the whole refund failing. That is the safer
+ * direction for the buyer and it is visible: the residue shows up as an order
+ * stuck short of `refunded`, which R5 in `paymentReconcile` reports.
+ */
+import { siteSettingsRepository } from "../../../../features/admin/repository/site-settings.repository.js";
+import { refundCapacity, } from "../../../shared/checkout/refundable-base.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+export async function resolveRefundCapacity(order) {
+    const settings = await siteSettingsRepository.getSingleton().catch((err) => {
+        void normalizeError(err);
+        return null;
+    });
+    return refundCapacity(order, settings?.commissions?.gstPercent);
+}