@mohasinac/appkit 4.13.1 → 4.15.0

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,49 @@ 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,
+            // `encryptPiiFields` is a flat top-level loop and never descends into
+            // arrays, so anything PII-named reaching `changes` would persist in
+            // PLAINTEXT inside statusHistory. None of ORDER_TRACKED_FIELDS is PII
+            // today — this is defence for the next field somebody adds.
+            piiFields: ORDER_PII_FIELDS,
+            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 +116,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 +133,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 +148,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 +163,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 +296,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 +535,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,94 @@ 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;
+}
+/**
+ * A buyout is a REAL BID, not a bid-free purchase.
+ *
+ * An earlier draft of this type asserted "zero bids BY DEFINITION, because
+ * buy-now is only valid while `!bidsHaveStarted`". That gate no longer
+ * exists: `buyNowAuction` places an actual `BidDocument` (`isBuyout: true`)
+ * plus a 1h locked cart line and leaves the auction **live**, and Buy Now is
+ * offered whenever `buyNowPrice` still beats the standing bid. Recording
+ * `bidCount: 0` would bake a falsehood into an immutable audit record.
+ *
+ * `standingBidAtBuyout` is the highest NON-buyout bid the buyout beat — read
+ * from the bids rather than `product.currentBid`, because a pending buyout
+ * deliberately never writes to that mirror.
+ *
+ * An unpaid buyout lapses to **`cancelled`**, not `forfeited`, and the seller
+ * is deliberately not notified: nothing was ever sold. That makes its
+ * timeline materially different from a lapsed auction win.
+ */
+export interface OrderSourceAuctionBuyNow {
+    path: "auction-buy-now";
+    auctionId: string;
+    /** The buyout bid itself — a buyout IS a bid. */
+    bidId: string;
+    buyNowPrice: number;
+    listPrice: number;
+    /** Highest non-buyout bid at the moment of buyout. 0 when nobody had bid. */
+    standingBidAtBuyout: number;
+    /** Active non-buyout bids at buyout time. NOT always zero. */
+    bidCount: number;
+    boughtAt: Date;
+    /** `min(now + AUCTION_BUYOUT_WINDOW_MS, auctionEndDate)`. */
+    checkoutDeadline: Date;
+    auctionEndDate?: 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. 1 = accepted outright.
+     *
+     * Read straight off the accepted offer's `counterRound`, which W2 made a
+     * persisted field. Before that this number was **unknowable**: each counter
+     * created an unlinked document and `previousOfferId` lived only inside a
+     * `serverLogger.info` call, so a three-round negotiation left no trace of
+     * having been one.
+     */
+    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 +238,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 +348,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 +515,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?: {

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

@@ -2,7 +2,8 @@ import { type PaymentGateway, PaymentGatewayValues } from "../../payments/schema
 export { type PaymentGateway, PaymentGatewayValues };
 import type { ListingType } from "../../products/types/index";
 import type { OrderType } from "../utils/order-splitter";
-import type { AppliedOrderDiscount } from "../schemas/firestore";
+import type { AppliedOrderDiscount, OrderSourceContext } from "../schemas/firestore";
+import type { FieldChange } from "../../../_internal/shared/history/index";
 export type PaymentStatus = "pending" | "processing" | "paid" | "failed" | "refunded" | "partial_refund";
 export interface UserAddress {
     id: string;
@@ -46,12 +47,34 @@ export interface OrderItem {
     /** Snapshot of bundle.bundleProductIds at order-creation time. */
     bundleProductIds?: string[];
 }
-export interface OrderTimeline {
-    status: OrderStatus;
-    message?: string;
-    timestamp: string;
-    actor?: string;
+/**
+ * One entry on an order's timeline — the client-facing shape of
+ * `StatusChangeEntry`, with dates as ISO strings.
+ *
+ * The previous declaration here was `{status, message?, timestamp, actor?}`
+ * and had **zero writers** in the entire codebase since the day it was
+ * added, so nothing depended on it. `OrderStatusTimeline` synthesised its
+ * steps from four scalar date fields instead, which meant any transition
+ * without a dedicated date field — payment reviewed, proof re-upload asked
+ * for, a partial refund posted — could not appear at all.
+ */
+export interface OrderTimelineEntry {
+    at: string;
+    actorUid?: string;
+    actorRole: "buyer" | "seller" | "admin" | "system";
+    /**
+     * Delta only: `{ status: { from: "confirmed", to: "shipped" } }`.
+     * Reuses the primitive's `FieldChange` rather than restating the shape, so
+     * the client type cannot drift from what the repository writes.
+     */
+    changes: Record<string, FieldChange>;
+    reason?: string;
+    note?: string;
+    /** The function or job that caused it — what the timeline renders by. */
+    trigger: string;
 }
+/** @deprecated Use {@link OrderTimelineEntry}. Kept only to avoid breaking a stale import. */
+export type OrderTimeline = OrderTimelineEntry;
 export interface Order {
     id: string;
     userId: string;
@@ -108,7 +131,12 @@ export interface Order {
     /** Carrier tracking page URL — rendered as an external link that opens in a new tab. No live-tracking API integration; this is just the passthrough URL a seller/admin entered. */
     trackingUrl?: string;
     notes?: string;
-    timeline?: OrderTimeline[];
+    /** Real recorded transitions — see {@link OrderTimelineEntry}. */
+    timeline?: OrderTimelineEntry[];
+    /** Entries trimmed off the front of the capped history, if any. */
+    timelineTruncated?: number;
+    /** How the buyer acquired the right to buy. Written once, at creation. */
+    sourceContext?: OrderSourceContext;
     physicalLocation?: {
         zone: string;
         shelf: string;