@mohasinac/appkit 4.21.0 → 4.23.0

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/auctions/components/PlaceBidFormClient.js

@@ -183,7 +183,7 @@ export function PlaceBidFormClient({ productId, currentBid: ssrCurrentBid, start
     return (_jsxs(Stack, { className: `${__P.p5}`, border: "subtle", gap: "md", rounded: "xl", surface: "muted", children: [_jsxs(Stack, { gap: "xs", children: [_jsxs(Row, { justify: "between", align: "center", children: [_jsx(Text, { size: "xs", color: "muted", children: hasBids ? "Current bid" : "Starting bid" }), _jsx(Text, { size: "xs", color: "muted", children: hasBids ? "Starting bid" : "Minimum bid" })] }), _jsxs(Row, { justify: "between", align: "baseline", children: [_jsx(Span, { size: "xl", weight: "bold", className: "text-primary-600 dark:text-primary-400", children: formatCurrency(currentBid, currency) }), _jsx(Span, { size: "sm", color: "muted", children: formatCurrency(hasBids ? startingBid : minBid, currency) })] }), _jsxs(Text, { size: "xs", color: "faint", children: [bidCount, " ", bidCount === 1 ? "bid" : "bids", " \u00B7 min increment", " ", formatCurrency(minBidIncrement, currency)] })] }), _jsx(LoginRequiredModal, { isOpen: showLoginModal, onClose: () => setShowLoginModal(false), message: "You need to be signed in to place a bid. Please log in or create an account to continue." }), _jsx(Form, { schema: schema, onSubmit: (e) => {
                     // handler wired through render-prop below — keeps setFieldError in scope
                     e.preventDefault();
-                }, children: ({ setFieldError, clearErrors }) => (_jsxs(Stack, { gap: "sm", children: [_jsx(FormErrorSummary, {}), _jsxs(Row, { gap: "xs", wrap: true, role: "radiogroup", "aria-label": "Bid amount preset", children: [BID_PRESET_MULTIPLIERS.map((n) => {
+                }, children: ({ setFieldError, clearErrors, markSubmitAttempted }) => (_jsxs(Stack, { gap: "sm", children: [_jsx(FormErrorSummary, {}), _jsxs(Row, { gap: "xs", wrap: true, role: "radiogroup", "aria-label": "Bid amount preset", children: [BID_PRESET_MULTIPLIERS.map((n) => {
                                     const amount = presetAmount(n);
                                     const delta = amount - currentBid;
                                     // `delta` is 0 only for the opening preset on a bid-free
@@ -204,6 +204,8 @@ export function PlaceBidFormClient({ productId, currentBid: ssrCurrentBid, start
                                 : hasBids
                                     ? `Minimum next bid ${formatCurrency(minBid, currency)} (current bid + ${formatCurrency(minBidIncrement, currency)} increment).`
                                     : `Minimum opening bid ${formatCurrency(minBid, currency)} — the seller's starting bid. The ${formatCurrency(minBidIncrement, currency)} increment applies from the second bid on.` }), success && (_jsx(Text, { className: "text-success", size: "xs", children: "\u2713 Bid placed successfully!" })), !isEnded && auctionEndDate && (_jsxs(Text, { align: "center", size: "xs", color: "muted", children: ["Ends in ", _jsx(CountdownDisplay, { targetDate: auctionEndDate, format: "auto", expiredLabel: "Ended" })] })), _jsx(Button, { variant: "primary", size: "md", className: "w-full", disabled: isEnded || isPending, isLoading: isPending, type: "button", onClick: () => {
+                                // type="button" — no native submit, so unhide the summary here.
+                                markSubmitAttempted();
                                 clearErrors();
                                 const parsed = schema.safeParse({ bidAmount });
                                 if (!parsed.success)

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
      */

package/dist/features/auctions/repository/bid.repository.js

@@ -6,7 +6,8 @@ import { normalizeError } from "../../../errors/normalize";
  */
 import { BaseRepository, getFirestoreCount, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase";
 import { DatabaseError } from "../../../errors";
-import { BID_COLLECTION, createBidId } from "../schemas";
+import { BID_COLLECTION, BID_TRACKED_FIELDS, BID_HISTORY_PII_FIELDS, createBidId } from "../schemas";
+import { withHistory } from "../../../_internal/shared/history/index";
 import { encryptPiiFields, decryptPiiFields, BID_PII_FIELDS, } from "../../../security";
 import { BID_FIELDS } from "../../../constants/field-names";
 export class BidRepository extends BaseRepository {
@@ -115,12 +116,21 @@ export class BidRepository extends BaseRepository {
             data: this.mapDoc(doc),
         };
     }
-    markWon(batch, ref) {
-        batch.update(ref, {
-            status: "won",
-            isWinning: true,
-            updatedAt: new Date(),
-        });
+    /*
+     * ── Batch mutators ─────────────────────────────────────────────────────
+     *
+     * These take a `DocumentReference` because settlement writes every bid on
+     * an auction in one Firestore batch. `prior` is the document from the SAME
+     * query that produced the ref — every caller has it (`activeBids` and
+     * `losers` are both `{ ref, data }` pairs), so history costs no extra read
+     * even when an auction closes with hundreds of bids (Rule #6).
+     *
+     * Omitting `prior` is legitimate rather than broken: the entry then records
+     * `undefined → "lost"`, which is still true and still stamped with who and
+     * when. It just cannot say what the bid was before.
+     */
+    markWon(batch, ref, ctx, prior) {
+        batch.update(ref, this.withBidHistory(prior, { status: "won", isWinning: true, updatedAt: new Date() }, ctx, "markWon"));
     }
     /**
      * Link a won bid to the order it eventually became.
@@ -130,23 +140,21 @@ export class BidRepository extends BaseRepository {
      * /user/bids could not link anywhere, and nothing could tell a settled win
      * from an unpaid one.
      */
-    async attachOrder(bidId, orderId) {
-        await this.update(bidId, { orderId, updatedAt: new Date() });
+    async attachOrder(bidId, orderId, ctx, prior) {
+        const current = prior !== undefined ? prior : await this.findById(bidId);
+        await this.update(bidId, this.withBidHistory(current, { orderId, updatedAt: new Date() }, ctx, "attachOrder"));
     }
     /**
      * 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.
      */
-    async markForfeited(bidId) {
-        await this.update(bidId, { status: "forfeited", isWinning: false, updatedAt: new Date() });
+    async markForfeited(bidId, ctx, prior) {
+        const current = prior !== undefined ? prior : await this.findById(bidId);
+        await this.update(bidId, this.withBidHistory(current, { status: "forfeited", isWinning: false, updatedAt: new Date() }, ctx, "markForfeited"));
     }
-    markLost(batch, ref) {
-        batch.update(ref, {
-            status: "lost",
-            isWinning: false,
-            updatedAt: new Date(),
-        });
+    markLost(batch, ref, ctx, prior) {
+        batch.update(ref, this.withBidHistory(prior, { status: "lost", isWinning: false, updatedAt: new Date() }, ctx, "markLost"));
     }
     /**
      * Batched "everyone else lost", for callers that are not already inside a
@@ -154,12 +162,20 @@ export class BidRepository extends BaseRepository {
      * 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.
      */
-    async markManyLost(refs) {
+    async markManyLost(entries, ctx) {
         const CHUNK = 400; // under Firestore's 500-write batch limit, with headroom
-        for (let i = 0; i < refs.length; i += CHUNK) {
+        for (let i = 0; i < entries.length; i += CHUNK) {
             const batch = this.db.batch();
-            for (const ref of refs.slice(i, i + CHUNK))
-                this.markLost(batch, ref);
+            for (const entry of entries.slice(i, i + CHUNK)) {
+                // Accepts a bare ref OR a {ref, data} pair, so the caller that already
+                // holds the documents gets a real before-value on the timeline and the
+                // one that does not still works. Widened rather than made required
+                // because forcing a read per losing bid would put a large auction's
+                // settlement over the Firestore read budget.
+                const isPair = typeof entry === "object" && "ref" in entry;
+                const ref = isPair ? entry.ref : entry;
+                this.markLost(batch, ref, ctx, isPair ? entry.data : undefined);
+            }
             await batch.commit();
         }
     }
@@ -168,21 +184,29 @@ export class BidRepository extends BaseRepository {
      * status means "won, then defaulted", and a lapsed claim never won anything;
      * the auction it was placed against carried on untouched.
      */
-    async markCancelled(bidId) {
-        await this.update(bidId, { status: "cancelled", isWinning: false, updatedAt: new Date() });
+    async markCancelled(bidId, ctx, prior) {
+        const current = prior !== undefined ? prior : await this.findById(bidId);
+        await this.update(bidId, this.withBidHistory(current, { status: "cancelled", isWinning: false, updatedAt: new Date() }, ctx, "markCancelled"));
     }
-    markOutbid(batch, ref) {
-        batch.update(ref, {
-            status: "outbid",
-            isWinning: false,
-            updatedAt: new Date(),
-        });
+    markOutbid(batch, ref, ctx, prior) {
+        batch.update(ref, this.withBidHistory(prior, { status: "outbid", isWinning: false, updatedAt: new Date() }, ctx, "markOutbid"));
     }
-    markWinning(batch, ref) {
-        batch.update(ref, {
-            isWinning: true,
-            updatedAt: new Date(),
+    markWinning(batch, ref, ctx, prior) {
+        batch.update(ref, this.withBidHistory(prior, { isWinning: true, updatedAt: new Date() }, ctx, "markWinning"));
+    }
+    /** Append a timeline entry when the patch touches a tracked field. */
+    withBidHistory(current, patch, ctx, defaultTrigger) {
+        const withEntry = withHistory(current, patch, {
+            tracked: BID_TRACKED_FIELDS,
+            actor: ctx?.actor ?? { role: "system" },
+            trigger: ctx?.trigger ?? defaultTrigger,
+            reason: ctx?.reason,
+            note: ctx?.note,
+            // `userName`/`userEmail` are denormalised onto every bid, and
+            // `encryptPiiFields` never descends into arrays.
+            piiFields: BID_HISTORY_PII_FIELDS,
         });
+        return withEntry ?? patch;
     }
     /**
      * Find current winning bid for a product

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

@@ -2,6 +2,7 @@
  * Bids/Auctions Firestore Document Types & Constants
  */
 import { type GenerateBidIdInput } from "../../../utils/id-generators";
+import type { StatusChangeEntry } from "../../../_internal/shared/history/types";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 export type BidStatus = "active" | "outbid" | "won" | "lost" | "cancelled"
 /** Won, then the buyer let the 48h payment window lapse. */
@@ -52,6 +53,16 @@ export interface BidDocument extends BaseDocument {
      *     `claimAuctionForCheckout`, not by blocking the second buyer up front.
      */
     isBuyout?: boolean;
+    /**
+     * Who changed what, when, and why. See § "Status History" in CLAUDE.md.
+     *
+     * A bid moves through more states than any other record a buyer owns —
+     * active → outbid → active → won → forfeited, or cancelled for a lapsed
+     * buyout claim — and every one of those moves happened inside a batch with
+     * nothing recording it. "Why does this say forfeited" was unanswerable.
+     */
+    statusHistory?: StatusChangeEntry[];
+    statusHistoryTruncated?: number;
 }
 export declare const BID_COLLECTION: "bids";
 export declare const BID_INDEXED_FIELDS: readonly ["productId", "userId", "status", "isWinning", "bidDate", "createdAt"];
@@ -71,3 +82,19 @@ export declare const bidQueryHelpers: {
 export declare function createBidId(input: Omit<GenerateBidIdInput, "random"> & {
     random?: string;
 }): string;
+/**
+ * The fields whose changes earn a timeline entry.
+ *
+ * `bidAmount` is included because a proxy bid raises it in place, so the
+ * timeline is the only record of what the bidder actually committed at each
+ * step. `previousBidAmount` is excluded — it is the same information one
+ * entry earlier.
+ */
+export declare const BID_TRACKED_FIELDS: readonly ["status", "isWinning", "bidAmount", "orderId"];
+/**
+ * PII on this document, for `withHistory`'s scrub. `userName` and `userEmail`
+ * are denormalised onto every bid, so a diff of an unrelated field would drag
+ * them into an array `encryptPiiFields` cannot descend into — the exact leak
+ * the primitive's `piiFields` exists to prevent.
+ */
+export declare const BID_HISTORY_PII_FIELDS: readonly ["userName", "userEmail"];

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

@@ -49,3 +49,24 @@ export const bidQueryHelpers = {
 export function createBidId(input) {
     return generateBidId(input);
 }
+/**
+ * The fields whose changes earn a timeline entry.
+ *
+ * `bidAmount` is included because a proxy bid raises it in place, so the
+ * timeline is the only record of what the bidder actually committed at each
+ * step. `previousBidAmount` is excluded — it is the same information one
+ * entry earlier.
+ */
+export const BID_TRACKED_FIELDS = [
+    "status",
+    "isWinning",
+    "bidAmount",
+    "orderId",
+];
+/**
+ * PII on this document, for `withHistory`'s scrub. `userName` and `userEmail`
+ * are denormalised onto every bid, so a diff of an unrelated field would drag
+ * them into an array `encryptPiiFields` cannot descend into — the exact leak
+ * the primitive's `piiFields` exists to prevent.
+ */
+export const BID_HISTORY_PII_FIELDS = ["userName", "userEmail"];

package/dist/features/auth/schemas/index.d.ts

@@ -65,14 +65,14 @@ export declare const authUserSchema: z.ZodObject<{
     isEmailVerified: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     id: string;
-    role?: "user" | "admin" | "moderator" | "seller" | "employee" | undefined;
+    role?: "user" | "seller" | "admin" | "moderator" | "employee" | undefined;
     email?: string | undefined;
     displayName?: string | undefined;
     photoURL?: string | undefined;
     isEmailVerified?: boolean | undefined;
 }, {
     id: string;
-    role?: "user" | "admin" | "moderator" | "seller" | "employee" | undefined;
+    role?: "user" | "seller" | "admin" | "moderator" | "employee" | undefined;
     email?: string | undefined;
     displayName?: string | undefined;
     photoURL?: string | undefined;

package/dist/features/catalogue/actions/approve-catalogue-listing.js

@@ -23,11 +23,12 @@ export async function approveCatalogueListingAction(itemId) {
             throw new ValidationError("Only items pending approval can be approved");
         }
         const product = await createProductFromCatalogueItem(item, CONSIGNMENT_STORE_ID);
-        await catalogueRepository.update(itemId, {
+        // `item` came from the findById above, so the timeline entry is free.
+        await catalogueRepository.setListingStatus(itemId, {
             listingStatus: "listed",
             linkedProductId: product.id,
             linkedProductSlug: product.slug ?? product.id,
-        });
+        }, { actor: { role: "admin", uid: user.uid }, trigger: "approveCatalogueListing" }, item);
         return { productId: product.id, productSlug: product.slug ?? product.id };
     });
 }
@@ -42,9 +43,9 @@ export async function rejectCatalogueListingAction(itemId, reason) {
         if (item.listingStatus !== "pending_admin_approval") {
             throw new ValidationError("Only items pending approval can be rejected");
         }
-        await catalogueRepository.update(itemId, {
-            listingStatus: "rejected",
-            rejectionReason: reason,
-        });
+        await catalogueRepository.setListingStatus(itemId, { listingStatus: "rejected", rejectionReason: reason }, 
+        // The reason is the point of the entry — `rejectionReason` on the
+        // document is overwritten by the next decision.
+        { actor: { role: "admin", uid: user.uid }, trigger: "rejectCatalogueListing", reason }, item);
     });
 }

package/dist/features/catalogue/actions/list-from-catalogue.js

@@ -40,11 +40,11 @@ export async function listFromCatalogueAction(itemId) {
             storeId = store.id;
         }
         const product = await createProductFromCatalogueItem(item, storeId);
-        await catalogueRepository.update(itemId, {
+        await catalogueRepository.setListingStatus(itemId, {
             listingStatus: "listed",
             linkedProductId: product.id,
             linkedProductSlug: product.slug ?? product.id,
-        });
+        }, { actor: { role: "seller", uid: user.uid }, trigger: "listFromCatalogue" }, item);
         return { productId: product.id, productSlug: product.slug ?? product.id };
     });
 }

package/dist/features/catalogue/actions/submit-for-approval.js

@@ -22,9 +22,6 @@ export async function submitCatalogueItemForApprovalAction(itemId) {
             throw new ValidationError("Only items not yet submitted can be requested for listing");
         }
         assertCatalogueImagesFresh(item);
-        await catalogueRepository.update(itemId, {
-            listingStatus: "pending_admin_approval",
-            submittedForApprovalAt: new Date(),
-        });
+        await catalogueRepository.setListingStatus(itemId, { listingStatus: "pending_admin_approval", submittedForApprovalAt: new Date() }, { actor: { role: "buyer", uid: user.uid }, trigger: "submitCatalogueForApproval" }, item);
     });
 }

package/dist/features/catalogue/components/AdminCatalogueApprovalsView.js

@@ -10,6 +10,7 @@ import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints";
 import { apiClient } from "../../../http";
 import { toRecordArray, toRelativeDate, toStringValue, } from "../../admin/hooks/useAdminListingData";
 import { DataListingView } from "../../admin/components/DataListingView";
+import { RecordStatusTimeline } from "../../status-history/components/RecordStatusTimeline";
 /** The submitted item's photos — the whole point of a visual approval. */
 function toPhotoEntries(raw) {
     const images = Array.isArray(raw.images) ? raw.images : [];
@@ -71,7 +72,10 @@ export function AdminCatalogueApprovalsView() {
                     { label: "Quantity", value: String(raw.quantity ?? 1) },
                     { label: "Condition", value: toStringValue(raw.condition, "—") },
                     { label: "Submitted", value: selected?.updatedAt ?? "—" },
-                ], items: { heading: "Photos", entries: toPhotoEntries(raw) }, footer: selected ? (_jsxs(_Fragment, { children: [_jsx(Button, { variant: "danger", onClick: () => {
+                ], items: { heading: "Photos", entries: toPhotoEntries(raw) }, extra: 
+                // "Why was mine rejected and by whom" — `rejectionReason` alone is
+                // overwritten by the next decision.
+                _jsx(RecordStatusTimeline, { entries: raw.statusHistory, truncatedCount: raw.statusHistoryTruncated }), footer: selected ? (_jsxs(_Fragment, { children: [_jsx(Button, { variant: "danger", onClick: () => {
                                 setRejectTarget(selected.id);
                                 setSelected(null);
                             }, children: "Reject" }), _jsx(Button, { isLoading: approveMutation.isPending, onClick: () => {

package/dist/features/catalogue/components/CatalogueItemEditorView.js

@@ -62,7 +62,9 @@ export function CatalogueItemEditorView({ item, onSaved }) {
             onSaved?.(saved.id);
         },
     });
-    return (_jsx(Form, { schema: createCatalogueItemSchema, spacing: "md", children: ({ setFieldError }) => (_jsxs(Stack, { gap: "md", children: [item?.listingStatus && item.listingStatus !== "not_listed" && (_jsxs(Alert, { variant: "info", children: ["This item is ", item.listingStatus.replace(/_/g, " "), item.listingStatus === "rejected" && item.rejectionReason ? `: ${item.rejectionReason}` : "."] })), _jsxs(Grid, { cols: 2, gap: "md", children: [_jsx(FieldInput, { name: "title", label: "Title", required: true, value: title, onChange: setTitle }), _jsx(FieldSelect, { name: "condition", label: "Condition", value: condition, onChange: setCondition, options: CONDITION_OPTIONS }), _jsx(FieldInput, { name: "price", label: "Estimated resale price (\u20B9)", type: "number", min: "0", value: price, onChange: setPrice }), _jsx(FieldInput, { name: "quantity", label: "Quantity", type: "number", min: "1", value: quantity, onChange: setQuantity })] }), _jsx(FieldTextarea, { name: "description", label: "Description", value: description, onChange: setDescription, rows: 3 }), _jsx(MediaUploadList, { label: "Photos", value: galleryFields, onChange: (fields) => setImages(fields.map((f) => f.url)), onUpload: handleUpload, accept: "image/*", maxItems: 8, helperText: "Photos older than 30 days must be refreshed before this item can be listed." }), _jsxs(Row, { gap: "sm", align: "center", children: [_jsx(Toggle, { checked: visibility === "public", onChange: (checked) => setVisibility(checked ? "public" : "private"), size: "sm" }), _jsx(Span, { children: visibility === "public" ? "Public — visible on your profile" : "Private — only you can see it" })] }), _jsx(FormErrorSummary, {}), _jsx(Button, { type: "button", isLoading: saveMutation.isPending, onClick: () => {
+    return (_jsx(Form, { schema: createCatalogueItemSchema, spacing: "md", children: ({ setFieldError, markSubmitAttempted }) => (_jsxs(Stack, { gap: "md", children: [item?.listingStatus && item.listingStatus !== "not_listed" && (_jsxs(Alert, { variant: "info", children: ["This item is ", item.listingStatus.replace(/_/g, " "), item.listingStatus === "rejected" && item.rejectionReason ? `: ${item.rejectionReason}` : "."] })), _jsxs(Grid, { cols: 2, gap: "md", children: [_jsx(FieldInput, { name: "title", label: "Title", required: true, value: title, onChange: setTitle }), _jsx(FieldSelect, { name: "condition", label: "Condition", value: condition, onChange: setCondition, options: CONDITION_OPTIONS }), _jsx(FieldInput, { name: "price", label: "Estimated resale price (\u20B9)", type: "number", min: "0", value: price, onChange: setPrice }), _jsx(FieldInput, { name: "quantity", label: "Quantity", type: "number", min: "1", value: quantity, onChange: setQuantity })] }), _jsx(FieldTextarea, { name: "description", label: "Description", value: description, onChange: setDescription, rows: 3 }), _jsx(MediaUploadList, { label: "Photos", value: galleryFields, onChange: (fields) => setImages(fields.map((f) => f.url)), onUpload: handleUpload, accept: "image/*", maxItems: 8, helperText: "Photos older than 30 days must be refreshed before this item can be listed." }), _jsxs(Row, { gap: "sm", align: "center", children: [_jsx(Toggle, { checked: visibility === "public", onChange: (checked) => setVisibility(checked ? "public" : "private"), size: "sm" }), _jsx(Span, { children: visibility === "public" ? "Public — visible on your profile" : "Private — only you can see it" })] }), _jsx(FormErrorSummary, {}), _jsx(Button, { type: "button", isLoading: saveMutation.isPending, onClick: () => {
+                        // type="button" — no native submit, so unhide the summary here.
+                        markSubmitAttempted();
                         const parsed = createCatalogueItemSchema.safeParse({
                             title,
                             images,

package/dist/features/catalogue/repository/catalogue.repository.d.ts

@@ -3,9 +3,32 @@
  */
 import { BaseRepository, parseSieveDateValue, type SieveModel, type FirebaseSieveResult } from "../../../providers/db-firebase";
 import { type CatalogueItemDocument, type CatalogueItemCreateInput, type CatalogueItemUpdateInput } from "../schemas/firestore";
+import { type HistoryActor } from "../../../_internal/shared/history/index";
+/** Who/why for a catalogue write that lands in `statusHistory`. */
+export interface CatalogueWriteContext {
+    actor?: HistoryActor;
+    trigger?: string;
+    reason?: string;
+    note?: string;
+}
 export declare class CatalogueRepository extends BaseRepository<CatalogueItemDocument> {
     constructor();
     create(input: CatalogueItemCreateInput): Promise<CatalogueItemDocument>;
+    /**
+     * The approval-workflow write path — the funnel this repository did not have.
+     *
+     * `listingStatus` was moved by FIVE scattered `update()` calls across four
+     * action files and a scheduled job, none of which recorded who did it or
+     * why. `rejectionReason` was the only trace an admin decision left, and the
+     * next decision overwrites it.
+     *
+     * Every caller already holds the item (each does its own `findById` to
+     * authorise the transition), so `prior` makes the timeline entry free.
+     * Deliberately NOT a `BaseRepository` hook: `update()` does not read before
+     * writing, so a generic hook would force a pre-read on every update of
+     * every collection (Rule #6), and it carries neither actor nor trigger.
+     */
+    setListingStatus(itemId: string, patch: CatalogueItemUpdateInput, ctx?: CatalogueWriteContext, prior?: CatalogueItemDocument | null): Promise<CatalogueItemDocument>;
     /** Stamps lastImageUpdateAt whenever `images` changes — the single field the freshness gate checks. */
     update(itemId: string, input: CatalogueItemUpdateInput): Promise<CatalogueItemDocument>;
     listPublicByOwner(ownerId: string): Promise<CatalogueItemDocument[]>;

package/dist/features/catalogue/repository/catalogue.repository.js

@@ -2,7 +2,8 @@
  * Personal Catalogue Repository (Feature B).
  */
 import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase";
-import { CATALOGUE_COLLECTION, CATALOGUE_FIELDS, createCatalogueItemId, } from "../schemas/firestore";
+import { CATALOGUE_COLLECTION, CATALOGUE_FIELDS, CATALOGUE_TRACKED_FIELDS, CATALOGUE_HISTORY_PII_FIELDS, createCatalogueItemId, } from "../schemas/firestore";
+import { withHistory } from "../../../_internal/shared/history/index";
 export class CatalogueRepository extends BaseRepository {
     constructor() {
         super(CATALOGUE_COLLECTION);
@@ -20,6 +21,32 @@ export class CatalogueRepository extends BaseRepository {
         await this.getCollection().doc(id).set(prepareForFirestore(data));
         return { id, ...data };
     }
+    /**
+     * The approval-workflow write path — the funnel this repository did not have.
+     *
+     * `listingStatus` was moved by FIVE scattered `update()` calls across four
+     * action files and a scheduled job, none of which recorded who did it or
+     * why. `rejectionReason` was the only trace an admin decision left, and the
+     * next decision overwrites it.
+     *
+     * Every caller already holds the item (each does its own `findById` to
+     * authorise the transition), so `prior` makes the timeline entry free.
+     * Deliberately NOT a `BaseRepository` hook: `update()` does not read before
+     * writing, so a generic hook would force a pre-read on every update of
+     * every collection (Rule #6), and it carries neither actor nor trigger.
+     */
+    async setListingStatus(itemId, patch, ctx, prior) {
+        const current = prior !== undefined ? prior : await this.findById(itemId);
+        const withEntry = withHistory(current, patch, {
+            tracked: CATALOGUE_TRACKED_FIELDS,
+            actor: ctx?.actor ?? { role: "system" },
+            trigger: ctx?.trigger ?? "setListingStatus",
+            reason: ctx?.reason,
+            note: ctx?.note,
+            piiFields: CATALOGUE_HISTORY_PII_FIELDS,
+        });
+        return this.update(itemId, withEntry ?? patch);
+    }
     /** Stamps lastImageUpdateAt whenever `images` changes — the single field the freshness gate checks. */
     async update(itemId, input) {
         const patch = { ...input };

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

@@ -7,6 +7,7 @@
  * `mycatalog-` to stay visually distinct from `catalog-`.
  */
 import { type GenerateCatalogueItemIdInput } from "../../../utils/id-generators";
+import type { StatusChangeEntry } from "../../../_internal/shared/history/types";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 import type { ProductDraftFields } from "../../shipments/schemas/firestore";
 export declare const CATALOGUE_COLLECTION: "catalogueItems";
@@ -32,6 +33,17 @@ export interface CatalogueItemDocument extends BaseDocument, Partial<Omit<Produc
     rejectionReason?: string;
     linkedProductId?: string;
     linkedProductSlug?: string;
+    /**
+     * Who changed what, when, and why. See § "Status History" in CLAUDE.md.
+     *
+     * A catalogue item's status is a small approval workflow between an owner
+     * and an admin (`not_listed → pending_admin_approval → listed | rejected`),
+     * so "why was mine rejected and by whom" is exactly the question the
+     * timeline exists for. `rejectionReason` alone is overwritten by the next
+     * decision.
+     */
+    statusHistory?: StatusChangeEntry[];
+    statusHistoryTruncated?: number;
 }
 export declare const CATALOGUE_IMAGE_FRESHNESS_DAYS: 30;
 export declare const CATALOGUE_FIELDS: {
@@ -45,3 +57,10 @@ export declare const CATALOGUE_FIELDS: {
 export type CatalogueItemCreateInput = Omit<CatalogueItemDocument, "id" | "createdAt" | "updatedAt" | "lastImageUpdateAt" | "listingStatus">;
 export type CatalogueItemUpdateInput = Partial<Omit<CatalogueItemDocument, "id" | "createdAt" | "ownerId">>;
 export declare function createCatalogueItemId(input: GenerateCatalogueItemIdInput): string;
+/** The fields whose changes earn a timeline entry. */
+export declare const CATALOGUE_TRACKED_FIELDS: readonly ["listingStatus", "rejectionReason", "linkedProductId", "submittedForApprovalAt"];
+/**
+ * PII on this document, for `withHistory`'s scrub. `ownerId` is a UID, not
+ * PII, and is what the timeline's actor already carries.
+ */
+export declare const CATALOGUE_HISTORY_PII_FIELDS: readonly ["ownerName", "ownerEmail"];

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

@@ -20,3 +20,15 @@ export const CATALOGUE_FIELDS = {
 export function createCatalogueItemId(input) {
     return generateCatalogueItemId(input);
 }
+/** The fields whose changes earn a timeline entry. */
+export const CATALOGUE_TRACKED_FIELDS = [
+    "listingStatus",
+    "rejectionReason",
+    "linkedProductId",
+    "submittedForApprovalAt",
+];
+/**
+ * PII on this document, for `withHistory`'s scrub. `ownerId` is a UID, not
+ * PII, and is what the timeline's actor already carries.
+ */
+export const CATALOGUE_HISTORY_PII_FIELDS = ["ownerName", "ownerEmail"];

package/dist/features/categories/schemas/index.d.ts

@@ -452,7 +452,7 @@ export declare const categoryFirestoreSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough"> | undefined;
     featuredPriority?: number | undefined;
     isBrand?: boolean | undefined;
-    createdByType?: "store" | "admin" | undefined;
+    createdByType?: "admin" | "store" | undefined;
     createdByStoreId?: string | undefined;
     itemCode?: string | undefined;
     brandWebsite?: string | undefined;
@@ -551,7 +551,7 @@ export declare const categoryFirestoreSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough"> | undefined;
     featuredPriority?: number | undefined;
     isBrand?: boolean | undefined;
-    createdByType?: "store" | "admin" | undefined;
+    createdByType?: "admin" | "store" | undefined;
     createdByStoreId?: string | undefined;
     itemCode?: string | undefined;
     brandWebsite?: string | undefined;