@mohasinac/appkit 4.59.0 → 4.60.0

package/dist/features/orders/actions/refund-actions.js

@@ -10,8 +10,14 @@ import { serverLogger } from "../../../monitoring/index.js";
 import { orderRepository } from "../../orders/repository/orders.repository.js";
 import { RefundStatusValues } from "../../orders/schemas/index.js";
 import { siteSettingsRepository } from "../../admin/repository/site-settings.repository.js";
+/*
+ * One owner for "how much of the platform fee is withheld". Shared with the
+ * cumulative refund cap, so the figure SHOWN to the buyer and the money
+ * actually withheld cannot diverge — they did: this file showed a net figure
+ * while `cancelOrder` moved no money at all (D14).
+ */
+import { platformFeeWithheld, refundCapacity, } from "../../../_internal/shared/checkout/refundable-base.js";
 import { sendNotification } from "../../admin/actions/notification-actions.js";
-const DEFAULT_PLATFORM_FEE_PERCENT = 5;
 const DEFAULT_GST_PERCENT = 18;
 export async function issuePartialRefund(adminUid, orderId, deductFees, refundNote) {
     const order = await orderRepository.findById(orderId);
@@ -22,13 +28,37 @@ export async function issuePartialRefund(adminUid, orderId, deductFees, refundNo
     if (order.refundStatus === RefundStatusValues.COMPLETED)
         throw new ValidationError("Order has already been fully refunded.");
     const settings = await siteSettingsRepository.getSingleton();
-    const platformFeePercent = settings.commissions?.platformFeePercent ?? DEFAULT_PLATFORM_FEE_PERCENT;
     const gstPercent = settings.commissions?.gstPercent ?? DEFAULT_GST_PERCENT;
-    const effectiveRate = platformFeePercent * (1 + gstPercent / 100);
+    /*
+     * ── D32: THE SINGLE WORST MONEY DEFECT IN THE AUDIT ─────────────────────
+     *
+     * This computed a PERCENTAGE OF THE REFUND:
+     *
+     *     const effectiveRate = platformFeePercent * (1 + gstPercent / 100);
+     *     const feeDeducted   = (grossRefund * effectiveRate) / 100;
+     *
+     * which ignores `commissions.platformFeeMax` (default **₹10**) entirely, and
+     * ignores `order.platformFee` — the amount that was ACTUALLY COLLECTED and
+     * is stored on the order.
+     *
+     * Measured on a ₹5,000 order at 2% + 18% GST: it deducted **₹118** from a
+     * buyer who had paid **₹11.80**, keeping ~₹106.20 of their GOODS money and
+     * labelling it a platform fee. The error grows with order value, so it was
+     * largest exactly where a buyer would notice.
+     *
+     * 🛑 `platformFeeWithheld` returns the fee as CHARGED, never a recomputed
+     * rate, and it is shared with the cumulative refund cap — so the figure
+     * SHOWN to the buyer here and the money actually withheld now come from one
+     * place. They did not before: this function showed a net figure while
+     * `cancelOrder` moved no money at all (D14).
+     *
+     * `gstPercent` is passed only as the LEGACY fallback, for orders written
+     * before `platformFeeGst` was persisted (2026-10-21). An order that carries
+     * the field ignores it entirely — which is the point, since reading today's
+     * rate for a historical order is the mistake this replaces.
+     */
     const grossRefund = order.totalPrice;
-    const feeDeducted = deductFees
-        ? parseFloat(((grossRefund * effectiveRate) / 100).toFixed(2))
-        : 0;
+    const feeDeducted = deductFees ? platformFeeWithheld(order, gstPercent) : 0;
     const netRefund = parseFloat((grossRefund - feeDeducted).toFixed(2));
     await orderRepository.update(orderId, {
         refundStatus: "processing",
@@ -75,12 +105,42 @@ export async function previewCancellationRefund(userId, orderId) {
     if (order.paymentStatus !== "paid")
         return null;
     const settings = await siteSettingsRepository.getSingleton();
-    const platformFeePercent = settings.commissions?.platformFeePercent ?? DEFAULT_PLATFORM_FEE_PERCENT;
     const gstPercent = settings.commissions?.gstPercent ?? DEFAULT_GST_PERCENT;
-    const effectiveRate = platformFeePercent * (1 + gstPercent / 100);
+    /*
+     * 🛑 A SECOND COPY of D32 lived here, and the plan only named one.
+     *
+     * Identical arithmetic to the function above — `platformFeePercent × (1 +
+     * gstPercent/100)` applied to the whole refund, ignoring the ₹10 cap and the
+     * stored `order.platformFee`. And this is the WORSE of the two, because this
+     * is the function whose output is shown to the BUYER before they confirm a
+     * cancellation: it quoted a net refund ₹106 short on a ₹5,000 order.
+     *
+     * Found by grepping for the shape rather than the name — the plan cited
+     * `refund-actions.ts:104-110`, which is the other one. Root Cause #75's
+     * lesson exactly: a rule reachable by copy-paste gets copied, and the copy
+     * is not found by searching for the function that was supposed to own it.
+     *
+     * ── 2026-10-21: and `refundCapacity`, not `totalPrice − withheld` ─────────
+     *
+     * 🛑 The net figure now subtracts refunds ALREADY COMMITTED on this order,
+     * because `cancelOrderWithRefund` moves exactly `refundCapacity().remaining`
+     * — so if these two expressions differ, the number shown to the buyer is not
+     * the number that moves, which is the whole defect D14 is about.
+     *
+     * They differ on precisely one order: a partially-refunded one. The old
+     * expression ignored prior refunds, so cancelling an order that had already
+     * had a line refunded quoted the buyer the full base a second time. That
+     * would not have over-paid — `reserveRefund`'s transactional cap refuses it
+     * — but it would have quoted a figure and then failed, which is a worse
+     * experience than quoting the right one.
+     *
+     * On an order with no prior refunds the two are identical, so nothing changes
+     * for the common case.
+     */
+    const capacity = refundCapacity(order, gstPercent);
     const grossRefund = order.totalPrice;
-    const feeDeducted = parseFloat(((grossRefund * effectiveRate) / 100).toFixed(2));
-    const netRefund = parseFloat((grossRefund - feeDeducted).toFixed(2));
+    const feeDeducted = capacity.withheld;
+    const netRefund = capacity.remaining;
     return {
         orderId,
         grossRefund,

package/dist/features/orders/components/OrderCompletionPanel.d.ts

@@ -0,0 +1,27 @@
+export interface RateableLine {
+    orderItemId: string;
+    productId: string;
+    productTitle: string;
+    existingRating?: number;
+}
+export interface OrderCompletionPanelProps {
+    orderId: string;
+    /** `/api/user/orders/{id}/completion`. Injected so appkit owns no route map. */
+    endpoint: string;
+    /** Already complete — the panel then only confirms it. */
+    completedAt?: string | null;
+    /** Who closed it: the buyer's uid, or `"system"` for the 7-day sweep. */
+    completedBy?: string | null;
+    /** Delivered? Nothing can be rated or completed before the parcel arrives. */
+    isDelivered: boolean;
+    /**
+     * Anything contested — an open return, refund or dispute.
+     *
+     * The server refuses in that case regardless; this suppresses the panel so
+     * the buyer is not offered a button that would be refused, and is told why.
+     */
+    isContested?: boolean;
+    /** Called after a successful completion, so the page can refresh the order. */
+    onCompleted?: () => void;
+}
+export declare function OrderCompletionPanel({ orderId, endpoint, completedAt, completedBy, isDelivered, isContested, onCompleted, }: OrderCompletionPanelProps): import("react").JSX.Element | null;

package/dist/features/orders/components/OrderCompletionPanel.js

@@ -0,0 +1,192 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * OrderCompletionPanel — rate the lines, then close the order.
+ *
+ * ## The owner's rule, and why this panel is the only way to use it
+ *
+ * *"points only get issued on successful purchases after buyer put reviews,
+ * then only… they are also assigned if the user [raises] no issues or updates
+ * after 7 days of delivery"*, and then: *"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."*
+ *
+ * So completion has two writers converging on one fact (`completedAt`): the
+ * 7-day `order-complete` obligation, and this. Both were built — the sweep,
+ * the dispute cutoff, the per-item review link, `markOrderCompleteAction` — and
+ * **the buyer had no UI for any of it.** A grep for `markOrderCompleteAction`
+ * across the app returned two hits, both my own comments. This is the surface
+ * that makes the rule usable rather than merely implemented.
+ *
+ * ## 🛑 ≥1 rated line, never all of them
+ *
+ * Requiring every line makes a six-item order's completion hostage to the one
+ * item the buyer has no opinion about — and their alternative is to wait seven
+ * days and be completed automatically with **no** review, which is worse for
+ * everyone. One rating is the signal; demanding six is a toll. The server
+ * enforces the same rule, so this is the affordance, not the gate.
+ *
+ * ## 🛑 The button says what it DOES, all four consequences
+ *
+ * Completing closes the dispute window, releases the seller's payout and
+ * awards points. A buyer pressing "Mark complete" without being told that it
+ * ends their ability to raise a new dispute would be waiving a right by
+ * pressing a button labelled as housekeeping. `payout-release` is
+ * `blockedBy: ["order-complete"]`, so the early release is a CONSEQUENCE of
+ * this press rather than a second decision — which is precisely why it has to
+ * be disclosed here.
+ *
+ * ## Per LINE, not per product (the Zomato shape)
+ *
+ * `orderItemId` is `${orderId}__${productId}__${n}`, so the same product
+ * ordered twice is two ratings. `ReviewDocument` was already per-product; what
+ * it lacked was any link to the ORDER — no `orderId` anywhere, and
+ * `isVerifiedPurchase` was read in two places and written by nothing, so a
+ * review had never been attributable to a purchase.
+ *
+ * EXPORTS: OrderCompletionPanel, type OrderCompletionPanelProps
+ *
+ * @tag domain:orders,reviews
+ * @tag layer:component
+ * @tag pattern:form
+ * @tag access:client
+ * @tag consumers:user/orders/[id]
+ * @tag sideEffects:network
+ */
+import { useCallback, useEffect, useState } from "react";
+import { Alert } from "../../../ui/components/Alert.js";
+import { Button } from "../../../ui/components/Button.js";
+/*
+ * `Div` has its OWN module; `Row` and `Stack` are in `Layout`. Imported from
+ * the defining modules rather than the `ui` barrel — Root Cause #18, and the
+ * barrel is also what the build-weight work is unwinding.
+ */
+import { Div } from "../../../ui/components/Div.js";
+import { Icon } from "../../../ui/components/Icon.js";
+import { Row, Stack } from "../../../ui/components/Layout.js";
+import { Text } from "../../../ui/components/Typography.js";
+import { Textarea } from "../../../ui/components/Textarea.js";
+import { Skeleton } from "../../../ui/components/Skeleton.js";
+import { normalizeError } from "../../../errors/normalize.js";
+const MIN_COMMENT = 10;
+/**
+ * Stars as buttons.
+ *
+ * 🛑 `aria-label` per star and `aria-pressed` on the selected one — a row of
+ * five unlabelled glyphs is unusable with a screen reader, and the rating is
+ * the only required field here. Colour is never the sole signal: the selected
+ * star is filled AND pressed.
+ */
+function StarRow({ value, onChange, disabled, }) {
+    return (_jsx(Row, { gap: "xs", role: "group", "aria-label": "Rating out of 5", children: [1, 2, 3, 4, 5].map((n) => (_jsx(Button, { variant: n <= value ? "primary" : "outline", size: "sm", disabled: disabled, "aria-label": `${n} star${n === 1 ? "" : "s"}`, "aria-pressed": n === value, onClick: () => onChange(n), children: _jsx(Icon, { name: "review", filled: n <= value }) }, n))) }));
+}
+export function OrderCompletionPanel({ orderId, endpoint, completedAt, completedBy, isDelivered, isContested, onCompleted, }) {
+    const [lines, setLines] = useState([]);
+    const [loading, setLoading] = useState(true);
+    const [loadError, setLoadError] = useState(null);
+    const [openLine, setOpenLine] = useState(null);
+    const [rating, setRating] = useState(0);
+    const [comment, setComment] = useState("");
+    const [busy, setBusy] = useState(false);
+    const [actionError, setActionError] = useState(null);
+    const load = useCallback(() => {
+        setLoading(true);
+        setLoadError(null);
+        fetch(endpoint)
+            .then(async (r) => {
+            const body = await r.json().catch(() => null);
+            /*
+             * 🛑 The status is checked BEFORE the body is trusted. `errorResponse()`
+             * is valid JSON with a non-2xx status, so `body?.data?.items ?? []`
+             * would turn "the request failed" into "nothing to rate" — and this
+             * panel would then hide itself, which is the most convincing possible
+             * way to lose a feature.
+             */
+            if (!r.ok)
+                throw new Error(body?.error ?? `Could not load this order (${r.status})`);
+            return (body?.data?.items ?? []);
+        })
+            .then(setLines)
+            .catch((err) => setLoadError(normalizeError(err).message))
+            .finally(() => setLoading(false));
+    }, [endpoint]);
+    useEffect(() => {
+        if (!completedAt && isDelivered && !isContested)
+            load();
+        else
+            setLoading(false);
+    }, [completedAt, isDelivered, isContested, load]);
+    // ── Already complete: confirm it and say which path closed it ────────────
+    if (completedAt) {
+        const bySystem = completedBy === "system";
+        return (_jsx(Div, { surface: "card", padding: "md", children: _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: "This order is complete" }), _jsxs(Text, { size: "xs", color: "muted", children: [bySystem
+                                ? `Completed automatically on ${new Date(completedAt).toLocaleDateString()}, seven days after delivery with nothing raised against it.`
+                                : `You marked this complete on ${new Date(completedAt).toLocaleDateString()}.`, " ", "The dispute window for it has closed."] })] }) }));
+    }
+    if (!isDelivered)
+        return null;
+    if (isContested) {
+        return (_jsx(Div, { surface: "card", padding: "md", children: _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: "Rating is paused on this order" }), _jsx(Text, { size: "xs", color: "muted", children: "There is an open return, refund or dispute. Once that is resolved you can rate what you bought and close the order." })] }) }));
+    }
+    const ratedCount = lines.filter((l) => l.existingRating != null).length;
+    const canComplete = ratedCount > 0;
+    const submitRating = async (orderItemId) => {
+        setBusy(true);
+        setActionError(null);
+        try {
+            const res = await fetch(endpoint, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ action: "rate", orderItemId, rating, comment }),
+            });
+            if (!res.ok) {
+                const body = await res.json().catch(() => null);
+                throw new Error(body?.error ?? `That rating was not saved (${res.status})`);
+            }
+            setOpenLine(null);
+            setRating(0);
+            setComment("");
+            load();
+        }
+        catch (err) {
+            setActionError(normalizeError(err).message);
+        }
+        finally {
+            setBusy(false);
+        }
+    };
+    const complete = async () => {
+        setBusy(true);
+        setActionError(null);
+        try {
+            const res = await fetch(endpoint, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ action: "complete" }),
+            });
+            if (!res.ok) {
+                const body = await res.json().catch(() => null);
+                throw new Error(body?.error ?? `The order was not completed (${res.status})`);
+            }
+            onCompleted?.();
+        }
+        catch (err) {
+            setActionError(normalizeError(err).message);
+        }
+        finally {
+            setBusy(false);
+        }
+    };
+    return (_jsx(Div, { surface: "card", padding: "md", children: _jsxs(Stack, { gap: "md", children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: "Rate what you bought" }), _jsx(Text, { size: "xs", color: "muted", children: "Rate each item separately. One rating is enough to close the order \u2014 or leave it and we will close it automatically seven days after delivery." })] }), actionError ? (_jsx(Alert, { variant: "error", title: "That did not save", children: actionError })) : null, loading ? (_jsxs(Stack, { gap: "sm", children: [_jsx(Skeleton, { variant: "rectangular", height: "48px" }), _jsx(Skeleton, { variant: "rectangular", height: "48px" })] })) : loadError ? (_jsxs(Alert, { variant: "error", title: "Couldn't load the items", children: [loadError, " Refresh to retry."] })) : lines.length === 0 ? (_jsx(Text, { size: "xs", color: "muted", children: "There is nothing on this order to rate." })) : (_jsx(Stack, { gap: "sm", children: lines.map((line) => (_jsxs(Div, { border: "default", rounded: "default", padding: "sm", children: [_jsxs(Row, { justify: "between", align: "start", gap: "sm", wrap: true, children: [_jsx(Text, { size: "sm", className: "flex-1 line-clamp-2", color: "primary", children: line.productTitle }), line.existingRating != null ? (_jsxs(Text, { size: "xs", color: "success", children: ["★".repeat(line.existingRating), " rated"] })) : openLine === line.orderItemId ? null : (_jsx(Button, { variant: "outline", size: "sm", onClick: () => {
+                                            setOpenLine(line.orderItemId);
+                                            setRating(0);
+                                            setComment("");
+                                        }, children: "Rate this" }))] }), openLine === line.orderItemId ? (_jsxs(Stack, { gap: "sm", className: "mt-2", children: [_jsx(StarRow, { value: rating, onChange: setRating, disabled: busy }), _jsx(Textarea, { value: comment, onChange: (e) => setComment(e.target.value), rows: 3, placeholder: "What was it like? The next buyer reads this." }), _jsxs(Row, { gap: "sm", children: [_jsx(Button, { variant: "primary", size: "sm", isLoading: busy, 
+                                                /*
+                                                 * Mirrors the route's own floor. A one-word review is
+                                                 * indistinguishable from an empty box to the next
+                                                 * buyer, which is why the server has the same minimum
+                                                 * rather than this being a UI preference.
+                                                 */
+                                                disabled: busy || rating === 0 || comment.trim().length < MIN_COMMENT, onClick: () => submitRating(line.orderItemId), children: "Save rating" }), _jsx(Button, { variant: "ghost", size: "sm", disabled: busy, onClick: () => setOpenLine(null), children: "Cancel" })] })] })) : null] }, line.orderItemId))) })), _jsx(Div, { border: "subtle", className: "border-t", padding: "t-sm", children: _jsxs(Stack, { gap: "sm", children: [_jsx(Text, { size: "xs", color: "muted", children: "Marking this complete confirms you are happy with it. It closes the window for raising a new dispute on this order, releases the seller\u2019s payment, and credits your points." }), _jsxs(Row, { gap: "sm", align: "center", wrap: true, children: [_jsx(Button, { variant: "primary", size: "sm", isLoading: busy, disabled: busy || !canComplete, onClick: complete, children: "Mark complete" }), !canComplete ? (_jsx(Text, { size: "xs", color: "muted", children: "Rate at least one item first." })) : null] })] }) })] }) }));
+}

package/dist/features/orders/components/OrdersList.js

@@ -14,7 +14,7 @@ const STATUS_COLORS = {
     cancelled: "bg-error-surface text-error",
     refunded: "bg-warning-surface text-warning",
     return_requested: "bg-warning-surface text-warning",
-    returned: "bg-[var(--appkit-color-surface)] text-[var(--appkit-color-text-muted)] bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text-muted)]",
+    returned: "bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text-muted)]",
 };
 export function OrderCard({ order, onClick, labels = {}, renderActions }) {
     const date = order.createdAt
@@ -24,7 +24,7 @@ export function OrderCard({ order, onClick, labels = {}, renderActions }) {
             day: "numeric",
         })
         : "";
-    const statusColor = STATUS_COLORS[order.orderStatus] ?? "bg-[var(--appkit-color-surface)] bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text-muted)]";
+    const statusColor = STATUS_COLORS[order.orderStatus] ?? "bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text-muted)]";
     // SB8-F — count unrevealed prize-draw entries to surface a "reveals pending" badge.
     const unrevealedPrizeDraws = order.items.filter((it) => it.listingType === "prize-draw" &&
         it.prizeRevealStatus !== undefined &&

package/dist/features/orders/components/RefundHistoryTable.js

@@ -10,7 +10,9 @@ function formatDate(d) {
     return dt.toLocaleDateString("en-IN", { day: "numeric", month: "short", year: "numeric" });
 }
 function RefundRow({ event, currency }) {
-    return (_jsxs(Row, { border: "subtle", justify: "between", align: "start", gap: "sm", className: "border-b last:border-0", padding: "y-sm", children: [_jsxs(Stack, { gap: "xs", className: "flex-1", children: [_jsxs(Row, { gap: "sm", align: "center", children: [_jsx(Badge, { variant: event.type === "full" ? "danger" : "warning", children: event.type === "full" ? REFUND_COPY.history.badgeFull : REFUND_COPY.history.badgePartial }), _jsx(Text, { size: "xs", color: "muted", children: formatDate(event.refundedAt) })] }), _jsx(Text, { size: "sm", children: event.reason }), event.manualTransactionId && (_jsxs(Text, { size: "xs", color: "muted", children: [REFUND_COPY.history.labelTxn, " ", event.manualTransactionId] })), event.phonepeRefundId && (_jsxs(Text, { size: "xs", color: "muted", children: [REFUND_COPY.history.labelPhonePe, " ", event.phonepeRefundId] }))] }), _jsx(Text, { size: "sm", weight: "semibold", className: "shrink-0", children: formatCurrency(event.amount, currency) })] }));
+    return (_jsxs(Row, { border: "subtle", justify: "between", align: "start", gap: "sm", className: "border-b last:border-0", padding: "y-sm", children: [_jsxs(Stack, { gap: "xs", className: "flex-1", children: [_jsxs(Row, { gap: "sm", align: "center", children: [_jsx(Badge, { variant: event.type === "full" ? "danger" : "warning", children: event.type === "full" ? REFUND_COPY.history.badgeFull : REFUND_COPY.history.badgePartial }), _jsx(Text, { size: "xs", color: "muted", children: formatDate(event.refundedAt) })] }), _jsx(Text, { size: "sm", children: event.reason }), event.manualTransactionId && (_jsxs(Text, { size: "xs", color: "muted", children: [REFUND_COPY.history.labelTxn, " ", event.manualTransactionId] })), (event.gatewayRefundId ?? event.phonepeRefundId) && (_jsxs(Text, { size: "xs", color: "muted", children: [event.gateway
+                                ? `${event.gateway} refund:`
+                                : REFUND_COPY.history.labelPhonePe, " ", event.gatewayRefundId ?? event.phonepeRefundId] })), event.status === "failed" && (_jsxs(Text, { size: "xs", color: "error", children: ["Failed", event.failureReason ? ` — ${event.failureReason}` : ""] })), event.status === "reserved" && (_jsx(Text, { size: "xs", color: "muted", children: "In progress \u2014 awaiting the gateway" }))] }), _jsx(Text, { size: "sm", weight: "semibold", className: "shrink-0", children: formatCurrency(event.amount, currency) })] }));
 }
 /** Warning triangle icon — inline SVG kept here since it's a single-use decorative element. */
 function WarningIcon() {

package/dist/features/orders/components/index.d.ts

@@ -15,3 +15,5 @@ export type { RefundRequestViewProps } from "./RefundRequestView";
 export { YourPurchaseStrip } from "./YourPurchaseStrip";
 export type { YourPurchaseStripProps, PurchaseContext } from "./YourPurchaseStrip";
 export { EmiInstallmentsPanel, type EmiInstallmentsPanelProps, } from "./EmiInstallmentsPanel";
+export { OrderCompletionPanel } from "./OrderCompletionPanel";
+export type { OrderCompletionPanelProps, RateableLine } from "./OrderCompletionPanel";

package/dist/features/orders/components/index.js

@@ -8,3 +8,9 @@ export { RefundHistoryTable } from "./RefundHistoryTable.js";
 export { RefundRequestView } from "./RefundRequestView.js";
 export { YourPurchaseStrip } from "./YourPurchaseStrip.js";
 export { EmiInstallmentsPanel, } from "./EmiInstallmentsPanel.js";
+/*
+ * The buyer's completion surface — per-line ratings plus Mark complete. The
+ * owner's completion rule had no UI at all before this: a grep for
+ * `markOrderCompleteAction` across the app returned two hits, both comments.
+ */
+export { OrderCompletionPanel } from "./OrderCompletionPanel.js";

package/dist/features/orders/constants/transitions.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The order status machine — which transitions are legal.
+ *
+ * ## 🛑 THIS MAP WAS BUILT FROM A CENSUS, NOT FROM A DESIGN
+ *
+ * The plan that called for it said "~32 writers and no `from` check anywhere,
+ * so inventing the map silently breaks working flows — the failure mode is a
+ * legitimate admin action that now throws." That is the right fear and it is
+ * why a read-only census came first. **What the census found contradicted the
+ * plan's own number**, which is worth recording:
+ *
+ * `orderRepository.updateStatus` has **four** callers, not thirty-two:
+ *
+ *   1. `_internal/server/features/orders/actions.ts:99` — hardcodes
+ *      `"return_requested"`, cast `as any`.
+ *   2. `_internal/server/features/orders/actions.ts:113` — passes
+ *      `parsed.data.status` straight through, cast `as any`.
+ *   3. `src/app/api/store/orders/[id]/route.ts:242` — passes `data.status`
+ *      from the SELLER's request body.
+ *   4. `features/admin/actions/admin-actions.ts:152`.
+ *
+ * 🛑 **And the finding that matters: two of those four accept an arbitrary
+ * status from a request body, both with `as any` silencing the one type-level
+ * signal there was.** So a seller PATCHing their own order could set
+ * `delivered` on an unpaid order, or regress `delivered` → `pending`, and
+ * nothing anywhere would refuse it. The "~32 writers" framing made this look
+ * like a sprawling refactor; it is four call sites and a guard.
+ *
+ * (The other ~30 hits a naive grep returns are `offer.repository.ts`'s OWN
+ * `updateStatus` — a different method on a different collection. Conflating
+ * them is how the estimate got to 32, and acting on it would have meant
+ * "fixing" the offer lifecycle by accident.)
+ *
+ * ## Three entries look wrong and are not
+ *
+ * - **`return_requested` → `delivered`.** A REJECTED return must go back to
+ *   its prior terminal state, not strand the order in a requested-return limbo
+ *   forever. Without this the seller's "no, this is not a valid return" has no
+ *   expressible outcome.
+ * - **`cancelled` → `refunded` and `returned` → `refunded`.** Money moves
+ *   AFTER the goods decision. `refunded` is the only genuinely terminal state;
+ *   `cancelled` is a goods outcome that may still owe money.
+ * - **`pending` → `refunded` is ABSENT.** A pending order was never captured,
+ *   so there is nothing to refund. If a writer is found doing this, the writer
+ *   is the bug — do not widen the map to accommodate it.
+ */
+import type { OrderStatus } from "../types/index";
+/**
+ * Legal next states per status. A `Record<OrderStatus, …>` so a tenth status
+ * cannot be added to the union without declaring where it can go — an array or
+ * a `Record<string, …>` catches neither mistake, which is how ten independent
+ * enumerations of `ListingType` came to disagree (Root Cause #61).
+ */
+export declare const ORDER_STATUS_TRANSITIONS: Record<OrderStatus, readonly OrderStatus[]>;
+/** Statuses from which nothing may follow. */
+export declare const ORDER_TERMINAL_STATUSES: readonly OrderStatus[];
+export declare function isLegalOrderTransition(from: OrderStatus, to: OrderStatus): boolean;
+/** Human-readable refusal, for the error a caller sees. */
+export declare function describeIllegalTransition(from: OrderStatus, to: OrderStatus): string;

package/dist/features/orders/constants/transitions.js

@@ -0,0 +1,104 @@
+/**
+ * The order status machine — which transitions are legal.
+ *
+ * ## 🛑 THIS MAP WAS BUILT FROM A CENSUS, NOT FROM A DESIGN
+ *
+ * The plan that called for it said "~32 writers and no `from` check anywhere,
+ * so inventing the map silently breaks working flows — the failure mode is a
+ * legitimate admin action that now throws." That is the right fear and it is
+ * why a read-only census came first. **What the census found contradicted the
+ * plan's own number**, which is worth recording:
+ *
+ * `orderRepository.updateStatus` has **four** callers, not thirty-two:
+ *
+ *   1. `_internal/server/features/orders/actions.ts:99` — hardcodes
+ *      `"return_requested"`, cast `as any`.
+ *   2. `_internal/server/features/orders/actions.ts:113` — passes
+ *      `parsed.data.status` straight through, cast `as any`.
+ *   3. `src/app/api/store/orders/[id]/route.ts:242` — passes `data.status`
+ *      from the SELLER's request body.
+ *   4. `features/admin/actions/admin-actions.ts:152`.
+ *
+ * 🛑 **And the finding that matters: two of those four accept an arbitrary
+ * status from a request body, both with `as any` silencing the one type-level
+ * signal there was.** So a seller PATCHing their own order could set
+ * `delivered` on an unpaid order, or regress `delivered` → `pending`, and
+ * nothing anywhere would refuse it. The "~32 writers" framing made this look
+ * like a sprawling refactor; it is four call sites and a guard.
+ *
+ * (The other ~30 hits a naive grep returns are `offer.repository.ts`'s OWN
+ * `updateStatus` — a different method on a different collection. Conflating
+ * them is how the estimate got to 32, and acting on it would have meant
+ * "fixing" the offer lifecycle by accident.)
+ *
+ * ## Three entries look wrong and are not
+ *
+ * - **`return_requested` → `delivered`.** A REJECTED return must go back to
+ *   its prior terminal state, not strand the order in a requested-return limbo
+ *   forever. Without this the seller's "no, this is not a valid return" has no
+ *   expressible outcome.
+ * - **`cancelled` → `refunded` and `returned` → `refunded`.** Money moves
+ *   AFTER the goods decision. `refunded` is the only genuinely terminal state;
+ *   `cancelled` is a goods outcome that may still owe money.
+ * - **`pending` → `refunded` is ABSENT.** A pending order was never captured,
+ *   so there is nothing to refund. If a writer is found doing this, the writer
+ *   is the bug — do not widen the map to accommodate it.
+ */
+/**
+ * Legal next states per status. A `Record<OrderStatus, …>` so a tenth status
+ * cannot be added to the union without declaring where it can go — an array or
+ * a `Record<string, …>` catches neither mistake, which is how ten independent
+ * enumerations of `ListingType` came to disagree (Root Cause #61).
+ */
+export const ORDER_STATUS_TRANSITIONS = {
+    pending: ["confirmed", "processing", "cancelled"],
+    confirmed: ["processing", "shipped", "cancelled", "refunded"],
+    processing: ["shipped", "cancelled", "refunded"],
+    shipped: ["delivered", "return_requested", "cancelled", "refunded"],
+    delivered: ["return_requested", "refunded"],
+    return_requested: ["returned", "delivered", "refunded", "cancelled"],
+    returned: ["refunded"],
+    cancelled: ["refunded"],
+    refunded: [],
+};
+/*
+ * Two entries beyond the plan's proposed map, and they have DIFFERENT
+ * justifications — which is worth separating, because one is evidence and the
+ * other is caution.
+ *
+ * **`pending → processing` — VERIFIED.** `paymentReviewAutoApprove.ts:66`
+ * writes `status: "processing"` on a pending order, and
+ * `checkout/actions.ts:1210` creates one directly as `PROCESSING` under the
+ * admin bypass. The plan's proposed map omitted this hop, so adopting the plan
+ * verbatim would have made the 2-hour auto-approve sweep start throwing — the
+ * exact "a legitimate flow now fails" regression the census existed to prevent.
+ * The census wins, as the plan instructed.
+ *
+ * 🛑 **`shipped → cancelled` — NOT verified, permissive by choice.** I wrote a
+ * comment claiming the census justified this via an RTO flow, then checked: the
+ * only grep hits were that comment and an unused `RTO_ENTRY_CUSTODY` constant.
+ * No writer produces it today. It is kept because the asymmetry of harm is
+ * one-sided — being too permissive here allows a transition nothing currently
+ * makes, while being too strict would break a dispatch-then-cancel flow the
+ * moment one is built — but it is a JUDGEMENT, not a measurement, and the next
+ * person should know which is which.
+ */
+/** Statuses from which nothing may follow. */
+export const ORDER_TERMINAL_STATUSES = ["refunded"];
+export function isLegalOrderTransition(from, to) {
+    /*
+     * A no-op write is always legal. Re-writing the same status happens all the
+     * time — a patch that touches `trackingNumber` and re-sends the status it
+     * already had — and refusing it would break those writers for no gain.
+     */
+    if (from === to)
+        return true;
+    return (ORDER_STATUS_TRANSITIONS[from] ?? []).includes(to);
+}
+/** Human-readable refusal, for the error a caller sees. */
+export function describeIllegalTransition(from, to) {
+    const allowed = ORDER_STATUS_TRANSITIONS[from] ?? [];
+    return allowed.length === 0
+        ? `An order in "${from}" is terminal — it cannot move to "${to}".`
+        : `An order in "${from}" cannot move to "${to}". Allowed: ${allowed.join(", ")}.`;
+}