@mohasinac/appkit 4.58.0 → 4.60.0

package/dist/_internal/server/features/order-completion/actions.js

@@ -0,0 +1,336 @@
+"use server";
+/**
+ * Order completion — per-item ratings, and the two ways an order completes.
+ *
+ * ## The owner's rule, 2026-10-21
+ *
+ * > *"Points only get issued on successful purchases after buyer put reviews…
+ * > they are also assigned if the user [raises] no issues or updates after 7
+ * > days of delivery — no further disputes should be entertained as well."*
+ *
+ * > *"Auto assigned after 7 days of delivery, when order is marked complete; if
+ * > review is given and order marked complete by the buyer before — immediate
+ * > disburse."*
+ *
+ * > *"Like in Zomato, each item of the order can be individually rated and a
+ * > comment can be given — use that."*
+ *
+ * So completion has exactly two writers, and they are not equivalent:
+ *
+ * | writer | when | effect |
+ * |---|---|---|
+ * | `obligationSweep` (`order-complete`) | 7 days after delivery, nothing contested | completes; points award |
+ * | `markOrderCompleteAction` | the buyer, having rated at least one item | completes NOW; **immediate disburse** |
+ *
+ * 🛑 **The "immediate disburse" half needs no extra mechanism, and that is the
+ * nicest property of the design.** `payout-release` is already
+ * `blockedBy: ["order-complete", …]`, so a buyer completing early opens the
+ * seller's payout gate early as a CONSEQUENCE rather than as a second
+ * decision. The buyer confirming satisfaction is precisely the signal a quiet
+ * period exists to wait for — so when it arrives, waiting out the rest of the
+ * period is pure dead time for the seller.
+ */
+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, ConflictError } from "../../../../errors/index.js";
+import { orderRepository } from "../../../../features/orders/repository/orders.repository.js";
+import { reviewRepository } from "../../../../features/reviews/repository/reviews.repository.js";
+import { obligationsRepository } from "../../../../features/obligations/repository/obligations.repository.js";
+import { awardPurchasePoints } from "../points/award.js";
+/**
+ * Which lines of this order the buyer may rate, and which they already have.
+ *
+ * 🛑 Reads the buyer's OWN reviews (`findByUser`) rather than each product's
+ * reviews (`findByProduct`). A product can carry thousands of reviews and a
+ * buyer carries a handful, so this is bounded by the right dimension —
+ * `findByProduct` on a popular bey would be an unbounded read to answer a
+ * question about one person (Rule #6).
+ */
+export async function getRateableItemsAction(orderId) {
+    return wrapAction(async () => {
+        const user = await requireRoleUser(["user", "buyer", "seller", "admin"]);
+        const order = await orderRepository.findById(orderId);
+        if (!order)
+            throw new NotFoundError(`Order ${orderId} not found`);
+        if (order.userId !== user.uid) {
+            throw new ValidationError("You can only rate your own order.");
+        }
+        const mine = await reviewRepository.findByUser(user.uid);
+        const byLine = new Map();
+        const byProduct = new Map();
+        for (const r of mine) {
+            if (r.orderId !== orderId)
+                continue;
+            if (r.orderItemId)
+                byLine.set(r.orderItemId, r.rating);
+            byProduct.set(r.productId, r.rating);
+        }
+        return orderLinesOf(order).map((line) => {
+            /*
+             * Line id first, product id as the fallback — a review written before
+             * `orderItemId` existed can only be matched by product, and treating it
+             * as "not rated" would ask the buyer to rate something twice.
+             */
+            const existing = byLine.get(line.orderItemId) ?? byProduct.get(line.productId);
+            return {
+                ...line,
+                ...(existing !== undefined ? { existingRating: existing } : {}),
+            };
+        });
+    });
+}
+/**
+ * The order's rateable lines.
+ *
+ * 🛑 `items[]` is OPTIONAL on `OrderDocument` — the flat
+ * `productId`/`productTitle`/`quantity`/`unitPrice` fields are the primary
+ * shape, not legacy residue (CLAUDE.md corrected this on 2026-10-03 after the
+ * opposite was assumed for months). So both shapes are handled, and the flat
+ * one synthesises a line id from the order itself.
+ */
+function orderLinesOf(order) {
+    /*
+     * 🛑 `OrderDocumentItem` HAS NO `itemId` — verified against the interface,
+     * which carries `productId`/`productTitle`/`quantity`/`unitPrice`/`totalPrice`
+     * and no identity of its own. So a line id has to be synthesised, and the
+     * obvious synthesis is wrong.
+     *
+     * An INDEX-based id (`${order.id}__${index}`) shifts the moment a line is
+     * cancelled or the array is rewritten — and `expandCartLineToOrderRows` fans
+     * a grouped line into N rows, so rewrites happen. A rating would then attach
+     * to a different product than the one it was written about. That is the
+     * merge-by-index hazard the lottery-slot fix is about, one feature over.
+     *
+     * Keyed on `productId` plus an occurrence counter instead: stable under
+     * reordering and under the removal of OTHER lines, and only ambiguous if two
+     * rows of the SAME product change relative order — which is both rarer and
+     * deterministic, since the counter follows array order within that product.
+     */
+    if (order.items?.length) {
+        const seen = new Map();
+        return order.items.map((item) => {
+            const n = seen.get(item.productId) ?? 0;
+            seen.set(item.productId, n + 1);
+            return {
+                orderItemId: `${order.id}__${item.productId}__${n}`,
+                productId: item.productId,
+                productTitle: item.productTitle ?? item.productId,
+            };
+        });
+    }
+    /*
+     * The FLAT shape. `items[]` is optional and the flat
+     * `productId`/`productTitle` fields are the primary form, not legacy residue
+     * — CLAUDE.md corrected the opposite assumption on 2026-10-03 after it had
+     * stood for months.
+     */
+    if (!order.productId)
+        return [];
+    return [
+        {
+            orderItemId: `${order.id}__${order.productId}__0`,
+            productId: order.productId,
+            productTitle: order.productTitle ?? order.productId,
+        },
+    ];
+}
+/**
+ * Rate ONE line of an order — the Zomato-style per-item review.
+ *
+ * 🛑 Gated on DELIVERY, not on completion. A buyer must be able to rate before
+ * marking the order complete, because rating is the precondition for the fast
+ * completion path — gating it on completion would make the fast path
+ * unreachable, which is a circular dependency that would look like a bug in
+ * the button.
+ */
+export async function rateOrderItemAction(input) {
+    return wrapAction(async () => {
+        const user = await requireRoleUser(["user", "buyer", "seller", "admin"]);
+        if (!Number.isInteger(input.rating) || input.rating < 1 || input.rating > 5) {
+            throw new ValidationError("A rating must be a whole number from 1 to 5.");
+        }
+        const comment = input.comment?.trim() ?? "";
+        if (comment.length < 5) {
+            throw new ValidationError("Please say a little about this item — at least a few words.");
+        }
+        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 rate your own order.");
+        }
+        if (!order.deliveryDate) {
+            throw new ValidationError("This order has not been delivered yet, so there is nothing to rate.");
+        }
+        const line = orderLinesOf(order).find((l) => l.orderItemId === input.orderItemId);
+        if (!line) {
+            throw new NotFoundError(`Order ${input.orderId} has no line ${input.orderItemId}`);
+        }
+        /*
+         * One rating per line. Checked against the buyer's own reviews, which is
+         * the same bounded read `getRateableItemsAction` uses.
+         *
+         * 🛑 A 409 rather than an overwrite: editing a published review is a
+         * different operation with its own moderation implications, and silently
+         * replacing one would let a buyer revise a 1-star to a 5-star after a
+         * seller contacted them, with no trace that it had changed.
+         */
+        const mine = await reviewRepository.findByUser(user.uid);
+        const already = mine.find((r) => r.orderId === input.orderId &&
+            (r.orderItemId === input.orderItemId || r.productId === line.productId));
+        if (already) {
+            throw new ConflictError("You have already rated this item. Edit your existing review rather than adding a second one.");
+        }
+        /*
+         * `createReview`, not `create` — the repository's own method, which mints
+         * the semantic review id and sets `status: "pending"` so a rating enters
+         * moderation exactly as any other review does. A per-item rating is not a
+         * privileged class of review.
+         */
+        const review = await reviewRepository.createReview({
+            productId: line.productId,
+            productTitle: line.productTitle,
+            userId: user.uid,
+            /* `name`, not `displayName` — AuthPayload carries the Google "name"
+               claim under that key and has no `displayName` at all. */
+            userName: user.name ?? user.email ?? "Buyer",
+            rating: input.rating,
+            title: input.title?.trim() || line.productTitle,
+            comment,
+            ...(input.images?.length ? { images: input.images, hasImages: true } : {}),
+            /*
+             * The link that did not exist. `orderId` + `orderItemId` are what make
+             * "was this order rated" answerable, and `isVerifiedPurchase` is finally
+             * written by something — it was read in two places and written by
+             * nothing, so no review has ever been attributable to a purchase.
+             */
+            orderId: order.id,
+            orderItemId: line.orderItemId,
+            isVerifiedPurchase: true,
+            ...(order.storeId ? { storeId: order.storeId } : {}),
+        });
+        serverLogger.info("order item rated", {
+            orderId: order.id,
+            orderItemId: line.orderItemId,
+            rating: input.rating,
+        });
+        return { reviewId: review.id };
+    });
+}
+/**
+ * The buyer marks the order complete — the FAST path.
+ *
+ * Requires at least one rated line, per the owner's rule (*"if review is given
+ * and order marked complete by the buyer"*).
+ *
+ * 🛑 **At least one, not all.** Requiring every line would make a six-item
+ * order's completion hostage to the one item the buyer has no opinion about —
+ * and the buyer's alternative is simply to wait 7 days and be completed
+ * automatically with no review at all, which is strictly worse for everyone.
+ * One rating is the signal; demanding six is a toll.
+ *
+ * 🛑 It REFUSES while anything is contested, and the check is the obligation
+ * policy's own `precondition` rather than a second hand-written copy — so the
+ * buyer-initiated path and the 7-day sweep cannot disagree about what "nothing
+ * contested" means.
+ */
+export async function markOrderCompleteAction(orderId) {
+    return wrapAction(async () => {
+        const user = await requireRoleUser(["user", "buyer", "seller", "admin"]);
+        const order = await orderRepository.findById(orderId);
+        if (!order)
+            throw new NotFoundError(`Order ${orderId} not found`);
+        if (order.userId !== user.uid) {
+            throw new ValidationError("You can only complete your own order.");
+        }
+        if (order.completedAt) {
+            throw new ConflictError("This order is already marked complete.");
+        }
+        if (!order.deliveryDate) {
+            throw new ValidationError("This order has not been delivered yet. You can mark it complete once it arrives.");
+        }
+        /*
+         * Nothing contested. Deliberately mirrors `order-complete`'s precondition
+         * — a buyer must not be able to close the dispute window on an order they
+         * have an open return or refund against, which would be them waiving a
+         * claim by pressing a button labelled "mark complete".
+         */
+        if (order.status === "return_requested" ||
+            order.status === "returned" ||
+            order.returnRequestedAt ||
+            order.disputeRaised ||
+            (order.refunds?.length ?? 0) > 0) {
+            throw new ValidationError("This order has an open return, refund or dispute. It will complete once that is resolved.");
+        }
+        const mine = await reviewRepository.findByUser(user.uid);
+        const ratedThisOrder = mine.some((r) => r.orderId === orderId);
+        if (!ratedThisOrder) {
+            throw new ValidationError("Please rate at least one item from this order first — that is what lets us close it now rather than waiting out the 7-day window.");
+        }
+        const now = new Date();
+        await orderRepository.update(orderId, {
+            completedAt: now,
+            completedBy: user.uid,
+        });
+        /*
+         * Close the timer, so the sweep does not re-fire on an order the buyer has
+         * already closed. `met`, not `acted`: the thing the obligation was waiting
+         * for HAPPENED, which is exactly what that state means.
+         */
+        await obligationsRepository().close(orderId, "order-complete", {
+            state: "met",
+            closeReason: `the buyer marked the order complete after rating it`,
+            now,
+        });
+        /*
+         * 🛑 The payout gate opens as a CONSEQUENCE, not as a second write.
+         * `payout-release` is `blockedBy: ["order-complete", …]`, so closing the
+         * obligation above is what unblocks it — which is the "immediate disburse"
+         * the owner asked for, with no extra mechanism and no second place to keep
+         * in step.
+         */
+        const stillBlocking = await obligationsRepository().listOpenForSubject(orderId);
+        const payoutUnblocked = !stillBlocking.some((o) => o.kind !== "payout-release");
+        serverLogger.warn("order marked complete by buyer — fast path", {
+            orderId,
+            payoutUnblocked,
+            stillOpen: stillBlocking.map((o) => o.kind),
+        });
+        /*
+         * ── THE POINTS AWARD (Phase P, 2026-10-21) ────────────────────────────
+         *
+         * Now written, because the key it needed exists: `awardPurchasePoints`
+         * checks `order.pointsAwardedAt` and writes it alongside the credit, which
+         * is what makes a double fire safe. This path and the 7-day sweep both
+         * call the same function — and a double call is the NORMAL case here, not
+         * an edge, because a buyer completing early means the sweep later finds an
+         * order already complete.
+         *
+         * 🛑 Best-effort, and awaited rather than fire-and-forget. Awaited so the
+         * response can honestly say points were credited; best-effort because the
+         * order IS complete and the buyer has been told so — failing the whole
+         * action over the credit would leave them unable to retry a completion
+         * that already happened. A miss is recoverable (the sweep re-attempts on
+         * its next tick, keyed) and loud.
+         */
+        let pointsAwarded = 0;
+        try {
+            const award = await awardPurchasePoints({
+                ...order,
+                completedAt: now,
+                completedBy: user.uid,
+            });
+            pointsAwarded = award.awarded;
+        }
+        catch (err) {
+            void normalizeError(err);
+            serverLogger.error("order completed but points were NOT credited", {
+                orderId,
+                userId: user.uid,
+            });
+        }
+        return { completedAt: now.toISOString(), payoutUnblocked, pointsAwarded };
+    });
+}

package/dist/_internal/server/features/order-completion/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * order-completion — server surface.
+ *
+ * The buyer's side of the owner's 2026-10-21 rule: per-item ratings
+ * (Zomato-style) and the fast completion path they unlock.
+ */
+export { getRateableItemsAction, rateOrderItemAction, markOrderCompleteAction, type RateableOrderItem, type RateOrderItemInput, } from "./actions";

package/dist/_internal/server/features/order-completion/index.js

@@ -0,0 +1,7 @@
+/**
+ * order-completion — server surface.
+ *
+ * The buyer's side of the owner's 2026-10-21 rule: per-item ratings
+ * (Zomato-style) and the fast completion path they unlock.
+ */
+export { getRateableItemsAction, rateOrderItemAction, markOrderCompleteAction, } from "./actions.js";

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

@@ -1,5 +1,18 @@
 import { type ActionResult } from "@mohasinac/appkit/server";
 export declare function createOrderAction(input: unknown): Promise<ActionResult<unknown>>;
+/**
+ * Cancel an order, and give the money back if any was taken (D14).
+ *
+ * 🛑 `assertOrderCancellable` already RETURNS the order it validated, and this
+ * threw that away and let `cancelOrder` fetch it again. Reusing it saves a read
+ * on every cancellation and — more importantly — means the refund is decided
+ * against the same document the ownership and dispatch checks ran on, rather
+ * than against a re-read that could have moved in between.
+ *
+ * The response shape widened from the bare order to `{ order, refund }`. The
+ * order alone could not express the thing a buyer most needs to know, which is
+ * whether their money is coming back automatically or waiting on a human.
+ */
 export declare function cancelOrderAction(input: unknown): Promise<ActionResult<unknown>>;
 /**
  * Buyer requests a return on a delivered order.

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

@@ -6,6 +6,7 @@ import { createOrderSchema, updateOrderStatusSchema, cancelOrderSchema, returnRe
 import { isFinalSaleExempt } from "../../../shared/features/orders/return-reasons.js";
 import { REFUND_COPY } from "../../../shared/features/orders/refund-copy.js";
 import { assertOrderCancellable, assertReturnWindowOpen } from "./service.js";
+import { cancelOrderWithRefund } from "./cancellation-refund.js";
 import { ValidationError } from "../../../shared/errors/index.js";
 import { OrderNotFoundError, OrderOwnershipError } from "../../../shared/features/orders/errors.js";
 import { isAdminUser, isModeratorUser } from "../../../../features/auth/role-predicates.js";
@@ -14,6 +15,13 @@ import { restoreStockForOrder } from "../checkout/stock-restore.js";
 import { getAdminDb } from "../../../../providers/db-firebase/index.js";
 import { enqueueJob } from "../../../../features/jobs/actions/enqueue-job.js";
 import { PAYMENT_WINDOW_MS, PAYMENT_FRAUD_REJECTED_REASON, isManualPaymentMethod } from "../../../../features/orders/constants/payment-window.js";
+/*
+ * The dispute cutoff is DERIVED from the `order-complete` policy, never read
+ * off a stored flag — one definition of "7 days after delivery", shared with
+ * the sweep that closes the window and with whatever page tells the buyer when
+ * it closes.
+ */
+import { deadlinesFor } from "../../../shared/obligations/deadlines.js";
 import { normalizeError } from "../../../../errors/normalize.js";
 import { serverLogger } from "../../../../monitoring/index.js";
 export async function createOrderAction(input) {
@@ -29,14 +37,32 @@ export async function createOrderAction(input) {
         });
     });
 }
+/**
+ * Cancel an order, and give the money back if any was taken (D14).
+ *
+ * 🛑 `assertOrderCancellable` already RETURNS the order it validated, and this
+ * threw that away and let `cancelOrder` fetch it again. Reusing it saves a read
+ * on every cancellation and — more importantly — means the refund is decided
+ * against the same document the ownership and dispatch checks ran on, rather
+ * than against a re-read that could have moved in between.
+ *
+ * The response shape widened from the bare order to `{ order, refund }`. The
+ * order alone could not express the thing a buyer most needs to know, which is
+ * whether their money is coming back automatically or waiting on a human.
+ */
 export async function cancelOrderAction(input) {
     return wrapAction(async () => {
         const user = await requireRoleUser(["user", "buyer", "seller", "admin"]);
         const parsed = cancelOrderSchema.safeParse(input);
         if (!parsed.success)
             throw new ValidationError(parsed.error.issues[0]?.message ?? "Invalid input");
-        await assertOrderCancellable(parsed.data.orderId, user.uid);
-        return orderRepository.cancelOrder(parsed.data.orderId, parsed.data.reason ?? "Cancelled by user");
+        const order = await assertOrderCancellable(parsed.data.orderId, user.uid);
+        return cancelOrderWithRefund(order, {
+            reason: parsed.data.reason ?? "Cancelled by user",
+            actorUid: user.uid,
+            actorRole: "buyer",
+            trigger: "cancelOrderAction",
+        });
     });
 }
 /**
@@ -375,6 +401,34 @@ export async function raiseOrderDisputeAction(orderId, reason) {
         }
         if (order.disputeStatus === "open")
             return; // idempotent
+        /*
+         * ── THE DISPUTE CUTOFF ────────────────────────────────────────────────
+         *
+         * Owner's rule, 2026-10-21: *"after 7 days of delivery no further disputes
+         * should be entertained."*
+         *
+         * 🛑 Enforced here, at the one place a dispute is RAISED, rather than in
+         * the sweep — because a cutoff is a refusal, and a refusal has to live
+         * where the request arrives. The `order-complete` obligation firing records
+         * that the window shut; this is what makes the record mean something.
+         *
+         * 🛑 It closes the door to NEW disputes ONLY. An existing dispute, an
+         * in-flight return, or a refund already posted are all untouched — the
+         * `order-complete` precondition refuses to fire while any of those is live,
+         * so by construction this cutoff can only exist on an order where nothing
+         * was ever contested. Reading the rule as "everything closes at 7 days"
+         * would cancel a return the buyer raised on day 6, which is the opposite of
+         * what a dispute window is for.
+         *
+         * Derived from `deliveryDate` rather than read off a stored flag, for the
+         * same reason every other deadline here is derived: a stored
+         * `disputeWindowClosed` boolean would need a backfill and would drift from
+         * the policy the day the duration changed (Root Cause #42).
+         */
+        const completion = deadlinesFor(order).find((d) => d.kind === "order-complete");
+        if (completion && completion.dueAt.getTime() <= Date.now()) {
+            throw new ValidationError(`The dispute window for this order closed on ${completion.dueAt.toLocaleDateString("en-IN")} — 7 days after delivery. Contact support if you believe this is wrong.`);
+        }
         await orderRepository.update(orderId, {
             disputeRaised: true,
             disputeRaisedBy: user.uid,

package/dist/_internal/server/features/orders/adapters.js

@@ -228,6 +228,32 @@ export function orderDocumentToOrder(doc) {
         autoApproved: doc.autoApproved,
         disputeRaised: doc.disputeRaised,
         disputeStatus: doc.disputeStatus,
+        /*
+         * Completion, and the two anchors `OrderCompletionPanel` needs to decide
+         * whether anything is contested.
+         *
+         * 🛑 Mapped in the SAME change as the client type, because the failure mode
+         * of mapping neither — or one — is invisible. With `completedAt` undefined
+         * the panel renders its rating UI forever and never confirms completion,
+         * which reads as ordinary behaviour; with `returnRequestedAt` undefined it
+         * offers "Mark complete" on an order with a live return, the server refuses
+         * it, and the buyer gets an error for pressing a button we showed them.
+         *
+         * This is the field-by-field repeat of the manual-payment incident four
+         * lines below: `paymentStatus` was mapped, nothing else payment-related
+         * was, and the whole proof-upload flow was dead for every buyer while the
+         * page politely said it did not apply.
+         */
+        completedAt: toIsoOrUndefined(doc.completedAt),
+        completedBy: doc.completedBy,
+        returnRequestedAt: toIsoOrUndefined(doc.returnRequestedAt),
+        /*
+         * A COUNT, not the events. The panel needs one bit — has any money already
+         * moved — and `refunds[]` carries staff uids, gateway refund ids and
+         * operator-facing reason strings. Publishing those to a buyer's page to
+         * answer a yes/no question is the spread-and-publish shape (Root Cause #70).
+         */
+        refundCount: doc.refunds?.length ?? 0,
         // Manual-payment (cash / UPI / EMI) passthrough. These were previously
         // dropped here, which silently disabled the entire buyer proof-upload
         // flow: `/user/orders/[id]/payment` branches on `paymentMethod` and so

package/dist/_internal/server/features/orders/cancellation-refund.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Cancel an order AND give the money back — one owner, three callers.
+ *
+ * ## D14, and why passing the amount was only half of it
+ *
+ * `cancelOrder(orderId, reason, refundAmount?)` has carried an optional
+ * `refundAmount` since it was written, and **all four callers omitted it**. So
+ * cancelling a *paid* order restored stock and left the money with us, while
+ * `previewCancellationRefund` showed the buyer a figure nothing honoured.
+ *
+ * 🛑 **But passing the amount alone would have made it WORSE.** `cancelOrder`'s
+ * body writes `{ refundAmount, refundStatus: "pending" }` and nothing else —
+ * there is no provider call anywhere in it. So the obvious fix creates a *new*
+ * dead state: a recorded refund intent that nothing ever settles, which is
+ * strictly worse than today's honest silence because it reads, in the database,
+ * as though a refund is on its way. The amount and the movement have to land
+ * together, which is why this module exists rather than a one-line edit at each
+ * call site.
+ *
+ * ## The decision table
+ *
+ * Every row cancels the order and **restores its stock** — see `releaseStock`,
+ * which closes a second half of D14 the plan had recorded backwards. The table
+ * is only about the money.
+ *
+ * | condition | what happens to the money |
+ * |---|---|
+ * | `paymentStatus !== "paid"` | **nothing** — nothing was ever captured |
+ * | nothing left refundable | nothing — already refunded in full |
+ * | goods have left the seller | intent recorded, **case opened** — a human decides |
+ * | paid by cash / UPI-manual / EMI | intent recorded, **case opened** — there is no automatic rail |
+ * | paid through the gateway | **refunded automatically**, in full, once |
+ *
+ * The last row is the only automatic money movement, and it satisfies the
+ * plan's guardrail for one: the ceiling is an amount we captured, the recipient
+ * is the payer, and no counterparty is debited.
+ *
+ * ## Three things that are load-bearing
+ *
+ * **It goes through `processRefundAction`, never `payment.refund()` directly.**
+ * That action owns the idempotency claim, the cumulative cap against
+ * `refundableBase`, and the two-phase reserve/settle write around the provider
+ * call. A direct provider call here would reintroduce every defect step 8
+ * closed — D1, D2, D6 and D7 at once.
+ *
+ * **The key is `cancel_{orderId}`** — a NATURAL key, so a double-clicked Cancel
+ * button, a retried server action and a sweep all collapse to one refund. A
+ * `randomUUID()` here would be D2 wearing a new name.
+ *
+ * ## Points ARE reversed here now (Phase P)
+ *
+ * `pointsLedger`'s own header states the rule as a legal boundary: *"points
+ * spent on a cancelled order are returned as points"* — never as money, because
+ * paying them out in rupees is what would make this stored value, which in
+ * India is PPI territory with RBI authorisation attached.
+ *
+ * `reverseRedemptionForOrder` is that rule's first writer; the kind had been
+ * declared with none since it was written (D48). It is idempotent on the order
+ * — one reversal per order, checked by query before the write, because an
+ * append-only ledger cannot net off a double reversal.
+ *
+ * 🛑 It is a NO-OP today and still correct to call. No order has ever consumed
+ * points: the one code path that redeemed any was deleted on 2026-10-21
+ * because it debited the buyer without reducing the charge (D46 — see the note
+ * at its former site in `checkout/actions.ts`), and it had no caller, route
+ * field or UI tender before that. So the query finds no redemption and returns
+ * `{ reversed: 0 }`.
+ * Wiring it now rather than later is the cheap half — the expensive half is the
+ * ledger write, which is already keyed. When redemption becomes a real tender,
+ * cancellation already gives the points back instead of needing to remember to.
+ *
+ * **Cancel, then stock, then money.** The cancellation is the urgent half and
+ * must not be held hostage to a gateway round trip; the restock is a local
+ * write another buyer is actively waiting on; the refund is the one step that
+ * can hang for a full network timeout. The cost of that ordering is a window
+ * where the order is `cancelled` with the money still held — which is exactly
+ * why `refundAmount` is written *at cancellation time*, before the provider is
+ * called: a crash in the window leaves a detectable artefact rather than
+ * nothing, and R5 in `paymentReconcile` is the thing that finds it. The reverse
+ * ordering has no such consolation, because a refund posted against a live
+ * order that then fails to cancel is money gone from an order the buyer still
+ * expects to receive.
+ */
+import type { OrderDocument } from "../../../../features/orders/schemas/firestore";
+import type { CancellationRefundOutcome } from "../../../../features/orders/types/index";
+import type { HistoryActor } from "../../../shared/history/types";
+export interface CancelWithRefundOptions {
+    reason: string;
+    /**
+     * The uid of whoever asked for this — a buyer, a seller, or an admin.
+     *
+     * 🛑 OPTIONAL, and omitted by the obligation sweep on purpose.
+     * `HistoryActor.uid`'s own doc says it is "absent for `system` (cron jobs,
+     * Firestore triggers)", so stamping a literal `"system"` into a field that
+     * otherwise only ever holds Firebase uids would make `actorUid === someUid`
+     * comparisons quietly wrong and would read, in a timeline, as a user account
+     * named system.
+     */
+    actorUid?: string;
+    actorRole: HistoryActor["role"];
+    /** Overrides the history trigger label with the calling path's name. */
+    trigger?: string;
+}
+export interface CancelWithRefundResult {
+    order: OrderDocument;
+    refund: CancellationRefundOutcome;
+}
+/**
+ * Cancel an order and settle whatever money that owes.
+ *
+ * Callers pass the order they have already fetched and authorised. That is not
+ * only a saved read: the authorisation differs per caller (a buyer owns the
+ * order, a seller owns the store, an admin owns neither) and this function must
+ * not be the place that decides it.
+ */
+export declare function cancelOrderWithRefund(order: OrderDocument, opts: CancelWithRefundOptions): Promise<CancelWithRefundResult>;