@mohasinac/appkit 4.59.0 → 4.60.0

package/dist/features/admin/components/AdminGatewayEventsView.d.ts

@@ -0,0 +1,54 @@
+/**
+ * AdminGatewayEventsView — the webhook inbox, readable for the first time.
+ *
+ * ## What this is for
+ *
+ * `gatewayEvents` records every delivery verbatim, including event types we are
+ * subscribed to but do not implement — which is the whole reason the inbox
+ * exists rather than a logger line. Before it, a `payment.dispute.created`
+ * arriving ahead of the dispute handler would simply have vanished.
+ *
+ * This page answers three operator questions: did it arrive, what did we do
+ * with it, and can it be made to arrive again.
+ *
+ * ## 🛑 "Reopen for redelivery" is NOT "reprocess", and the UI must not imply it
+ *
+ * Nothing here can replay an event. R1's own header explains why: dispatching
+ * from anywhere but the webhook route would duplicate that route's whole switch
+ * and its RTDB signalling in a second place (Root Cause #75). The action only
+ * stops the inbox from refusing the NEXT delivery as a duplicate — the operator
+ * still presses Resend in the gateway dashboard.
+ *
+ * So the button says what it does, and the confirmation says what is left to
+ * do. A button labelled "Reprocess" doing only this would be the worst kind of
+ * half-truth: it would look like the work had happened.
+ *
+ * ## 🛑 Two statuses that look like failures and are not
+ *
+ * `ignored` means an event type we do not implement was recorded verbatim —
+ * healthy, and the inbox's purpose. `conflict` means a LATE event would have
+ * regressed an order's status, so it was recorded and not applied; the ack was
+ * 200 because the event is not wrong, it is out of date. Labelling either as an
+ * error would send operators chasing non-problems, which is how a queue stops
+ * being read.
+ *
+ * ## 🛑 No search box, and no sort on `status`
+ *
+ * `searchPlaceholder` is omitted because the endpoint does not read `q`;
+ * declaring it is what makes a dead box exist. And `status` is `canSort: false`
+ * in `SIEVE_FIELDS`, so a sort on it would be DROPPED silently by sievejs
+ * (Root Cause #63) — the status FILTER is the control, and it is in the panel.
+ *
+ * EXPORTS: AdminGatewayEventsView, type AdminGatewayEventsViewProps
+ *
+ * @tag domain:gateway-events
+ * @tag layer:component
+ * @tag pattern:listing
+ * @tag access:client
+ * @tag consumers:admin/maintenance/gateway-events
+ * @tag sideEffects:network
+ */
+import React from "react";
+import type { ListingLayoutProps } from "../../../ui";
+export type AdminGatewayEventsViewProps = ListingLayoutProps;
+export declare function AdminGatewayEventsView({ children, ...props }: AdminGatewayEventsViewProps): React.JSX.Element;

package/dist/features/admin/components/AdminGatewayEventsView.js

@@ -0,0 +1,209 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * AdminGatewayEventsView — the webhook inbox, readable for the first time.
+ *
+ * ## What this is for
+ *
+ * `gatewayEvents` records every delivery verbatim, including event types we are
+ * subscribed to but do not implement — which is the whole reason the inbox
+ * exists rather than a logger line. Before it, a `payment.dispute.created`
+ * arriving ahead of the dispute handler would simply have vanished.
+ *
+ * This page answers three operator questions: did it arrive, what did we do
+ * with it, and can it be made to arrive again.
+ *
+ * ## 🛑 "Reopen for redelivery" is NOT "reprocess", and the UI must not imply it
+ *
+ * Nothing here can replay an event. R1's own header explains why: dispatching
+ * from anywhere but the webhook route would duplicate that route's whole switch
+ * and its RTDB signalling in a second place (Root Cause #75). The action only
+ * stops the inbox from refusing the NEXT delivery as a duplicate — the operator
+ * still presses Resend in the gateway dashboard.
+ *
+ * So the button says what it does, and the confirmation says what is left to
+ * do. A button labelled "Reprocess" doing only this would be the worst kind of
+ * half-truth: it would look like the work had happened.
+ *
+ * ## 🛑 Two statuses that look like failures and are not
+ *
+ * `ignored` means an event type we do not implement was recorded verbatim —
+ * healthy, and the inbox's purpose. `conflict` means a LATE event would have
+ * regressed an order's status, so it was recorded and not applied; the ack was
+ * 200 because the event is not wrong, it is out of date. Labelling either as an
+ * error would send operators chasing non-problems, which is how a queue stops
+ * being read.
+ *
+ * ## 🛑 No search box, and no sort on `status`
+ *
+ * `searchPlaceholder` is omitted because the endpoint does not read `q`;
+ * declaring it is what makes a dead box exist. And `status` is `canSort: false`
+ * in `SIEVE_FIELDS`, so a sort on it would be DROPPED silently by sievejs
+ * (Root Cause #63) — the status FILTER is the control, and it is in the panel.
+ *
+ * EXPORTS: AdminGatewayEventsView, type AdminGatewayEventsViewProps
+ *
+ * @tag domain:gateway-events
+ * @tag layer:component
+ * @tag pattern:listing
+ * @tag access:client
+ * @tag consumers:admin/maintenance/gateway-events
+ * @tag sideEffects:network
+ */
+import React, { useState } from "react";
+import { sieveFilter, SIEVE_OP, sortBy, } from "@mohasinac/appkit/client";
+import { FilterChipGroup, ListingLayout, Modal, RecordDetailModal, Row, RowActionMenu, Stack, Text, Button, } from "../../../ui/index.js";
+import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints.js";
+import { ADMIN_GATEWAY_EVENT_KIND_TABS, ADMIN_GATEWAY_EVENT_STATUS_TABS, } from "../constants/filter-tabs.js";
+import { toRecordArray, toRelativeDate, toStringValue, } from "../hooks/useAdminListingData.js";
+import { DataListingView } from "./DataListingView.js";
+/** Operator-facing status names — see the 🛑 about `ignored` and `conflict`. */
+const STATUS_LABEL = {
+    received: "Received, not yet settled",
+    processing: "Being processed",
+    processed: "Processed",
+    failed: "Failed",
+    conflict: "Arrived late — recorded, not applied",
+    ignored: "Recorded, no handler for this type",
+};
+export function AdminGatewayEventsView({ children, ...props }) {
+    const [detail, setDetail] = useState(null);
+    const [reopenId, setReopenId] = useState(null);
+    const [busy, setBusy] = useState(false);
+    const [revision, setRevision] = useState(0);
+    if (React.Children.count(children) > 0) {
+        return (_jsx(ListingLayout, { portal: "admin", ...props, children: children }));
+    }
+    const reopen = async (id) => {
+        setBusy(true);
+        try {
+            const res = await fetch(ADMIN_ENDPOINTS.MAINTENANCE_GATEWAY_EVENTS, {
+                method: "PATCH",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ id }),
+            });
+            if (!res.ok)
+                throw new Error(`Could not reopen that event (${res.status})`);
+            setRevision((r) => r + 1);
+            setReopenId(null);
+            setDetail(null);
+        }
+        finally {
+            setBusy(false);
+        }
+    };
+    const config = {
+        portal: "admin",
+        title: "Gateway events",
+        subtitle: "Every webhook delivery, recorded verbatim — including event types we have no handler for. Read-only apart from reopening one for redelivery.",
+        emptyLabel: "No gateway events recorded",
+        // 🛑 No `searchPlaceholder` — the endpoint does not read `q`.
+        filterKeys: ["status", "kind"],
+        /*
+         * `receivedAt`, which every row has. 🛑 NOT `status`, which is
+         * `canSort: false` in SIEVE_FIELDS and would therefore be dropped by
+         * sievejs with no error (Root Cause #63); and not `processedAt`, which is
+         * optional — a Firestore `orderBy` excludes documents lacking the field, so
+         * it would hide every unsettled event, i.e. exactly the ones worth seeing
+         * (Root Cause #100).
+         */
+        defaultSort: sortBy("receivedAt", "DESC"),
+        queryKey: ["admin", "gateway-events", "listing", String(revision)],
+        endpoint: ADMIN_ENDPOINTS.MAINTENANCE_GATEWAY_EVENTS,
+        /*
+         * 🛑 ONLY `receivedAt`, and the omission is an index-weight decision rather
+         * than a shortfall.
+         *
+         * `attempts` is `canSort: true`, so "Most attempts" would work — but each
+         * filter+sort combination needs its own composite index, and a sort on a
+         * second field triples them: `(status, attempts)`, `(kind, attempts)`,
+         * `(status, kind, attempts)` on top of the three `receivedAt` ones.
+         *
+         * `gatewayEvents` takes a row for every webhook delivery, which makes it
+         * the highest-write collection in this subsystem — and a composite index is
+         * a write multiplier on EVERY document, forever, not a read-time cost. Six
+         * indexes to rank a rarely-opened diagnostic by a number the `failed` status
+         * filter already finds is the wrong trade.
+         *
+         * Two indexes are added for the filter combinations that remain:
+         * `(status, receivedAt desc)` and `(status, kind, receivedAt desc)`.
+         * `(kind, receivedAt desc)` already existed.
+         */
+        sortOptions: [
+            { value: sortBy("receivedAt", "DESC"), label: "Newest" },
+            { value: sortBy("receivedAt", "ASC"), label: "Oldest" },
+        ],
+        mapRows: (response) => toRecordArray(response.items).map((item, index) => {
+            const status = toStringValue(item.status, "received");
+            const attempts = typeof item.attempts === "number" ? item.attempts : 0;
+            return {
+                id: toStringValue(item.id, `event-${index}`),
+                primary: `${toStringValue(item.gateway, "?")} · ${toStringValue(item.kind, "other")}`,
+                secondary: [
+                    STATUS_LABEL[status] ?? status,
+                    toStringValue(item.gatewayOrderId, "") || null,
+                    toStringValue(item.gatewayPaymentId, "") || null,
+                    // Only when informative — "1 attempt" is the normal case and noise.
+                    attempts > 1 ? `${attempts} attempts` : null,
+                    item.terminal === true ? "terminal" : null,
+                ]
+                    .filter(Boolean)
+                    .join(" · "),
+                status,
+                updatedAt: toRelativeDate(item.receivedAt),
+                _raw: item,
+            };
+        }),
+        getTotal: (response, mappedRows) => typeof response.meta?.total === "number" ? response.meta.total : mappedRows.length,
+        onRowClick: (row) => setDetail(row._raw),
+        buildFilters: (state) => {
+            const parts = [];
+            if (state.status && state.status !== "All")
+                parts.push(sieveFilter("status", SIEVE_OP.EQ, state.status));
+            if (state.kind && state.kind !== "All")
+                parts.push(sieveFilter("kind", SIEVE_OP.EQ, state.kind));
+            return parts.length > 0 ? parts.join(",") : undefined;
+        },
+        renderRowActions: (row) => (_jsx(RowActionMenu, { actions: [
+                { label: "View details", onClick: () => setDetail(row._raw) },
+                { label: "Reopen for redelivery", onClick: () => setReopenId(row.id) },
+            ] })),
+        renderFilterPanel: ({ pendingFilters, setPendingFilters }) => (_jsxs(Stack, { gap: "md", children: [_jsx(FilterChipGroup, { label: "Status", tabs: ADMIN_GATEWAY_EVENT_STATUS_TABS, value: pendingFilters.status ?? "", onChange: (id) => setPendingFilters((p) => ({ ...p, status: id })) }), _jsx(FilterChipGroup, { label: "Kind", tabs: ADMIN_GATEWAY_EVENT_KIND_TABS, value: pendingFilters.kind ?? "", onChange: (id) => setPendingFilters((p) => ({ ...p, kind: id })) })] })),
+    };
+    const detailStatus = detail ? toStringValue(detail.status, "") : "";
+    return (_jsxs(_Fragment, { children: [_jsx(DataListingView, { config: config }), _jsx(RecordDetailModal, { isOpen: detail !== null, onClose: () => setDetail(null), title: detail
+                    ? `${toStringValue(detail.gateway, "?")} · ${toStringValue(detail.kind, "other")}`
+                    : "Gateway event", badges: detail
+                    ? [
+                        { label: STATUS_LABEL[detailStatus] ?? detailStatus },
+                        ...(detail.terminal === true
+                            ? [{ label: "terminal", variant: "warning" }]
+                            : []),
+                    ]
+                    : undefined, fields: detail
+                    ? [
+                        { label: "Event id", value: toStringValue(detail.id, "") },
+                        { label: "Provider event id", value: toStringValue(detail.providerEventId, "") || "— (deduped on the body digest instead)" },
+                        { label: "Body SHA-256", value: toStringValue(detail.bodySha256, "") },
+                        { label: "Gateway order", value: toStringValue(detail.gatewayOrderId, "") || "—" },
+                        { label: "Gateway payment", value: toStringValue(detail.gatewayPaymentId, "") || "—" },
+                        { label: "Amount", value: typeof detail.amount === "number" ? `₹${detail.amount.toFixed(2)}` : "—" },
+                        { label: "Orders placed", value: Array.isArray(detail.orderIds) ? detail.orderIds.join(", ") : "—" },
+                        { label: "Received", value: toStringValue(detail.receivedAt, "") },
+                        { label: "Settled", value: toStringValue(detail.processedAt, "") || "— not settled" },
+                        { label: "Attempts", value: String(detail.attempts ?? 0) },
+                        { label: "Lease expires", value: toStringValue(detail.leaseExpiresAt, "") },
+                        { label: "Last error", value: toStringValue(detail.lastError, "") || "—" },
+                        { label: "Retention expiry", value: toStringValue(detail.expiresAt, "") },
+                    ]
+                    : undefined, 
+                /*
+                 * `payload` is the REDACTED projection, never the raw body — Razorpay's
+                 * payment entity carries email, contact, card.last4, vpa and bank, and
+                 * `redactGatewayPayload` strips them recursively. `bodySha256` above
+                 * preserves integrity regardless, which is what makes redaction safe.
+                 */
+                metadata: detail && detail.payload && typeof detail.payload === "object"
+                    ? detail.payload
+                    : undefined, footer: detail ? (_jsx(Button, { variant: "outline", size: "sm", onClick: () => setReopenId(toStringValue(detail.id, "")), children: "Reopen for redelivery" })) : undefined }), _jsx(Modal, { isOpen: reopenId !== null, onClose: () => setReopenId(null), title: "Reopen this event for redelivery", size: "sm", children: _jsxs(Stack, { gap: "md", children: [_jsxs(Text, { size: "sm", children: ["This clears the terminal flag and the attempt count so the inbox will ", _jsx("strong", { children: "accept" }), " the next delivery of this event instead of refusing it as a duplicate."] }), _jsx(Row, { surface: "warning-surface", padding: "sm", rounded: "default", children: _jsxs(Text, { size: "sm", color: "warning", children: ["It does not reprocess anything by itself. Nothing outside the webhook route knows how to handle an event, so after this you still need to press ", _jsx("strong", { children: "Resend" }), " on this delivery in the gateway dashboard \u2014 or wait for the gateway\u2019s own retry."] }) }), _jsxs(Row, { justify: "end", gap: "sm", children: [_jsx(Button, { variant: "ghost", onClick: () => setReopenId(null), disabled: busy, children: "Cancel" }), _jsx(Button, { variant: "primary", isLoading: busy, disabled: busy, onClick: () => reopen(reopenId), children: "Reopen" })] })] }) })] }));
+}

package/dist/features/admin/components/AdminGuideHubView.js

@@ -81,5 +81,5 @@ export function AdminGuideHubView({ permissions = [], isFullAdmin = false }) {
     const hasPermission = (perm) => isFullAdmin || permissions.includes(perm);
     const visibleCards = GUIDE_CARDS.filter((c) => hasPermission(c.permission));
     const hasAny = visibleCards.length > 0;
-    return (_jsxs(Stack, { gap: "xl", padding: "b-2xl", children: [_jsx(Section, { overflow: "hidden", className: "border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)]", rounded: "2xl", shadow: "sm", children: _jsxs(Div, { paddingX: "x-md-xl", paddingY: "y-xl", className: "[background:linear-gradient(135deg,var(--appkit-color-primary-700)_0%,var(--appkit-color-cobalt)_60%,var(--appkit-color-secondary-400)_100%)]", children: [_jsxs(Row, { className: "mb-3", align: "center", gap: "3", children: [_jsx(Row, { className: "flex-shrink-0 w-10 h-10", surface: "default", align: "center", justify: "center", rounded: "xl", children: _jsx(BookOpen, { className: "w-5 h-5 text-white" }) }), _jsx(Text, { color: "inverse", className: "/80 tracking-widest", size: "sm", weight: "semibold", transform: "uppercase", children: "Admin & Employee Guide" })] }), _jsx(Heading, { color: "inverse", level: 1, className: "mb-2", mdSize: "3xl", size: "2xl", weight: "bold", children: "LetItRip Internal Guide" }), _jsx(Text, { color: "inverse", className: "/80", size: "base", children: "Everything you need to operate and manage LetItRip \u2014 India's largest collectibles marketplace." })] }) }), _jsx(Alert, { variant: "info", compact: true, children: "These guides describe expected platform behaviour. Real access to each section is enforced independently by the permission system \u2014 this page is reference only." }), !hasAny && (_jsx(Alert, { variant: "info", title: "Limited access", children: "Your permission set doesn't include read access to any admin sections yet. Contact your admin to request the permissions you need." })), hasAny && (_jsxs(Section, { children: [_jsx(Heading, { level: 2, className: "text-[var(--appkit-color-text)] mb-4", size: "lg", weight: "semibold", children: "Guides" }), _jsx(Grid, { cols: "cards", gap: "md", children: visibleCards.map(({ Icon, title, description, href }) => (_jsxs(TextLink, { variant: "bare", href: href, rounded: "xl", layout: "flex-col", gap: "md", paddingX: "lg", paddingY: "lg", shadow: "hover-md", className: "group border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] hover:border-[var(--appkit-color-primary)] transition-all", children: [_jsxs(Row, { align: "center", gap: "3", children: [_jsx(Row, { className: "flex-shrink-0 w-9 h-9 [background:linear-gradient(135deg,var(--appkit-color-primary-700)_0%,var(--appkit-color-cobalt)_100%)]", align: "center", justify: "center", rounded: "lg", children: _jsx(Icon, { className: "w-4 h-4 text-white" }) }), _jsx(Text, { className: "text-[var(--appkit-color-text)] group-hover:text-[var(--appkit-color-primary)] transition-colors", weight: "semibold", children: title })] }), _jsx(Text, { className: "text-[var(--appkit-color-text-muted)] leading-relaxed", size: "sm", children: description }), _jsx(Text, { className: "text-[var(--appkit-color-primary)] mt-auto", size: "xs", weight: "medium", children: "Read guide \u2192" })] }, title))) })] })), _jsx(Section, { className: CLS_WARN_PANEL, children: _jsxs(Row, { align: "start", gap: "3", children: [_jsx(AlertTriangle, { className: "w-5 h-5 text-warning flex-shrink-0 mt-0.5" }), _jsxs(Div, { children: [_jsx(Text, { className: CLS_WARN_HEAD, children: "Remember: with great access comes responsibility" }), _jsx(Text, { className: CLS_WARN_BODY, children: "Admin actions are logged. Never access user PII (email, phone) without a legitimate support reason. Never grant capabilities or permissions without documented approval. When in doubt, escalate to a senior admin." })] })] }) })] }));
+    return (_jsxs(Stack, { gap: "xl", padding: "b-2xl", children: [_jsx(Section, { overflow: "hidden", className: "border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)]", rounded: "2xl", shadow: "sm", children: _jsxs(Div, { paddingX: "x-md-xl", paddingY: "y-xl", className: "[background:linear-gradient(135deg,var(--appkit-color-primary-700)_0%,var(--appkit-color-cobalt)_60%,var(--appkit-color-secondary-400)_100%)]", children: [_jsxs(Row, { className: "mb-3", align: "center", gap: "3", children: [_jsx(Row, { className: "flex-shrink-0 w-10 h-10", surface: "default", align: "center", justify: "center", rounded: "xl", children: _jsx(BookOpen, { className: "w-5 h-5 text-white" }) }), _jsx(Text, { color: "inverse-muted", className: "tracking-widest", size: "sm", weight: "semibold", transform: "uppercase", children: "Admin & Employee Guide" })] }), _jsx(Heading, { color: "inverse", level: 1, className: "mb-2", mdSize: "3xl", size: "2xl", weight: "bold", children: "LetItRip Internal Guide" }), _jsx(Text, { color: "inverse-muted", size: "base", children: "Everything you need to operate and manage LetItRip \u2014 India's largest collectibles marketplace." })] }) }), _jsx(Alert, { variant: "info", compact: true, children: "These guides describe expected platform behaviour. Real access to each section is enforced independently by the permission system \u2014 this page is reference only." }), !hasAny && (_jsx(Alert, { variant: "info", title: "Limited access", children: "Your permission set doesn't include read access to any admin sections yet. Contact your admin to request the permissions you need." })), hasAny && (_jsxs(Section, { children: [_jsx(Heading, { level: 2, className: "text-[var(--appkit-color-text)] mb-4", size: "lg", weight: "semibold", children: "Guides" }), _jsx(Grid, { cols: "cards", gap: "md", children: visibleCards.map(({ Icon, title, description, href }) => (_jsxs(TextLink, { variant: "bare", href: href, rounded: "xl", layout: "flex-col", gap: "md", paddingX: "lg", paddingY: "lg", shadow: "hover-md", className: "group border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] hover:border-[var(--appkit-color-primary)] transition-all", children: [_jsxs(Row, { align: "center", gap: "3", children: [_jsx(Row, { className: "flex-shrink-0 w-9 h-9 [background:linear-gradient(135deg,var(--appkit-color-primary-700)_0%,var(--appkit-color-cobalt)_100%)]", align: "center", justify: "center", rounded: "lg", children: _jsx(Icon, { className: "w-4 h-4 text-white" }) }), _jsx(Text, { className: "text-[var(--appkit-color-text)] group-hover:text-[var(--appkit-color-primary)] transition-colors", weight: "semibold", children: title })] }), _jsx(Text, { className: "text-[var(--appkit-color-text-muted)] leading-relaxed", size: "sm", children: description }), _jsx(Text, { className: "text-[var(--appkit-color-primary)] mt-auto", size: "xs", weight: "medium", children: "Read guide \u2192" })] }, title))) })] })), _jsx(Section, { className: CLS_WARN_PANEL, children: _jsxs(Row, { align: "start", gap: "3", children: [_jsx(AlertTriangle, { className: "w-5 h-5 text-warning flex-shrink-0 mt-0.5" }), _jsxs(Div, { children: [_jsx(Text, { className: CLS_WARN_HEAD, children: "Remember: with great access comes responsibility" }), _jsx(Text, { className: CLS_WARN_BODY, children: "Admin actions are logged. Never access user PII (email, phone) without a legitimate support reason. Never grant capabilities or permissions without documented approval. When in doubt, escalate to a senior admin." })] })] }) })] }));
 }

package/dist/features/admin/components/AdminMoneyCasesView.d.ts

@@ -0,0 +1,60 @@
+/**
+ * AdminMoneyCasesView — the operator queue for everything where money is at
+ * risk, and the FIRST surface `paymentCases` has ever had.
+ *
+ * ## Why this page is the point of the whole payment-protection spine
+ *
+ * The event inbox, the four reconcilers, the obligation sweep, the dispute
+ * ingest, the protection claims and the grievance intake all converge on one
+ * collection — and until this view existed, **nothing could read it.** Thirty-six
+ * commits of detection wrote rows into a queue with no screen. That is Root
+ * Cause #56 at the scale of a subsystem: *a feature is built, one of its
+ * surfaces is missing, and nothing notices.*
+ *
+ * The daily digest was the only consumer, and it was built first for exactly
+ * that reason — it PUSHES, so the queue had one reader from day one. This is
+ * the pull side.
+ *
+ * ## 🛑 It is NOT under `/admin/maintenance/`
+ *
+ * Maintenance means "something broke, look when you can" and is granted to
+ * `maintenance_employee`. A case here can carry a gateway's own `respond_by` —
+ * miss it and the chargeback is lost by default irrespective of who was right —
+ * and an `amountAtRisk` in real rupees. Hence its own section and
+ * `admin:payment-cases:read|write`, admin only.
+ *
+ * ## 🛑 NO SEARCH BOX, and that is a decision
+ *
+ * `ListingViewConfig.searchPlaceholder` is optional and *"declaring it is what
+ * makes the box exist"*. `/api/admin/payment-cases` does not read `q`, and
+ * ~39 views in this codebase already render a box whose endpoint ignores the
+ * term — the user types, the request carries it, nothing changes, no error.
+ * Omitting it is the fix; a placeholder describing a capability the endpoint
+ * lacks is the defect.
+ *
+ * ## 🛑 The default sort cannot be `dueAt`
+ *
+ * `dueAt` is OPTIONAL and most cases have none — only a dispute and a grievance
+ * carry an external clock. A Firestore `orderBy` on an optional field silently
+ * EXCLUDES every document that lacks it (Root Cause #100), so sorting by
+ * deadline would hide the great majority of the queue while looking like it had
+ * simply ordered it. `lastObservedAt` is written by `openOrObserve` on every
+ * case, every time, so it is the only safe default — and it happens to be the
+ * right one: "what has been seen most recently".
+ *
+ * Deadline pressure is surfaced instead by the `dueAt` row text and by R4,
+ * which escalates and re-notifies at T-72h and T-24h.
+ *
+ * EXPORTS: AdminMoneyCasesView, type AdminMoneyCasesViewProps
+ *
+ * @tag domain:payment-cases
+ * @tag layer:component
+ * @tag pattern:listing
+ * @tag access:client
+ * @tag consumers:admin/money-cases
+ * @tag sideEffects:network
+ */
+import React from "react";
+import type { ListingLayoutProps } from "../../../ui";
+export type AdminMoneyCasesViewProps = ListingLayoutProps;
+export declare function AdminMoneyCasesView({ children, ...props }: AdminMoneyCasesViewProps): React.JSX.Element;

package/dist/features/admin/components/AdminMoneyCasesView.js

@@ -0,0 +1,287 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * AdminMoneyCasesView — the operator queue for everything where money is at
+ * risk, and the FIRST surface `paymentCases` has ever had.
+ *
+ * ## Why this page is the point of the whole payment-protection spine
+ *
+ * The event inbox, the four reconcilers, the obligation sweep, the dispute
+ * ingest, the protection claims and the grievance intake all converge on one
+ * collection — and until this view existed, **nothing could read it.** Thirty-six
+ * commits of detection wrote rows into a queue with no screen. That is Root
+ * Cause #56 at the scale of a subsystem: *a feature is built, one of its
+ * surfaces is missing, and nothing notices.*
+ *
+ * The daily digest was the only consumer, and it was built first for exactly
+ * that reason — it PUSHES, so the queue had one reader from day one. This is
+ * the pull side.
+ *
+ * ## 🛑 It is NOT under `/admin/maintenance/`
+ *
+ * Maintenance means "something broke, look when you can" and is granted to
+ * `maintenance_employee`. A case here can carry a gateway's own `respond_by` —
+ * miss it and the chargeback is lost by default irrespective of who was right —
+ * and an `amountAtRisk` in real rupees. Hence its own section and
+ * `admin:payment-cases:read|write`, admin only.
+ *
+ * ## 🛑 NO SEARCH BOX, and that is a decision
+ *
+ * `ListingViewConfig.searchPlaceholder` is optional and *"declaring it is what
+ * makes the box exist"*. `/api/admin/payment-cases` does not read `q`, and
+ * ~39 views in this codebase already render a box whose endpoint ignores the
+ * term — the user types, the request carries it, nothing changes, no error.
+ * Omitting it is the fix; a placeholder describing a capability the endpoint
+ * lacks is the defect.
+ *
+ * ## 🛑 The default sort cannot be `dueAt`
+ *
+ * `dueAt` is OPTIONAL and most cases have none — only a dispute and a grievance
+ * carry an external clock. A Firestore `orderBy` on an optional field silently
+ * EXCLUDES every document that lacks it (Root Cause #100), so sorting by
+ * deadline would hide the great majority of the queue while looking like it had
+ * simply ordered it. `lastObservedAt` is written by `openOrObserve` on every
+ * case, every time, so it is the only safe default — and it happens to be the
+ * right one: "what has been seen most recently".
+ *
+ * Deadline pressure is surfaced instead by the `dueAt` row text and by R4,
+ * which escalates and re-notifies at T-72h and T-24h.
+ *
+ * EXPORTS: AdminMoneyCasesView, type AdminMoneyCasesViewProps
+ *
+ * @tag domain:payment-cases
+ * @tag layer:component
+ * @tag pattern:listing
+ * @tag access:client
+ * @tag consumers:admin/money-cases
+ * @tag sideEffects:network
+ */
+import React, { useState } from "react";
+import { sieveFilter, SIEVE_OP, sortBy, } from "@mohasinac/appkit/client";
+import { Button, FilterChipGroup, ListingLayout, RecordDetailModal, Row, RowActionMenu, Stack, Text, } from "../../../ui/index.js";
+import { RecordStatusTimeline } from "../../status-history/components/RecordStatusTimeline.js";
+import { ReviewDecisionModal } from "../../store-extensions/components/ReviewDecisionModal.js";
+import { paymentCaseResolveFormSchema, } from "../../payment-cases/schemas/resolve-form.js";
+import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints.js";
+import { ADMIN_PAYMENT_CASE_KIND_TABS, ADMIN_PAYMENT_CASE_SEVERITY_TABS, ADMIN_PAYMENT_CASE_STATUS_TABS, } from "../constants/filter-tabs.js";
+import { toRecordArray, toRelativeDate, toStringValue, } from "../hooks/useAdminListingData.js";
+import { DataListingView } from "./DataListingView.js";
+/**
+ * Operator-facing names. Deliberately describe the PROBLEM rather than echo
+ * the field value — `missing_order` is "Captured, no order", which is what has
+ * actually happened and what the next action depends on.
+ *
+ * Kept beside the chip labels rather than shared with them: the chips are terse
+ * because they sit in a grid, these head a row and can afford a clause.
+ */
+const KIND_LABEL = {
+    missing_order: "Captured payment with no order",
+    unprocessed_event: "Gateway event never processed",
+    status_conflict: "Late event would have regressed an order",
+    dispute: "Chargeback",
+    refund_mismatch: "Refund totals disagree with the gateway",
+    amount_mismatch: "Captured amount ≠ recorded total",
+    dead_job: "Job exhausted its retries",
+    grievance: "Statutory grievance",
+    shipping_unpriced: "Store shipping could not be priced",
+    protection_claim: "Protection claim",
+    manual_refund_due: "Refund owed, no automatic rail",
+};
+/** Rupees, for a row. Plain `toFixed` — these are already decimal rupees. */
+function money(value) {
+    return typeof value === "number" ? `₹${value.toFixed(2)}` : null;
+}
+/**
+ * Narrow a JSON value to status-history entries.
+ *
+ * 🛑 A FUNCTION, NOT A CAST. This was `detail.statusHistory as
+ * StatusChangeEntry[] | undefined`, which `tsc` rejects as insufficiently
+ * overlapping — and the suggested `as unknown as` is the double cast this
+ * repo bans outright, because it has zero runtime effect and silences the one
+ * type-level signal there was.
+ *
+ * `detail` is a `JsonObject` off the wire, so narrowing is genuinely needed;
+ * the file already does exactly this for scalars via `toStringValue`. An
+ * array whose members are not objects returns undefined rather than being
+ * waved through — the timeline renders nothing, which is the honest outcome
+ * for data it cannot read.
+ */
+function toStatusHistory(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const ok = value.every((e) => typeof e === "object" && e !== null);
+    return ok ? value : undefined;
+}
+export function AdminMoneyCasesView({ children, ...props }) {
+    const [detail, setDetail] = useState(null);
+    const [resolveTargetId, setResolveTargetId] = useState(null);
+    const [dismissTargetId, setDismissTargetId] = useState(null);
+    /*
+     * Bumped after every mutation. `DataListingView` keys its react-query cache
+     * on `queryKey`, so changing the key is what forces a refetch — the reports
+     * page calls its own `load()` because it owns its fetch; this one does not.
+     */
+    const [revision, setRevision] = useState(0);
+    if (React.Children.count(children) > 0) {
+        return (_jsx(ListingLayout, { portal: "admin", ...props, children: children }));
+    }
+    const patch = async (id, body) => {
+        const res = await fetch(ADMIN_ENDPOINTS.PAYMENT_CASE_BY_ID(id), {
+            method: "PATCH",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            /*
+             * Thrown so `ReviewDecisionModal` stays OPEN and keeps the note the
+             * operator just typed. Its catch shows a toast and leaves the dialog up —
+             * a decision that did not save must not look like one that did.
+             */
+            throw new Error(`Could not update this case (${res.status})`);
+        }
+        setRevision((r) => r + 1);
+        setDetail(null);
+    };
+    const config = {
+        portal: "admin",
+        title: "Money cases",
+        subtitle: "Everything where money is at risk — chargebacks, captured payments with no order, refunds owed, protection claims and grievances. Opened automatically; only a human can close one.",
+        emptyLabel: "No open money cases",
+        // 🛑 No `searchPlaceholder` / `search` — the endpoint does not read `q`.
+        filterKeys: ["status", "kind", "severity"],
+        defaultSort: sortBy("lastObservedAt", "DESC"),
+        queryKey: ["admin", "payment-cases", "listing", String(revision)],
+        endpoint: ADMIN_ENDPOINTS.PAYMENT_CASES,
+        /*
+         * ── Two traps avoided here, both measured rather than assumed ──────────
+         *
+         * 🛑 THERE IS NO "SORT BY SEVERITY" OPTION, even though `severity` is
+         * `canSort: true` and the option is the obvious one to offer. It stores the
+         * STRINGS `error` / `warning` / `info`, so Firestore orders them
+         * alphabetically — and `DESC` therefore yields **warning, info, error**,
+         * putting the most urgent cases LAST. A sort that silently inverts the
+         * thing it claims to rank is worse than no sort (Root Cause #63), and it
+         * would be believed. `PAYMENT_CASE_SEVERITY_RANK` exists in TypeScript but
+         * is not a stored field, so there is nothing to order by; the severity
+         * FILTER is the correct control and it is in the panel.
+         *
+         * 🛑 The two optional-field sorts NAME their own exclusion. `dueAt` and
+         * `amountAtRisk` are both optional, and a Firestore `orderBy` excludes
+         * every document that LACKS the field (Root Cause #100) — so these sorts
+         * genuinely do shrink the list. For these two that is the right semantics
+         * ("soonest deadline" is a question about dated cases), but the shrinking
+         * must be stated: an unexplained shorter list is how someone concludes the
+         * queue is empty when it is not.
+         */
+        sortOptions: [
+            { value: sortBy("lastObservedAt", "DESC"), label: "Most recently seen" },
+            { value: sortBy("lastObservedAt", "ASC"), label: "Longest unseen" },
+            { value: sortBy("dueAt", "ASC"), label: "Soonest deadline (dated cases only)" },
+            { value: sortBy("amountAtRisk", "DESC"), label: "Largest amount (money cases only)" },
+            { value: sortBy("observedCount", "DESC"), label: "Most often re-seen" },
+            { value: sortBy("createdAt", "DESC"), label: "Newest" },
+            { value: sortBy("createdAt", "ASC"), label: "Oldest" },
+        ],
+        mapRows: (response) => toRecordArray(response.items).map((item, index) => {
+            const kind = toStringValue(item.kind, "unknown");
+            const observed = typeof item.observedCount === "number" ? item.observedCount : 1;
+            const amount = money(item.amountAtRisk);
+            const due = toStringValue(item.dueAt, "");
+            return {
+                id: toStringValue(item.id, `case-${index}`),
+                primary: toStringValue(item.title, KIND_LABEL[kind] ?? kind),
+                secondary: [
+                    KIND_LABEL[kind] ?? kind,
+                    amount ? `${amount} at risk` : null,
+                    // An external deadline is the one thing worth putting in a row.
+                    due ? `due ${new Date(due).toLocaleString()}` : null,
+                    // Only mentioned when it is informative — "seen once" is noise.
+                    observed > 1 ? `seen ${observed}×` : null,
+                ]
+                    .filter(Boolean)
+                    .join(" · "),
+                status: toStringValue(item.status, "open"),
+                updatedAt: toRelativeDate(item.lastObservedAt ?? item.createdAt),
+                _raw: item,
+            };
+        }),
+        getTotal: (response, mappedRows) => typeof response.meta?.total === "number" ? response.meta.total : mappedRows.length,
+        onRowClick: (row) => setDetail(row._raw),
+        buildFilters: (state) => {
+            const parts = [];
+            if (state.status && state.status !== "All")
+                parts.push(sieveFilter("status", SIEVE_OP.EQ, state.status));
+            if (state.kind && state.kind !== "All")
+                parts.push(sieveFilter("kind", SIEVE_OP.EQ, state.kind));
+            if (state.severity && state.severity !== "All")
+                parts.push(sieveFilter("severity", SIEVE_OP.EQ, state.severity));
+            return parts.length > 0 ? parts.join(",") : undefined;
+        },
+        renderRowActions: (row) => {
+            const status = row.status;
+            const closed = status === "actioned" || status === "dismissed";
+            return (_jsx(RowActionMenu, { actions: [
+                    { label: "View details", onClick: () => setDetail(row._raw) },
+                    /*
+                     * "Take" needs no note — it records that someone is looking, which
+                     * the schema's own `superRefine` exempts from the resolution floor.
+                     * Hidden once closed: re-opening a closed case is not a thing this
+                     * surface offers, because `resolve()` is one-way by design.
+                     */
+                    ...(closed
+                        ? []
+                        : [
+                            {
+                                label: status === "under-review" ? "Already taken" : "Take",
+                                onClick: () => patch(row.id, { status: "under-review" }),
+                                disabled: status === "under-review",
+                            },
+                            { label: "Resolve", onClick: () => setResolveTargetId(row.id) },
+                            { label: "Dismiss", onClick: () => setDismissTargetId(row.id) },
+                        ]),
+                ] }));
+        },
+        renderFilterPanel: ({ pendingFilters, setPendingFilters }) => (_jsxs(Stack, { gap: "md", children: [_jsx(FilterChipGroup, { label: "Status", tabs: ADMIN_PAYMENT_CASE_STATUS_TABS, value: pendingFilters.status ?? "", onChange: (id) => setPendingFilters((p) => ({ ...p, status: id })) }), _jsx(FilterChipGroup, { label: "Severity", tabs: ADMIN_PAYMENT_CASE_SEVERITY_TABS, value: pendingFilters.severity ?? "", onChange: (id) => setPendingFilters((p) => ({ ...p, severity: id })) }), _jsx(FilterChipGroup, { label: "Kind", tabs: ADMIN_PAYMENT_CASE_KIND_TABS, value: pendingFilters.kind ?? "", onChange: (id) => setPendingFilters((p) => ({ ...p, kind: id })) })] })),
+    };
+    const detailKind = detail ? toStringValue(detail.kind, "") : "";
+    const detailStatus = detail ? toStringValue(detail.status, "") : "";
+    const selfHealed = detail ? toStringValue(detail.selfHealedAt, "") : "";
+    return (_jsxs(_Fragment, { children: [_jsx(DataListingView, { config: config }), _jsx(RecordDetailModal, { isOpen: detail !== null, onClose: () => setDetail(null), title: detail ? toStringValue(detail.title, "Money case") : "Money case", badges: detail
+                    ? [
+                        { label: detailStatus || "open" },
+                        { label: KIND_LABEL[detailKind] ?? detailKind },
+                        { label: toStringValue(detail.severity, "info") },
+                    ]
+                    : undefined, description: detail ? toStringValue(detail.detail, "") : undefined, fields: detail
+                    ? [
+                        { label: "Case id", value: toStringValue(detail.id, "") },
+                        { label: "Subject", value: `${toStringValue(detail.entityType, "")} ${toStringValue(detail.entityId, "")}` },
+                        { label: "Amount at risk", value: money(detail.amountAtRisk) ?? "—" },
+                        {
+                            label: "External deadline",
+                            value: toStringValue(detail.dueAt, "") || "none — this case has no clock",
+                        },
+                        {
+                            label: "Times observed",
+                            value: String(detail.observedCount ?? 1),
+                        },
+                        { label: "Last seen", value: toStringValue(detail.lastObservedAt, "") },
+                        { label: "Assigned to", value: toStringValue(detail.assignedTo, "") || "—" },
+                        { label: "Gateway payment", value: toStringValue(detail.gatewayPaymentId, "") || "—" },
+                        { label: "Resolution", value: toStringValue(detail.resolution, "") || "—" },
+                    ]
+                    : undefined, 
+                /*
+                 * 🛑 `selfHealedAt` is rendered as a QUESTION, never as a resolution.
+                 *
+                 * A reconciler that stops observing a problem writes this field and
+                 * nothing else — the case stays `open` on purpose. "The symptom went
+                 * away" and "a human understands why" are different facts, and on money
+                 * only the second one closes anything: a self-healed `missing_order`
+                 * might mean the retry worked, or might mean somebody refunded it by
+                 * hand and the order will never exist.
+                 */
+                extra: detail ? (_jsxs(Stack, { gap: "md", children: [selfHealed ? (_jsx(Row, { surface: "info-surface", padding: "sm", rounded: "default", children: _jsxs(Text, { size: "sm", color: "info", children: ["A reconciler no longer sees this problem (as of", " ", new Date(selfHealed).toLocaleString(), "). That is not a resolution \u2014 confirm what happened, then resolve or dismiss it."] }) })) : null, _jsx(RecordStatusTimeline, { entries: toStatusHistory(detail.statusHistory), truncatedCount: typeof detail.statusHistoryTruncated === "number"
+                                ? detail.statusHistoryTruncated
+                                : undefined, emptyLabel: "Opened automatically; nothing has happened to it yet" })] })) : undefined, footer: detail && detailStatus !== "actioned" && detailStatus !== "dismissed" ? (_jsxs(_Fragment, { children: [_jsx(Button, { variant: "outline", size: "sm", onClick: () => setResolveTargetId(toStringValue(detail.id, "")), children: "Resolve" }), _jsx(Button, { variant: "ghost", size: "sm", onClick: () => setDismissTargetId(toStringValue(detail.id, "")), children: "Dismiss" })] })) : undefined }), _jsx(ReviewDecisionModal, { isOpen: resolveTargetId !== null, onClose: () => setResolveTargetId(null), title: "Resolve this case", schema: paymentCaseResolveFormSchema, status: "actioned", noteField: "resolution", noteLabel: "What did you do?", noteHelp: "Required. The next person reading this case has only what you write here.", notePlaceholder: "e.g. Refunded \u20B92,511.80 to the buyer from the Razorpay dashboard; the order could not be placed because the address was missing.", confirmLabel: "Resolve case", onConfirm: (values) => patch(resolveTargetId, values) }), _jsx(ReviewDecisionModal, { isOpen: dismissTargetId !== null, onClose: () => setDismissTargetId(null), title: "Dismiss this case", schema: paymentCaseResolveFormSchema, status: "dismissed", noteField: "resolution", noteLabel: "Why is nothing wrong here?", noteHelp: "Required. A dismissed case with no reason reads identically to one nobody looked at.", notePlaceholder: "e.g. Duplicate of the event two rows above \u2014 same payment id, already refunded.", confirmLabel: "Dismiss case", onConfirm: (values) => patch(dismissTargetId, values) })] }));
+}