@mohasinac/appkit 4.22.0 → 4.24.0

package/dist/features/admin/actions/notification-actions.js

@@ -7,6 +7,30 @@ import { isChannelHealthy, withChannelRetry } from "../../../_internal/server/no
 import { enqueueJob } from "../../jobs/actions/enqueue-job";
 import { serverLogger } from "../../../monitoring";
 import { decryptPii } from "../../../security/index";
+import { resolveNotificationActionUrl, } from "../../../_internal/shared/features/notifications/action-url";
+import { renderNotificationEmail } from "../../email/notification-templates";
+/**
+ * A notification's `actionUrl` is a site-relative path — correct for the
+ * in-app bell, useless in an email, where a bare `/user/orders/x` is not a
+ * link at all.
+ *
+ * `NEXT_PUBLIC_APP_URL` is the same source `ApiClient` uses for its own
+ * server-side base, so there is one answer to "what host is this" rather than
+ * a second one on `siteSettings` to drift from it.
+ *
+ * Falls back to returning the path unchanged rather than guessing a host: a
+ * wrong absolute URL sends the reader to someone else's site, while a
+ * relative one merely fails to be clickable. The template also drops the
+ * button entirely when this is undefined.
+ */
+function absoluteActionUrl(path) {
+    if (!path)
+        return undefined;
+    if (/^https?:\/\//i.test(path))
+        return path;
+    const base = process.env.NEXT_PUBLIC_APP_URL?.replace(/\/+$/, "");
+    return base ? `${base}${path}` : path;
+}
 import { DEFAULT_NOTIFICATION_CHANNELS, meetsMinPriority, } from "../schemas/firestore";
 /**
  * Notification types whose WhatsApp send is gated behind the buyer's
@@ -24,7 +48,27 @@ const ORDER_GATED_TYPES = new Set([
     "order_cancelled",
     "refund_initiated",
 ]);
-/** Notification type → the flat `SiteSettingsCredentials` field holding its approved Meta template name. */
+/**
+ * Notification type → the flat `SiteSettingsCredentials` field holding its
+ * approved Meta template name.
+ *
+ * 🛑 **`Partial` here is CORRECT and is not the `typeToPrefsKey` mistake.**
+ *
+ * The distinction is what a missing key MEANS. A missing `typeToPrefsKey`
+ * entry silently ignored a user's opt-out — a real setting that read as
+ * honoured and was not. A missing entry here means "no Meta-approved template
+ * exists for this type", which is a fact about the Meta account, not a bug:
+ * six of the 28 types have one, and the rest legitimately fall back to
+ * free-form (which Meta accepts inside the 24-hour customer-service window
+ * and rejects outside it — the runner already logs that rejection).
+ *
+ * Getting six approved templates is a Meta Business review process, not a
+ * code change, so listing all 28 here with empty values would be a
+ * `Record<…>` that lies about coverage.
+ *
+ * The six that ARE approved are the order lifecycle, which is also the set
+ * gated behind the buyer's ₹10 addon above — the two lists agree on purpose.
+ */
 const WHATSAPP_TEMPLATE_FIELD = {
     order_placed: "whatsappTemplateOrderPlaced",
     order_confirmed: "whatsappTemplateOrderConfirmed",
@@ -56,6 +100,46 @@ export async function listNotifications(userId, limit = 20) {
 export async function getUnreadNotificationCount(userId) {
     return notificationRepository.getUnreadCount(userId);
 }
+/**
+ * Which portal each notification type belongs to.
+ *
+ * `Record<NotificationType, …>`, so a new type cannot compile without an
+ * answer — the same discipline `typeToPrefsKey` needed after it silently
+ * omitted three types and ignored those users' opt-outs.
+ */
+const TYPE_AUDIENCE = {
+    // Buyer-facing: the order lifecycle they are waiting on.
+    order_placed: "buyer",
+    order_confirmed: "buyer",
+    order_shipped: "buyer",
+    order_delivered: "buyer",
+    order_cancelled: "buyer",
+    refund_initiated: "buyer",
+    payment_review: "buyer",
+    emi_installment_due_soon: "buyer",
+    emi_installment_overdue: "buyer",
+    prize_won: "buyer",
+    prize_reveal_expired: "buyer",
+    product_available: "buyer",
+    bid_placed: "buyer",
+    bid_outbid: "buyer",
+    bid_won: "buyer",
+    bid_lost: "buyer",
+    offer_responded: "buyer",
+    offer_counter_accepted: "buyer",
+    offer_expired: "buyer",
+    review_replied: "buyer",
+    catalogue_images_stale: "buyer",
+    // Seller-facing.
+    auction_ended: "seller", // "your auction closed with no winner"
+    offer_received: "seller",
+    review_approved: "seller",
+    // Account-level, which lives in the user portal for everyone.
+    welcome: "buyer",
+    account_action: "buyer",
+    system: "buyer",
+    promotion: "buyer",
+};
 /**
  * Create an in-app notification and fan out to enabled external channels.
  *
@@ -67,9 +151,26 @@ export async function getUnreadNotificationCount(userId) {
  *   5. The required credentials are set in siteSettings.credentials
  */
 export async function sendNotification(input) {
-    const { userEmail, userPhone, emailHtml, ...notifInput } = input;
+    const { userEmail, userPhone, emailHtml, audience, ...notifInput } = input;
+    /*
+     * Fill `actionUrl` when the caller did not.
+     *
+     * It was set by 5 of 40 call sites, so 35 notifications arrived in the bell
+     * as text with nothing to click. Resolving it HERE rather than asking 35
+     * writers to remember means the destination is right by construction, and
+     * changing where a `bid` notification lands is one edit rather than a sweep.
+     *
+     * A caller-supplied value always wins — a few writers legitimately point at
+     * something the relatedType cannot express (the payment-proof upload page
+     * rather than the order page).
+     */
+    const resolvedActionUrl = notifInput.actionUrl ??
+        resolveNotificationActionUrl(notifInput.relatedType, notifInput.relatedId, audience ?? TYPE_AUDIENCE[notifInput.type] ?? "buyer");
     // Always write the in-app notification first.
-    const notification = await notificationRepository.create(notifInput);
+    const notification = await notificationRepository.create({
+        ...notifInput,
+        ...(resolvedActionUrl ? { actionUrl: resolvedActionUrl } : {}),
+    });
     // Load channel config + credentials (one Firestore read).
     let settings;
     try {
@@ -102,6 +203,20 @@ export async function sendNotification(input) {
     const resolvedPhone = userPhone ??
         (fetchedUserDoc?.phoneNumber ? decryptPii(fetchedUserDoc.phoneNumber) : undefined);
     // Map NotificationType to a NotificationTypePrefs key.
+    /*
+     * 🛑 COMPLETE and compile-checked: `Record<NotificationType, …>`, not
+     * `Partial<Record<string, …>>`.
+     *
+     * The partial version silently omitted `emi_installment_due_soon`,
+     * `emi_installment_overdue` and `payment_review` — and a missing key means
+     * `typeKey` is undefined, so the opt-out check below never fires and the
+     * user's preference is IGNORED. A silently-ignored opt-out is worse than a
+     * missing feature: the toggle is right there, it reads as honoured, and
+     * mail keeps arriving.
+     *
+     * Typed on the union so the next type added cannot compile without an
+     * answer to "which toggle silences this".
+     */
     const typeToPrefsKey = {
         order_placed: "orderUpdates", order_confirmed: "orderUpdates",
         order_shipped: "orderUpdates", order_delivered: "orderUpdates",
@@ -116,6 +231,19 @@ export async function sendNotification(input) {
         product_available: "system",
         prize_won: "orderUpdates",
         prize_reveal_expired: "orderUpdates",
+        // Money owed on an order. Under orderUpdates rather than a new toggle:
+        // an EMI installment IS an order update, and inventing an eighth
+        // preference key means an existing user's saved prefs have no value for
+        // it — which reads as "off" or "on" depending on the default and is a
+        // migration nobody asked for.
+        emi_installment_due_soon: "orderUpdates",
+        emi_installment_overdue: "orderUpdates",
+        // The manual-payment review queue — the buyer's proof was verified,
+        // rejected, or needs re-uploading. Squarely an order update.
+        payment_review: "orderUpdates",
+        // "Your catalogue photos are going stale" — housekeeping about the user's
+        // own account, which is what `system` covers.
+        catalogue_images_stale: "system",
     };
     const typeKey = typeToPrefsKey[type];
     // If the user has explicitly disabled this notification type, skip all external channels.
@@ -138,7 +266,24 @@ export async function sendNotification(input) {
                 await withChannelRetry("email", () => emailProvider.send({
                     to: resolvedEmail,
                     subject: title,
-                    html: emailHtml ?? `<p>${message}</p>`,
+                    /*
+                     * A real template, not `<p>{message}</p>`.
+                     *
+                     * `emailHtml` existed on the input from the day the channel was
+                     * built and NOT ONE of the 40 call sites passed it, so all 28
+                     * types shipped a bare paragraph — no framing, no branding,
+                     * nothing to click. Rendering here rather than asking 40 writers
+                     * to remember is what makes that structurally impossible to
+                     * regress: a caller-supplied `emailHtml` still wins, for the
+                     * handful of flows with genuinely bespoke mail.
+                     */
+                    html: emailHtml ??
+                        renderNotificationEmail(type, {
+                            title,
+                            message,
+                            siteName: fromName,
+                            actionUrl: absoluteActionUrl(resolvedActionUrl),
+                        }),
                     text: message,
                 }));
                 emailStatus = "sent";

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

@@ -14,6 +14,7 @@ import { buildBidDetailFields, bidStatusBadge } from "../../auctions/components/
 import { toRecordArray, toRelativeDate, toCurrency, toStringValue, } from "../hooks/useAdminListingData";
 import { DataListingView } from "./DataListingView";
 import { apiClient } from "../../../http";
+import { RecordStatusTimeline } from "../../status-history/components/RecordStatusTimeline";
 export function AdminBidsView({ children, ...props }) {
     const queryClient = useQueryClient();
     const { showToast } = useToast();
@@ -98,7 +99,12 @@ export function AdminBidsView({ children, ...props }) {
     const detailBadge = detail ? bidStatusBadge(detail.status) : null;
     return (_jsxs(_Fragment, { children: [_jsx(DataListingView, { config: config }), _jsx(RecordDetailModal, { isOpen: detail !== null, onClose: () => setDetail(null), title: toStringValue(detail?.detail?.productTitle, "Bid"), badges: detailBadge ? [{ label: detailBadge.label }] : undefined, fields: detail
                     ? buildBidDetailFields(detail.detail, "admin")
-                    : undefined }), _jsx(ConfirmDeleteModal, { isOpen: cancelOpen, onClose: () => {
+                    : undefined, extra: 
+                // A bid moves through more states than any record a buyer owns, and
+                // every one of them happened inside a settlement batch with nothing
+                // recording it until W18. Absent history renders the empty label,
+                // never a step invented from `updatedAt`.
+                _jsx(RecordStatusTimeline, { entries: detail?.detail?.statusHistory, truncatedCount: detail?.detail?.statusHistoryTruncated }) }), _jsx(ConfirmDeleteModal, { isOpen: cancelOpen, onClose: () => {
                     setCancelOpen(false);
                     setSelectedRow(null);
                 }, onConfirm: () => {

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

@@ -1,4 +1,5 @@
 import React from "react";
+import type { StatusChangeEntry } from "../../../_internal/shared/history/types";
 import { type ScammerStatus } from "../../scams/schemas/firestore";
 export interface AdminScammerEditorViewProps {
     open: boolean;
@@ -11,7 +12,10 @@ export interface AdminScammerEditorViewProps {
     upiIds?: string[];
     currentStatus?: ScammerStatus;
     verificationNote?: string;
+    /** The profile's own decision history. Absent on profiles predating W18. */
+    statusHistory?: StatusChangeEntry[];
+    statusHistoryTruncated?: number;
     reportedBy?: string;
     reportedByAnon?: boolean;
 }
-export declare function AdminScammerEditorView({ open, onClose, scammerId, displayNames, scamType, description, phones, upiIds, currentStatus, verificationNote, reportedBy, reportedByAnon, }: AdminScammerEditorViewProps): React.JSX.Element;
+export declare function AdminScammerEditorView({ open, onClose, scammerId, displayNames, scamType, description, phones, upiIds, currentStatus, verificationNote, statusHistory, statusHistoryTruncated, reportedBy, reportedByAnon, }: AdminScammerEditorViewProps): React.JSX.Element;

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

@@ -6,6 +6,7 @@ import { useQueryClient } from "@tanstack/react-query";
 import { Button, Code, Div, FormActions, HorizontalRule, Label, Row, Select, SideDrawer, Span, Stack, Text, Textarea, useToast } from "../../../ui";
 import { apiClient } from "../../../http";
 import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints";
+import { RecordStatusTimeline } from "../../status-history/components/RecordStatusTimeline";
 import { ScammerStatusValues, } from "../../scams/schemas/firestore";
 import { SCAMMER_STATUS_BADGE, SCAMMER_STATUS_LABEL, SCAMMER_STATUS_OPTIONS, } from "../../scams/constants/scammer-status-display";
 const __P = {
@@ -13,7 +14,7 @@ const __P = {
     p4: "p-[var(--appkit-space-4)]",
 };
 const CLS_SECTION_LABEL = "text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] uppercase tracking-wide";
-export function AdminScammerEditorView({ open, onClose, scammerId, displayNames = [], scamType, description, phones = [], upiIds = [], currentStatus, verificationNote, reportedBy, reportedByAnon, }) {
+export function AdminScammerEditorView({ open, onClose, scammerId, displayNames = [], scamType, description, phones = [], upiIds = [], currentStatus, verificationNote, statusHistory, statusHistoryTruncated, reportedBy, reportedByAnon, }) {
     const queryClient = useQueryClient();
     const { showToast } = useToast();
     const [status, setStatus] = React.useState(currentStatus ?? "pending_review");
@@ -53,5 +54,5 @@ export function AdminScammerEditorView({ open, onClose, scammerId, displayNames
             showToast(err?.message ?? "Failed to delete profile.", "error");
         },
     });
-    return (_jsx(SideDrawer, { isOpen: open, onClose: onClose, title: displayNames.length > 0 ? displayNames[0] : "Scammer Profile", children: _jsxs(Stack, { className: `${__P.p4}`, gap: "md", children: [_jsxs(Row, { align: "center", gap: "sm", children: [_jsx(Span, { size: "xs", weight: "medium", className: `inline-flex ${SCAMMER_STATUS_BADGE[currentStatus ?? ScammerStatusValues.PENDING_REVIEW]}`, rounded: "full", padding: "pill-sm-tall", children: SCAMMER_STATUS_LABEL[currentStatus ?? ScammerStatusValues.PENDING_REVIEW] }), scamType && (_jsx(Span, { size: "xs", rounded: "full", padding: "pill-sm-tall", surface: "subtle", color: "muted", children: scamType.replace(/_/g, " ") }))] }), displayNames.length > 0 && (_jsxs(Div, { children: [_jsx(Text, { className: "mb-1 tracking-wide", color: "muted", size: "xs", weight: "semibold", transform: "uppercase", children: "Names / Aliases" }), _jsx(Row, { wrap: true, gap: "xs", children: displayNames.map((name, i) => (_jsx(Span, { size: "xs", rounded: "full", surface: "subtle", padding: "pill-sm", children: name }, i))) })] })), (phones.length > 0 || upiIds.length > 0) && (_jsxs(Div, { className: `${__P.p3}`, rounded: "lg", surface: "muted", border: "default", children: [phones.length > 0 && (_jsxs(Div, { className: "mb-2", children: [_jsx(Text, { className: CLS_SECTION_LABEL, children: "Phone numbers" }), _jsx(Row, { wrap: true, gap: "xs", children: phones.map((p, i) => (_jsx(Code, { size: "xs", rounded: "default", padding: "sm", surface: "subtle", children: p }, i))) })] })), upiIds.length > 0 && (_jsxs(_Fragment, { children: [_jsx(Text, { className: CLS_SECTION_LABEL, children: "UPI IDs" }), _jsx(Row, { wrap: true, gap: "xs", children: upiIds.map((u, i) => (_jsx(Code, { size: "xs", rounded: "default", padding: "sm", surface: "subtle", children: u }, i))) })] }))] })), description && (_jsxs(Div, { className: `${__P.p3}`, rounded: "lg", surface: "muted", border: "default", children: [_jsx(Text, { className: CLS_SECTION_LABEL, children: "Description" }), _jsx(Text, { className: "whitespace-pre-wrap", color: "primary", size: "sm", children: description })] })), _jsxs(Div, { textSize: "xs", color: "muted", children: ["Reported by:", " ", _jsx(Span, { weight: "medium", color: "muted", children: reportedByAnon ? "Anonymous" : (reportedBy ?? "Unknown") })] }), _jsx(HorizontalRule, { tone: "subtle", spacing: "comfortable" }), _jsx(Select, { label: "Status", options: SCAMMER_STATUS_OPTIONS, value: status, onValueChange: setStatus }), _jsxs(Stack, { gap: "xs", children: [_jsx(Label, { className: "uppercase tracking-wide", color: "muted", size: "xs", weight: "semibold", children: "Verification note (internal)" }), _jsx(Textarea, { value: note, onChange: (e) => setNote(e.target.value), rows: 3, placeholder: "e.g. Verified via 3 independent reports\u2026" })] }), _jsxs(FormActions, { align: "right", children: [_jsx(Button, { type: "button", variant: "danger", size: "sm", disabled: !scammerId, isLoading: deleteMutation.isPending, onClick: () => deleteMutation.mutate(), children: "Delete" }), _jsx(Button, { type: "button", variant: "secondary", onClick: onClose, children: "Cancel" }), _jsx(Button, { type: "button", isLoading: updateMutation.isPending, disabled: !scammerId || updateMutation.isPending, onClick: () => updateMutation.mutate(), children: "Save changes" })] })] }) }));
+    return (_jsx(SideDrawer, { isOpen: open, onClose: onClose, title: displayNames.length > 0 ? displayNames[0] : "Scammer Profile", children: _jsxs(Stack, { className: `${__P.p4}`, gap: "md", children: [_jsx(RecordStatusTimeline, { title: "Decision history", entries: statusHistory, truncatedCount: statusHistoryTruncated }), _jsxs(Row, { align: "center", gap: "sm", children: [_jsx(Span, { size: "xs", weight: "medium", className: `inline-flex ${SCAMMER_STATUS_BADGE[currentStatus ?? ScammerStatusValues.PENDING_REVIEW]}`, rounded: "full", padding: "pill-sm-tall", children: SCAMMER_STATUS_LABEL[currentStatus ?? ScammerStatusValues.PENDING_REVIEW] }), scamType && (_jsx(Span, { size: "xs", rounded: "full", padding: "pill-sm-tall", surface: "subtle", color: "muted", children: scamType.replace(/_/g, " ") }))] }), displayNames.length > 0 && (_jsxs(Div, { children: [_jsx(Text, { className: "mb-1 tracking-wide", color: "muted", size: "xs", weight: "semibold", transform: "uppercase", children: "Names / Aliases" }), _jsx(Row, { wrap: true, gap: "xs", children: displayNames.map((name, i) => (_jsx(Span, { size: "xs", rounded: "full", surface: "subtle", padding: "pill-sm", children: name }, i))) })] })), (phones.length > 0 || upiIds.length > 0) && (_jsxs(Div, { className: `${__P.p3}`, rounded: "lg", surface: "muted", border: "default", children: [phones.length > 0 && (_jsxs(Div, { className: "mb-2", children: [_jsx(Text, { className: CLS_SECTION_LABEL, children: "Phone numbers" }), _jsx(Row, { wrap: true, gap: "xs", children: phones.map((p, i) => (_jsx(Code, { size: "xs", rounded: "default", padding: "sm", surface: "subtle", children: p }, i))) })] })), upiIds.length > 0 && (_jsxs(_Fragment, { children: [_jsx(Text, { className: CLS_SECTION_LABEL, children: "UPI IDs" }), _jsx(Row, { wrap: true, gap: "xs", children: upiIds.map((u, i) => (_jsx(Code, { size: "xs", rounded: "default", padding: "sm", surface: "subtle", children: u }, i))) })] }))] })), description && (_jsxs(Div, { className: `${__P.p3}`, rounded: "lg", surface: "muted", border: "default", children: [_jsx(Text, { className: CLS_SECTION_LABEL, children: "Description" }), _jsx(Text, { className: "whitespace-pre-wrap", color: "primary", size: "sm", children: description })] })), _jsxs(Div, { textSize: "xs", color: "muted", children: ["Reported by:", " ", _jsx(Span, { weight: "medium", color: "muted", children: reportedByAnon ? "Anonymous" : (reportedBy ?? "Unknown") })] }), _jsx(HorizontalRule, { tone: "subtle", spacing: "comfortable" }), _jsx(Select, { label: "Status", options: SCAMMER_STATUS_OPTIONS, value: status, onValueChange: setStatus }), _jsxs(Stack, { gap: "xs", children: [_jsx(Label, { className: "uppercase tracking-wide", color: "muted", size: "xs", weight: "semibold", children: "Verification note (internal)" }), _jsx(Textarea, { value: note, onChange: (e) => setNote(e.target.value), rows: 3, placeholder: "e.g. Verified via 3 independent reports\u2026" })] }), _jsxs(FormActions, { align: "right", children: [_jsx(Button, { type: "button", variant: "danger", size: "sm", disabled: !scammerId, isLoading: deleteMutation.isPending, onClick: () => deleteMutation.mutate(), children: "Delete" }), _jsx(Button, { type: "button", variant: "secondary", onClick: onClose, children: "Cancel" }), _jsx(Button, { type: "button", isLoading: updateMutation.isPending, disabled: !scammerId || updateMutation.isPending, onClick: () => updateMutation.mutate(), children: "Save changes" })] })] }) }));
 }

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

@@ -1,4 +1,5 @@
 import React from "react";
+import type { StatusChangeEntry } from "../../../_internal/shared/history/types";
 interface TicketMessageClient {
     id?: string;
     authorId?: string;
@@ -28,6 +29,9 @@ export interface AdminSupportTicketDetailViewProps {
     orderId?: string;
     /** ST-6 — current relatedParties snapshot from the ticket document. */
     relatedParties?: RelatedPartiesClient;
+    /** The ticket's `statusHistory`. Absent on tickets predating W18. */
+    statusHistory?: StatusChangeEntry[];
+    statusHistoryTruncated?: number;
 }
-export declare function AdminSupportTicketDetailView({ open, onClose, ticketId, subject, userDisplayName, category, currentStatus, currentPriority, description, messages, internalNotes, orderId, relatedParties, }: AdminSupportTicketDetailViewProps): React.JSX.Element;
+export declare function AdminSupportTicketDetailView({ open, onClose, ticketId, subject, userDisplayName, category, currentStatus, currentPriority, description, messages, internalNotes, orderId, relatedParties, statusHistory, statusHistoryTruncated, }: AdminSupportTicketDetailViewProps): React.JSX.Element;
 export {};

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

@@ -6,6 +6,7 @@ import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { Button, Div, FormActions, HorizontalRule, Input, Label, Row, Select, SideDrawer, Span, Stack, Text, Textarea, Toggle, useToast } from "../../../ui";
 import { apiClient } from "../../../http";
 import { ADMIN_ENDPOINTS, SUPPORT_ENDPOINTS } from "../../../constants/api-endpoints";
+import { RecordStatusTimeline } from "../../status-history/components/RecordStatusTimeline";
 const __P = {
     p3: "p-[var(--appkit-space-3)]",
     p4: "p-[var(--appkit-space-4)]",
@@ -38,7 +39,7 @@ const ROLE_LABEL = {
     support: "Support",
     admin: "Admin",
 };
-export function AdminSupportTicketDetailView({ open, onClose, ticketId, subject, userDisplayName, category, currentStatus, currentPriority, description, messages = [], internalNotes, orderId, relatedParties, }) {
+export function AdminSupportTicketDetailView({ open, onClose, ticketId, subject, userDisplayName, category, currentStatus, currentPriority, description, messages = [], internalNotes, orderId, relatedParties, statusHistory, statusHistoryTruncated, }) {
     const queryClient = useQueryClient();
     const { showToast } = useToast();
     const [status, setStatus] = React.useState(currentStatus ?? "open");
@@ -259,7 +260,7 @@ export function AdminSupportTicketDetailView({ open, onClose, ticketId, subject,
             showToast(err?.message ?? "Failed to update order items.", "error");
         },
     });
-    return (_jsx(SideDrawer, { isOpen: open, onClose: onClose, title: subject ?? "Support Ticket", children: _jsxs(Stack, { className: `${__P.p4}`, gap: "md", children: [_jsxs(Row, { align: "center", gap: "sm", wrap: true, children: [_jsx(Span, { size: "xs", weight: "medium", className: `inline-flex ${STATUS_COLOR[currentStatus ?? "open"] ?? STATUS_COLOR.open}`, rounded: "full", padding: "pill-sm-tall", children: (currentStatus ?? "open").replace(/_/g, " ") }), _jsx(Span, { size: "xs", rounded: "full", padding: "pill-sm-tall", surface: "subtle", color: "muted", children: category }), orderId && (_jsxs(Span, { size: "xs", rounded: "full", padding: "pill-sm-tall", surface: "subtle", color: "muted", children: ["Order: ", orderId] }))] }), _jsxs(Div, { textSize: "sm", color: "muted", children: ["From: ", _jsx(Span, { weight: "medium", color: "primary", children: userDisplayName })] }), description && (_jsxs(Div, { className: `${__P.p3}`, rounded: "lg", surface: "muted", border: "default", children: [_jsx(Text, { className: "mb-1 tracking-wide", color: "muted", size: "xs", weight: "semibold", transform: "uppercase", children: "Description" }), _jsx(Text, { className: "whitespace-pre-wrap", color: "primary", size: "sm", children: description })] })), messages.length > 0 && (_jsxs(Stack, { gap: "sm", children: [_jsxs(Text, { className: "tracking-wide", color: "muted", size: "xs", weight: "semibold", transform: "uppercase", children: ["Messages (", messages.length, ")"] }), _jsx(Stack, { className: `max-h-64 ${__O.yAuto}`, gap: "sm", children: messages.map((msg, i) => (_jsxs(Div, { textSize: "sm", surface: msg.authorRole === "user" ? "default" : "info-surface", className: msg.authorRole === "user" ? "border border-[var(--appkit-color-border)]" : "border border-[var(--appkit-color-info)]", rounded: "lg", padding: "sm", children: [_jsxs(Row, { color: "muted", textSize: "xs", className: "mb-1", align: "center", gap: "sm", children: [_jsx(Span, { weight: "medium", color: "muted", children: ROLE_LABEL[msg.authorRole ?? "user"] ?? msg.authorRole }), msg.createdAt && (_jsx(Span, { children: new Date(msg.createdAt).toLocaleString() }))] }), _jsx(Text, { className: "whitespace-pre-wrap", color: "primary", children: msg.body })] }, msg.id ?? i))) })] })), _jsxs(Stack, { gap: "xs", children: [_jsx(Label, { className: "uppercase tracking-wide", color: "muted", size: "xs", weight: "semibold", children: "Reply to user" }), _jsx(Textarea, { value: replyBody, onChange: (e) => setReplyBody(e.target.value), rows: 3, placeholder: "Type a reply\u2026" }), _jsx(Button, { type: "button", variant: "primary", size: "sm", isLoading: replyMutation.isPending, disabled: !replyBody.trim() || !ticketId || replyMutation.isPending, onClick: () => replyMutation.mutate(), children: "Send reply" })] }), _jsx(HorizontalRule, { tone: "subtle", spacing: "comfortable" }), _jsx(Select, { label: "Status", options: STATUS_OPTIONS, value: status, onValueChange: setStatus }), _jsx(Select, { label: "Priority", options: PRIORITY_OPTIONS, value: priority, onValueChange: setPriority }), _jsxs(Stack, { gap: "xs", children: [_jsx(Label, { className: "uppercase tracking-wide", color: "muted", size: "xs", weight: "semibold", children: "Internal notes (staff only)" }), _jsx(Textarea, { value: notes, onChange: (e) => setNotes(e.target.value), rows: 3, placeholder: "Notes visible only to admins and employees\u2026" })] }), _jsxs(Stack, { padding: "sm", gap: "sm", rounded: "lg", border: "default", children: [_jsx(Text, { className: "tracking-wide", color: "muted", size: "xs", weight: "semibold", transform: "uppercase", children: "Linked parties" }), _jsx(Text, { size: "xs", color: "muted", children: "Tag the buyer / store / order / product / bid this ticket concerns." }), [
+    return (_jsx(SideDrawer, { isOpen: open, onClose: onClose, title: subject ?? "Support Ticket", children: _jsxs(Stack, { className: `${__P.p4}`, gap: "md", children: [_jsxs(Row, { align: "center", gap: "sm", wrap: true, children: [_jsx(Span, { size: "xs", weight: "medium", className: `inline-flex ${STATUS_COLOR[currentStatus ?? "open"] ?? STATUS_COLOR.open}`, rounded: "full", padding: "pill-sm-tall", children: (currentStatus ?? "open").replace(/_/g, " ") }), _jsx(Span, { size: "xs", rounded: "full", padding: "pill-sm-tall", surface: "subtle", color: "muted", children: category }), orderId && (_jsxs(Span, { size: "xs", rounded: "full", padding: "pill-sm-tall", surface: "subtle", color: "muted", children: ["Order: ", orderId] }))] }), _jsxs(Div, { textSize: "sm", color: "muted", children: ["From: ", _jsx(Span, { weight: "medium", color: "primary", children: userDisplayName })] }), description && (_jsxs(Div, { className: `${__P.p3}`, rounded: "lg", surface: "muted", border: "default", children: [_jsx(Text, { className: "mb-1 tracking-wide", color: "muted", size: "xs", weight: "semibold", transform: "uppercase", children: "Description" }), _jsx(Text, { className: "whitespace-pre-wrap", color: "primary", size: "sm", children: description })] })), messages.length > 0 && (_jsxs(Stack, { gap: "sm", children: [_jsxs(Text, { className: "tracking-wide", color: "muted", size: "xs", weight: "semibold", transform: "uppercase", children: ["Messages (", messages.length, ")"] }), _jsx(Stack, { className: `max-h-64 ${__O.yAuto}`, gap: "sm", children: messages.map((msg, i) => (_jsxs(Div, { textSize: "sm", surface: msg.authorRole === "user" ? "default" : "info-surface", className: msg.authorRole === "user" ? "border border-[var(--appkit-color-border)]" : "border border-[var(--appkit-color-info)]", rounded: "lg", padding: "sm", children: [_jsxs(Row, { color: "muted", textSize: "xs", className: "mb-1", align: "center", gap: "sm", children: [_jsx(Span, { weight: "medium", color: "muted", children: ROLE_LABEL[msg.authorRole ?? "user"] ?? msg.authorRole }), msg.createdAt && (_jsx(Span, { children: new Date(msg.createdAt).toLocaleString() }))] }), _jsx(Text, { className: "whitespace-pre-wrap", color: "primary", children: msg.body })] }, msg.id ?? i))) })] })), _jsxs(Stack, { gap: "xs", children: [_jsx(Label, { className: "uppercase tracking-wide", color: "muted", size: "xs", weight: "semibold", children: "Reply to user" }), _jsx(Textarea, { value: replyBody, onChange: (e) => setReplyBody(e.target.value), rows: 3, placeholder: "Type a reply\u2026" }), _jsx(Button, { type: "button", variant: "primary", size: "sm", isLoading: replyMutation.isPending, disabled: !replyBody.trim() || !ticketId || replyMutation.isPending, onClick: () => replyMutation.mutate(), children: "Send reply" })] }), _jsx(HorizontalRule, { tone: "subtle", spacing: "comfortable" }), _jsx(RecordStatusTimeline, { entries: statusHistory, truncatedCount: statusHistoryTruncated }), _jsx(HorizontalRule, { tone: "subtle", spacing: "comfortable" }), _jsx(Select, { label: "Status", options: STATUS_OPTIONS, value: status, onValueChange: setStatus }), _jsx(Select, { label: "Priority", options: PRIORITY_OPTIONS, value: priority, onValueChange: setPriority }), _jsxs(Stack, { gap: "xs", children: [_jsx(Label, { className: "uppercase tracking-wide", color: "muted", size: "xs", weight: "semibold", children: "Internal notes (staff only)" }), _jsx(Textarea, { value: notes, onChange: (e) => setNotes(e.target.value), rows: 3, placeholder: "Notes visible only to admins and employees\u2026" })] }), _jsxs(Stack, { padding: "sm", gap: "sm", rounded: "lg", border: "default", children: [_jsx(Text, { className: "tracking-wide", color: "muted", size: "xs", weight: "semibold", transform: "uppercase", children: "Linked parties" }), _jsx(Text, { size: "xs", color: "muted", children: "Tag the buyer / store / order / product / bid this ticket concerns." }), [
                             ["userId", "User slug"],
                             ["storeId", "Store slug"],
                             ["orderId", "Order ID"],

package/dist/features/admin/schemas/firestore.d.ts

@@ -4,7 +4,18 @@
  */
 import type { AboutContentDocument } from "../../about/schemas/firestore";
 export declare const ADMIN_CHECKOUT_BYPASS_FLAG_KEY: "adminCheckoutBypass";
-export type NotificationType = "order_placed" | "order_confirmed" | "order_shipped" | "order_delivered" | "order_cancelled" | "bid_placed" | "bid_outbid" | "bid_won" | "bid_lost" | "auction_ended" | "review_approved" | "review_replied" | "product_available" | "promotion" | "system" | "welcome" | "account_action" | "offer_received" | "offer_responded" | "offer_expired" | "offer_counter_accepted" | "refund_initiated" | "prize_won" | "prize_reveal_expired" | "emi_installment_due_soon" | "emi_installment_overdue" | "payment_review";
+export declare const NOTIFICATION_TYPE_VALUES: readonly ["order_placed", "order_confirmed", "order_shipped", "order_delivered", "order_cancelled", "bid_placed", "bid_outbid", "bid_won", "bid_lost", "auction_ended", "review_approved", "review_replied", "product_available", "promotion", "system", "welcome", "account_action", "offer_received", "offer_responded", "offer_expired", "offer_counter_accepted", "refund_initiated", "prize_won", "prize_reveal_expired", "emi_installment_due_soon", "emi_installment_overdue", "payment_review", "catalogue_images_stale"];
+export type NotificationType = (typeof NOTIFICATION_TYPE_VALUES)[number];
+/**
+ * What a notification points AT. Drives the shared `actionUrl` resolver, so a
+ * value here without a per-record page in some role is a notification that
+ * lands nowhere.
+ *
+ * Runtime array for the same reason as the type union above — and
+ * `catalogueItem` was being sent with an `as never` cast rather than added.
+ */
+export declare const NOTIFICATION_RELATED_TYPE_VALUES: readonly ["order", "product", "bid", "review", "blog", "user", "offer", "support_ticket", "scammer", "catalogueItem", "payout", "store"];
+export type NotificationRelatedType = (typeof NOTIFICATION_RELATED_TYPE_VALUES)[number];
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 export type NotificationPriority = "low" | "normal" | "high";
 export interface NotificationDocument extends BaseDocument {
@@ -19,7 +30,7 @@ export interface NotificationDocument extends BaseDocument {
     isRead: boolean;
     readAt?: Date;
     relatedId?: string;
-    relatedType?: "order" | "product" | "bid" | "review" | "blog" | "user" | "offer" | "support_ticket" | "scammer";
+    relatedType?: NotificationRelatedType;
     /** Outcome of the async whatsappNotify job for this notification's WhatsApp send, if one was enqueued. */
     whatsappStatus?: "queued" | "sent" | "failed" | "skipped";
     /** jobs/{id} doc that ran (or is running) the WhatsApp send for this notification. */
@@ -82,7 +93,7 @@ export type NotificationUpdateInput = Partial<Pick<NotificationDocument, "isRead
 export declare const notificationQueryHelpers: {
     readonly byUser: (userId: string) => readonly ["userId", "==", string];
     readonly unread: (userId: string) => readonly [readonly ["userId", "==", string], readonly ["isRead", "==", false]];
-    readonly byType: (type: NotificationType) => readonly ["type", "==", NotificationType];
+    readonly byType: (type: NotificationType) => readonly ["type", "==", "system" | "welcome" | "promotion" | "order_placed" | "order_confirmed" | "order_shipped" | "order_delivered" | "order_cancelled" | "bid_placed" | "bid_outbid" | "bid_won" | "bid_lost" | "auction_ended" | "review_approved" | "review_replied" | "product_available" | "account_action" | "offer_received" | "offer_responded" | "offer_expired" | "offer_counter_accepted" | "refund_initiated" | "prize_won" | "prize_reveal_expired" | "emi_installment_due_soon" | "emi_installment_overdue" | "payment_review" | "catalogue_images_stale"];
 };
 export interface ChatRoomDocument extends BaseDocument {
     buyerId: string;

package/dist/features/admin/schemas/firestore.js

@@ -8,6 +8,85 @@ import { DEFAULT_AUCTION_BID_INCREMENT_TIERS } from "../../../_internal/shared/f
 // single occurrence in schemas. Splitting the literal makes the substring
 // audit-invisible while keeping the runtime key correct.
 export const ADMIN_CHECKOUT_BYPASS_FLAG_KEY = "adminCheckoutBypass";
+/*
+ * 🛑 The ONE notification-type union. Four existed until 2026-08-26:
+ *
+ *   · this one (27) — what `NotificationDocument.type` actually holds
+ *   · `constants/notification-types.ts` (9) — fed the admin filter chips and
+ *     the per-channel allow-list, so the admin list could not filter 18 of
+ *     the 27 real types and an admin literally could not allow-list
+ *     `offer_received` or `payment_review` for email or WhatsApp
+ *   · `features/account/types/index.ts` (5: order|offer|promo|system|message)
+ *     — a different vocabulary entirely, on a `UserNotification` type with
+ *     zero real consumers
+ *   · `seed/factories/notification.factory.ts` (9) — and THIS is the one
+ *     `appkit/src/index.ts` exported publicly as `NotificationType`, so every
+ *     external consumer got the seed factory's guess
+ *
+ * Between them they invented FOUR values no notification has ever had:
+ * `review_posted`, `payout_processed`, `review_received`, `payout_completed`.
+ * Note the first two and the last two are different spellings of the same two
+ * imagined concepts, which is how independent copies drift.
+ *
+ * A runtime array with the type derived from it, so a Zod enum, a chip list
+ * and a `Record<NotificationType, …>` all resolve here and a new value is one
+ * edit. Same shape as `ALL_LISTING_TYPES` after Root Cause #61.
+ */
+export const NOTIFICATION_TYPE_VALUES = [
+    "order_placed",
+    "order_confirmed",
+    "order_shipped",
+    "order_delivered",
+    "order_cancelled",
+    "bid_placed",
+    "bid_outbid",
+    "bid_won",
+    "bid_lost",
+    "auction_ended",
+    "review_approved",
+    "review_replied",
+    "product_available",
+    "promotion",
+    "system",
+    "welcome",
+    "account_action",
+    "offer_received",
+    "offer_responded",
+    "offer_expired",
+    "offer_counter_accepted",
+    "refund_initiated",
+    "prize_won",
+    "prize_reveal_expired",
+    "emi_installment_due_soon",
+    "emi_installment_overdue",
+    "payment_review",
+    // Was being SENT with an `as never` cast on the whole payload, which is how
+    // it stayed off this union: the cast silenced the one signal that would
+    // have said so, and with it every other field's type-check on that call.
+    "catalogue_images_stale",
+];
+/**
+ * What a notification points AT. Drives the shared `actionUrl` resolver, so a
+ * value here without a per-record page in some role is a notification that
+ * lands nowhere.
+ *
+ * Runtime array for the same reason as the type union above — and
+ * `catalogueItem` was being sent with an `as never` cast rather than added.
+ */
+export const NOTIFICATION_RELATED_TYPE_VALUES = [
+    "order",
+    "product",
+    "bid",
+    "review",
+    "blog",
+    "user",
+    "offer",
+    "support_ticket",
+    "scammer",
+    "catalogueItem",
+    "payout",
+    "store",
+];
 export const NOTIFICATIONS_COLLECTION = "notifications";
 export const NOTIFICATIONS_INDEXED_FIELDS = [
     "userId",

package/dist/features/auctions/repository/bid.repository.d.ts

@@ -7,6 +7,14 @@ import { BaseRepository, parseSieveDateValue } from "../../../providers/db-fireb
 import type { DocumentReference, WriteBatch } from "firebase-admin/firestore";
 import type { SieveModel, FirebaseSieveResult } from "../../../providers/db-firebase";
 import type { BidDocument, BidCreateInput, BidUpdateInput, BidAdminUpdateInput, BidStatus } from "../schemas";
+import { type HistoryActor } from "../../../_internal/shared/history/index";
+/** Who/why for a bid write that lands in `statusHistory`. */
+export interface BidWriteContext {
+    actor?: HistoryActor;
+    trigger?: string;
+    reason?: string;
+    note?: string;
+}
 export declare class BidRepository extends BaseRepository<BidDocument> {
     constructor();
     /** Override mapDoc to auto-decrypt PII on every bid read */
@@ -49,7 +57,7 @@ export declare class BidRepository extends BaseRepository<BidDocument> {
         ref: DocumentReference;
         data: BidDocument;
     } | null>;
-    markWon(batch: WriteBatch, ref: DocumentReference): void;
+    markWon(batch: WriteBatch, ref: DocumentReference, ctx?: BidWriteContext, prior?: BidDocument | null): void;
     /**
      * Link a won bid to the order it eventually became.
      *
@@ -58,29 +66,34 @@ export declare class BidRepository extends BaseRepository<BidDocument> {
      * /user/bids could not link anywhere, and nothing could tell a settled win
      * from an unpaid one.
      */
-    attachOrder(bidId: string, orderId: string): Promise<void>;
+    attachOrder(bidId: string, orderId: string, ctx?: BidWriteContext, prior?: BidDocument | null): Promise<void>;
     /**
      * The winner never paid within their checkout window. Distinct from "lost"
      * (outbid) — this bidder won and then defaulted, which a seller may want to
      * act on.
      */
-    markForfeited(bidId: string): Promise<void>;
-    markLost(batch: WriteBatch, ref: DocumentReference): void;
+    markForfeited(bidId: string, ctx?: BidWriteContext, prior?: BidDocument | null): Promise<void>;
+    markLost(batch: WriteBatch, ref: DocumentReference, ctx?: BidWriteContext, prior?: BidDocument | null): void;
     /**
      * Batched "everyone else lost", for callers that are not already inside a
      * batch of their own — a Buy Now purchase ends the auction outside the
      * settlement job, and the losing bids can be any number, so this writes them
      * in Firestore-batch chunks rather than one round-trip per bid.
      */
-    markManyLost(refs: readonly DocumentReference[]): Promise<void>;
+    markManyLost(entries: readonly (DocumentReference | {
+        ref: DocumentReference;
+        data?: BidDocument;
+    })[], ctx?: BidWriteContext): Promise<void>;
     /**
      * A pending Buy Now claim that never became a sale. Not `forfeited` — that
      * status means "won, then defaulted", and a lapsed claim never won anything;
      * the auction it was placed against carried on untouched.
      */
-    markCancelled(bidId: string): Promise<void>;
-    markOutbid(batch: WriteBatch, ref: DocumentReference): void;
-    markWinning(batch: WriteBatch, ref: DocumentReference): void;
+    markCancelled(bidId: string, ctx?: BidWriteContext, prior?: BidDocument | null): Promise<void>;
+    markOutbid(batch: WriteBatch, ref: DocumentReference, ctx?: BidWriteContext, prior?: BidDocument | null): void;
+    markWinning(batch: WriteBatch, ref: DocumentReference, ctx?: BidWriteContext, prior?: BidDocument | null): void;
+    /** Append a timeline entry when the patch touches a tracked field. */
+    private withBidHistory;
     /**
      * Find current winning bid for a product
      */