@mohasinac/appkit 4.21.0 → 4.23.0

package/dist/features/payments/repository/payout.repository.js

@@ -5,7 +5,8 @@
  * Handles seller payout requests and admin payout processing.
  */
 import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase";
-import { PAYOUT_COLLECTION, PAYOUT_FIELDS, createPayoutId } from "../schemas";
+import { PAYOUT_COLLECTION, PAYOUT_FIELDS, PAYOUT_TRACKED_FIELDS, createPayoutId } from "../schemas";
+import { withHistory } from "../../../_internal/shared/history/index";
 import { encryptPiiFields, decryptPiiFields, addPiiIndices, PAYOUT_PII_FIELDS, PAYOUT_PII_INDEX_MAP, encryptPayoutBankAccount, decryptPayoutBankAccount, } from "../../../security";
 export class PayoutRepository extends BaseRepository {
     constructor() {
@@ -120,10 +121,14 @@ export class PayoutRepository extends BaseRepository {
         }));
     }
     /**
-     * Update payout status (admin action)
+     * Update payout status (admin action).
+     *
+     * `prior` keeps the timeline entry read-free — the admin route already
+     * fetches the payout to authorise the change (Rule #6).
      */
-    async updateStatus(payoutId, status, extra) {
-        return this.update(payoutId, {
+    async updateStatus(payoutId, status, extra, ctx, prior) {
+        const current = prior !== undefined ? prior : await this.findById(payoutId);
+        return this.update(payoutId, this.withPayoutHistory(current, {
             status,
             ...extra,
             ...(status === PAYOUT_FIELDS.STATUS_VALUES.PAID ||
@@ -131,29 +136,50 @@ export class PayoutRepository extends BaseRepository {
                 ? { processedAt: new Date() }
                 : {}),
             updatedAt: new Date(),
-        });
+        }, ctx, "adminUpdatePayout"));
     }
-    markProcessing(ref) {
-        return ref.update({
-            status: "processing",
-            processedAt: new Date(),
-            updatedAt: new Date(),
-        });
+    /*
+     * ── Batch dispatch primitives ──────────────────────────────────────────
+     *
+     * These take a `DocumentReference` rather than an id because the payouts
+     * batch already holds one from its query snapshot. `prior` comes from the
+     * SAME snapshot, so history costs no read here either — but it must be the
+     * caller's running copy, not the original: the sequence is
+     * pending → processing → failed, and diffing the final write against the
+     * ORIGINAL snapshot would record "pending → failed" and lose the dispatch
+     * attempt entirely.
+     */
+    markProcessing(ref, ctx, prior) {
+        return ref.update(this.withPayoutHistory(prior, { status: "processing", processedAt: new Date(), updatedAt: new Date() }, ctx, "payoutBatch:dispatch"));
     }
-    recordSuccess(ref, razorpayPayoutId, razorpayStatus) {
-        return ref.update({
-            razorpayPayoutId,
-            razorpayStatus,
-            updatedAt: new Date(),
-        });
+    recordSuccess(ref, razorpayPayoutId, razorpayStatus, ctx, prior) {
+        return ref.update(this.withPayoutHistory(prior, { razorpayPayoutId, razorpayStatus, updatedAt: new Date() }, ctx, "payoutBatch:accepted"));
     }
-    recordFailure(ref, failureCount, reason, isFinal) {
-        return ref.update({
+    recordFailure(ref, failureCount, reason, isFinal, ctx, prior) {
+        return ref.update(this.withPayoutHistory(prior, {
             status: isFinal ? "failed" : "pending",
             failureCount,
             lastFailureReason: reason,
             updatedAt: new Date(),
+        }, 
+        // The reason is the point of the entry — `lastFailureReason` is
+        // overwritten by the next retry, so history is where the earlier
+        // attempts survive.
+        { ...ctx, reason }, isFinal ? "payoutBatch:failedFinal" : "payoutBatch:failedRetrying"));
+    }
+    /** Append a timeline entry when the patch touches a tracked field. */
+    withPayoutHistory(current, patch, ctx, defaultTrigger) {
+        const withEntry = withHistory(current, patch, {
+            tracked: PAYOUT_TRACKED_FIELDS,
+            actor: ctx?.actor ?? { role: "system" },
+            trigger: ctx?.trigger ?? defaultTrigger,
+            reason: ctx?.reason,
+            note: ctx?.note,
+            // `sellerEmail` / `upiId` — `encryptPiiFields` never descends into
+            // arrays, so either reaching `changes` would persist in PLAINTEXT.
+            piiFields: PAYOUT_PII_FIELDS,
         });
+        return withEntry ?? patch;
     }
     /**
      * Get all order IDs that have already been paid out for a seller.

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

@@ -3,6 +3,7 @@
  */
 import { type GeneratePayoutIdInput } from "../../../utils/id-generators";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+import type { StatusChangeEntry } from "../../../_internal/shared/history/types";
 export interface PayoutBankAccount {
     accountHolderName: string;
     accountNumberMasked: string;
@@ -70,7 +71,38 @@ export interface PayoutDocument extends BaseDocument {
     transactionId?: string;
     /** Seller-set personal follow-up flag — surfaced only to the owning seller, never mutated by admin. */
     sellerReminderFlag?: boolean;
+    /** Razorpay's payout id, once the API accepted the dispatch. */
+    razorpayPayoutId?: string;
+    /** Razorpay's own status string — NOT this document's `status`. */
+    razorpayStatus?: string;
+    /** Consecutive dispatch failures. At MAX_FAILURES the payout goes `failed`. */
+    failureCount?: number;
+    /**
+     * Why the LAST attempt failed. Overwritten by every retry, which is why the
+     * timeline tracks it: `statusHistory` is the only place the earlier reasons
+     * survive.
+     */
+    lastFailureReason?: string;
+    /**
+     * Who changed what, when, and why. See § "Status History" in CLAUDE.md.
+     *
+     * Payouts are the entity where this matters most to a seller: "it says
+     * failed, what happened" was previously answerable only from
+     * `lastFailureReason`, which the NEXT retry overwrites.
+     */
+    statusHistory?: StatusChangeEntry[];
+    statusHistoryTruncated?: number;
 }
+/**
+ * The fields whose changes earn a timeline entry.
+ *
+ * `netAmount`/`refundDeductions` are excluded — a refund deduction is money
+ * churn before dispatch, and § "Status History" keeps money off the timeline;
+ * `refundDeductions[]` on the document is already its own record.
+ * `failureCount` is excluded because `lastFailureReason` changing is the
+ * event, and tracking both would double every retry entry.
+ */
+export declare const PAYOUT_TRACKED_FIELDS: readonly ["status", "processedAt", "transactionId", "razorpayPayoutId", "razorpayStatus", "lastFailureReason"];
 export declare const PAYOUT_COLLECTION: "payouts";
 export declare const PAYOUT_INDEXED_FIELDS: readonly ["storeId", "status", "requestedAt", "createdAt"];
 export declare const DEFAULT_PLATFORM_FEE_RATE: 0.05;
@@ -91,7 +123,7 @@ export declare const PAYOUT_FIELDS: {
     };
 };
 export declare const PAYOUT_PUBLIC_FIELDS: readonly ["id", "storeId", "amount", "currency", "status", "paymentMethod", "requestedAt", "processedAt", "createdAt"];
-export declare const PAYOUT_ADMIN_UPDATEABLE_FIELDS: readonly ["status", "adminNote", "processedAt"];
+export declare const PAYOUT_ADMIN_UPDATEABLE_FIELDS: readonly ["status", "adminNote", "processedAt", "transactionId"];
 /** The only field a seller may write on their own payout doc. */
 export declare const PAYOUT_SELLER_UPDATEABLE_FIELDS: readonly ["sellerReminderFlag"];
 export type PayoutCreateInput = Omit<PayoutDocument, "id" | "createdAt" | "updatedAt" | "status" | "requestedAt">;

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

@@ -8,6 +8,23 @@ export const PayoutStatusValues = {
     PAID: "paid",
     FAILED: "failed",
 };
+/**
+ * The fields whose changes earn a timeline entry.
+ *
+ * `netAmount`/`refundDeductions` are excluded — a refund deduction is money
+ * churn before dispatch, and § "Status History" keeps money off the timeline;
+ * `refundDeductions[]` on the document is already its own record.
+ * `failureCount` is excluded because `lastFailureReason` changing is the
+ * event, and tracking both would double every retry entry.
+ */
+export const PAYOUT_TRACKED_FIELDS = [
+    "status",
+    "processedAt",
+    "transactionId",
+    "razorpayPayoutId",
+    "razorpayStatus",
+    "lastFailureReason",
+];
 export const PAYOUT_COLLECTION = "payouts";
 export const PAYOUT_INDEXED_FIELDS = [
     "storeId",
@@ -47,10 +64,32 @@ export const PAYOUT_PUBLIC_FIELDS = [
     "processedAt",
     "createdAt",
 ];
+/*
+ * 🛑 `transactionId` was MISSING here until 2026-08-26, and the whole
+ * mark-paid flow was built on top of the gap:
+ *
+ *   · `AdminPayoutMarkPaidModal` collects a UTR and makes it REQUIRED
+ *   · `PATCH /api/admin/payouts/[id]` declares it in its Zod schema and its
+ *     own docstring advertises "+ transaction reference"
+ *   · that route's test asserts it reaches `adminUpdatePayout`
+ *   · `adminUpdatePayout` picks only the fields in THIS list, so it was
+ *     dropped — and the route replies `{ id, ...body }`, echoing the
+ *     discarded UTR back as though it had been stored
+ *
+ * Every payout marked paid before this therefore has no payment reference,
+ * which is the one field a seller disputing "you say you paid me" needs.
+ * Root Cause #40's shape: a 200 that confirms a write which never happened.
+ *
+ * `processedAt` stays accepted for back-compat but is server-stamped by
+ * `updateStatus` on the transition into paid/failed — a client-sent
+ * timestamp is how the reports collection ended up with two shapes in one
+ * field.
+ */
 export const PAYOUT_ADMIN_UPDATEABLE_FIELDS = [
     "status",
     "adminNote",
     "processedAt",
+    "transactionId",
 ];
 /** The only field a seller may write on their own payout doc. */
 export const PAYOUT_SELLER_UPDATEABLE_FIELDS = ["sellerReminderFlag"];

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

@@ -33,20 +33,20 @@ export declare const payoutRefundDeductionSchema: z.ZodObject<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">>]>;
 }, "strip", z.ZodTypeAny, {
+    reason: string;
     orderId: string;
     refundId: string;
     refundedAmount: number;
     deductedAmount: number;
-    reason: string;
     appliedAt: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
 }, {
+    reason: string;
     orderId: string;
     refundId: string;
     refundedAmount: number;
     deductedAmount: number;
-    reason: string;
     appliedAt: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
@@ -116,20 +116,20 @@ export declare const payoutFirestoreSchema: z.ZodObject<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">>]>;
     }, "strip", z.ZodTypeAny, {
+        reason: string;
         orderId: string;
         refundId: string;
         refundedAmount: number;
         deductedAmount: number;
-        reason: string;
         appliedAt: string | Date | z.objectOutputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
     }, {
+        reason: string;
         orderId: string;
         refundId: string;
         refundedAmount: number;
         deductedAmount: number;
-        reason: string;
         appliedAt: string | Date | z.objectInputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -171,6 +171,9 @@ export declare const payoutFirestoreSchema: z.ZodObject<{
     platformFeeRate: number;
     paymentMethod: "bank_transfer" | "upi";
     orderIds: string[];
+    processedAt?: string | Date | z.objectOutputType<{
+        toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
     bankAccount?: {
         accountHolderName: string;
         accountNumberMasked: string;
@@ -186,19 +189,16 @@ export declare const payoutFirestoreSchema: z.ZodObject<{
     gstRate?: number | undefined;
     isAutomatic?: boolean | undefined;
     refundDeductions?: {
+        reason: string;
         orderId: string;
         refundId: string;
         refundedAmount: number;
         deductedAmount: number;
-        reason: string;
         appliedAt: string | Date | z.objectOutputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
     }[] | undefined;
     netAmount?: number | undefined;
-    processedAt?: string | Date | z.objectOutputType<{
-        toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
-    }, z.ZodTypeAny, "passthrough"> | undefined;
 }, {
     currency: string;
     status: "paid" | "failed" | "pending" | "processing";
@@ -221,6 +221,9 @@ export declare const payoutFirestoreSchema: z.ZodObject<{
     platformFeeRate: number;
     paymentMethod: "bank_transfer" | "upi";
     orderIds: string[];
+    processedAt?: string | Date | z.objectInputType<{
+        toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
     bankAccount?: {
         accountHolderName: string;
         accountNumberMasked: string;
@@ -236,19 +239,16 @@ export declare const payoutFirestoreSchema: z.ZodObject<{
     gstRate?: number | undefined;
     isAutomatic?: boolean | undefined;
     refundDeductions?: {
+        reason: string;
         orderId: string;
         refundId: string;
         refundedAmount: number;
         deductedAmount: number;
-        reason: string;
         appliedAt: string | Date | z.objectInputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
     }[] | undefined;
     netAmount?: number | undefined;
-    processedAt?: string | Date | z.objectInputType<{
-        toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
-    }, z.ZodTypeAny, "passthrough"> | undefined;
 }>;
 export type PayoutFromSchema = z.infer<typeof payoutFirestoreSchema>;
 /** Zod schema for payout status — use instead of inline `z.enum(["pending",...])`. */

package/dist/features/products/components/MakeOfferButton.js

@@ -38,7 +38,9 @@ export function MakeOfferButton({ productId, listedPrice, currency, minOfferPerc
     const schema = makeOfferFormSchema({ listedPrice, minOffer, formatAmount: fmt });
     const [offerAmount, setOfferAmount] = useState(String(Math.max(minOfferAmount(listedPrice, 90), minOffer)));
     const [buyerNote, setBuyerNote] = useState("");
-    function submit(setFieldError, clearErrors) {
+    function submit(setFieldError, clearErrors, markSubmitAttempted) {
+        // type="button" — no native submit, so unhide the summary here.
+        markSubmitAttempted();
         clearErrors();
         const parsed = schema.safeParse({ offerAmount, buyerNote: buyerNote || undefined });
         if (!parsed.success) {
@@ -75,8 +77,8 @@ export function MakeOfferButton({ productId, listedPrice, currency, minOfferPerc
     if (state === "pending") {
         return (_jsxs(Div, { className: `${CLS_PENDING_BOX} ${className}`, children: [_jsx(Span, { size: "lg", children: "\u23F3" }), _jsx(Text, { className: CLS_PENDING_TITLE, children: "Offer Pending" }), _jsx(Text, { className: CLS_PENDING_BODY, children: "You already have an offer on this item. Check My Offers for updates." })] }));
     }
-    return (_jsxs(_Fragment, { children: [_jsx(LoginRequiredModal, { isOpen: showLoginModal, onClose: () => setShowLoginModal(false), message: "You need to be signed in to make an offer. Please log in or create an account to continue." }), _jsx(Button, { variant: "ghost", size: "md", border: "strong", className: `w-full ${className}`, onClick: () => setState("open"), children: "Make Offer" }), _jsx(Modal, { isOpen: state === "open", onClose: () => setState("idle"), size: "md", title: "Make an offer", children: _jsx(Form, { schema: schema, onSubmit: (e) => e.preventDefault(), children: ({ setFieldError, clearErrors }) => (_jsxs(Stack, { gap: "md", children: [_jsxs(Text, { size: "xs", color: "muted", children: ["Listed at ", fmt(listedPrice), " \u00B7 Minimum offer: ", fmt(minOffer)] }), _jsx(FieldInput, { name: "offerAmount", type: "number", label: "Your offer amount", required: true, value: offerAmount, onChange: (value) => {
+    return (_jsxs(_Fragment, { children: [_jsx(LoginRequiredModal, { isOpen: showLoginModal, onClose: () => setShowLoginModal(false), message: "You need to be signed in to make an offer. Please log in or create an account to continue." }), _jsx(Button, { variant: "ghost", size: "md", border: "strong", className: `w-full ${className}`, onClick: () => setState("open"), children: "Make Offer" }), _jsx(Modal, { isOpen: state === "open", onClose: () => setState("idle"), size: "md", title: "Make an offer", children: _jsx(Form, { schema: schema, onSubmit: (e) => e.preventDefault(), children: ({ setFieldError, clearErrors, markSubmitAttempted }) => (_jsxs(Stack, { gap: "md", children: [_jsxs(Text, { size: "xs", color: "muted", children: ["Listed at ", fmt(listedPrice), " \u00B7 Minimum offer: ", fmt(minOffer)] }), _jsx(FieldInput, { name: "offerAmount", type: "number", label: "Your offer amount", required: true, value: offerAmount, onChange: (value) => {
                                     setOfferAmount(value);
                                     clearErrors();
-                                }, min: minOffer, max: listedPrice - 1, step: 1, "aria-label": "Offer amount" }), _jsxs(Text, { size: "xs", color: "faint", children: ["Must be between ", fmt(minOffer), " and ", fmt(listedPrice - 1)] }), _jsx(FieldInput, { name: "buyerNote", type: "text", label: "Note to seller (optional)", value: buyerNote, onChange: setBuyerNote, placeholder: "E.g. Bundle deal, long-time fan\u2026", maxLength: 300, "aria-label": "Note to seller" }), _jsx(Text, { size: "xs", color: "muted", children: "The seller will accept, decline, or suggest a counter price." }), _jsx(FormErrorSummary, {}), _jsxs(Stack, { gap: "xs", children: [_jsx(Button, { action: ACTIONS.PRODUCT["make-offer"], variant: "primary", size: "sm", type: "button", isLoading: isPending, disabled: isPending, onClick: () => submit(setFieldError, clearErrors), children: isPending ? "Sending…" : `Send offer of ${fmt(Number(offerAmount) || 0)}` }), _jsx(Button, { variant: "ghost", size: "sm", type: "button", onClick: () => setState("idle"), disabled: isPending, children: "Cancel" })] })] })) }) })] }));
+                                }, min: minOffer, max: listedPrice - 1, step: 1, "aria-label": "Offer amount" }), _jsxs(Text, { size: "xs", color: "faint", children: ["Must be between ", fmt(minOffer), " and ", fmt(listedPrice - 1)] }), _jsx(FieldInput, { name: "buyerNote", type: "text", label: "Note to seller (optional)", value: buyerNote, onChange: setBuyerNote, placeholder: "E.g. Bundle deal, long-time fan\u2026", maxLength: 300, "aria-label": "Note to seller" }), _jsx(Text, { size: "xs", color: "muted", children: "The seller will accept, decline, or suggest a counter price." }), _jsx(FormErrorSummary, {}), _jsxs(Stack, { gap: "xs", children: [_jsx(Button, { action: ACTIONS.PRODUCT["make-offer"], variant: "primary", size: "sm", type: "button", isLoading: isPending, disabled: isPending, onClick: () => submit(setFieldError, clearErrors, markSubmitAttempted), children: isPending ? "Sending…" : `Send offer of ${fmt(Number(offerAmount) || 0)}` }), _jsx(Button, { variant: "ghost", size: "sm", type: "button", onClick: () => setState("idle"), disabled: isPending, children: "Cancel" })] })] })) }) })] }));
 }

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

@@ -373,7 +373,7 @@ export declare const productItemSchema: z.ZodObject<{
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
     insurance?: boolean | undefined;
     insuranceCost?: number | undefined;
-    shippingPaidBy?: "seller" | "buyer" | undefined;
+    shippingPaidBy?: "buyer" | "seller" | undefined;
     auctionEndDate?: string | Date | undefined;
     startingBid?: number | undefined;
     currentBid?: number | undefined;
@@ -512,7 +512,7 @@ export declare const productItemSchema: z.ZodObject<{
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
     insurance?: boolean | undefined;
     insuranceCost?: number | undefined;
-    shippingPaidBy?: "seller" | "buyer" | undefined;
+    shippingPaidBy?: "buyer" | "seller" | undefined;
     auctionEndDate?: string | Date | undefined;
     startingBid?: number | undefined;
     currentBid?: number | undefined;

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

@@ -269,7 +269,7 @@ export declare const couponFirestoreSchema: z.ZodObject<{
     code: string;
     type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     id: string;
-    scope: "admin" | "seller";
+    scope: "seller" | "admin";
     name: string;
     createdAt: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
@@ -327,7 +327,7 @@ export declare const couponFirestoreSchema: z.ZodObject<{
     code: string;
     type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     id: string;
-    scope: "admin" | "seller";
+    scope: "seller" | "admin";
     name: string;
     createdAt: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
@@ -459,7 +459,7 @@ export declare const claimedCouponSnapshotSchema: z.ZodObject<{
     }>;
 }, "strip", z.ZodTypeAny, {
     type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
-    scope: "admin" | "seller";
+    scope: "seller" | "admin";
     name: string;
     discount: {
         value: number;
@@ -478,7 +478,7 @@ export declare const claimedCouponSnapshotSchema: z.ZodObject<{
     description?: string | undefined;
 }, {
     type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
-    scope: "admin" | "seller";
+    scope: "seller" | "admin";
     name: string;
     discount: {
         value: number;
@@ -545,7 +545,7 @@ export declare const claimedCouponFirestoreSchema: z.ZodObject<{
         }>;
     }, "strip", z.ZodTypeAny, {
         type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
-        scope: "admin" | "seller";
+        scope: "seller" | "admin";
         name: string;
         discount: {
             value: number;
@@ -564,7 +564,7 @@ export declare const claimedCouponFirestoreSchema: z.ZodObject<{
         description?: string | undefined;
     }, {
         type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
-        scope: "admin" | "seller";
+        scope: "seller" | "admin";
         name: string;
         discount: {
             value: number;
@@ -624,7 +624,7 @@ export declare const claimedCouponFirestoreSchema: z.ZodObject<{
     couponId: string;
     couponSnapshot: {
         type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
-        scope: "admin" | "seller";
+        scope: "seller" | "admin";
         name: string;
         discount: {
             value: number;
@@ -664,7 +664,7 @@ export declare const claimedCouponFirestoreSchema: z.ZodObject<{
     couponId: string;
     couponSnapshot: {
         type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
-        scope: "admin" | "seller";
+        scope: "seller" | "admin";
         name: string;
         discount: {
             value: number;
@@ -738,7 +738,7 @@ export declare const couponItemSchema: z.ZodObject<{
     code: string;
     type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     id: string;
-    scope: "admin" | "seller";
+    scope: "seller" | "admin";
     name: string;
     createdAt: string;
     updatedAt: string;
@@ -762,7 +762,7 @@ export declare const couponItemSchema: z.ZodObject<{
     code: string;
     type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     id: string;
-    scope: "admin" | "seller";
+    scope: "seller" | "admin";
     name: string;
     createdAt: string;
     updatedAt: string;
@@ -794,7 +794,7 @@ export declare const promotionsListParamsSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     sort?: string | undefined;
     page?: number | undefined;
-    scope?: "admin" | "seller" | undefined;
+    scope?: "seller" | "admin" | undefined;
     pageSize?: number | undefined;
     storeId?: string | undefined;
     isActive?: boolean | undefined;
@@ -802,7 +802,7 @@ export declare const promotionsListParamsSchema: z.ZodObject<{
 }, {
     sort?: string | undefined;
     page?: number | undefined;
-    scope?: "admin" | "seller" | undefined;
+    scope?: "seller" | "admin" | undefined;
     pageSize?: number | undefined;
     storeId?: string | undefined;
     isActive?: boolean | undefined;

package/dist/features/scams/repository/scammer.repository.d.ts

@@ -1,4 +1,12 @@
 import { BaseRepository, parseSieveDateValue, type FirebaseSieveResult, type SieveModel } from "../../../providers/db-firebase";
+import { type HistoryActor } from "../../../_internal/shared/history/index";
+/** Who/why for a scammer write that lands in `statusHistory`. */
+export interface ScammerWriteContext {
+    actor?: HistoryActor;
+    trigger?: string;
+    reason?: string;
+    note?: string;
+}
 import { type ScammerDocument, type ScammerIncidentDocument, type ScammerCommentDocument, type ScammerCreateInput, type ScammerAdminUpdateInput } from "../schemas/firestore";
 declare class ScammerRepository extends BaseRepository<ScammerDocument> {
     constructor();
@@ -53,7 +61,16 @@ declare class ScammerRepository extends BaseRepository<ScammerDocument> {
     listAll(model: SieveModel): Promise<FirebaseSieveResult<ScammerDocument>>;
     findBySeoSlug(seoSlug: string): Promise<ScammerDocument | null>;
     create(input: ScammerCreateInput): Promise<ScammerDocument>;
-    adminUpdate(id: string, input: ScammerAdminUpdateInput): Promise<void>;
+    /**
+     * The single admin write path for a scammer profile.
+     *
+     * The PATCH route used to call `update()` directly, bypassing this method
+     * entirely — so a decision on a public accusation against a named person
+     * left no record beyond `verifiedBy`/`verifiedAt`, which the NEXT decision
+     * overwrites. `prior` comes from the route's own 404 lookup, so the
+     * timeline entry costs no second read (Rule #6).
+     */
+    adminUpdate(id: string, input: ScammerAdminUpdateInput, ctx?: ScammerWriteContext, prior?: ScammerDocument | null): Promise<void>;
     incrementViews(id: string): Promise<void>;
     /**
      * Search for profiles whose phones, upiIds, emails, or displayNames arrays

package/dist/features/scams/repository/scammer.repository.js

@@ -3,6 +3,8 @@ import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../..
 import { normalizeError } from "../../../errors/normalize";
 import { serverLogger } from "../../../monitoring/server-logger";
 import { increment } from "../../../contracts/field-ops";
+import { withHistory } from "../../../_internal/shared/history/index";
+import { SCAMMER_TRACKED_FIELDS, SCAMMER_HISTORY_PII_FIELDS } from "../schemas/firestore";
 import { SCAMMER_COLLECTION, SCAMMER_FIELDS, SCAMMER_INCIDENTS_SUBCOLLECTION, SCAMMER_COMMENTS_SUBCOLLECTION, DEFAULT_SCAMMER_DATA, } from "../schemas/firestore";
 class ScammerRepository extends BaseRepository {
     constructor() {
@@ -68,9 +70,29 @@ class ScammerRepository extends BaseRepository {
             throw new DatabaseError(`Failed to create scammer profile: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    async adminUpdate(id, input) {
+    /**
+     * The single admin write path for a scammer profile.
+     *
+     * The PATCH route used to call `update()` directly, bypassing this method
+     * entirely — so a decision on a public accusation against a named person
+     * left no record beyond `verifiedBy`/`verifiedAt`, which the NEXT decision
+     * overwrites. `prior` comes from the route's own 404 lookup, so the
+     * timeline entry costs no second read (Rule #6).
+     */
+    async adminUpdate(id, input, ctx, prior) {
         try {
-            const data = prepareForFirestore({ ...input, updatedAt: new Date() });
+            const current = prior !== undefined ? prior : await this.findById(id);
+            const withEntry = withHistory(current, { ...input, updatedAt: new Date() }, {
+                tracked: SCAMMER_TRACKED_FIELDS,
+                actor: ctx?.actor ?? { role: "system" },
+                trigger: ctx?.trigger ?? "adminUpdateScammer",
+                reason: ctx?.reason,
+                note: ctx?.note,
+                // A scammer profile is built entirely from identifying details, and
+                // `encryptPiiFields` never descends into arrays.
+                piiFields: SCAMMER_HISTORY_PII_FIELDS,
+            });
+            const data = prepareForFirestore(withEntry ?? { ...input, updatedAt: new Date() });
             await this.getCollection().doc(id).update(data);
         }
         catch (error) {

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

@@ -24,6 +24,7 @@
  *  - If matches found → suggest linking to existing profile (new incident) instead of new profile
  *  - SCAMMER_MATCH_FIELDS lists the Firestore array-contains fields used for this query
  */
+import type { StatusChangeEntry } from "../../../_internal/shared/history/types";
 import type { ScamType } from "../constants/scam-types";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 export declare const ScammerStatusValues: {
@@ -159,6 +160,16 @@ export interface ScammerDocument extends BaseDocument {
      * Reset to false when all contests are reviewed.
      */
     isContested?: boolean;
+    /**
+     * Who changed what, when, and why. See § "Status History" in CLAUDE.md.
+     *
+     * A scammer profile is a public accusation against a named person, so "who
+     * verified this and on what note" is the record that matters most on it.
+     * `verifiedBy`/`verifiedAt` only ever hold the LAST decision — a profile
+     * verified, then removed, then re-verified keeps no trace of the middle.
+     */
+    statusHistory?: StatusChangeEntry[];
+    statusHistoryTruncated?: number;
 }
 /**
  * One victim's report linked to an existing scammer profile.
@@ -358,3 +369,16 @@ export declare const SCAMMER_FIELDS: {
 export declare const SCAM_PLATFORM_LABELS: Record<ScamPlatform, string>;
 export declare const SOCIAL_PLATFORM_LABELS: Record<SocialPlatform, string>;
 export declare const SCAMMER_STATUS_LABELS: Record<ScammerStatus, string>;
+/**
+ * The fields whose changes earn a timeline entry.
+ *
+ * `verificationNote` is included because it is the REASON attached to a
+ * decision, and it is overwritten by the next one.
+ */
+export declare const SCAMMER_TRACKED_FIELDS: readonly ["status", "verifiedBy", "verifiedAt", "verificationNote", "isPubliclyVisible"];
+/**
+ * PII on this document, for `withHistory`'s scrub. A scammer profile is built
+ * ENTIRELY out of identifying details, so this list is long on purpose —
+ * `encryptPiiFields` never descends into arrays, and history is an array.
+ */
+export declare const SCAMMER_HISTORY_PII_FIELDS: readonly ["name", "displayName", "email", "phone", "phoneNumber", "upiId", "bankAccount", "accountNumber", "reporterEmail", "reporterName"];

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

@@ -231,3 +231,33 @@ export const SCAMMER_STATUS_LABELS = {
     rejected: "Rejected",
     removed: "Removed",
 };
+/**
+ * The fields whose changes earn a timeline entry.
+ *
+ * `verificationNote` is included because it is the REASON attached to a
+ * decision, and it is overwritten by the next one.
+ */
+export const SCAMMER_TRACKED_FIELDS = [
+    "status",
+    "verifiedBy",
+    "verifiedAt",
+    "verificationNote",
+    "isPubliclyVisible",
+];
+/**
+ * PII on this document, for `withHistory`'s scrub. A scammer profile is built
+ * ENTIRELY out of identifying details, so this list is long on purpose —
+ * `encryptPiiFields` never descends into arrays, and history is an array.
+ */
+export const SCAMMER_HISTORY_PII_FIELDS = [
+    "name",
+    "displayName",
+    "email",
+    "phone",
+    "phoneNumber",
+    "upiId",
+    "bankAccount",
+    "accountNumber",
+    "reporterEmail",
+    "reporterName",
+];