@mohasinac/appkit 4.13.0 → 4.14.0

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

@@ -2,8 +2,27 @@ import type { DocumentReference, WriteBatch } from "firebase-admin/firestore";
 import type { FirebaseSieveResult, SieveModel } from "../../../providers/db-firebase";
 import { BaseRepository, parseSieveDateValue } from "../../../providers/db-firebase";
 import { type OrderCreateInput, type OrderDocument, type OrderRefundEvent } from "../schemas";
+import { type HistoryActor, type FieldChange } from "../../../_internal/shared/history/index";
 import type { OrderStatus, PaymentStatus } from "../types";
 import { type PaymentReviewQueueMode } from "../constants/payment-window";
+/**
+ * Who/why for a write that lands in `statusHistory`.
+ *
+ * Optional everywhere so existing callers keep compiling and record
+ * `system`; pass it wherever the acting user is known.
+ */
+export interface OrderWriteContext {
+    actor?: HistoryActor;
+    /** Overrides the default trigger label with the calling function's name. */
+    trigger?: string;
+    reason?: string;
+    note?: string;
+    /**
+     * Changes the field diff cannot express — used by `postRefundEvent` to put
+     * the refund itself on the timeline rather than an array-length delta.
+     */
+    extraChanges?: Record<string, FieldChange>;
+}
 declare class OrderRepository extends BaseRepository<OrderDocument> {
     constructor();
     private decryptOrder;
@@ -15,10 +34,23 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
     findByStatus(status: OrderStatus): Promise<OrderDocument[]>;
     findConfirmed(): Promise<OrderDocument[]>;
     findPending(): Promise<OrderDocument[]>;
-    updateStatus(orderId: string, status: OrderStatus, additionalData?: Partial<OrderDocument>): Promise<OrderDocument>;
+    /**
+     * Every write primitive below routes through this so `statusHistory` is
+     * appended at the SEVEN places a tracked field can change, rather than at
+     * the ~32 call sites above them. That is what makes order history a
+     * contained change instead of a codebase-wide sweep — and it follows the
+     * precedent `postRefundEvent` already set for append-only order data.
+     *
+     * `ctx` is optional throughout: a caller that has not been updated yet
+     * records `system` rather than failing, so this rolls out incrementally.
+     * The actor is worth passing wherever it is known — a history entry that
+     * cannot say who cancelled an order is a much weaker record.
+     */
+    private updateWithHistory;
+    updateStatus(orderId: string, status: OrderStatus, additionalData?: Partial<OrderDocument>, ctx?: OrderWriteContext): Promise<OrderDocument>;
     assignWorker(orderId: string, workerId: string): Promise<OrderDocument>;
     unassignWorker(orderId: string): Promise<OrderDocument>;
-    markPicked(orderId: string): Promise<OrderDocument>;
+    markPicked(orderId: string, ctx?: OrderWriteContext): Promise<OrderDocument>;
     markPacked(orderId: string): Promise<OrderDocument>;
     /**
      * Payment Detail Parity (Feature C) — the COD counterpart to the manual
@@ -27,10 +59,10 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
      * verify against, so `verifiedBy` is the acting user's uid and
      * `verificationMethod` is always "cod_collection".
      */
-    markCodCollected(orderId: string, verifiedBy: string, note?: string): Promise<OrderDocument>;
+    markCodCollected(orderId: string, verifiedBy: string, note?: string, ctx?: OrderWriteContext): Promise<OrderDocument>;
     findFulfillmentQueue(storeId: string): Promise<OrderDocument[]>;
-    updatePaymentStatus(orderId: string, paymentStatus: PaymentStatus, paymentId?: string): Promise<OrderDocument>;
-    cancelOrder(orderId: string, reason: string, refundAmount?: number): Promise<OrderDocument>;
+    updatePaymentStatus(orderId: string, paymentStatus: PaymentStatus, paymentId?: string, ctx?: OrderWriteContext): Promise<OrderDocument>;
+    cancelOrder(orderId: string, reason: string, refundAmount?: number, ctx?: OrderWriteContext): Promise<OrderDocument>;
     findRecentByUser(userId: string): Promise<OrderDocument[]>;
     hasUserPurchased(userId: string, productId: string): Promise<boolean>;
     /**
@@ -217,7 +249,7 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
      * Append one refund event to the order and mark it non-contestable.
      * If `becomeRefunded` is true, also transitions the order status to "refunded".
      */
-    postRefundEvent(orderId: string, event: OrderRefundEvent, becomeRefunded?: boolean): Promise<OrderDocument>;
+    postRefundEvent(orderId: string, event: OrderRefundEvent, becomeRefunded?: boolean, ctx?: OrderWriteContext): Promise<OrderDocument>;
     /** Fetch all orders sharing a paymentBatchId (for sibling-orders display). */
     findByPaymentBatchId(batchId: string): Promise<OrderDocument[]>;
     /**
@@ -327,8 +359,23 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
     markPayoutRequested(batch: WriteBatch, ref: DocumentReference, payoutId: string): void;
     /**
      * Cloud Functions: stage a cancellation update into a caller-owned WriteBatch.
+     *
+     * `fromStatus` is supplied by the caller because a batch write does no read
+     * — but the sweep that calls this already filtered on a status, so it knows
+     * the value. Passing it beats recording `null` for something that is
+     * genuinely known one stack frame up.
+     */
+    cancelInBatch(batch: WriteBatch, ref: DocumentReference, fromStatus?: OrderStatus | null): void;
+    /**
+     * History append for the two WriteBatch paths, which cannot read-then-diff.
+     *
+     * Uses `arrayUnion` so the entry lands without a prior read. The FIFO cap
+     * therefore is NOT applied here — it is enforced on the next ordinary
+     * write. That is an acceptable trade: both batch paths are terminal
+     * transitions (cancelled, payout-requested) that fire at most once per
+     * order, so they cannot be what overflows the array.
      */
-    cancelInBatch(batch: WriteBatch, ref: DocumentReference): void;
+    private batchHistoryPatch;
 }
 declare const orderRepository: OrderRepository;
 export { OrderRepository, orderRepository };

package/dist/features/orders/repository/orders.repository.js

@@ -2,8 +2,9 @@ import { normalizeError } from "../../../errors/normalize";
 import { DatabaseError, NotFoundError } from "../../../errors";
 import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase";
 import { decryptPiiFields, encryptPiiFields, ORDER_PII_FIELDS, } from "../../../security";
-import { serverTimestamp } from "../../../contracts/field-ops";
-import { createOrderId, ORDER_COLLECTION, OrderStatusValues, } from "../schemas";
+import { serverTimestamp, arrayUnion } from "../../../contracts/field-ops";
+import { createOrderId, ORDER_COLLECTION, ORDER_TRACKED_FIELDS, OrderStatusValues, } from "../schemas";
+import { withHistory } from "../../../_internal/shared/history/index";
 import { MANUAL_PAYMENT_METHODS, PAYMENT_REVIEW_QUEUE_SCAN_LIMIT, } from "../constants/payment-window";
 import { ORDER_FIELDS } from "../../../constants/field-names";
 /**
@@ -65,12 +66,44 @@ class OrderRepository extends BaseRepository {
     async findPending() {
         return this.findBy(ORDER_FIELDS.STATUS, "pending");
     }
-    async updateStatus(orderId, status, additionalData) {
-        return this.update(orderId, {
-            status,
-            ...additionalData,
-            updatedAt: new Date(),
+    /**
+     * Every write primitive below routes through this so `statusHistory` is
+     * appended at the SEVEN places a tracked field can change, rather than at
+     * the ~32 call sites above them. That is what makes order history a
+     * contained change instead of a codebase-wide sweep — and it follows the
+     * precedent `postRefundEvent` already set for append-only order data.
+     *
+     * `ctx` is optional throughout: a caller that has not been updated yet
+     * records `system` rather than failing, so this rolls out incrementally.
+     * The actor is worth passing wherever it is known — a history entry that
+     * cannot say who cancelled an order is a much weaker record.
+     */
+    async updateWithHistory(orderId, patch, ctx, defaultTrigger, 
+    /**
+     * The already-fetched document, when the caller has one. Three of the six
+     * write primitives (`markPicked`, `markCodCollected`, `postRefundEvent`)
+     * read the order before patching it — passing it through avoids a second
+     * read of the same document on every one of those writes, which matters
+     * against the Firestore daily read budget (Rule #6).
+     */
+    known) {
+        const current = known !== undefined ? known : await this.findById(orderId);
+        const withEntry = withHistory(current, patch, {
+            tracked: ORDER_TRACKED_FIELDS,
+            actor: ctx?.actor ?? { role: "system" },
+            trigger: ctx?.trigger ?? defaultTrigger,
+            reason: ctx?.reason,
+            note: ctx?.note,
+            extraChanges: ctx?.extraChanges,
+            historyField: "statusHistory",
+            truncatedField: "statusHistoryTruncated",
         });
+        // `null` means no tracked field actually changed — write the patch as-is
+        // so an untracked update never grows the array.
+        return this.update(orderId, (withEntry ?? patch));
+    }
+    async updateStatus(orderId, status, additionalData, ctx) {
+        return this.updateWithHistory(orderId, { status, ...additionalData, updatedAt: new Date() }, ctx, "orderRepository.updateStatus");
     }
     async assignWorker(orderId, workerId) {
         return this.update(orderId, { assignedWorkerId: workerId, updatedAt: new Date() });
@@ -78,12 +111,12 @@ class OrderRepository extends BaseRepository {
     async unassignWorker(orderId) {
         return this.update(orderId, { assignedWorkerId: undefined, updatedAt: new Date() });
     }
-    async markPicked(orderId) {
+    async markPicked(orderId, ctx) {
         const order = await this.findById(orderId);
         if (!order)
             throw new NotFoundError(`Order ${orderId} not found`);
         const nextStatus = order.status === "confirmed" ? "processing" : order.status;
-        return this.update(orderId, { pickedAt: new Date(), status: nextStatus, updatedAt: new Date() });
+        return this.updateWithHistory(orderId, { pickedAt: new Date(), status: nextStatus, updatedAt: new Date() }, ctx, "orderRepository.markPicked", order);
     }
     async markPacked(orderId) {
         return this.update(orderId, { packedAt: new Date(), updatedAt: new Date() });
@@ -95,11 +128,11 @@ class OrderRepository extends BaseRepository {
      * verify against, so `verifiedBy` is the acting user's uid and
      * `verificationMethod` is always "cod_collection".
      */
-    async markCodCollected(orderId, verifiedBy, note) {
+    async markCodCollected(orderId, verifiedBy, note, ctx) {
         const order = await this.findById(orderId);
         if (!order)
             throw new NotFoundError(`Order ${orderId} not found`);
-        return this.update(orderId, {
+        return this.updateWithHistory(orderId, {
             paymentStatus: "paid",
             paymentRecord: {
                 method: "cod",
@@ -110,7 +143,10 @@ class OrderRepository extends BaseRepository {
                 verificationMethod: "cod_collection",
             },
             updatedAt: new Date(),
-        });
+        }, 
+        // `verifiedBy` is the acting user — use it unless the caller supplied a
+        // richer actor. Cash collection is always a person, never the system.
+        ctx ?? { actor: { uid: verifiedBy, role: "seller" }, note }, "orderRepository.markCodCollected", order);
     }
     async findFulfillmentQueue(storeId) {
         const snap = await this.db
@@ -122,21 +158,25 @@ class OrderRepository extends BaseRepository {
             .get();
         return snap.docs.map((doc) => this.decryptOrder({ id: doc.id, ...doc.data() }));
     }
-    async updatePaymentStatus(orderId, paymentStatus, paymentId) {
-        return this.update(orderId, {
+    async updatePaymentStatus(orderId, paymentStatus, paymentId, ctx) {
+        return this.updateWithHistory(orderId, {
             paymentStatus,
             ...(paymentId ? { paymentId } : {}),
             updatedAt: new Date(),
-        });
+        }, ctx, "orderRepository.updatePaymentStatus");
     }
-    async cancelOrder(orderId, reason, refundAmount) {
-        return this.update(orderId, {
+    async cancelOrder(orderId, reason, refundAmount, ctx) {
+        return this.updateWithHistory(orderId, {
             status: "cancelled",
             cancellationDate: new Date(),
             cancellationReason: reason,
             ...(refundAmount ? { refundAmount, refundStatus: "pending" } : {}),
             updatedAt: new Date(),
-        });
+        }, 
+        // The cancellation reason is already a first-class argument here — carry
+        // it into the history entry so the timeline can say WHY, not just that
+        // it was cancelled.
+        { ...ctx, reason: ctx?.reason ?? reason }, "orderRepository.cancelOrder");
     }
     async findRecentByUser(userId) {
         const now = new Date();
@@ -251,17 +291,38 @@ class OrderRepository extends BaseRepository {
      * Append one refund event to the order and mark it non-contestable.
      * If `becomeRefunded` is true, also transitions the order status to "refunded".
      */
-    async postRefundEvent(orderId, event, becomeRefunded = false) {
+    async postRefundEvent(orderId, event, becomeRefunded = false, ctx) {
         const order = await this.findById(orderId);
         if (!order)
             throw new NotFoundError(`Order ${orderId} not found`);
         const existing = order.refunds ?? [];
-        return this.update(orderId, {
+        return this.updateWithHistory(orderId, {
             refunds: [...existing, event],
             contestable: false,
             ...(becomeRefunded ? { status: "refunded" } : {}),
             updatedAt: new Date(),
-        });
+        }, {
+            ...ctx,
+            // The refund is contributed explicitly rather than diffed. A raw diff
+            // of `refunds[]` would say "an array of 1 became an array of 2" —
+            // true, and useless on a timeline. PARTIAL refunds matter as much as
+            // full ones here: a partial changes no tracked field at all, so
+            // without this it would leave no trace despite being exactly the kind
+            // of event a buyer later asks about.
+            extraChanges: {
+                refund: {
+                    from: null,
+                    to: {
+                        refundId: event.refundId,
+                        type: event.type,
+                        amount: event.amount,
+                        reason: event.reason,
+                    },
+                },
+            },
+            actor: ctx?.actor ?? { uid: event.refundedBy, role: "admin" },
+            reason: ctx?.reason ?? event.reason,
+        }, "orderRepository.postRefundEvent", order);
     }
     /** Fetch all orders sharing a paymentBatchId (for sibling-orders display). */
     async findByPaymentBatchId(batchId) {
@@ -469,19 +530,52 @@ class OrderRepository extends BaseRepository {
             payoutStatus: "requested",
             payoutId,
             updatedAt: serverTimestamp(),
+            ...this.batchHistoryPatch({
+                changes: { payoutStatus: { from: "eligible", to: "requested" } },
+                trigger: "orderRepository.markPayoutRequested",
+            }),
         });
     }
     /**
      * Cloud Functions: stage a cancellation update into a caller-owned WriteBatch.
+     *
+     * `fromStatus` is supplied by the caller because a batch write does no read
+     * — but the sweep that calls this already filtered on a status, so it knows
+     * the value. Passing it beats recording `null` for something that is
+     * genuinely known one stack frame up.
      */
-    cancelInBatch(batch, ref) {
+    cancelInBatch(batch, ref, fromStatus = null) {
         batch.update(ref, {
             status: OrderStatusValues.CANCELLED,
             cancellationDate: new Date(),
             cancellationReason: "payment_timeout",
             updatedAt: serverTimestamp(),
+            ...this.batchHistoryPatch({
+                changes: { status: { from: fromStatus, to: OrderStatusValues.CANCELLED } },
+                reason: "payment_timeout",
+                trigger: "orderRepository.cancelInBatch",
+            }),
         });
     }
+    /**
+     * History append for the two WriteBatch paths, which cannot read-then-diff.
+     *
+     * Uses `arrayUnion` so the entry lands without a prior read. The FIFO cap
+     * therefore is NOT applied here — it is enforced on the next ordinary
+     * write. That is an acceptable trade: both batch paths are terminal
+     * transitions (cancelled, payout-requested) that fire at most once per
+     * order, so they cannot be what overflows the array.
+     */
+    batchHistoryPatch(input) {
+        const entry = {
+            at: new Date(),
+            actorRole: "system",
+            changes: input.changes,
+            trigger: input.trigger,
+            ...(input.reason ? { reason: input.reason } : {}),
+        };
+        return { statusHistory: arrayUnion(entry) };
+    }
 }
 OrderRepository.SELLER_SIEVE_FIELDS = {
     id: { canFilter: true, canSort: false },

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

@@ -5,6 +5,59 @@ import type { OrderStatus, PaymentStatus } from "../types";
 import type { OrderType } from "../utils/order-splitter";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 import type { ListingType } from "../../products/types";
+import type { StatusChangeEntry } from "../../../_internal/shared/history/index";
+export interface OrderSourceStandard {
+    path: "standard";
+    listPrice: number;
+}
+export interface OrderSourceAuctionWon {
+    path: "auction-won";
+    auctionId: string;
+    bidId: string;
+    winningBidAmount: number;
+    /** Bids placed across the whole auction — the "against N bidders" figure. */
+    bidCount: number;
+    startingBid: number;
+    reservePrice?: number;
+    reserveMet: boolean;
+    auctionEndedAt: Date;
+    /** Second-highest bid, when there was one. */
+    runnerUpAmount?: number;
+}
+export interface OrderSourceAuctionBuyNow {
+    path: "auction-buy-now";
+    auctionId: string;
+    buyNowPrice: number;
+    listPrice: number;
+    boughtAt: Date;
+}
+export interface OrderSourceOfferAccepted {
+    path: "offer-accepted";
+    offerId: string;
+    offeredAmount: number;
+    /** The asking price at the moment the offer was made. */
+    listPriceAtOffer: number;
+    counterAmount?: number;
+    /** How many counter rounds before agreement. 0 = accepted outright. */
+    counterRounds: number;
+    acceptedBy: string;
+    acceptedAt: Date;
+    checkoutDeadline?: Date;
+}
+export interface OrderSourcePreOrder {
+    path: "pre-order";
+    depositAmount: number;
+    balanceDue: number;
+    expectedDeliveryDate?: Date;
+}
+export interface OrderSourcePrizeDraw {
+    path: "prize-draw";
+    prizeDrawProductId: string;
+    pricePerEntry: number;
+    entryCount: number;
+    revealMode: "instant" | "scheduled";
+}
+export type OrderSourceContext = OrderSourceStandard | OrderSourceAuctionWon | OrderSourceAuctionBuyNow | OrderSourceOfferAccepted | OrderSourcePreOrder | OrderSourcePrizeDraw;
 /** Manual shipping is the only supported method — sellers enter carrier + tracking directly, no carrier API integration. */
 export type ShippingMethod = "custom";
 export type RefundType = "full" | "partial";
@@ -150,6 +203,18 @@ export interface OrderDocument extends BaseDocument {
     storeName?: string;
     items?: OrderDocumentItem[];
     orderType?: OrderType;
+    /**
+     * True when this `orderType: "auction"` order came from Buy Now rather than
+     * from winning the bidding.
+     *
+     * Not a new `orderType` value on purpose — the /user/orders tabs key on
+     * `orderType`, and a buyout IS an auction order from the buyer's point of
+     * view. What it changes is the ADMIN review window: a buyout is settled in a
+     * one-hour scramble against a still-live auction, so `paymentReviewAutoApprove`
+     * gives an admin a full day to verify its proof instead of the usual couple of
+     * hours before auto-approving.
+     */
+    isBuyout?: boolean;
     imageUrls?: string[];
     quantity: number;
     unitPrice: number;
@@ -248,6 +313,37 @@ export interface OrderDocument extends BaseDocument {
      * orders are the source of truth for invoicing, refunds, and disputes.
      */
     paymentBatchId?: string;
+    /**
+     * Append-only delta log of every tracked-field change on this order —
+     * who, when, from what to what, and which function did it.
+     *
+     * DELTAS, never snapshots: only `statusHistory[0]` (the creation entry)
+     * carries a `snapshot`, holding the provenance that cannot be re-derived
+     * later because its sources move on — the discounts and add-ons actually
+     * applied and the fee breakdown at the moment of purchase.
+     *
+     * Capped at `STATUS_HISTORY_MAX` (FIFO). An unbounded array on a document
+     * this hot inflates every read of it (Rule #6).
+     */
+    statusHistory?: StatusChangeEntry[];
+    /**
+     * Entries dropped off the front of `statusHistory` over this order's
+     * lifetime. Present so the UI can say "earlier history trimmed" instead
+     * of implying the order simply had no earlier history.
+     */
+    statusHistoryTruncated?: number;
+    /**
+     * How the buyer acquired the right to buy, written ONCE at creation.
+     *
+     * A discriminated union rather than optional fields, because `orderType`
+     * cannot distinguish an auction that was WON from one that was BOUGHT OUT
+     * — both are `"auction"` — and `winningBidAmount`/`bidCount` are
+     * meaningless on a buy-now, where there are zero bids by definition.
+     *
+     * Never recomputed: a settled auction's numbers must not move when the
+     * auction document is later archived or the product is re-priced.
+     */
+    sourceContext?: OrderSourceContext;
     /**
      * Append-only log of refund events on this order. Multiple partial refund
      * events are allowed until the cumulative amount equals `totalPrice`.
@@ -384,6 +480,27 @@ export declare const ORDER_INDEXED_FIELDS: readonly ["userId", "productId", "sto
 export declare const DEFAULT_ORDER_DATA: Partial<OrderDocument>;
 export declare const ORDER_PUBLIC_FIELDS: readonly ["id", "productId", "productTitle", "quantity", "unitPrice", "totalPrice", "currency", "status", "paymentStatus", "shippingAddress", "trackingNumber", "notes", "orderDate", "shippingDate", "deliveryDate", "createdAt"];
 export declare const ORDER_UPDATABLE_FIELDS: readonly ["notes", "shippingAddress"];
+/**
+ * The fields whose changes are recorded in `statusHistory`.
+ *
+ * Deliberately minimal — the timeline answers "where is my order and what
+ * happened to it", nothing else.
+ *
+ * **Money is NOT tracked here.** `appliedDiscounts`, `storeAddons` and the
+ * fee fields hold the FINAL state on the order document, and that is the
+ * record. Logging every intermediate coupon/add-on change would bury the five
+ * transitions anyone actually reads under pricing churn, and a coupon that
+ * was dropped before the order existed is not part of the order's history.
+ *
+ * **Acquisition is NOT tracked here either** — how the buyer got the right to
+ * buy (auction won, offer accepted, bought out) is written once to
+ * `sourceContext` at creation. It never changes, so it is not a timeline
+ * event.
+ *
+ * A whole-document diff would append an entry for every `updatedAt` bump —
+ * which is every single write — and exhaust the FIFO cap within days.
+ */
+export declare const ORDER_TRACKED_FIELDS: readonly ["status", "paymentStatus", "paymentReviewOutcome", "trackingNumber", "cancellationReason"];
 export type OrderCreateInput = Omit<OrderDocument, "id" | "createdAt" | "updatedAt" | "orderDate">;
 export type OrderUpdateInput = Partial<Pick<OrderDocument, (typeof ORDER_UPDATABLE_FIELDS)[number]>>;
 export type OrderAdminUpdateInput = Partial<Omit<OrderDocument, "id" | "createdAt">>;

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

@@ -88,6 +88,36 @@ export const ORDER_PUBLIC_FIELDS = [
     "createdAt",
 ];
 export const ORDER_UPDATABLE_FIELDS = ["notes", "shippingAddress"];
+/**
+ * The fields whose changes are recorded in `statusHistory`.
+ *
+ * Deliberately minimal — the timeline answers "where is my order and what
+ * happened to it", nothing else.
+ *
+ * **Money is NOT tracked here.** `appliedDiscounts`, `storeAddons` and the
+ * fee fields hold the FINAL state on the order document, and that is the
+ * record. Logging every intermediate coupon/add-on change would bury the five
+ * transitions anyone actually reads under pricing churn, and a coupon that
+ * was dropped before the order existed is not part of the order's history.
+ *
+ * **Acquisition is NOT tracked here either** — how the buyer got the right to
+ * buy (auction won, offer accepted, bought out) is written once to
+ * `sourceContext` at creation. It never changes, so it is not a timeline
+ * event.
+ *
+ * A whole-document diff would append an entry for every `updatedAt` bump —
+ * which is every single write — and exhaust the FIFO cap within days.
+ */
+export const ORDER_TRACKED_FIELDS = [
+    "status",
+    "paymentStatus",
+    /** Manual-payment review: proof verified, re-upload requested, rejected. */
+    "paymentReviewOutcome",
+    /** The substance of the "shipped" transition. */
+    "trackingNumber",
+    /** Why it was cancelled — a bare "cancelled" is not a useful entry. */
+    "cancellationReason",
+];
 export const orderQueryHelpers = {
     byUser: (userId) => ["userId", "==", userId],
     byStore: (storeId) => ["storeId", "==", storeId],

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

@@ -562,14 +562,7 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     platformFee?: number | undefined;
     paymentMethod?: string | undefined;
     notes?: string | undefined;
-    storeName?: string | undefined;
     prizeRevealMode?: "scheduled" | "instant" | undefined;
-    physicalLocation?: {
-        zone: string;
-        shelf: string;
-        bin: string;
-    } | undefined;
-    payoutStatus?: "paid" | "eligible" | "requested" | undefined;
     paymentId?: string | undefined;
     shippingAddress?: string | undefined;
     trackingNumber?: string | undefined;
@@ -588,6 +581,7 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     depositAmount?: number | undefined;
     codRemainingAmount?: number | undefined;
     shippingFee?: number | undefined;
+    payoutStatus?: "paid" | "eligible" | "requested" | undefined;
     payoutId?: string | undefined;
     shippingMethod?: "custom" | undefined;
     shippingCarrier?: string | undefined;
@@ -611,9 +605,13 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         }, z.ZodTypeAny, "passthrough">;
     } | undefined;
     prizeDrawProductId?: string | undefined;
+    storeName?: string | undefined;
     couponCode?: string | undefined;
-    emiEnabled?: boolean | undefined;
-    emiTenureMonths?: number | undefined;
+    physicalLocation?: {
+        zone: string;
+        shelf: string;
+        bin: string;
+    } | undefined;
     orderType?: string | undefined;
     imageUrls?: string[] | undefined;
     refundFeeDeducted?: number | undefined;
@@ -629,6 +627,8 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         couponId?: string | undefined;
     }[] | undefined;
     codHandlingFee?: number | undefined;
+    emiEnabled?: boolean | undefined;
+    emiTenureMonths?: number | undefined;
     emiTokenAmount?: number | undefined;
     emiSurchargeAmount?: number | undefined;
     emiInstallments?: {
@@ -710,14 +710,7 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     platformFee?: number | undefined;
     paymentMethod?: string | undefined;
     notes?: string | undefined;
-    storeName?: string | undefined;
     prizeRevealMode?: "scheduled" | "instant" | undefined;
-    physicalLocation?: {
-        zone: string;
-        shelf: string;
-        bin: string;
-    } | undefined;
-    payoutStatus?: "paid" | "eligible" | "requested" | undefined;
     paymentId?: string | undefined;
     shippingAddress?: string | undefined;
     trackingNumber?: string | undefined;
@@ -736,6 +729,7 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     depositAmount?: number | undefined;
     codRemainingAmount?: number | undefined;
     shippingFee?: number | undefined;
+    payoutStatus?: "paid" | "eligible" | "requested" | undefined;
     payoutId?: string | undefined;
     shippingMethod?: "custom" | undefined;
     shippingCarrier?: string | undefined;
@@ -759,9 +753,13 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         }, z.ZodTypeAny, "passthrough">;
     } | undefined;
     prizeDrawProductId?: string | undefined;
+    storeName?: string | undefined;
     couponCode?: string | undefined;
-    emiEnabled?: boolean | undefined;
-    emiTenureMonths?: number | undefined;
+    physicalLocation?: {
+        zone: string;
+        shelf: string;
+        bin: string;
+    } | undefined;
     orderType?: string | undefined;
     imageUrls?: string[] | undefined;
     refundFeeDeducted?: number | undefined;
@@ -777,6 +775,8 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         couponId?: string | undefined;
     }[] | undefined;
     codHandlingFee?: number | undefined;
+    emiEnabled?: boolean | undefined;
+    emiTenureMonths?: number | undefined;
     emiTokenAmount?: number | undefined;
     emiSurchargeAmount?: number | undefined;
     emiInstallments?: {