@mohasinac/appkit 4.58.0 → 4.60.0

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

@@ -12,9 +12,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
  *
  *     Event handlers cannot be passed to Client Component props.
  *
- * at render. `ProductOwnerQuickActions` records that this exact mistake took
- * down every `/products/[slug]` page in production, with an opaque digest per
- * handler.
+ * at render. The now-deleted product-specific wrapper recorded that this exact
+ * mistake took down every `/products/[slug]` page in production, with an
+ * opaque digest per handler.
  *
  * That is why ten detail views were passing `editHref` and nothing else: the
  * bin and the clone are rendered behind `{showDelete && …}` / `{showClone && …}`,
@@ -23,20 +23,26 @@ import { jsx as _jsx } from "react/jsx-runtime";
  *
  * ## 🛑 Why ONE wrapper and not one per resource
  *
- * `ProductOwnerQuickActions` is resource-specific because products are the one
- * collection a SELLER can also own, so its endpoints live under
- * `SELLER_ENDPOINTS` and its clone has a bespoke redirect to the copy's editor.
- * Everything here is admin-owned and differs only by three strings, so eight
- * near-identical files would trip the Duplication Framework's Rule of Three
- * immediately. One table, one component.
+ * There used to be TWO wrappers — this one and `ProductOwnerQuickActions` —
+ * because a product is the only collection a SELLER can also own, so it needs
+ * `SELLER_ENDPOINTS`, a clone that lands on the copy's editor, and a
+ * post-delete target that is not an admin list.
+ *
+ * 🛑 THOSE THREE DIFFERENCES ARE NOW ROWS IN THE TABLE, NOT A SECOND FILE.
+ * Every one of them is real and every one survives — but none needed a
+ * separate component to express, and having two meant two places for the box,
+ * the placement and the visibility rule to drift. That drift is exactly what
+ * shipped: five card types pinned the toolbar to four different corners, one
+ * of them on top of its own CTA, and the category hero rendered it over the
+ * `<h1>`. One table, one component, one position everywhere.
  *
  * ## Why the redirect lands on the ADMIN list
  *
  * You deleted the record from its own public page, so that page is now a 404 —
  * staying is not an option and the public index tells you nothing about whether
  * the delete worked. The admin list is where the absence is verifiable.
- * `ProductOwnerQuickActions` differs deliberately: a seller may delete a
- * product and has no admin list to land on.
+ * PRODUCT differs deliberately, through its own `afterDelete`: a seller may
+ * delete a product and has no admin list to land on.
  *
  * @tag domain:admin
  * @tag layer:components
@@ -44,7 +50,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
  */
 import { useCallback } from "react";
 import { OwnerQuickActions } from "./OwnerQuickActions.js";
-import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints.js";
+import { ADMIN_ENDPOINTS, SELLER_ENDPOINTS } from "../../../constants/api-endpoints.js";
 import { ROUTES } from "../../../next/routing/route-map.js";
 const WIRING = {
     CATEGORY: {
@@ -97,6 +103,18 @@ const WIRING = {
         editHref: (id) => String(ROUTES.ADMIN.CATEGORIES_EDIT(id)),
         afterDelete: String(ROUTES.ADMIN.CATEGORIES),
     },
+    PRODUCT: {
+        endpoint: SELLER_ENDPOINTS.PRODUCT_BY_ID,
+        editHref: (id) => String(ROUTES.STORE.PRODUCTS_EDIT(id)),
+        afterDelete: String(ROUTES.STORE.PRODUCTS),
+        clone: SELLER_ENDPOINTS.PRODUCT_DUPLICATE,
+        afterClone: (newId) => String(ROUTES.STORE.PRODUCTS_EDIT(newId)),
+    },
+    FAQ: {
+        endpoint: ADMIN_ENDPOINTS.FAQ_BY_ID,
+        editHref: (id) => String(ROUTES.ADMIN.FAQS_EDIT(id)),
+        afterDelete: String(ROUTES.ADMIN.FAQS),
+    },
     SUBLISTING: {
         endpoint: ADMIN_ENDPOINTS.SUBLISTING_CATEGORY_BY_ID,
         editHref: (id) => String(ROUTES.ADMIN.SUBLISTING_CATEGORIES_EDIT(id)),
@@ -112,7 +130,7 @@ export function RecordOwnerQuickActions({ resource, recordId, recordLabel, owner
      * navigates away — so a swallowed failure is indistinguishable from "it
      * worked but the page did not move", and the obvious user response is to
      * press the button again. Returning early on `!res.ok` is the bug
-     * `ProductOwnerQuickActions` documents having had.
+     * the deleted product wrapper documented having had.
      */
     const handleDelete = useCallback(async () => {
         const res = await fetch(wiring.endpoint(recordId), { method: "DELETE" });
@@ -124,5 +142,34 @@ export function RecordOwnerQuickActions({ resource, recordId, recordLabel, owner
             window.location.assign(wiring.afterDelete);
         }
     }, [wiring, recordId]);
-    return (_jsx(OwnerQuickActions, { resource: resource, placement: placement, onMedia: onMedia, className: className, recordLabel: recordLabel, ownerId: ownerId, storeId: storeId, editHref: wiring.editHref(recordId), onDelete: handleDelete }));
+    /*
+     * Clone, for the resources whose table entry declares one.
+     *
+     * 🛑 Built UNCONDITIONALLY — the hook cannot be called behind an `if` — but
+     * passed to `OwnerQuickActions` only when `wiring.clone` exists, which is
+     * what makes the button absent rather than present-and-broken for the
+     * resources that cannot be copied.
+     *
+     * 🛑 THROWS on failure, like `handleDelete` above and for the same reason:
+     * `OwnerQuickActions` catches and toasts, so returning quietly is
+     * indistinguishable from "it worked but the page did not move", and the
+     * obvious user response is to press it again. The previous product-specific
+     * implementation returned early after showing its own toast, which is the
+     * double-toast path this avoids.
+     */
+    const handleClone = useCallback(async () => {
+        if (!wiring.clone)
+            return;
+        const res = await fetch(wiring.clone(recordId), { method: "POST" });
+        if (!res.ok) {
+            const body = (await res.json().catch(() => null));
+            throw Object.assign(new Error("Clone failed"), { code: body?.code });
+        }
+        const json = (await res.json().catch(() => null));
+        const newId = json?.data?.id;
+        if (newId && wiring.afterClone && typeof window !== "undefined") {
+            window.location.assign(wiring.afterClone(newId));
+        }
+    }, [wiring, recordId]);
+    return (_jsx(OwnerQuickActions, { resource: resource, placement: placement, onMedia: onMedia, className: className, recordLabel: recordLabel, ownerId: ownerId, storeId: storeId, editHref: wiring.editHref(recordId), onDelete: handleDelete, onClone: wiring.clone ? handleClone : undefined }));
 }

package/dist/features/admin/components/analytics/AdminStatCard.d.ts

@@ -9,6 +9,40 @@ export interface AdminStatCardProps {
     /** Named preset or raw CSS gradient string */
     gradient?: keyof typeof GRADIENTS | string;
     className?: string;
+    /**
+     * Change against the previous comparable period, as a SIGNED percentage.
+     * `12.4` renders "▲ 12.4%", `-3` renders "▼ 3%", `0` renders "no change".
+     *
+     * 🛑 OMIT IT WHEN THERE IS NO COMPARISON, and never pass `0` to mean "we
+     * did not measure". A number here is a factual claim about a previous
+     * period; `0` claims the figure held steady, which is a different and
+     * stronger statement than silence. The whole reason a trend is worth adding
+     * is that it is trusted, and a fabricated flat line is the cheapest way to
+     * lose that.
+     */
+    trendPercent?: number;
+    /**
+     * What `trendPercent` is measured against — "vs last week", "vs yesterday".
+     *
+     * 🛑 REQUIRED WHENEVER `trendPercent` IS PASSED, enforced by the discriminated
+     * shape below rather than by a comment. "▲ 12.4%" alone is unreadable: up
+     * on what? The same number is excellent against last month and alarming
+     * against last hour.
+     */
+    trendLabel?: string;
+    /**
+     * 🛑 DOES A HIGHER NUMBER MEAN BETTER? Defaults to `true`, and the exception
+     * is the reason this prop exists: refunds, cancellations, failed payments
+     * and error counts all go UP when things go WRONG. Colouring those green
+     * because the arrow points up is a dashboard actively misinforming the
+     * person reading it.
+     */
+    higherIsBetter?: boolean;
+    /**
+     * Recent values, oldest first, for the sparkline. Needs at least two points
+     * to draw a line; fewer renders nothing rather than a dot or a flat stub.
+     */
+    series?: readonly number[];
 }
-export declare function AdminStatCard({ label, value, sub, icon, gradient, className, }: AdminStatCardProps): React.JSX.Element;
+export declare function AdminStatCard({ label, value, sub, icon, gradient, className, trendPercent, trendLabel, higherIsBetter, series, }: AdminStatCardProps): React.JSX.Element;
 export {};

package/dist/features/admin/components/analytics/AdminStatCard.js

@@ -11,7 +11,82 @@ const GRADIENTS = {
     amber: "var(--appkit-gradient-warning-stat)",
     rose: "var(--appkit-gradient-danger-stat)",
 };
-export function AdminStatCard({ label, value, sub, icon, gradient = "brand", className = "", }) {
+/**
+ * A 40×24 trend line. Deliberately NOT recharts.
+ *
+ * 🛑 recharts IS installed and is used for the three real charts in this app —
+ * but it is a ~100 KB client bundle with a `ResponsiveContainer` that measures
+ * on mount, and a dashboard home renders six to eight of these. Six
+ * ResizeObservers to draw six polylines is a layout-thrash and a bundle cost
+ * for 24 pixels of decoration. An inline `<svg>` with a `<polyline>` is the
+ * whole feature.
+ *
+ * `preserveAspectRatio="none"` so the line fills its box at any size: the
+ * values are normalised to 0–100 here, so the viewBox IS the data range and
+ * stretching it is correct rather than distorting.
+ */
+function Sparkline({ series, rising, }) {
+    const min = Math.min(...series);
+    const max = Math.max(...series);
+    /*
+     * 🛑 A FLAT SERIES IS DRAWN FLAT, not divided by zero. When every value is
+     * equal `max - min` is 0; the guard puts the line down the middle, which is
+     * what "no change" looks like. Without it every point becomes NaN and the
+     * polyline silently renders nothing — a missing sparkline that reads as
+     * "no data" about a series that is simply steady.
+     */
+    const span = max - min || 1;
+    const points = series
+        .map((v, i) => {
+        const x = (i / (series.length - 1)) * 100;
+        // SVG y grows downward, so the value is inverted.
+        const y = 100 - ((v - min) / span) * 100;
+        return `${x.toFixed(2)},${y.toFixed(2)}`;
+    })
+        .join(" ");
+    return (_jsx("svg", { viewBox: "0 0 100 100", preserveAspectRatio: "none", className: "h-full w-full", focusable: "false", children: _jsx("polyline", { points: points, fill: "none", stroke: rising
+                ? "var(--appkit-color-success)"
+                : "var(--appkit-color-error)", strokeWidth: 6, strokeLinecap: "round", strokeLinejoin: "round", vectorEffect: "non-scaling-stroke" }) }));
+}
+export function AdminStatCard({ label, value, sub, icon, gradient = "brand", className = "", trendPercent, trendLabel, higherIsBetter = true, series, }) {
     const resolvedGradient = GRADIENTS[gradient] ?? gradient;
-    return (_jsxs(Div, { className: `relative border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] overflow-hidden ${className}`, rounded: "xl", shadow: "sm-hover-md", children: [_jsx(DynamicBgDiv, { background: resolvedGradient, className: "absolute top-0 left-0 right-0 h-[3px]", "aria-hidden": "true" }), _jsxs(Row, { paddingX: "x-5", paddingY: "b-md-lg", padding: "t-lg", align: "start", justify: "between", gap: "3", children: [_jsxs(Div, { className: "min-w-0 flex-1", children: [_jsx(Text, { className: "text-[11px] tracking-widest text-[var(--appkit-color-text-muted)]", weight: "semibold", transform: "uppercase", children: label }), _jsx(Heading, { level: 3, className: "mt-2 tabular-nums leading-none text-[var(--appkit-color-text)]", size: "2xl", weight: "bold", children: value }), sub && (_jsx(Text, { className: "mt-1.5 text-[var(--appkit-color-text-muted)]", size: "xs", children: sub }))] }), icon && (_jsx(DynamicBgDiv, { background: resolvedGradient, className: "flex-shrink-0 w-10 h-10 flex items-center justify-center rounded-lg text-[length:var(--appkit-text-xl)]", children: icon }))] })] }));
+    /*
+     * 🛑 `!= null`, NOT a truthiness check. `trendPercent === 0` is a real
+     * measurement — "this figure did not move" — and `if (trendPercent)` would
+     * discard exactly that reading while keeping every other one. The same
+     * mistake as `rating !== undefined` passing for `rating: 0`, which showed
+     * five stars on unreviewed products (and is fixed two commits over).
+     */
+    const showTrend = trendPercent != null;
+    /* Two points minimum: one point is not a line, and a 1-point polyline
+     * renders as nothing at all rather than as a dot. */
+    const showSpark = Array.isArray(series) && series.length >= 2;
+    const up = showTrend && trendPercent > 0;
+    const down = showTrend && trendPercent < 0;
+    const flat = showTrend && trendPercent === 0;
+    /*
+     * 🛑 GOOD/BAD IS NOT UP/DOWN. Refunds, cancellations, failed payments and
+     * error counts all rise when things go wrong, so `higherIsBetter` decides
+     * the colour and the arrow only decides the direction. Tying the tone to
+     * the arrow would paint a spike in refunds green.
+     */
+    const good = higherIsBetter ? up : down;
+    const bad = higherIsBetter ? down : up;
+    const trendTone = flat ? "muted" : good ? "success" : bad ? "error" : "muted";
+    const trendArrow = flat ? "–" : up ? "▲" : "▼";
+    const trendText = flat
+        ? "no change"
+        : `${up ? "up" : "down"} ${Math.abs(trendPercent).toFixed(1).replace(/\.0$/, "")}%`;
+    // The sparkline's colour follows the same good/bad rule, not its slope.
+    const sparkRising = good || (flat && higherIsBetter);
+    return (_jsxs(Div, { className: `relative border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] overflow-hidden ${className}`, rounded: "xl", shadow: "sm-hover-md", children: [_jsx(DynamicBgDiv, { background: resolvedGradient, className: "absolute top-0 left-0 right-0 h-[3px]", "aria-hidden": "true" }), _jsxs(Row, { paddingX: "x-5", paddingY: "b-md-lg", padding: "t-lg", align: "start", justify: "between", gap: "3", children: [_jsxs(Div, { className: "min-w-0 flex-1", children: [_jsx(Text, { className: "text-[11px] tracking-widest text-[var(--appkit-color-text-muted)]", weight: "semibold", transform: "uppercase", children: label }), _jsx(Heading, { level: 3, className: "mt-2 tabular-nums leading-none text-[var(--appkit-color-text)]", size: "2xl", weight: "bold", children: value }), sub && (_jsx(Text, { className: "mt-1.5 text-[var(--appkit-color-text-muted)]", size: "xs", children: sub }))] }), icon && (_jsx(DynamicBgDiv, { background: resolvedGradient, className: "flex-shrink-0 w-10 h-10 flex items-center justify-center rounded-lg text-[length:var(--appkit-text-xl)]", children: icon }))] }), (showTrend || showSpark) && (_jsxs(Row, { paddingX: "x-5", padding: "b-md", align: "center", justify: "between", gap: "3", children: [showTrend ? (_jsxs(Text, { size: "xs", color: trendTone, weight: "semibold", children: [_jsxs("span", { "aria-hidden": "true", children: [trendArrow, " "] }), trendText, trendLabel ? (_jsxs(Text, { as: "span", size: "xs", color: "muted", weight: "normal", children: [" ", trendLabel] })) : null] })) : (_jsx("span", {})), showSpark && (
+                    /*
+                      🛑 `aria-hidden`, with NO accessible label. A sparkline is a
+                      decorative restatement of a trend already given in words
+                      directly beside it — describing it again would make a screen
+                      reader read the same fact twice. If the series ever carried
+                      information the trend line does not, it needs a real chart with
+                      a real description, not a label bolted onto 40 pixels.
+                    */
+                    _jsx(Div, { "aria-hidden": "true", className: "h-6 w-20 flex-shrink-0 opacity-80", children: _jsx(Sparkline, { series: series, rising: sparkRising }) }))] }))] }));
 }

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

@@ -105,6 +105,10 @@ export { AdminPayoutMarkPaidModal } from "./AdminPayoutMarkPaidModal";
 export type { AdminPayoutMarkPaidModalProps } from "./AdminPayoutMarkPaidModal";
 export { AdminAuditLogView } from "./AdminAuditLogView";
 export type { AdminAuditLogViewProps } from "./AdminAuditLogView";
+export { AdminMoneyCasesView } from "./AdminMoneyCasesView";
+export type { AdminMoneyCasesViewProps } from "./AdminMoneyCasesView";
+export { AdminGatewayEventsView } from "./AdminGatewayEventsView";
+export type { AdminGatewayEventsViewProps } from "./AdminGatewayEventsView";
 export { ViewAuditLogEntryModal } from "./ViewAuditLogEntryModal";
 export type { AuditLogEntryDetail, ViewAuditLogEntryModalProps } from "./ViewAuditLogEntryModal";
 export { ViewNotificationModal } from "./ViewNotificationModal";

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

@@ -57,6 +57,12 @@ export { AdminHistoryView } from "./AdminHistoryView.js";
 export { AdminPayoutsView } from "./AdminPayoutsView.js";
 export { AdminPayoutMarkPaidModal } from "./AdminPayoutMarkPaidModal.js";
 export { AdminAuditLogView } from "./AdminAuditLogView.js";
+/*
+ * Payment protection — the operator queue for everything where money is at
+ * risk, and the first surface `paymentCases` has ever had.
+ */
+export { AdminMoneyCasesView } from "./AdminMoneyCasesView.js";
+export { AdminGatewayEventsView } from "./AdminGatewayEventsView.js";
 export { ViewAuditLogEntryModal } from "./ViewAuditLogEntryModal.js";
 export { ViewNotificationModal } from "./ViewNotificationModal.js";
 export { AdminReviewsView } from "./AdminReviewsView.js";

package/dist/features/admin/constants/filter-tabs.d.ts

@@ -699,3 +699,159 @@ export declare const SELLER_BID_STATUS_TABS: readonly [{
     readonly id: "cancelled";
     readonly label: "Cancelled";
 }];
+/** Admin > Money cases — `PaymentCaseStatus`. `open` is the birth state. */
+export declare const ADMIN_PAYMENT_CASE_STATUS_TABS: readonly [{
+    readonly id: "All";
+    readonly label: "All";
+}, {
+    readonly id: "open";
+    readonly label: "Open";
+}, {
+    readonly id: "under-review";
+    readonly label: "Under review";
+}, {
+    readonly id: "actioned";
+    readonly label: "Actioned";
+}, {
+    readonly id: "dismissed";
+    readonly label: "Dismissed";
+}];
+/**
+ * Admin > Money cases — `PaymentCaseKind`, all eleven.
+ *
+ * Labels are what an operator recognises, not the field value: `missing_order`
+ * reads as "Captured, no order", which is what the problem IS. The ids stay
+ * byte-exact against the union because they go straight into a Sieve equality
+ * and a near-miss returns zero rows forever with no error (Root Cause #33).
+ */
+export declare const ADMIN_PAYMENT_CASE_KIND_TABS: readonly [{
+    readonly id: "All";
+    readonly label: "All";
+}, {
+    readonly id: "missing_order";
+    readonly label: "Captured, no order";
+}, {
+    readonly id: "dispute";
+    readonly label: "Chargeback";
+}, {
+    readonly id: "manual_refund_due";
+    readonly label: "Refund owed";
+}, {
+    readonly id: "refund_mismatch";
+    readonly label: "Refund mismatch";
+}, {
+    readonly id: "amount_mismatch";
+    readonly label: "Amount mismatch";
+}, {
+    readonly id: "unprocessed_event";
+    readonly label: "Unprocessed event";
+}, {
+    readonly id: "status_conflict";
+    readonly label: "Status conflict";
+}, {
+    readonly id: "protection_claim";
+    readonly label: "Protection claim";
+}, {
+    readonly id: "grievance";
+    readonly label: "Grievance";
+}, {
+    readonly id: "shipping_unpriced";
+    readonly label: "Shipping unpriced";
+}, {
+    readonly id: "dead_job";
+    readonly label: "Dead job";
+}, {
+    readonly id: "ledger_drift";
+    readonly label: "Points drift";
+}];
+/** Admin > Money cases — `PaymentCaseSeverity`. Escalate-only, never downgraded. */
+export declare const ADMIN_PAYMENT_CASE_SEVERITY_TABS: readonly [{
+    readonly id: "All";
+    readonly label: "All";
+}, {
+    readonly id: "error";
+    readonly label: "Error";
+}, {
+    readonly id: "warning";
+    readonly label: "Warning";
+}, {
+    readonly id: "info";
+    readonly label: "Info";
+}];
+/**
+ * Admin > Gateway events — `GatewayEventStatus`.
+ *
+ * `ignored` is a real, healthy outcome and not a failure: an event type we are
+ * subscribed to but do not implement is recorded verbatim and settled
+ * `ignored`, which is the whole reason the inbox records unknown events rather
+ * than dropping them. `conflict` means a late event would have regressed an
+ * order's status — also not an error.
+ */
+export declare const ADMIN_GATEWAY_EVENT_STATUS_TABS: readonly [{
+    readonly id: "All";
+    readonly label: "All";
+}, {
+    readonly id: "received";
+    readonly label: "Received";
+}, {
+    readonly id: "processing";
+    readonly label: "Processing";
+}, {
+    readonly id: "processed";
+    readonly label: "Processed";
+}, {
+    readonly id: "failed";
+    readonly label: "Failed";
+}, {
+    readonly id: "conflict";
+    readonly label: "Late / conflict";
+}, {
+    readonly id: "ignored";
+    readonly label: "Ignored";
+}];
+/** Admin > Gateway events — `GatewayEventKind`. */
+export declare const ADMIN_GATEWAY_EVENT_KIND_TABS: readonly [{
+    readonly id: "All";
+    readonly label: "All";
+}, {
+    readonly id: "paid";
+    readonly label: "Paid";
+}, {
+    readonly id: "failed";
+    readonly label: "Failed";
+}, {
+    readonly id: "refund";
+    readonly label: "Refund";
+}, {
+    readonly id: "dispute";
+    readonly label: "Dispute";
+}, {
+    readonly id: "other";
+    readonly label: "Other";
+}];
+/** Admin > Protection claims — `ProtectionClaimStatus`. */
+export declare const ADMIN_PROTECTION_CLAIM_STATUS_TABS: readonly [{
+    readonly id: "All";
+    readonly label: "All";
+}, {
+    readonly id: "open";
+    readonly label: "Open";
+}, {
+    readonly id: "awaiting-return";
+    readonly label: "Awaiting return";
+}, {
+    readonly id: "inspecting";
+    readonly label: "Inspecting";
+}, {
+    readonly id: "upheld";
+    readonly label: "Upheld";
+}, {
+    readonly id: "rejected";
+    readonly label: "Rejected";
+}, {
+    readonly id: "withdrawn";
+    readonly label: "Withdrawn";
+}, {
+    readonly id: "expired";
+    readonly label: "Expired";
+}];

package/dist/features/admin/constants/filter-tabs.js

@@ -401,3 +401,109 @@ export const SELLER_BID_STATUS_TABS = [
     { id: "lost", label: "Lost" },
     { id: "cancelled", label: "Cancelled" },
 ];
+// ============================================================================
+// PAYMENT PROTECTION — the four collections the money spine writes to
+//
+// All eight arrays below are registered in `audit-filter-tab-enums`, whose
+// COVERAGE check is what makes them worth having: a kind with no chip is a kind
+// an operator cannot isolate, and these are the queues where that costs money
+// rather than convenience (Root Cause #72).
+//
+// They are rendered in a filter PANEL, not an always-visible chip row — eleven
+// case kinds and twelve obligation kinds are a complete set, not a scannable
+// one, and `renderFilterPanel` is where a complete set belongs.
+// ============================================================================
+/** Admin > Money cases — `PaymentCaseStatus`. `open` is the birth state. */
+export const ADMIN_PAYMENT_CASE_STATUS_TABS = [
+    ALL_TAB,
+    { id: "open", label: "Open" },
+    { id: "under-review", label: "Under review" },
+    { id: "actioned", label: "Actioned" },
+    { id: "dismissed", label: "Dismissed" },
+];
+/**
+ * Admin > Money cases — `PaymentCaseKind`, all eleven.
+ *
+ * Labels are what an operator recognises, not the field value: `missing_order`
+ * reads as "Captured, no order", which is what the problem IS. The ids stay
+ * byte-exact against the union because they go straight into a Sieve equality
+ * and a near-miss returns zero rows forever with no error (Root Cause #33).
+ */
+export const ADMIN_PAYMENT_CASE_KIND_TABS = [
+    ALL_TAB,
+    { id: "missing_order", label: "Captured, no order" },
+    { id: "dispute", label: "Chargeback" },
+    { id: "manual_refund_due", label: "Refund owed" },
+    { id: "refund_mismatch", label: "Refund mismatch" },
+    { id: "amount_mismatch", label: "Amount mismatch" },
+    { id: "unprocessed_event", label: "Unprocessed event" },
+    { id: "status_conflict", label: "Status conflict" },
+    { id: "protection_claim", label: "Protection claim" },
+    { id: "grievance", label: "Grievance" },
+    { id: "shipping_unpriced", label: "Shipping unpriced" },
+    { id: "dead_job", label: "Dead job" },
+    { id: "ledger_drift", label: "Points drift" },
+];
+/** Admin > Money cases — `PaymentCaseSeverity`. Escalate-only, never downgraded. */
+export const ADMIN_PAYMENT_CASE_SEVERITY_TABS = [
+    ALL_TAB,
+    { id: "error", label: "Error" },
+    { id: "warning", label: "Warning" },
+    { id: "info", label: "Info" },
+];
+/**
+ * Admin > Gateway events — `GatewayEventStatus`.
+ *
+ * `ignored` is a real, healthy outcome and not a failure: an event type we are
+ * subscribed to but do not implement is recorded verbatim and settled
+ * `ignored`, which is the whole reason the inbox records unknown events rather
+ * than dropping them. `conflict` means a late event would have regressed an
+ * order's status — also not an error.
+ */
+export const ADMIN_GATEWAY_EVENT_STATUS_TABS = [
+    ALL_TAB,
+    { id: "received", label: "Received" },
+    { id: "processing", label: "Processing" },
+    { id: "processed", label: "Processed" },
+    { id: "failed", label: "Failed" },
+    { id: "conflict", label: "Late / conflict" },
+    { id: "ignored", label: "Ignored" },
+];
+/** Admin > Gateway events — `GatewayEventKind`. */
+export const ADMIN_GATEWAY_EVENT_KIND_TABS = [
+    ALL_TAB,
+    { id: "paid", label: "Paid" },
+    { id: "failed", label: "Failed" },
+    { id: "refund", label: "Refund" },
+    { id: "dispute", label: "Dispute" },
+    { id: "other", label: "Other" },
+];
+/*
+ * 🛑 NO obligation tab arrays, and the absence is deliberate.
+ *
+ * `ADMIN_OBLIGATION_STATE_TABS` and `ADMIN_OBLIGATION_KIND_TABS` were written
+ * here and removed before shipping, because `/admin/maintenance/obligations`
+ * does not filter:
+ *
+ *   · the page reads `obligationsRepository.listDue()`, which returns OPEN and
+ *     overdue rows by definition — so a state filter would offer five chips of
+ *     which exactly one can ever match anything;
+ *   · `ObligationsRepository` declares **no `SIEVE_FIELDS`**, on its own stated
+ *     reasoning that a filterable surface nothing calls is the speculative-infra
+ *     pattern. Adding one to feed chips nobody needs would be that pattern
+ *     twice over.
+ *
+ * Twelve chips with nothing behind them is exactly the dead control this file's
+ * COVERAGE note exists to prevent — it would just fail in the other direction.
+ */
+/** Admin > Protection claims — `ProtectionClaimStatus`. */
+export const ADMIN_PROTECTION_CLAIM_STATUS_TABS = [
+    ALL_TAB,
+    { id: "open", label: "Open" },
+    { id: "awaiting-return", label: "Awaiting return" },
+    { id: "inspecting", label: "Inspecting" },
+    { id: "upheld", label: "Upheld" },
+    { id: "rejected", label: "Rejected" },
+    { id: "withdrawn", label: "Withdrawn" },
+    { id: "expired", label: "Expired" },
+];

package/dist/features/admin/repository/site-settings.repository.d.ts

@@ -5,6 +5,28 @@
  */
 import { BaseRepository } from "../../../providers/db-firebase";
 import { SiteSettingsDocument, SiteSettingsCredentialsMasked, SiteSettingsUpdateInput } from "../schemas";
+/**
+ * Flatten a nested update into Firestore dotted field paths, so a partial
+ * group update MERGES into the stored map instead of replacing it.
+ *
+ * `update({ commissions: { gstPercent: 18 } })` deletes every other key under
+ * `commissions`; `update({ "commissions.gstPercent": 18 })` touches one leaf.
+ * See the call site for the five keys that were silently destroyed by the
+ * former (D13).
+ *
+ * Three cases are deliberately NOT recursed into:
+ *
+ * · **Arrays** — an array is a VALUE, not a map. Flattening
+ *   `legalPages.sections.0.title` would make a shorter replacement array leave
+ *   the old tail in place, which is a worse bug than the one being fixed.
+ * · **`undefined`** — kept at its own path so a caller can still delete a
+ *   field. Recursing would turn it into a path to nothing.
+ * · **`Date` and any other class instance** — Firestore stores a `Date` as a
+ *   Timestamp; walking its properties would write `{}`. Tested by rejecting
+ *   anything whose prototype is not `Object.prototype`, which also covers
+ *   `FieldValue` sentinels and `Timestamp` itself.
+ */
+export declare function toDottedPaths(input: Record<string, unknown>, prefix?: string): Record<string, unknown>;
 /**
  * Repository for site settings management
  *