npm - @mohasinac/appkit - Versions diffs - 4.58.0 → 4.60.0 - Mend

@mohasinac/appkit 4.58.0 → 4.60.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1080) hide show

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

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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) })] }));
+}

package/dist/features/admin/components/AdminPartsView.js CHANGED Viewed

@@ -1,5 +1,5 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * AdminPartsView — browse and correct the generated part glossary.
  *
@@ -156,5 +156,5 @@ export function AdminPartsView({ children, ...props }) {
     if (React.Children.count(children) > 0) {
         return (_jsxs(ListingLayout, { portal: "admin", ...props, children: [_jsx(Heading, { level: 1, className: "sr-only", children: "Parts" }), children] }));
     }
-    return (_jsxs(_Fragment, { children: [_jsx(Heading, { level: 1, className: "sr-only", children: "Parts" }), _jsx(DataListingView, { config: ADMIN_PARTS_CONFIG })] }));
+    return _jsx(DataListingView, { config: ADMIN_PARTS_CONFIG });
 }