@mohasinac/appkit 4.22.0 → 4.24.0

package/dist/features/status-history/components/RecordStatusTimeline.js

@@ -0,0 +1,90 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { StatusTimeline } from "./StatusTimeline";
+/**
+ * The timeline for an entity with no fixed phase vocabulary.
+ *
+ * ## Why this exists rather than seven more wrappers
+ *
+ * `OrderStatusTimeline` and `OfferPhaseTimeline` each supply a KNOWN sequence
+ * of phases — placed → paid → shipped → delivered, made → countered →
+ * accepted → paid — and render the steps a record has not reached yet as
+ * upcoming. That shape earns a dedicated wrapper because the vocabulary is
+ * part of the product.
+ *
+ * Support tickets, payouts, stores, scammer profiles, bids, shipments,
+ * catalogue items and ads have no such sequence: a store goes active →
+ * suspended → active, a bid goes active → outbid → active → won, a payout
+ * retries. There is nothing to pre-render. So the timeline is simply the
+ * entries that happened, in order — and writing that eight times would be
+ * eight chances for the actor label, the em-dash rule or the negative tone to
+ * drift, which is the bug-fix multiplier the Duplication Framework names.
+ *
+ * ## Never fabricate a step
+ *
+ * A record written before its entity adopted history has no `statusHistory`
+ * at all. That renders `emptyLabel`, NOT a step derived from `updatedAt` —
+ * "last write of any kind" is not an event, and a made-up date makes the
+ * record lie. Same rule the offer timeline follows for `expired`.
+ */
+/**
+ * Statuses that render in the error tone.
+ *
+ * Deliberately a shared set rather than a per-entity prop: these words mean
+ * the same thing on every entity that uses them, and a per-entity list is one
+ * more thing to keep aligned. A value not listed renders neutral, which is
+ * the safe direction — a real transition shown in the wrong tone is a smaller
+ * defect than a normal one shown as a failure.
+ */
+const NEGATIVE_STATUSES = new Set([
+    "cancelled",
+    "canceled",
+    "rejected",
+    "failed",
+    "forfeited",
+    "suspended",
+    "removed",
+    "declined",
+    "expired",
+    "lost",
+]);
+/** Ended, but not a failure — the record simply moved on. */
+const MUTED_STATUSES = new Set(["outbid", "closed", "superseded", "archived"]);
+function humanise(value) {
+    if (value === null || value === undefined || value === "")
+        return "—";
+    if (typeof value === "boolean")
+        return value ? "yes" : "no";
+    const s = String(value);
+    return s.replace(/_/g, " ").replace(/^./, (c) => c.toUpperCase());
+}
+/**
+ * One entry → one step.
+ *
+ * `status` is the headline when it changed; otherwise the step is named after
+ * the fields that did move, so an entry recording only "ETA moved" still
+ * reads as a real event rather than a blank row.
+ */
+function toStep(entry, index) {
+    const statusChange = entry.changes["status"] ?? entry.changes["listingStatus"];
+    const to = statusChange?.to;
+    const label = statusChange
+        ? humanise(to)
+        : Object.keys(entry.changes).map(humanise).join(", ") || "Updated";
+    const toKey = typeof to === "string" ? to.toLowerCase() : "";
+    return {
+        key: `${entry.at instanceof Date ? entry.at.toISOString() : String(entry.at)}-${index}`,
+        label,
+        date: entry.at instanceof Date ? entry.at.toISOString() : String(entry.at),
+        negative: NEGATIVE_STATUSES.has(toKey),
+        muted: MUTED_STATUSES.has(toKey),
+        actorRole: entry.actorRole,
+        reason: entry.reason,
+        note: entry.note,
+    };
+}
+export function RecordStatusTimeline({ entries, truncatedCount, title = "History", emptyLabel = "No recorded history yet", className, }) {
+    const steps = (entries ?? []).map(toStep);
+    return (_jsx(StatusTimeline, { title: title, steps: steps, truncatedCount: truncatedCount, emptyLabel: emptyLabel, className: className }));
+}
+export default RecordStatusTimeline;

package/dist/features/status-history/index.d.ts

@@ -9,3 +9,5 @@
  */
 export { StatusTimeline, stepsFromEntries } from "./components/StatusTimeline";
 export type { StatusTimelineProps, TimelineEntry, TimelineStep } from "./components/StatusTimeline";
+export { RecordStatusTimeline } from "./components/RecordStatusTimeline";
+export type { RecordStatusTimelineProps } from "./components/RecordStatusTimeline";

package/dist/features/status-history/index.js

@@ -8,3 +8,4 @@
  * is an entirely unrelated concept.
  */
 export { StatusTimeline, stepsFromEntries } from "./components/StatusTimeline";
+export { RecordStatusTimeline } from "./components/RecordStatusTimeline";

package/dist/features/stores/repository/store.repository.d.ts

@@ -6,6 +6,14 @@
  */
 import { BaseRepository, type SieveModel, type FirebaseSieveResult, type DocumentSnapshot } from "../../../providers/db-firebase";
 import { StoreDocument } from "../schemas";
+import { type HistoryActor } from "../../../_internal/shared/history/index";
+/** Who/why for a store write that lands in `statusHistory`. */
+export interface StoreWriteContext {
+    actor?: HistoryActor;
+    trigger?: string;
+    reason?: string;
+    note?: string;
+}
 export declare class StoreRepository extends BaseRepository<StoreDocument> {
     constructor();
     private encryptSecrets;
@@ -33,9 +41,29 @@ export declare class StoreRepository extends BaseRepository<StoreDocument> {
      */
     updateStore(storeSlug: string, data: Partial<Omit<StoreDocument, "id" | "storeSlug" | "ownerId" | "createdAt">>): Promise<StoreDocument>;
     /**
-     * Admin: approve or reject a store.
+     * Admin: approve, reject or suspend a store — and the ONLY correct way to
+     * move `status`, because `isPublic` must move with it.
+     *
+     * `status` and `isPublic` are two distinct fields and public visibility
+     * gates on `isPublic`. The admin PATCH route wrote `status` directly and
+     * never touched `isPublic` until 2026-08-26, so approving a pending store
+     * left it `isPublic: false` — active, and invisible on every public
+     * surface, with nothing anywhere reporting a problem. Same two-field trap
+     * CLAUDE.md already records for `becomeSeller` / `createStore`.
+     *
+     * `extra` carries the other admin fields so a single save is a single
+     * write and a single timeline entry; `prior` keeps that entry read-free
+     * for the route, which has already fetched the store to 404 on a missing
+     * one (Rule #6).
+     */
+    setStatus(storeSlug: string, status: StoreDocument["status"], extra?: Partial<StoreDocument>, ctx?: StoreWriteContext, prior?: StoreDocument | null): Promise<StoreDocument>;
+    /**
+     * Admin field edits that do NOT move `status` — verification, featuring,
+     * capabilities, the suspension reason on an already-suspended store.
      */
-    setStatus(storeSlug: string, status: StoreDocument["status"]): Promise<StoreDocument>;
+    adminUpdate(storeSlug: string, patch: Partial<StoreDocument>, ctx?: StoreWriteContext, prior?: StoreDocument | null): Promise<StoreDocument>;
+    /** Append a timeline entry when the patch touches a tracked field. */
+    private withStoreHistory;
     /**
      * Paginated list of stores with Sieve filtering/sorting.
      * Filters to active + public stores for the public listing.

package/dist/features/stores/repository/store.repository.js

@@ -6,10 +6,11 @@
  */
 import { BaseRepository, prepareForFirestore, applySieveToFirestore, } from "../../../providers/db-firebase";
 import { increment } from "../../../contracts/field-ops";
-import { STORE_COLLECTION, STORE_FIELDS, DEFAULT_STORE_DATA, StoreStatusValues, } from "../schemas";
+import { STORE_COLLECTION, STORE_FIELDS, DEFAULT_STORE_DATA, StoreStatusValues, STORE_TRACKED_FIELDS, STORE_HISTORY_PII_FIELDS, } from "../schemas";
 import { DatabaseError } from "../../../errors";
 import { normalizeError } from "../../../errors/normalize";
 import { encryptSecret, decryptSecret, } from "../../../security/settings-encryption";
+import { withHistory } from "../../../_internal/shared/history/index";
 export class StoreRepository extends BaseRepository {
     constructor() {
         super(STORE_COLLECTION);
@@ -97,16 +98,54 @@ export class StoreRepository extends BaseRepository {
         });
     }
     /**
-     * Admin: approve or reject a store.
+     * Admin: approve, reject or suspend a store — and the ONLY correct way to
+     * move `status`, because `isPublic` must move with it.
+     *
+     * `status` and `isPublic` are two distinct fields and public visibility
+     * gates on `isPublic`. The admin PATCH route wrote `status` directly and
+     * never touched `isPublic` until 2026-08-26, so approving a pending store
+     * left it `isPublic: false` — active, and invisible on every public
+     * surface, with nothing anywhere reporting a problem. Same two-field trap
+     * CLAUDE.md already records for `becomeSeller` / `createStore`.
+     *
+     * `extra` carries the other admin fields so a single save is a single
+     * write and a single timeline entry; `prior` keeps that entry read-free
+     * for the route, which has already fetched the store to 404 on a missing
+     * one (Rule #6).
      */
-    async setStatus(storeSlug, status) {
-        return this.update(storeSlug, {
+    async setStatus(storeSlug, status, extra, ctx, prior) {
+        const current = prior !== undefined ? prior : await this.findById(storeSlug);
+        return this.update(storeSlug, this.withStoreHistory(current, {
             status,
             // Auto-set isPublic when approved
             ...(status === StoreStatusValues.ACTIVE && { isPublic: true }),
             ...(status !== StoreStatusValues.ACTIVE && { isPublic: false }),
+            ...extra,
             updatedAt: new Date(),
+        }, ctx, "setStatus"));
+    }
+    /**
+     * Admin field edits that do NOT move `status` — verification, featuring,
+     * capabilities, the suspension reason on an already-suspended store.
+     */
+    async adminUpdate(storeSlug, patch, ctx, prior) {
+        const current = prior !== undefined ? prior : await this.findById(storeSlug);
+        return this.update(storeSlug, this.withStoreHistory(current, { ...patch, updatedAt: new Date() }, ctx, "adminUpdateStore"));
+    }
+    /** Append a timeline entry when the patch touches a tracked field. */
+    withStoreHistory(current, patch, ctx, defaultTrigger) {
+        const withEntry = withHistory(current, patch, {
+            tracked: STORE_TRACKED_FIELDS,
+            actor: ctx?.actor ?? { role: "system" },
+            trigger: ctx?.trigger ?? defaultTrigger,
+            reason: ctx?.reason,
+            note: ctx?.note,
+            // `mapDoc` decrypts whatsappConfig.accessToken on EVERY read, so a
+            // live Meta credential is in memory whenever this diff runs, and
+            // `encryptPiiFields` never descends into arrays.
+            piiFields: STORE_HISTORY_PII_FIELDS,
         });
+        return withEntry ?? patch;
     }
     /**
      * Paginated list of stores with Sieve filtering/sorting.

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

@@ -4,6 +4,7 @@
  * Canonical Firestore document interfaces, collection names, field constants,
  * and helpers for the stores feature.
  */
+import type { StatusChangeEntry } from "../../../_internal/shared/history/types";
 import type { StoreCapability } from "../../auth/permissions/constants";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 export type ShippingProviderType = "self-courier" | "store-pickup" | "custom";
@@ -139,7 +140,35 @@ export interface StoreDocument extends BaseDocument {
         /** When the seller first connected their account */
         connectedAt?: Date;
     };
+    /**
+     * Who changed what, when, and why. See § "Status History" in CLAUDE.md.
+     *
+     * The question this answers for a seller is "why is my store suspended and
+     * who did it" — previously recoverable only from `adminAuditLog`, which is
+     * admin-only and which the seller can never see.
+     */
+    statusHistory?: StatusChangeEntry[];
+    statusHistoryTruncated?: number;
 }
+/**
+ * The fields whose changes earn a timeline entry.
+ *
+ * `isPublic` is tracked alongside `status` deliberately: the two are supposed
+ * to move together (`setStatus` syncs them) and the admin PATCH route did NOT
+ * until 2026-08-26, so an approved store stayed invisible. A timeline that
+ * shows them diverging is how the next instance gets noticed.
+ *
+ * `adminNotes` is excluded — its own schema comment says it is never shown to
+ * the store owner or the public, and `statusHistory` rides on the store
+ * document the owner can read.
+ */
+export declare const STORE_TRACKED_FIELDS: readonly ["status", "isPublic", "isVerified", "isFeatured", "suspensionReason", "capabilities"];
+/**
+ * PII on this document, for `withHistory`'s scrub. `whatsappConfig.accessToken`
+ * is a live Meta credential; `mapDoc` decrypts it on EVERY read, so it is
+ * present in memory whenever a diff runs.
+ */
+export declare const STORE_HISTORY_PII_FIELDS: readonly ["accessToken", "payoutDetails", "upiVpa", "accountNumber"];
 export type { StoreCapability } from "../../auth/permissions/constants";
 export declare const STORE_COLLECTION: "stores";
 export declare const STORE_FIELDS: {

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

@@ -12,6 +12,37 @@ export const StoreStatusValues = {
     SUSPENDED: "suspended",
     REJECTED: "rejected",
 };
+/**
+ * The fields whose changes earn a timeline entry.
+ *
+ * `isPublic` is tracked alongside `status` deliberately: the two are supposed
+ * to move together (`setStatus` syncs them) and the admin PATCH route did NOT
+ * until 2026-08-26, so an approved store stayed invisible. A timeline that
+ * shows them diverging is how the next instance gets noticed.
+ *
+ * `adminNotes` is excluded — its own schema comment says it is never shown to
+ * the store owner or the public, and `statusHistory` rides on the store
+ * document the owner can read.
+ */
+export const STORE_TRACKED_FIELDS = [
+    "status",
+    "isPublic",
+    "isVerified",
+    "isFeatured",
+    "suspensionReason",
+    "capabilities",
+];
+/**
+ * PII on this document, for `withHistory`'s scrub. `whatsappConfig.accessToken`
+ * is a live Meta credential; `mapDoc` decrypts it on EVERY read, so it is
+ * present in memory whenever a diff runs.
+ */
+export const STORE_HISTORY_PII_FIELDS = [
+    "accessToken",
+    "payoutDetails",
+    "upiVpa",
+    "accountNumber",
+];
 export const STORE_COLLECTION = "stores";
 export const STORE_FIELDS = {
     ID: "id",

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

@@ -1,6 +1,14 @@
 import { BaseRepository } from "../../../providers/db-firebase";
 import type { FirebaseSieveFields, FirebaseSieveResult, SieveModel } from "../../../providers/db-firebase";
 import { type SupportTicketDocument, type SupportTicketCreateInput, type SupportTicketUpdateInput, type TicketMessage, type TicketStatus } from "../schemas/firestore";
+import { type HistoryActor } from "../../../_internal/shared/history/index";
+/** Who/why for a write that lands in `statusHistory`. */
+export interface TicketWriteContext {
+    actor?: HistoryActor;
+    trigger?: string;
+    reason?: string;
+    note?: string;
+}
 export declare class SupportRepository extends BaseRepository<SupportTicketDocument> {
     static readonly SIEVE_FIELDS: FirebaseSieveFields;
     constructor();
@@ -10,9 +18,45 @@ export declare class SupportRepository extends BaseRepository<SupportTicketDocum
     countActiveTickets(userId: string): Promise<number>;
     getActiveOrderTicket(userId: string, orderId: string): Promise<SupportTicketDocument | null>;
     getActiveCategoryTicket(userId: string, category: string): Promise<SupportTicketDocument | null>;
-    updateTicketStatus(ticketId: string, update: SupportTicketUpdateInput): Promise<SupportTicketDocument>;
-    addMessage(ticketId: string, message: TicketMessage, newStatus?: TicketStatus): Promise<void>;
-    assignTicket(ticketId: string, assignedTo: string, assignedToName: string): Promise<SupportTicketDocument>;
+    /**
+     * The single status/assignment write path.
+     *
+     * `prior` is not an optimisation detail — the caller that matters (the admin
+     * PATCH route) already fetches the ticket to 404 on a missing one, so
+     * threading it through means history costs ZERO extra Firestore reads
+     * (Rule #6). Omit it and this falls back to a read, which is correct but
+     * avoidable.
+     */
+    updateTicketStatus(ticketId: string, update: SupportTicketUpdateInput, ctx?: TicketWriteContext, prior?: SupportTicketDocument | null): Promise<SupportTicketDocument>;
+    /**
+     * Stamp `resolvedAt` / `closedAt` on the transition INTO that status.
+     *
+     * Both fields were declared, constant-named and listed in the update input,
+     * and no code path had ever written either (verified 2026-08-26) — so every
+     * resolved ticket in the collection has no resolution time.
+     *
+     * Guarded on the transition, not on the status: re-saving a priority change
+     * on an already-resolved ticket must not move its resolution time forward.
+     * Never fabricated for a ticket resolved before this existed — that one
+     * renders an em-dash, the same rule the offer timeline follows.
+     */
+    private resolutionStamps;
+    /** Append a timeline entry when the patch touches a tracked field. */
+    private withTicketHistory;
+    /**
+     * Append a reply, optionally moving the ticket's status.
+     *
+     * The message itself is NOT history — the thread is already the record of
+     * what was said. Only an accompanying status change earns an entry, and
+     * only then is a read taken, so an ordinary reply still costs one write and
+     * no read.
+     *
+     * `messages` stays an `arrayUnion` (concurrent replies must not clobber one
+     * another); `statusHistory` cannot, because `arrayUnion` has no way to
+     * enforce the FIFO cap — so it is folded in memory and written whole.
+     */
+    addMessage(ticketId: string, message: TicketMessage, newStatus?: TicketStatus, ctx?: TicketWriteContext, prior?: SupportTicketDocument | null): Promise<void>;
+    assignTicket(ticketId: string, assignedTo: string, assignedToName: string, ctx?: TicketWriteContext, prior?: SupportTicketDocument | null): Promise<SupportTicketDocument>;
     listAll(model: SieveModel): Promise<FirebaseSieveResult<SupportTicketDocument>>;
 }
 export declare const supportRepository: SupportRepository;

package/dist/features/support/repository/support.repository.js

@@ -3,7 +3,8 @@ import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../..
 import { normalizeError } from "../../../errors/normalize";
 import { DatabaseError } from "../../../errors";
 import { SUPPORT_TICKET_FIELDS } from "../../../constants/field-names";
-import { SUPPORT_TICKET_COLLECTION, ACTIVE_TICKET_STATUSES, } from "../schemas/firestore";
+import { SUPPORT_TICKET_COLLECTION, SUPPORT_TICKET_PII_FIELDS, SUPPORT_TICKET_TRACKED_FIELDS, TicketStatusValues, ACTIVE_TICKET_STATUSES, } from "../schemas/firestore";
+import { withHistory } from "../../../_internal/shared/history/index";
 export class SupportRepository extends BaseRepository {
     constructor() {
         super(SUPPORT_TICKET_COLLECTION);
@@ -73,13 +74,73 @@ export class SupportRepository extends BaseRepository {
         const doc = snap.docs[0];
         return { id: doc.id, ...doc.data() };
     }
-    async updateTicketStatus(ticketId, update) {
-        return this.update(ticketId, {
+    /**
+     * The single status/assignment write path.
+     *
+     * `prior` is not an optimisation detail — the caller that matters (the admin
+     * PATCH route) already fetches the ticket to 404 on a missing one, so
+     * threading it through means history costs ZERO extra Firestore reads
+     * (Rule #6). Omit it and this falls back to a read, which is correct but
+     * avoidable.
+     */
+    async updateTicketStatus(ticketId, update, ctx, prior) {
+        const current = prior !== undefined ? prior : await this.getTicketById(ticketId);
+        const patch = {
             ...update,
+            ...this.resolutionStamps(current, update.status),
             updatedAt: new Date(),
+        };
+        return this.update(ticketId, this.withTicketHistory(current, patch, ctx, "updateTicketStatus"));
+    }
+    /**
+     * Stamp `resolvedAt` / `closedAt` on the transition INTO that status.
+     *
+     * Both fields were declared, constant-named and listed in the update input,
+     * and no code path had ever written either (verified 2026-08-26) — so every
+     * resolved ticket in the collection has no resolution time.
+     *
+     * Guarded on the transition, not on the status: re-saving a priority change
+     * on an already-resolved ticket must not move its resolution time forward.
+     * Never fabricated for a ticket resolved before this existed — that one
+     * renders an em-dash, the same rule the offer timeline follows.
+     */
+    resolutionStamps(current, next) {
+        if (!next || next === current?.status)
+            return {};
+        const now = new Date();
+        if (next === TicketStatusValues.RESOLVED && !current?.resolvedAt)
+            return { resolvedAt: now };
+        if (next === TicketStatusValues.CLOSED && !current?.closedAt)
+            return { closedAt: now };
+        return {};
+    }
+    /** Append a timeline entry when the patch touches a tracked field. */
+    withTicketHistory(current, patch, ctx, defaultTrigger) {
+        const withEntry = withHistory(current, patch, {
+            tracked: SUPPORT_TICKET_TRACKED_FIELDS,
+            actor: ctx?.actor ?? { role: "system" },
+            trigger: ctx?.trigger ?? defaultTrigger,
+            reason: ctx?.reason,
+            note: ctx?.note,
+            // `encryptPiiFields` never descends into arrays, so a PII-named value
+            // reaching `changes` would persist in PLAINTEXT inside statusHistory.
+            piiFields: SUPPORT_TICKET_PII_FIELDS,
         });
+        return withEntry ?? patch;
     }
-    async addMessage(ticketId, message, newStatus) {
+    /**
+     * Append a reply, optionally moving the ticket's status.
+     *
+     * The message itself is NOT history — the thread is already the record of
+     * what was said. Only an accompanying status change earns an entry, and
+     * only then is a read taken, so an ordinary reply still costs one write and
+     * no read.
+     *
+     * `messages` stays an `arrayUnion` (concurrent replies must not clobber one
+     * another); `statusHistory` cannot, because `arrayUnion` has no way to
+     * enforce the FIFO cap — so it is folded in memory and written whole.
+     */
+    async addMessage(ticketId, message, newStatus, ctx, prior) {
         try {
             const ref = this.db
                 .collection(SUPPORT_TICKET_COLLECTION)
@@ -88,8 +149,10 @@ export class SupportRepository extends BaseRepository {
                 messages: firebaseFieldOps.arrayUnion(prepareForFirestore(message)),
                 updatedAt: new Date(),
             };
-            if (newStatus)
-                updateData.status = newStatus;
+            if (newStatus) {
+                const current = prior !== undefined ? prior : await this.getTicketById(ticketId);
+                Object.assign(updateData, this.withTicketHistory(current, { status: newStatus, ...this.resolutionStamps(current, newStatus) }, ctx, "addMessage"));
+            }
             await ref.update(updateData);
         }
         catch (err) {
@@ -97,12 +160,9 @@ export class SupportRepository extends BaseRepository {
             throw new DatabaseError("Failed to add message to ticket", err);
         }
     }
-    async assignTicket(ticketId, assignedTo, assignedToName) {
-        return this.update(ticketId, {
-            assignedTo,
-            assignedToName,
-            updatedAt: new Date(),
-        });
+    async assignTicket(ticketId, assignedTo, assignedToName, ctx, prior) {
+        const current = prior !== undefined ? prior : await this.getTicketById(ticketId);
+        return this.update(ticketId, this.withTicketHistory(current, { assignedTo, assignedToName, updatedAt: new Date() }, ctx, "assignTicket"));
     }
     async listAll(model) {
         return this.sieveQuery(model, SupportRepository.SIEVE_FIELDS, { defaultPageSize: 25, maxPageSize: 100 });

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

@@ -15,6 +15,7 @@
  *  - No new ticket in the same category while existing one is waiting_on_user
  */
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+import type { StatusChangeEntry } from "../../../_internal/shared/history/types";
 export declare const TicketCategoryValues: {
     readonly ORDER_ISSUE: "order_issue";
     readonly BILLING_PAYMENT: "billing_payment";
@@ -101,11 +102,47 @@ export interface SupportTicketDocument extends BaseDocument {
     internalNotes?: string;
     /** Threaded conversation. Ordered by createdAt asc. */
     messages: TicketMessage[];
+    /**
+     * Stamped by the repository the first time `status` becomes `resolved` /
+     * `closed`. Both were declared, given `SUPPORT_TICKET_FIELDS` constants and
+     * listed in `SupportTicketUpdateInput` — and **nothing ever wrote either**
+     * (verified 2026-08-26), so no resolved ticket in the collection carries a
+     * resolution time and "how long do tickets take" has never been answerable.
+     *
+     * Server-stamped, never client-sent: the same discipline the reports route
+     * adopted after a client-sent `resolvedAt` arrived as a JSON string into a
+     * `Date` field and split the collection into two shapes.
+     */
     resolvedAt?: Date;
     closedAt?: Date;
+    /**
+     * Who changed what, when, and why. See § "Status History" in CLAUDE.md.
+     * Append-only, capped at STATUS_HISTORY_MAX, oldest evicted first.
+     */
+    statusHistory?: StatusChangeEntry[];
+    /** How many entries fell off the front. Never imply "this is all of it". */
+    statusHistoryTruncated?: number;
 }
+/**
+ * The fields whose changes earn a timeline entry.
+ *
+ * Explicit, not a whole-document diff: a diff would record the `updatedAt`
+ * bump on every write and exhaust the 50-entry cap within days. `messages` is
+ * excluded on purpose — the thread is already the conversation, and mirroring
+ * every reply into history would bury the handful of transitions anyone reads.
+ */
+export declare const SUPPORT_TICKET_TRACKED_FIELDS: readonly ["status", "priority", "assignedTo", "resolvedAt", "closedAt"];
+/**
+ * PII on this document, for `withHistory`'s scrub.
+ *
+ * `assignedToName` is a staff display name denormalised for the admin table —
+ * not the ticket author's identity — but it is still a person's name reaching
+ * an array `encryptPiiFields` cannot descend into, so history carries the UID
+ * (`assignedTo`) and never the name.
+ */
+export declare const SUPPORT_TICKET_PII_FIELDS: readonly ["userEmail", "userDisplayName", "assignedToName"];
 export type SupportTicketCreateInput = Pick<SupportTicketDocument, "userId" | "userEmail" | "userDisplayName" | "category" | "subject" | "description" | "orderId">;
-export type SupportTicketUpdateInput = Partial<Pick<SupportTicketDocument, "status" | "priority" | "assignedTo" | "assignedToName" | "internalNotes" | "resolvedAt" | "closedAt" | "relatedParties">>;
+export type SupportTicketUpdateInput = Partial<Pick<SupportTicketDocument, "status" | "priority" | "assignedTo" | "assignedToName" | "internalNotes" | "relatedParties">>;
 export declare const SUPPORT_TICKET_COLLECTION: "supportTickets";
 export declare const SUPPORT_TICKET_ID_PREFIX: "ticket-";
 export declare const SUPPORT_TICKET_INDEXED_FIELDS: readonly ["userId", "status", "category", "priority", "assignedTo", "orderId", "createdAt", "updatedAt"];

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

@@ -63,6 +63,40 @@ export const ELIGIBLE_ORDER_STATUSES_FOR_TICKET = [
     "SHIPPED",
     "RETURN_REQUESTED",
 ];
+/**
+ * The fields whose changes earn a timeline entry.
+ *
+ * Explicit, not a whole-document diff: a diff would record the `updatedAt`
+ * bump on every write and exhaust the 50-entry cap within days. `messages` is
+ * excluded on purpose — the thread is already the conversation, and mirroring
+ * every reply into history would bury the handful of transitions anyone reads.
+ */
+export const SUPPORT_TICKET_TRACKED_FIELDS = [
+    "status",
+    "priority",
+    "assignedTo",
+    "resolvedAt",
+    "closedAt",
+];
+/**
+ * PII on this document, for `withHistory`'s scrub.
+ *
+ * `assignedToName` is a staff display name denormalised for the admin table —
+ * not the ticket author's identity — but it is still a person's name reaching
+ * an array `encryptPiiFields` cannot descend into, so history carries the UID
+ * (`assignedTo`) and never the name.
+ */
+export const SUPPORT_TICKET_PII_FIELDS = [
+    "userEmail",
+    "userDisplayName",
+    "assignedToName",
+];
+/*
+ * `resolvedAt` / `closedAt` are deliberately NOT in the update input. They are
+ * events, and the server is the only thing that knows when one happened —
+ * letting a client send them is how the reports collection ended up holding
+ * both Timestamps and ISO strings in one field.
+ */
 // ============================================================================
 // COLLECTION CONSTANTS
 // ============================================================================

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

@@ -182,6 +182,7 @@ export declare const supportTicketFirestoreSchema: z.ZodObject<{
     closedAt?: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
+    assignedToName?: string | undefined;
     relatedParties?: {
         storeId?: string | undefined;
         userId?: string | undefined;
@@ -189,7 +190,6 @@ export declare const supportTicketFirestoreSchema: z.ZodObject<{
         productId?: string | undefined;
         bidId?: string | undefined;
     } | undefined;
-    assignedToName?: string | undefined;
     internalNotes?: string | undefined;
 }, {
     status: "closed" | "open" | "resolved" | "in_progress" | "waiting_on_user";
@@ -225,6 +225,7 @@ export declare const supportTicketFirestoreSchema: z.ZodObject<{
     closedAt?: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
+    assignedToName?: string | undefined;
     relatedParties?: {
         storeId?: string | undefined;
         userId?: string | undefined;
@@ -232,7 +233,6 @@ export declare const supportTicketFirestoreSchema: z.ZodObject<{
         productId?: string | undefined;
         bidId?: string | undefined;
     } | undefined;
-    assignedToName?: string | undefined;
     internalNotes?: string | undefined;
 }>;
 export type SupportTicketFromSchema = z.infer<typeof supportTicketFirestoreSchema>;