@mohasinac/appkit 4.22.0 → 4.24.0

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;

package/dist/features/email/index.d.ts

@@ -5,5 +5,5 @@
  * `renderToStaticMarkup`. They emit table-based, inline-styled markup that
  * email clients render correctly.
  */
-export { EmailButton, EmailColumn, EmailContainer, EmailDivider, EmailDoc, EmailFooter, EmailHeader, EmailImage, EmailLink, EmailRow, } from "./primitives";
+export { EmailBold, EmailButton, EmailColumn, EmailContainer, EmailDivider, EmailDoc, EmailFooter, EmailHeader, EmailImage, EmailLink, EmailRow, } from "./primitives";
 export type { EmailButtonProps, EmailColumnProps, EmailContainerProps, EmailDividerProps, EmailDocProps, EmailFooterProps, EmailHeaderProps, EmailImageProps, EmailLinkProps, EmailRowProps, EmailTone, } from "./primitives";

package/dist/features/email/index.js

@@ -5,4 +5,8 @@
  * `renderToStaticMarkup`. They emit table-based, inline-styled markup that
  * email clients render correctly.
  */
-export { EmailButton, EmailColumn, EmailContainer, EmailDivider, EmailDoc, EmailFooter, EmailHeader, EmailImage, EmailLink, EmailRow, } from "./primitives";
+export { 
+// Was MISSING from this barrel, so both consumers reached past it into
+// ./primitives directly — a workaround that reads as intentional and
+// quietly says "the barrel is not the public surface after all".
+EmailBold, EmailButton, EmailColumn, EmailContainer, EmailDivider, EmailDoc, EmailFooter, EmailHeader, EmailImage, EmailLink, EmailRow, } from "./primitives";

package/dist/features/email/notification-templates.d.ts

@@ -0,0 +1,35 @@
+import "server-only";
+import type { NotificationType } from "../admin/schemas/firestore";
+export interface NotificationEmailContext {
+    title: string;
+    message: string;
+    siteName: string;
+    /** Absolute URL the CTA opens. Absent → the email renders without a button. */
+    actionUrl?: string;
+}
+export interface NotificationTemplateDef {
+    /** CTA label. Absent → no button, for a type with nowhere to go. */
+    cta?: string;
+    /**
+     * One line of framing above the message, so the reader knows what KIND of
+     * mail this is before reading it. Deliberately not the message itself —
+     * duplicating it is worse than omitting it.
+     */
+    lead: string;
+    /** Terminal-negative types render in the danger tone. */
+    tone?: "default" | "danger" | "success";
+}
+/**
+ * 🛑 Every notification type, no exceptions.
+ *
+ * When adding a type, the compiler will ask for an entry here. Answer three
+ * questions: what does the reader need to know before the message (`lead`),
+ * where are they going (`cta`, or none if nowhere), and is this good news.
+ */
+export declare const NOTIFICATION_EMAIL_TEMPLATES: Record<NotificationType, NotificationTemplateDef>;
+/**
+ * Render one notification as an email.
+ *
+ * Returns the full HTML document, ready for `emailHtml`.
+ */
+export declare function renderNotificationEmail(type: NotificationType, ctx: NotificationEmailContext): string;

package/dist/features/email/notification-templates.js

@@ -0,0 +1,96 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import "server-only";
+import { EmailBold, EmailButton, EmailContainer, EmailDivider, EmailDoc, EmailFooter, EmailHeader, EmailRow, } from "./primitives";
+/**
+ * A real email per notification type.
+ *
+ * ## What this replaces
+ *
+ * `emailHtml` has existed on `SendNotificationInput` since the channel was
+ * built, and **0 of 40** call sites passed it — so every one of the 28
+ * notification types fell through to `html: \`<p>${message}</p>\``. A bare
+ * paragraph, no subject context, no branding, nothing to click. That is the
+ * reported "emails are sent but I can't understand what is being sent".
+ *
+ * ## Why a Record, not a lookup with a fallback
+ *
+ * `Record<NotificationType, TemplateDef>` — a new notification type cannot
+ * compile without an email. A `Partial` with a default would have let the
+ * next type silently go back to `<p>{message}</p>`, which is how the feature
+ * got here in the first place.
+ *
+ * ## The two structural constraints
+ *
+ * 1. **`renderToStaticMarkup` must be a lazy `require`.** A top-level
+ *    `import` from "react-dom/server" is flagged by Next's static tracer as
+ *    soon as any module in the re-export chain is reachable from a Server
+ *    Component — and this one is, via `@mohasinac/appkit/server`. `require()`
+ *    is opaque to that analyser, so the chain stops here. Same reason
+ *    `features/contact/email.tsx` does it.
+ * 2. **Never a raw `<table>`.** The `Email*` primitives emit the table-based,
+ *    inline-styled markup email clients actually render; hand-rolled markup
+ *    is what `audit-email-raw-html` blocks.
+ */
+// See constraint (1) above — this MUST stay a lazy require.
+function renderToStaticMarkup(el) {
+    const m = require("react-dom/server");
+    return m.renderToStaticMarkup(el);
+}
+/**
+ * 🛑 Every notification type, no exceptions.
+ *
+ * When adding a type, the compiler will ask for an entry here. Answer three
+ * questions: what does the reader need to know before the message (`lead`),
+ * where are they going (`cta`, or none if nowhere), and is this good news.
+ */
+export const NOTIFICATION_EMAIL_TEMPLATES = {
+    order_placed: { lead: "We've received your order.", cta: "View order", tone: "success" },
+    order_confirmed: { lead: "Your order is confirmed and being prepared.", cta: "View order", tone: "success" },
+    order_shipped: { lead: "Your order is on its way.", cta: "Track order", tone: "success" },
+    order_delivered: { lead: "Your order has been delivered.", cta: "View order", tone: "success" },
+    order_cancelled: { lead: "Your order has been cancelled.", cta: "View order", tone: "danger" },
+    refund_initiated: { lead: "A refund is on its way back to you.", cta: "View order" },
+    payment_review: { lead: "There's an update on your payment.", cta: "View payment" },
+    emi_installment_due_soon: { lead: "An EMI installment is due soon.", cta: "View order" },
+    emi_installment_overdue: { lead: "An EMI installment is overdue.", cta: "View order", tone: "danger" },
+    bid_placed: { lead: "Your bid has been placed.", cta: "View bids" },
+    bid_outbid: { lead: "Someone has outbid you.", cta: "View bids", tone: "danger" },
+    bid_won: { lead: "You won the auction.", cta: "Complete checkout", tone: "success" },
+    bid_lost: { lead: "This auction closed without you.", cta: "View bids" },
+    auction_ended: { lead: "Your auction has ended.", cta: "View auction" },
+    offer_received: { lead: "A buyer has made you an offer.", cta: "Review offer" },
+    offer_responded: { lead: "The seller has responded to your offer.", cta: "View offer" },
+    offer_counter_accepted: { lead: "Your counter-offer was accepted.", cta: "Complete checkout", tone: "success" },
+    offer_expired: { lead: "An offer has expired.", cta: "View offers" },
+    prize_won: { lead: "You've won a prize.", cta: "View prize", tone: "success" },
+    prize_reveal_expired: { lead: "A prize reveal window has closed.", cta: "View prize draws" },
+    review_approved: { lead: "A review has been published.", cta: "Read review" },
+    review_replied: { lead: "Someone replied to your review.", cta: "Read reply" },
+    product_available: { lead: "Something you were watching is back in stock.", cta: "View listing" },
+    catalogue_images_stale: { lead: "Your catalogue photos need refreshing.", cta: "Update photos" },
+    welcome: { lead: "Welcome aboard.", cta: "Go to your account", tone: "success" },
+    account_action: { lead: "There's been a change to your account.", cta: "View account" },
+    // No CTA: a promotion's destination is whatever the copy names, and a
+    // generic "View" button on a marketing mail is worse than none.
+    promotion: { lead: "An offer you might like." },
+    // No CTA for the same reason — a system announcement has no record behind
+    // it, and `resolveNotificationActionUrl` correctly returns undefined.
+    system: { lead: "A message from the team." },
+};
+/**
+ * Render one notification as an email.
+ *
+ * Returns the full HTML document, ready for `emailHtml`.
+ */
+export function renderNotificationEmail(type, ctx) {
+    const def = NOTIFICATION_EMAIL_TEMPLATES[type];
+    /*
+     * `EmailButton` takes a narrower tone set than `EmailTone` — brand / accent
+     * / neutral only, because a button is a call to action and there is no
+     * useful "danger" button. So the template's tone drives the BUTTON's
+     * emphasis, not its colour: bad news gets the neutral button ("View order"
+     * on a cancellation should not shout), good news gets the brand one.
+     */
+    const buttonTone = def.tone === "danger" ? "neutral" : "brand";
+    return `<!DOCTYPE html>${renderToStaticMarkup(_jsx(EmailDoc, { title: ctx.title, children: _jsxs(EmailContainer, { children: [_jsx(EmailHeader, { brandName: ctx.siteName }), _jsxs(EmailRow, { children: [_jsx(EmailBold, { children: ctx.title }), _jsx("br", {}), _jsx("br", {}), def.lead] }), _jsx(EmailDivider, {}), _jsx(EmailRow, { children: ctx.message }), def.cta && ctx.actionUrl ? (_jsx(EmailRow, { children: _jsx(EmailButton, { href: ctx.actionUrl, tone: buttonTone, children: def.cta }) })) : null, _jsx(EmailFooter, { copyright: `© ${ctx.siteName}` })] }) }))}`;
+}

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

@@ -21,7 +21,7 @@ export declare const conversationMessageSchema: z.ZodObject<{
     body: string;
     isRead: boolean;
     senderId: string;
-    senderRole: "seller" | "buyer";
+    senderRole: "buyer" | "seller";
     sentAt: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
@@ -31,7 +31,7 @@ export declare const conversationMessageSchema: z.ZodObject<{
     body: string;
     isRead: boolean;
     senderId: string;
-    senderRole: "seller" | "buyer";
+    senderRole: "buyer" | "seller";
     sentAt: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
@@ -79,7 +79,7 @@ export declare const conversationFirestoreSchema: z.ZodObject<{
         body: string;
         isRead: boolean;
         senderId: string;
-        senderRole: "seller" | "buyer";
+        senderRole: "buyer" | "seller";
         sentAt: string | Date | z.objectOutputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -89,7 +89,7 @@ export declare const conversationFirestoreSchema: z.ZodObject<{
         body: string;
         isRead: boolean;
         senderId: string;
-        senderRole: "seller" | "buyer";
+        senderRole: "buyer" | "seller";
         sentAt: string | Date | z.objectInputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -127,7 +127,7 @@ export declare const conversationFirestoreSchema: z.ZodObject<{
         body: string;
         isRead: boolean;
         senderId: string;
-        senderRole: "seller" | "buyer";
+        senderRole: "buyer" | "seller";
         sentAt: string | Date | z.objectOutputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -160,7 +160,7 @@ export declare const conversationFirestoreSchema: z.ZodObject<{
         body: string;
         isRead: boolean;
         senderId: string;
-        senderRole: "seller" | "buyer";
+        senderRole: "buyer" | "seller";
         sentAt: string | Date | z.objectInputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;

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

@@ -128,9 +128,9 @@ export declare const orderRefundEventSchema: z.ZodObject<{
     overrideReason: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type: "full" | "partial";
+    reason: string;
     amount: number;
     refundId: string;
-    reason: string;
     refundedAt: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
@@ -143,9 +143,9 @@ export declare const orderRefundEventSchema: z.ZodObject<{
     overrideReason?: string | undefined;
 }, {
     type: "full" | "partial";
+    reason: string;
     amount: number;
     refundId: string;
-    reason: string;
     refundedAt: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
@@ -168,14 +168,14 @@ export declare const appliedOrderDiscountSchema: z.ZodObject<{
     code: string;
     type: "auto" | "coupon" | "deal";
     discountAmount: number;
-    scope?: "admin" | "seller" | undefined;
+    scope?: "seller" | "admin" | undefined;
     storeId?: string | undefined;
     couponId?: string | undefined;
 }, {
     code: string;
     type: "auto" | "coupon" | "deal";
     discountAmount: number;
-    scope?: "admin" | "seller" | undefined;
+    scope?: "seller" | "admin" | undefined;
     storeId?: string | undefined;
     couponId?: string | undefined;
 }>;
@@ -326,14 +326,14 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         code: string;
         type: "auto" | "coupon" | "deal";
         discountAmount: number;
-        scope?: "admin" | "seller" | undefined;
+        scope?: "seller" | "admin" | undefined;
         storeId?: string | undefined;
         couponId?: string | undefined;
     }, {
         code: string;
         type: "auto" | "coupon" | "deal";
         discountAmount: number;
-        scope?: "admin" | "seller" | undefined;
+        scope?: "seller" | "admin" | undefined;
         storeId?: string | undefined;
         couponId?: string | undefined;
     }>, "many">>;
@@ -464,9 +464,9 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         overrideReason: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         type: "full" | "partial";
+        reason: string;
         amount: number;
         refundId: string;
-        reason: string;
         refundedAt: string | Date | z.objectOutputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -479,9 +479,9 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         overrideReason?: string | undefined;
     }, {
         type: "full" | "partial";
+        reason: string;
         amount: number;
         refundId: string;
-        reason: string;
         refundedAt: string | Date | z.objectInputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -612,6 +612,7 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         shelf: string;
         bin: string;
     } | undefined;
+    offerId?: string | undefined;
     orderType?: string | undefined;
     imageUrls?: string[] | undefined;
     refundFeeDeducted?: number | undefined;
@@ -622,7 +623,7 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         code: string;
         type: "auto" | "coupon" | "deal";
         discountAmount: number;
-        scope?: "admin" | "seller" | undefined;
+        scope?: "seller" | "admin" | undefined;
         storeId?: string | undefined;
         couponId?: string | undefined;
     }[] | undefined;
@@ -649,14 +650,13 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     }[] | undefined;
     emiRemainingBalance?: number | undefined;
     emiComplete?: boolean | undefined;
-    offerId?: string | undefined;
     isNonRefundable?: boolean | undefined;
     paymentBatchId?: string | undefined;
     refunds?: {
         type: "full" | "partial";
+        reason: string;
         amount: number;
         refundId: string;
-        reason: string;
         refundedAt: string | Date | z.objectOutputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;
@@ -760,6 +760,7 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         shelf: string;
         bin: string;
     } | undefined;
+    offerId?: string | undefined;
     orderType?: string | undefined;
     imageUrls?: string[] | undefined;
     refundFeeDeducted?: number | undefined;
@@ -770,7 +771,7 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         code: string;
         type: "auto" | "coupon" | "deal";
         discountAmount: number;
-        scope?: "admin" | "seller" | undefined;
+        scope?: "seller" | "admin" | undefined;
         storeId?: string | undefined;
         couponId?: string | undefined;
     }[] | undefined;
@@ -797,14 +798,13 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     }[] | undefined;
     emiRemainingBalance?: number | undefined;
     emiComplete?: boolean | undefined;
-    offerId?: string | undefined;
     isNonRefundable?: boolean | undefined;
     paymentBatchId?: string | undefined;
     refunds?: {
         type: "full" | "partial";
+        reason: string;
         amount: number;
         refundId: string;
-        reason: string;
         refundedAt: string | Date | z.objectInputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough">;

package/dist/features/payments/repository/payout.repository.d.ts

@@ -7,6 +7,14 @@
 import { BaseRepository, parseSieveDateValue, type SieveModel, type FirebaseSieveResult } from "../../../providers/db-firebase";
 import type { DocumentReference, WriteResult } from "firebase-admin/firestore";
 import type { PayoutDocument, PayoutCreateInput, PayoutRefundDeduction, PayoutStatus, PayoutUpdateInput } from "../schemas";
+import { type HistoryActor } from "../../../_internal/shared/history/index";
+/** Who/why for a payout write that lands in `statusHistory`. */
+export interface PayoutWriteContext {
+    actor?: HistoryActor;
+    trigger?: string;
+    reason?: string;
+    note?: string;
+}
 export declare class PayoutRepository extends BaseRepository<PayoutDocument> {
     constructor();
     /** Decrypt PII fields on a payout document after Firestore read */
@@ -46,12 +54,17 @@ export declare class PayoutRepository extends BaseRepository<PayoutDocument> {
         data: PayoutDocument;
     }>>;
     /**
-     * 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).
      */
-    updateStatus(payoutId: string, status: PayoutStatus, extra?: PayoutUpdateInput): Promise<PayoutDocument>;
-    markProcessing(ref: DocumentReference): Promise<WriteResult>;
-    recordSuccess(ref: DocumentReference, razorpayPayoutId: string, razorpayStatus: string): Promise<WriteResult>;
-    recordFailure(ref: DocumentReference, failureCount: number, reason: string, isFinal: boolean): Promise<WriteResult>;
+    updateStatus(payoutId: string, status: PayoutStatus, extra?: PayoutUpdateInput, ctx?: PayoutWriteContext, prior?: PayoutDocument | null): Promise<PayoutDocument>;
+    markProcessing(ref: DocumentReference, ctx?: PayoutWriteContext, prior?: PayoutDocument | null): Promise<WriteResult>;
+    recordSuccess(ref: DocumentReference, razorpayPayoutId: string, razorpayStatus: string, ctx?: PayoutWriteContext, prior?: PayoutDocument | null): Promise<WriteResult>;
+    recordFailure(ref: DocumentReference, failureCount: number, reason: string, isFinal: boolean, ctx?: PayoutWriteContext, prior?: PayoutDocument | null): Promise<WriteResult>;
+    /** Append a timeline entry when the patch touches a tracked field. */
+    private withPayoutHistory;
     /**
      * Get all order IDs that have already been paid out for a seller.
      * Used to avoid double-paying the same orders.

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.