@mohasinac/appkit 4.13.1 → 4.15.0

package/dist/_internal/server/features/checkout/locked-lines.js

@@ -24,9 +24,15 @@
 import { offerRepository } from "../../../../features/seller/repository/offer.repository";
 import { bidRepository } from "../../../../repositories";
 import { OfferStatusValues } from "../../../../features/seller/schemas";
+import { BID_COLLECTION } from "../../../../features/auctions/schemas/firestore";
+import { PRODUCT_COLLECTION } from "../../../../features/products/schemas/firestore";
 import { ValidationError } from "../../../../errors";
+import { BID_ERROR_CODES } from "../../../../errors/error-codes";
+import { ERROR_MESSAGES } from "../../../../errors";
+import { getAdminDb } from "../../../../providers/db-firebase";
 import { serverLogger } from "../../../../monitoring/server-logger";
 import { normalizeError } from "../../../../errors/normalize";
+import { resolveDate } from "../../../../utils/date.formatter";
 import { activeLane, laneOf, laneBlockReason } from "../../../shared/checkout/lanes";
 /**
  * Refuse a checkout that isn't the cart's active lane.
@@ -49,6 +55,108 @@ export function assertCheckoutLane(allCartItems, selectedItems) {
 }
 /** Error code the client maps to a lane-aware message. */
 export const CHECKOUT_LANE_BLOCKED = "CHECKOUT_LANE_BLOCKED";
+const CLAIM_FAILURE_ERRORS = {
+    NOT_FOUND: {
+        message: ERROR_MESSAGES.BID.AUCTION_NOT_FOUND,
+        code: BID_ERROR_CODES.PRODUCT_NOT_FOUND,
+    },
+    ALREADY_SOLD: {
+        message: ERROR_MESSAGES.BID.AUCTION_ALREADY_SOLD,
+        code: BID_ERROR_CODES.AUCTION_ALREADY_SOLD,
+    },
+    AUCTION_ENDED: {
+        message: ERROR_MESSAGES.BID.AUCTION_ENDED_BEFORE_CHECKOUT,
+        code: BID_ERROR_CODES.AUCTION_ENDED_BEFORE_CHECKOUT,
+    },
+    LAPSED: {
+        message: ERROR_MESSAGES.BID.BUYOUT_LAPSED,
+        code: BID_ERROR_CODES.BUYOUT_LAPSED,
+    },
+    OUTBID: {
+        message: ERROR_MESSAGES.BID.BUYOUT_OUTBID,
+        code: BID_ERROR_CODES.BUYOUT_OUTBID,
+    },
+    WRONG_BUYER: {
+        message: ERROR_MESSAGES.BID.BUYOUT_LAPSED,
+        code: BID_ERROR_CODES.BUYOUT_LAPSED,
+    },
+};
+/**
+ * Convert a pending Buy Now claim into an actual sale, atomically.
+ *
+ * This is where a buyout is decided, and it is the ONLY place the auction is
+ * closed. `buyNowAuction` deliberately leaves the listing untouched: the auction
+ * keeps running, keeps taking bids, and keeps accepting other buyers' buyouts.
+ * That means several people can be holding a claim on the same auction at once,
+ * which is intentional — whoever reaches this transaction first gets the item,
+ * and everyone else is refused HERE, before their order is written and before
+ * any payment is captured.
+ *
+ * Four ways to lose, all of them checked inside the transaction against freshly
+ * read documents rather than against the caller's stale cart line:
+ *  - the auction is already sold (another buyout committed first);
+ *  - its clock ran out (settlement will award it to a real bidder — the user's
+ *    explicit rule: an unfinished buyout at auction end fails);
+ *  - the claim's own bid is no longer `active` (the deadline sweep cancelled it);
+ *  - bidding passed the buyout price, so buying out is no longer the better deal.
+ *
+ * Returns a discriminated result rather than throwing out of the transaction
+ * body, so each of these precise, buyer-readable refusals survives as itself
+ * instead of being reshaped by the transaction wrapper. The caller throws.
+ */
+export async function claimAuctionForCheckout(item, buyerUid) {
+    const productId = item.auctionId ?? item.productId;
+    const bidId = item.bidId;
+    if (!bidId)
+        return { ok: false, reason: "NOT_FOUND" };
+    const db = getAdminDb();
+    return db.runTransaction(async (tx) => {
+        const productRef = db.collection(PRODUCT_COLLECTION).doc(productId);
+        const bidRef = db.collection(BID_COLLECTION).doc(bidId);
+        const [productSnap, bidSnap] = await tx.getAll(productRef, bidRef);
+        if (!productSnap.exists || !bidSnap.exists) {
+            return { ok: false, reason: "NOT_FOUND" };
+        }
+        const product = productSnap.data();
+        const bid = bidSnap.data();
+        if (bid.userId !== buyerUid)
+            return { ok: false, reason: "WRONG_BUYER" };
+        if (bid.status !== "active")
+            return { ok: false, reason: "LAPSED" };
+        if (product.isSold === true)
+            return { ok: false, reason: "ALREADY_SOLD" };
+        const endDate = product.auctionEndDate ? resolveDate(product.auctionEndDate) : null;
+        if (endDate && endDate.getTime() <= Date.now()) {
+            return { ok: false, reason: "AUCTION_ENDED" };
+        }
+        const bidAmount = bid.bidAmount;
+        const standingBid = typeof product.currentBid === "number" ? product.currentBid : 0;
+        // `currentBid` never reflects a pending buyout (see BidDocument.isBuyout),
+        // so this compares against real bidding only — exactly the check the buyer
+        // passed when they started, re-run against the price as it is right now.
+        if (standingBid >= bidAmount) {
+            return { ok: false, reason: "OUTBID" };
+        }
+        tx.update(productRef, {
+            isSold: true,
+            availableQuantity: 0,
+            // Ends the auction NOW. Everything above has already established that
+            // nobody outbid the buyout price, so no bidder loses anything they would
+            // otherwise have won.
+            auctionEndDate: new Date(),
+            currentBid: bidAmount,
+            leadingBidderId: bid.userId,
+            bidsHaveStarted: true,
+            updatedAt: new Date(),
+        });
+        tx.update(bidRef, {
+            status: "won",
+            isWinning: true,
+            updatedAt: new Date(),
+        });
+        return { ok: true, bidAmount };
+    });
+}
 /**
  * Re-validate every locked line immediately before the order is written.
  *
@@ -56,10 +164,37 @@ export const CHECKOUT_LANE_BLOCKED = "CHECKOUT_LANE_BLOCKED";
  * to the cart, but nothing re-checked at order time — so a buyer could add an
  * accepted offer, wait out the 48h window, and still be charged the locked
  * price. Throws on the first invalid line; the caller's transaction aborts.
+ *
+ * Auction lines were skipped entirely until 2026-08-24 (`if (!item.offerId)
+ * continue`), so a won auction's own `checkoutDeadline` had never been checked
+ * at order time at all — and a buyout claim, which is decided here, had nowhere
+ * to be decided.
  */
 export async function assertLockedLinesStillValid(items, buyerUid) {
     const now = new Date();
     for (const item of items) {
+        // --- Auction lines: deadline for every one, plus the claim for a buyout ---
+        if (item.bidId || item.isAuctionWin) {
+            if (item.checkoutDeadline && now > resolveDate(item.checkoutDeadline)) {
+                throw new ValidationError(item.isBuyout
+                    ? ERROR_MESSAGES.BID.BUYOUT_LAPSED
+                    : "The payment window for this auction win has expired.", { code: item.isBuyout ? BID_ERROR_CODES.BUYOUT_LAPSED : undefined });
+            }
+            if (item.isBuyout) {
+                const claim = await claimAuctionForCheckout(item, buyerUid);
+                if (!claim.ok) {
+                    const { message, code } = CLAIM_FAILURE_ERRORS[claim.reason];
+                    serverLogger.info("claimAuctionForCheckout refused", {
+                        productId: item.auctionId ?? item.productId,
+                        bidId: item.bidId,
+                        buyerUid,
+                        reason: claim.reason,
+                    });
+                    throw new ValidationError(message, { code });
+                }
+            }
+            continue;
+        }
         if (!item.offerId)
             continue;
         const offer = await offerRepository.findById(item.offerId);
@@ -112,5 +247,41 @@ export async function finalizeLockedLines(items, orderId) {
                 });
             }
         }
+        if (item.isBuyout && item.bidId) {
+            await closeOutBuyoutLosers(item.auctionId ?? item.productId, item.bidId);
+        }
+    }
+}
+/**
+ * A buyout ended the auction, so everyone still bidding on it lost.
+ *
+ * Deliberately AFTER the claim transaction rather than inside it: the number of
+ * active bids on a hot auction is unbounded, and a transaction that touches all
+ * of them would either blow the 500-write limit or contend with every incoming
+ * bid. The claim only has to be atomic about who gets the ITEM; tidying up the
+ * losers is bookkeeping, so it is bounded, best-effort and logged.
+ *
+ * Their bids are `lost`, not `outbid` — the auction is over, which is the same
+ * distinction `auctionSettlement` draws.
+ */
+async function closeOutBuyoutLosers(productId, winningBidId) {
+    try {
+        const active = await bidRepository.getActiveByProduct(productId);
+        const losers = active.filter((e) => e.id !== winningBidId);
+        if (losers.length === 0)
+            return;
+        await bidRepository.markManyLost(losers.map((e) => e.ref));
+        serverLogger.info("finalizeLockedLines: buyout closed out losing bids", {
+            productId,
+            winningBidId,
+            losers: losers.length,
+        });
+    }
+    catch (err) {
+        void normalizeError(err);
+        serverLogger.error("finalizeLockedLines: buyout loser close-out failed", {
+            productId,
+            winningBidId,
+        });
     }
 }

package/dist/_internal/server/features/checkout/source-context.d.ts

@@ -0,0 +1,5 @@
+import type { CartItemDocument } from "../../../../features/cart/schemas/firestore";
+import type { ProductDocument } from "../../../../features/products/schemas/firestore";
+import type { OrderSourceContext } from "../../../../features/orders/schemas/firestore";
+import type { OrderType } from "../../../../features/orders/utils/order-splitter";
+export declare function buildOrderSourceContext(item: CartItemDocument, product: ProductDocument, orderType: OrderType): Promise<OrderSourceContext | undefined>;

package/dist/_internal/server/features/checkout/source-context.js

@@ -0,0 +1,157 @@
+/*
+ * WHY: An order records WHAT was bought and WHAT it cost, and nothing about how
+ *      the buyer earned the right to buy it at that price. `orderType` has five
+ *      values and cannot even separate "won at ₹4,200 against 11 bids" from
+ *      "bought out at ₹6,000 while the standing bid was ₹3,800" — both land as
+ *      `orderType: "auction"`. Everything else was recoverable only by reading
+ *      the auction or offer document, which is mutable and eventually archived.
+ * WHAT: `buildOrderSourceContext()` — the ONE builder for `OrderSourceContext`,
+ *       called by both order-creation paths (manual/COD and Razorpay).
+ *
+ * ## Why one shared function and not two inline blocks
+ *
+ * `createOrderForGroup` and `createRazorpayGroupOrder` are near-identical
+ * ~200-line twins that already drifted once on add-on fees (Root Cause #65).
+ * Two hand-written copies of this would be the create-vs-create axis of Root
+ * Cause #39: one lane records provenance, the other silently doesn't, and the
+ * difference is invisible until someone compares two orders months later.
+ *
+ * ## Written once, never recomputed
+ *
+ * These numbers describe a moment. `product.price` moves, `currentBid` is a
+ * mirror that a pending buyout deliberately never writes to, and a settled
+ * auction is eventually archived. Recomputing later would silently rewrite
+ * history, so nothing outside order creation may write this field.
+ *
+ * ## Read cost
+ *
+ * Standard, pre-order and prize-draw cost **zero** extra reads — everything
+ * comes from the product already in hand. Only the auction and offer lanes pay:
+ * one `findByProductSorted` for auctions (bid count, winner, runner-up, the
+ * standing bid — all four from one query) and one `findById` for offers. Since
+ * a checkout is single-lane by construction, a standard cart never pays either.
+ *
+ * ## Failure is non-fatal, deliberately
+ *
+ * A missing bid or offer document returns `undefined` rather than throwing. The
+ * money path must not fail because a provenance record could not be assembled —
+ * an order with no `sourceContext` is a thinner record; a checkout that 500s
+ * after payment authorisation is a support ticket.
+ *
+ * EXPORTS:
+ *   buildOrderSourceContext
+ *
+ * @tag domain:checkout,orders
+ * @tag layer:server-feature
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:checkout/actions.ts
+ * @tag sideEffects:firestore-read
+ */
+import { bidRepository } from "../../../../features/auctions/repository/bid.repository";
+import { offerRepository } from "../../../../features/seller/repository/offer.repository";
+import { normalizeError } from "../../../../errors/normalize";
+import { serverLogger } from "../../../../monitoring";
+/** Bids that count toward "against N bidders" — a buyout is excluded. */
+function competitiveBids(bids) {
+    return bids.filter((b) => !b.isBuyout).sort((a, b) => b.bidAmount - a.bidAmount);
+}
+export async function buildOrderSourceContext(item, product, orderType) {
+    try {
+        // The offer lane is checked BEFORE orderType, because an accepted offer on
+        // a standard listing arrives as orderType "offer" but an accepted offer on
+        // a classified does not — the cart line's own `offerId` is the reliable
+        // discriminator, exactly as `laneOf()` treats it.
+        if (item.offerId) {
+            const offer = await offerRepository.findById(item.offerId);
+            if (!offer)
+                return undefined;
+            return {
+                path: "offer-accepted",
+                offerId: offer.id,
+                offeredAmount: offer.offerAmount,
+                listPriceAtOffer: offer.listedPrice,
+                counterAmount: offer.counterAmount,
+                // Persisted since W2. Before the chain fields existed this number was
+                // genuinely unknowable — each counter created an unlinked document.
+                counterRounds: offer.counterRound ?? 1,
+                acceptedBy: offer.storeId,
+                acceptedAt: offer.acceptedAt ?? offer.respondedAt ?? new Date(),
+                checkoutDeadline: offer.checkoutDeadline,
+            };
+        }
+        if (item.bidId) {
+            const bids = await bidRepository.findByProductSorted(item.productId);
+            const rivals = competitiveBids(bids);
+            const auctionId = item.auctionId ?? item.productId;
+            if (item.isBuyout) {
+                return {
+                    path: "auction-buy-now",
+                    auctionId,
+                    bidId: item.bidId,
+                    buyNowPrice: item.lockedPrice ?? product.buyNowPrice ?? item.price,
+                    listPrice: product.price,
+                    // From the bids, not `product.currentBid` — a pending buyout never
+                    // writes that mirror, so reading it would understate the auction.
+                    standingBidAtBuyout: rivals[0]?.bidAmount ?? 0,
+                    bidCount: rivals.length,
+                    boughtAt: new Date(),
+                    checkoutDeadline: item.checkoutDeadline ?? new Date(),
+                    auctionEndDate: product.auctionEndDate,
+                };
+            }
+            const winning = bids.find((b) => b.id === item.bidId);
+            const winningAmount = winning?.bidAmount ?? item.lockedPrice ?? item.price;
+            const reserve = product.reservePrice;
+            return {
+                path: "auction-won",
+                auctionId,
+                bidId: item.bidId,
+                winningBidAmount: winningAmount,
+                bidCount: rivals.length,
+                startingBid: product.startingBid ?? 0,
+                reservePrice: reserve,
+                // No reserve set means the reserve cannot fail, so it is met.
+                reserveMet: reserve == null ? true : winningAmount >= reserve,
+                auctionEndedAt: product.auctionEndDate ?? new Date(),
+                runnerUpAmount: rivals.find((b) => b.id !== item.bidId)?.bidAmount,
+            };
+        }
+        if (orderType === "preorder") {
+            const deposit = product.preOrderDepositAmount ??
+                (product.preOrderDepositPercent != null
+                    ? (product.price * product.preOrderDepositPercent) / 100
+                    : 0);
+            return {
+                path: "pre-order",
+                depositAmount: deposit,
+                balanceDue: Math.max(0, product.price - deposit),
+                expectedDeliveryDate: product.preOrderDeliveryDate,
+            };
+        }
+        if (orderType === "prize-draw") {
+            return {
+                path: "prize-draw",
+                prizeDrawProductId: item.productId,
+                pricePerEntry: product.pricePerEntry ?? product.price,
+                entryCount: item.quantity,
+                // `prizeDrawMode` is reveal-vs-lottery, a different axis. The reveal
+                // TIMING is what this records: a draw with a reveal window is
+                // scheduled, one without reveals as soon as it sells out.
+                revealMode: product.prizeRevealWindowEnd ? "scheduled" : "instant",
+            };
+        }
+        return { path: "standard", listPrice: product.price };
+    }
+    catch (err) {
+        const normalized = normalizeError(err);
+        // Non-fatal by design — see the header. Logged loudly so a systematic
+        // failure shows up as a pattern rather than as quietly thinner orders.
+        serverLogger.warn("[checkout] could not build sourceContext", {
+            productId: item.productId,
+            orderType,
+            error: normalized.message,
+        });
+        return undefined;
+    }
+}

package/dist/_internal/server/features/homepage/index.d.ts

@@ -1,2 +1 @@
-export { getHomepageInitial, getHomepageSections, getHeroCarouselSlides, } from "./data";
 export { HOMEPAGE_FEATURED_REVIEWS_LIMIT, HOMEPAGE_RECENT_BLOG_POSTS_LIMIT, HOMEPAGE_MAX_SECTIONS, } from "../../../shared/features/homepage/config";

package/dist/_internal/server/features/homepage/index.js

@@ -1,2 +1,8 @@
-export { getHomepageInitial, getHomepageSections, getHeroCarouselSlides, } from "./data";
+// `getHomepageInitial` / `getHomepageSections` / `getHeroCarouselSlides` lived
+// in ./data and were deleted 2026-08-24. All three had ZERO call sites — the
+// live homepage is `MarketplaceHomepageView`, which reads its repositories
+// directly — and the only part worth keeping, the feature-flag gate, moved to
+// `_internal/shared/features/homepage/section-gate.ts` and is now actually
+// applied. The rest was a Rule #6 liability: `findActiveAuctions()` /
+// `findActivePreOrders()` were unbounded `.get()` collection scans.
 export { HOMEPAGE_FEATURED_REVIEWS_LIMIT, HOMEPAGE_RECENT_BLOG_POSTS_LIMIT, HOMEPAGE_MAX_SECTIONS, } from "../../../shared/features/homepage/config";

package/dist/_internal/server/features/lottery/adapters.js

@@ -1,8 +1,12 @@
 /** Strip price and weight from a single slot for client consumption. */
 export function toClientLotterySlot(slot) {
+    // Allow-list, not a spread: every field named here is a deliberate public
+    // exposure with a known reader (§ Public Data Projections). `image` is read
+    // by the prize collage on the lottery detail page.
     return {
         slotNumber: slot.slotNumber,
         name: slot.name,
+        image: slot.image,
         isBooked: slot.isBooked,
         bookedByUserLotteryNumber: slot.bookedByUserLotteryNumber,
         bookedByDisplayName: slot.bookedByDisplayName,

package/dist/_internal/server/features/offers/adapters.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Offer document → API shape.
+ *
+ * Offers had **no adapter at all** before this: all three routes
+ * (`/api/user/offers`, `/api/store/offers`, `/api/admin/offers`) returned raw
+ * `OfferDocument`s straight from the repository, carrying live `Date`
+ * objects. `UserOffersPanel.relativeTime` still has a defensive
+ * `date instanceof Date ? … : new Date(…)` branch precisely because the shape
+ * it receives depends on whether the value survived JSON serialisation.
+ *
+ * Mirrors `orders/adapters.ts`, including its `toIsoOrUndefined` helper.
+ */
+import type { OfferDocument } from "../../../../features/seller/schemas";
+import type { FieldChange } from "../../../shared/history/index";
+/** One entry on an offer's timeline — dates as ISO, ready for JSON. */
+export interface OfferTimelineEntry {
+    at: string;
+    actorUid?: string;
+    actorRole: "buyer" | "seller" | "admin" | "system";
+    changes: Record<string, FieldChange>;
+    reason?: string;
+    note?: string;
+    trigger: string;
+}
+/** One round of a negotiation, as rendered in the chain rail. */
+export interface OfferChainRound {
+    id: string;
+    counterRound: number;
+    status: OfferDocument["status"];
+    offerAmount: number;
+    counterAmount?: number;
+    /**
+     * `withdrawn` + a `supersededByOfferId` is NOT a walk-away — the buyer
+     * countered. The timeline renders it neutral ("Superseded") rather than
+     * negative ("Withdrawn"), which is why this flag is carried explicitly
+     * instead of being re-derived in the component.
+     */
+    superseded: boolean;
+    createdAt: string;
+    respondedAt?: string;
+    sellerNote?: string;
+    buyerNote?: string;
+}
+export interface Offer {
+    id: string;
+    productId: string;
+    productTitle: string;
+    productSlug?: string;
+    productImageUrl?: string;
+    storeId: string;
+    storeName: string;
+    offerAmount: number;
+    listedPrice: number;
+    counterAmount?: number;
+    lockedPrice?: number;
+    currency: string;
+    status: OfferDocument["status"];
+    buyerNote?: string;
+    sellerNote?: string;
+    expiresAt: string;
+    acceptedAt?: string;
+    checkoutDeadline?: string;
+    respondedAt?: string;
+    paidOrderId?: string;
+    paidAt?: string;
+    createdAt: string;
+    updatedAt: string;
+    timeline?: OfferTimelineEntry[];
+    timelineTruncated?: number;
+    previousOfferId?: string;
+    supersededByOfferId?: string;
+    chainRootOfferId?: string;
+    counterRound?: number;
+    /** True when this round was superseded by the buyer's own counter. */
+    superseded: boolean;
+    cancelledByAdminUid?: string;
+    cancelReason?: string;
+    buyerUid?: string;
+    buyerName?: string;
+    buyerEmail?: string;
+}
+export interface OfferAdapterOptions {
+    /**
+     * Include `buyerUid`/`buyerName`/`buyerEmail`.
+     *
+     * Default **false**, deliberately. The seller-facing route masks buyer
+     * identity, and a route that forgot to call `maskOfferForSeller` would
+     * previously have shipped it verbatim — there was no adapter to stop it.
+     * Making the omission the default means forgetting the flag under-shares
+     * rather than leaks.
+     */
+    includeBuyerIdentity?: boolean;
+}
+export declare function offerDocumentToOffer(doc: OfferDocument, opts?: OfferAdapterOptions): Offer;
+/**
+ * A chain round — the compact shape the timeline needs, without re-sending
+ * the whole document for every round.
+ *
+ * Buyer identity is never included: the chain is rendered on all three
+ * portals from one component, and the seller's view must not gain identity
+ * it is masked from elsewhere.
+ */
+export declare function offerToChainRound(doc: OfferDocument): OfferChainRound;

package/dist/_internal/server/features/offers/adapters.js

@@ -0,0 +1,88 @@
+/**
+ * Offer document → API shape.
+ *
+ * Offers had **no adapter at all** before this: all three routes
+ * (`/api/user/offers`, `/api/store/offers`, `/api/admin/offers`) returned raw
+ * `OfferDocument`s straight from the repository, carrying live `Date`
+ * objects. `UserOffersPanel.relativeTime` still has a defensive
+ * `date instanceof Date ? … : new Date(…)` branch precisely because the shape
+ * it receives depends on whether the value survived JSON serialisation.
+ *
+ * Mirrors `orders/adapters.ts`, including its `toIsoOrUndefined` helper.
+ */
+function toIsoOrUndefined(value) {
+    return value instanceof Date ? value.toISOString() : undefined;
+}
+function toIso(value) {
+    return value instanceof Date ? value.toISOString() : String(value);
+}
+export function offerDocumentToOffer(doc, opts = {}) {
+    const superseded = doc.status === "withdrawn" && Boolean(doc.supersededByOfferId);
+    return {
+        id: doc.id,
+        productId: doc.productId,
+        productTitle: doc.productTitle,
+        productSlug: doc.productSlug,
+        productImageUrl: doc.productImageUrl,
+        storeId: doc.storeId,
+        storeName: doc.storeName,
+        offerAmount: doc.offerAmount,
+        listedPrice: doc.listedPrice,
+        counterAmount: doc.counterAmount,
+        lockedPrice: doc.lockedPrice,
+        currency: doc.currency,
+        status: doc.status,
+        buyerNote: doc.buyerNote,
+        sellerNote: doc.sellerNote,
+        expiresAt: toIso(doc.expiresAt),
+        acceptedAt: toIsoOrUndefined(doc.acceptedAt),
+        checkoutDeadline: toIsoOrUndefined(doc.checkoutDeadline),
+        respondedAt: toIsoOrUndefined(doc.respondedAt),
+        paidOrderId: doc.paidOrderId,
+        paidAt: toIsoOrUndefined(doc.paidAt),
+        createdAt: toIso(doc.createdAt),
+        updatedAt: toIso(doc.updatedAt),
+        timeline: doc.statusHistory?.map((entry) => ({
+            at: entry.at instanceof Date ? entry.at.toISOString() : String(entry.at),
+            actorUid: entry.actorUid,
+            actorRole: entry.actorRole,
+            changes: entry.changes,
+            reason: entry.reason,
+            note: entry.note,
+            trigger: entry.trigger,
+        })),
+        timelineTruncated: doc.statusHistoryTruncated,
+        previousOfferId: doc.previousOfferId,
+        supersededByOfferId: doc.supersededByOfferId,
+        chainRootOfferId: doc.chainRootOfferId,
+        counterRound: doc.counterRound,
+        superseded,
+        cancelledByAdminUid: doc.cancelledByAdminUid,
+        cancelReason: doc.cancelReason,
+        ...(opts.includeBuyerIdentity
+            ? { buyerUid: doc.buyerUid, buyerName: doc.buyerName, buyerEmail: doc.buyerEmail }
+            : {}),
+    };
+}
+/**
+ * A chain round — the compact shape the timeline needs, without re-sending
+ * the whole document for every round.
+ *
+ * Buyer identity is never included: the chain is rendered on all three
+ * portals from one component, and the seller's view must not gain identity
+ * it is masked from elsewhere.
+ */
+export function offerToChainRound(doc) {
+    return {
+        id: doc.id,
+        counterRound: doc.counterRound ?? 1,
+        status: doc.status,
+        offerAmount: doc.offerAmount,
+        counterAmount: doc.counterAmount,
+        superseded: doc.status === "withdrawn" && Boolean(doc.supersededByOfferId),
+        createdAt: toIso(doc.createdAt),
+        respondedAt: toIsoOrUndefined(doc.respondedAt),
+        sellerNote: doc.sellerNote,
+        buyerNote: doc.buyerNote,
+    };
+}

package/dist/_internal/server/features/offers/index.d.ts

@@ -0,0 +1,2 @@
+export { offerDocumentToOffer, offerToChainRound, } from "./adapters";
+export type { Offer, OfferAdapterOptions, OfferChainRound, OfferTimelineEntry, } from "./adapters";

package/dist/_internal/server/features/offers/index.js

@@ -0,0 +1 @@
+export { offerDocumentToOffer, offerToChainRound, } from "./adapters";

package/dist/_internal/server/features/orders/adapters.js

@@ -104,6 +104,30 @@ export function orderDocumentToOrder(doc) {
         paymentReviewOutcome: doc.paymentReviewOutcome,
         paymentReviewNote: doc.paymentReviewNote,
         cancellationReason: doc.cancellationReason,
+        // ── W2: history + provenance ──────────────────────────────────────────
+        //
+        // `Order.timeline` has existed, been exported, and had ZERO writers since
+        // it was declared — `OrderStatusTimeline` synthesised its steps from four
+        // scalar dates instead, so a status change with no dedicated date field
+        // (payment reviewed, refund posted) was simply invisible.
+        //
+        // `statusHistory` is that field's real source. Dates are serialised to
+        // ISO here for the same reason every other date on this shape is: the
+        // client receives JSON, and a raw `Date` arrives as a string that no
+        // longer satisfies the type.
+        timeline: doc.statusHistory?.map((entry) => ({
+            at: entry.at instanceof Date ? entry.at.toISOString() : String(entry.at),
+            actorUid: entry.actorUid,
+            actorRole: entry.actorRole,
+            changes: entry.changes,
+            reason: entry.reason,
+            note: entry.note,
+            trigger: entry.trigger,
+        })),
+        /** Entries trimmed off the front — so the UI never implies "this is all of it". */
+        timelineTruncated: doc.statusHistoryTruncated,
+        /** How the buyer acquired the right to buy. Written once, at creation. */
+        sourceContext: doc.sourceContext,
         createdAt: doc.createdAt instanceof Date
             ? doc.createdAt.toISOString()
             : String(doc.createdAt),