@mohasinac/appkit 4.62.1 → 4.63.1

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

@@ -0,0 +1,140 @@
+/**
+ * D56 — a SELF-SERVE ad booking: one advertiser, one placement, one period.
+ *
+ * ## 🛑 Flat fee per slot per period, and explicitly NOT CPM
+ *
+ * Impression counting is a write per page view, which is the exact cost
+ * pattern that suspended this project (Root Cause #104: 3.1M ISR writes
+ * against a 200K allowance, 52.52 GB of Fast Origin Transfer against 10 GB,
+ * for eleven monthly active users). A flat fee is one write per BOOKING.
+ * Nothing here counts anything per render, and nothing should be added that
+ * does.
+ *
+ * ## Why a PERIOD rather than an arbitrary date range
+ *
+ * The plan's requirement is slot-availability locking — two advertisers must
+ * not book the same slot for overlapping dates. Firestore has no range
+ * constraint, so an arbitrary `startAt`/`endAt` pair can only be checked by
+ * QUERYING for overlaps and then writing, and two concurrent bookings both
+ * read "no overlap" and both write. That race is invisible in testing and
+ * sells the same slot twice.
+ *
+ * Discretising to a period makes the conflict a DOCUMENT COLLISION instead:
+ * the booking id is derived from `(placementId, period)`, so the second
+ * writer fails on an existing document inside its own transaction and
+ * Firestore does the locking. There is no query to race against.
+ *
+ * It also matches what is being sold. "The homepage banner for November" is
+ * the product; "the homepage banner from the 9th to the 23rd" is a pricing
+ * model nobody asked for and an availability calendar nobody can render.
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+export declare const AD_BOOKING_COLLECTION = "adBookings";
+/**
+ * A calendar month, `YYYY-MM`.
+ *
+ * 🛑 A STRING, not a Date. It is an identity — half of the booking's primary
+ * key — and a Date would make "the same month" a comparison rather than an
+ * equality, which is precisely what the document-collision lock depends on
+ * not being.
+ */
+export type AdPeriod = string;
+export declare function isAdPeriod(value: string): value is AdPeriod;
+/** The period a date falls in, in UTC. */
+export declare function adPeriodOf(date: Date): AdPeriod;
+/** First instant of a period, UTC. */
+export declare function adPeriodStart(period: AdPeriod): Date;
+/** First instant of the NEXT period — the exclusive end. */
+export declare function adPeriodEnd(period: AdPeriod): Date;
+/**
+ * 🛑 The booking id IS the lock. Derived, never generated.
+ *
+ * Two advertisers booking `banner-home` for `2026-11` compute the same id and
+ * the second `tx.create` throws `ALREADY_EXISTS` — which is the whole
+ * availability guarantee, enforced by Firestore rather than by a check
+ * somebody could forget to run.
+ */
+export declare function adBookingId(placementId: string, period: AdPeriod): string;
+/**
+ * Payment state. Deliberately coarse: this records whether the slot is PAID
+ * FOR, not how. The invoice and the ledger posting are Part 4's job and carry
+ * the detail; duplicating any of it here would be two records of one fact.
+ */
+export declare const AD_BOOKING_PAYMENT_STATES: readonly ["unpaid", "paid", "refunded"];
+export type AdBookingPaymentState = (typeof AD_BOOKING_PAYMENT_STATES)[number];
+/**
+ * Creative moderation. **Nothing renders on the site until `approved`.**
+ *
+ * 🛑 `pending` is the initial value and there is no way to write `approved`
+ * through the advertiser's own schema — see `adBookingWriteSchema`. A
+ * self-serve flow where the submitter can set their own moderation state is
+ * not moderated; it is a form with an extra field (Root Cause #76 — a field
+ * the form can send is a field the form can destroy, here inverted into a
+ * field the form can grant itself).
+ */
+export declare const AD_MODERATION_STATES: readonly ["pending", "approved", "rejected"];
+export type AdModerationState = (typeof AD_MODERATION_STATES)[number];
+export interface AdBookingCreative {
+    title: string;
+    body?: string;
+    imageUrl?: string;
+    ctaLabel?: string;
+    ctaHref?: string;
+}
+export interface AdBookingDocument extends BaseDocument {
+    /** Matches a `SiteSettingsAdPlacement.id`. */
+    placementId: string;
+    period: AdPeriod;
+    /** Auth uid of the advertiser. */
+    advertiserUid: string;
+    /** Denormalised for the admin queue — a moderator should not fan out to `users`. */
+    advertiserName?: string;
+    /**
+     * Rupees, SNAPSHOTTED at booking.
+     *
+     * 🛑 Never recomputed from the live rate card. The rate is a price the
+     * advertiser agreed to; re-deriving it at render or invoice time would
+     * silently reprice a sold slot the first time an admin edits the card —
+     * the same rule `sourceContext` follows for order provenance.
+     */
+    priceRs: number;
+    paymentState: AdBookingPaymentState;
+    /** Set by the Part 4 invoicing path once the booking is billed. */
+    invoiceId?: string;
+    creative: AdBookingCreative;
+    moderation: {
+        state: AdModerationState;
+        /** Required on a rejection — see `moderateAdCreative`. */
+        note?: string;
+        reviewedAt?: Date;
+        /**
+         * Staff uid. 🛑 Never returned to the advertiser: who rejected you is
+         * not information a self-serve submitter needs, and naming an individual
+         * moderator invites them being contacted directly.
+         */
+        reviewedBy?: string;
+    };
+    /** Set when an admin or the advertiser cancels. A cancelled booking frees nothing — see below. */
+    cancelledAt?: Date;
+    cancelledReason?: string;
+}
+/**
+ * Does this booking put a creative on the page right now?
+ *
+ * 🛑 All four conditions, and the order is not an accident — moderation is
+ * checked before the calendar so an approved-but-future booking and an
+ * unreviewed current one are distinguishable in a debugger.
+ */
+export declare function isAdBookingLive(booking: Pick<AdBookingDocument, "moderation" | "paymentState" | "period" | "cancelledAt">, now?: Date): boolean;
+/**
+ * 🛑 A cancelled booking KEEPS its document, and therefore keeps the slot
+ * locked for its own period.
+ *
+ * Deleting it would free the slot — which sounds like the point and is the
+ * wrong behaviour twice over: the advertiser has paid for a period that has
+ * possibly already started, and re-selling a month mid-flight means two
+ * creatives were live in one slot at different times with one invoice
+ * between them. Freeing a period is an ADMIN act (`releaseAdSlot`), done
+ * knowingly, not a side effect of a cancel button.
+ */
+export declare const AD_BOOKING_CANCELLED_KEEPS_SLOT = true;

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

@@ -0,0 +1,109 @@
+/**
+ * D56 — a SELF-SERVE ad booking: one advertiser, one placement, one period.
+ *
+ * ## 🛑 Flat fee per slot per period, and explicitly NOT CPM
+ *
+ * Impression counting is a write per page view, which is the exact cost
+ * pattern that suspended this project (Root Cause #104: 3.1M ISR writes
+ * against a 200K allowance, 52.52 GB of Fast Origin Transfer against 10 GB,
+ * for eleven monthly active users). A flat fee is one write per BOOKING.
+ * Nothing here counts anything per render, and nothing should be added that
+ * does.
+ *
+ * ## Why a PERIOD rather than an arbitrary date range
+ *
+ * The plan's requirement is slot-availability locking — two advertisers must
+ * not book the same slot for overlapping dates. Firestore has no range
+ * constraint, so an arbitrary `startAt`/`endAt` pair can only be checked by
+ * QUERYING for overlaps and then writing, and two concurrent bookings both
+ * read "no overlap" and both write. That race is invisible in testing and
+ * sells the same slot twice.
+ *
+ * Discretising to a period makes the conflict a DOCUMENT COLLISION instead:
+ * the booking id is derived from `(placementId, period)`, so the second
+ * writer fails on an existing document inside its own transaction and
+ * Firestore does the locking. There is no query to race against.
+ *
+ * It also matches what is being sold. "The homepage banner for November" is
+ * the product; "the homepage banner from the 9th to the 23rd" is a pricing
+ * model nobody asked for and an availability calendar nobody can render.
+ */
+export const AD_BOOKING_COLLECTION = "adBookings";
+const PERIOD_PATTERN = /^\d{4}-(0[1-9]|1[0-2])$/;
+export function isAdPeriod(value) {
+    return PERIOD_PATTERN.test(value);
+}
+/** The period a date falls in, in UTC. */
+export function adPeriodOf(date) {
+    const y = date.getUTCFullYear();
+    const m = String(date.getUTCMonth() + 1).padStart(2, "0");
+    return `${y}-${m}`;
+}
+/** First instant of a period, UTC. */
+export function adPeriodStart(period) {
+    const [y, m] = period.split("-").map(Number);
+    return new Date(Date.UTC(y, m - 1, 1, 0, 0, 0, 0));
+}
+/** First instant of the NEXT period — the exclusive end. */
+export function adPeriodEnd(period) {
+    const [y, m] = period.split("-").map(Number);
+    return new Date(Date.UTC(y, m, 1, 0, 0, 0, 0));
+}
+/**
+ * 🛑 The booking id IS the lock. Derived, never generated.
+ *
+ * Two advertisers booking `banner-home` for `2026-11` compute the same id and
+ * the second `tx.create` throws `ALREADY_EXISTS` — which is the whole
+ * availability guarantee, enforced by Firestore rather than by a check
+ * somebody could forget to run.
+ */
+export function adBookingId(placementId, period) {
+    return `${placementId}__${period}`;
+}
+/**
+ * Payment state. Deliberately coarse: this records whether the slot is PAID
+ * FOR, not how. The invoice and the ledger posting are Part 4's job and carry
+ * the detail; duplicating any of it here would be two records of one fact.
+ */
+export const AD_BOOKING_PAYMENT_STATES = ["unpaid", "paid", "refunded"];
+/**
+ * Creative moderation. **Nothing renders on the site until `approved`.**
+ *
+ * 🛑 `pending` is the initial value and there is no way to write `approved`
+ * through the advertiser's own schema — see `adBookingWriteSchema`. A
+ * self-serve flow where the submitter can set their own moderation state is
+ * not moderated; it is a form with an extra field (Root Cause #76 — a field
+ * the form can send is a field the form can destroy, here inverted into a
+ * field the form can grant itself).
+ */
+export const AD_MODERATION_STATES = ["pending", "approved", "rejected"];
+/**
+ * Does this booking put a creative on the page right now?
+ *
+ * 🛑 All four conditions, and the order is not an accident — moderation is
+ * checked before the calendar so an approved-but-future booking and an
+ * unreviewed current one are distinguishable in a debugger.
+ */
+export function isAdBookingLive(booking, now = new Date()) {
+    if (booking.cancelledAt)
+        return false;
+    if (booking.moderation.state !== "approved")
+        return false;
+    if (booking.paymentState !== "paid")
+        return false;
+    const start = adPeriodStart(booking.period);
+    const end = adPeriodEnd(booking.period);
+    return now >= start && now < end;
+}
+/**
+ * 🛑 A cancelled booking KEEPS its document, and therefore keeps the slot
+ * locked for its own period.
+ *
+ * Deleting it would free the slot — which sounds like the point and is the
+ * wrong behaviour twice over: the advertiser has paid for a period that has
+ * possibly already started, and re-selling a month mid-flight means two
+ * creatives were live in one slot at different times with one invoice
+ * between them. Freeing a period is an ADMIN act (`releaseAdSlot`), done
+ * knowingly, not a side effect of a cancel button.
+ */
+export const AD_BOOKING_CANCELLED_KEEPS_SLOT = true;

package/dist/features/auctions/repository/bid.repository.js

@@ -276,7 +276,9 @@ export class BidRepository extends BaseRepository {
             reason: ctx?.reason,
             note: ctx?.note,
             // `userName`/`userEmail` are denormalised onto every bid, and
-            // `encryptPiiFields` never descends into arrays.
+            // `encryptPiiFields` covers a field only where it is NAMED. It CAN reach
+            // into an array via `array[].key`, but a bare key does not — so an
+            // undeclared nested value is stored in plaintext.
             piiFields: BID_HISTORY_PII_FIELDS,
         });
         return withEntry ?? patch;

package/dist/features/audit-log/schemas/firestore.d.ts

@@ -59,6 +59,61 @@ export declare const AdminAuditActionValues: {
      * returns the existing row, which is not an act worth logging.
      */
     readonly DISPUTE_REASON_CREATE: "dispute_reason_create";
+    readonly DISPUTE_REASON_RETIRE: "dispute_reason_retire";
+    /**
+     * An admin changed a platform rate through `/admin/pricing`.
+     *
+     * 🛑 Recorded here as well as in `siteSettings.rateChanges`, and the two are
+     * not redundant. The rate log answers "when did THIS rate last move" and is
+     * capped, so it can lose its oldest entries; this answers "what have admins
+     * done lately" across every privileged act, and is the one that has to
+     * survive. Same split as `points_adjust` against its ledger.
+     *
+     * Every rate here is money the platform charges or withholds, so this is the
+     * same class as `coupon_update` and `payout_mark_paid`.
+     */
+    readonly PRICING_UPDATE: "pricing_update";
+    /**
+     * An admin granted or revoked `trustedSeller` on a store.
+     *
+     * 🛑 Its OWN action rather than folded into `store_status_change`, because
+     * "what changed about this store" and "who accepted this risk" are
+     * different questions. Trusting a seller means paying before delivery, so
+     * the platform carries a lost parcel and a non-delivery dispute — and when
+     * one of those lands, the question is who decided and when.
+     *
+     * Recorded on a real change only. Re-saving an unrelated field on an
+     * already-trusted store writes nothing; a log of non-events stops being
+     * read.
+     */
+    readonly STORE_TRUST_CHANGE: "store_trust_change";
+    /** A role's permission set changed — the definition of who can do what. */
+    readonly ROLE_CHANGE: "role_change";
+    /**
+     * A tax code's rate or HSN mapping changed.
+     *
+     * 🛑 The one STATUTORY thing an admin can edit, which is why
+     * `/admin/pricing` deliberately does not mirror it. A wrong rate here is a
+     * wrong return, so "who set this and when" is the question an assessment
+     * asks first.
+     */
+    readonly TAX_CODE_CHANGE: "tax_code_change";
+    /** Sessions forcibly revoked — the user is signed out everywhere, now. */
+    readonly SESSION_REVOKE: "session_revoke";
+    /** A bulk operation over many users at once. */
+    readonly USER_BULK_ACTION: "user_bulk_action";
+    /** A moderation report resolved, dismissed or actioned. */
+    readonly MODERATION_DECISION: "moderation_decision";
+    /** A payment case claimed or resolved — money a buyer says did not arrive. */
+    readonly PAYMENT_CASE_DECISION: "payment_case_decision";
+    /**
+     * A scammer profile edited.
+     *
+     * 🛑 Public-facing accusation. The profile names a person or a payment
+     * handle, so the wording and the status are reputational — and the one
+     * question that follows a complaint is who wrote it.
+     */
+    readonly SCAMMER_PROFILE_UPDATE: "scammer_profile_update";
 };
 export type AdminAuditAction = (typeof AdminAuditActionValues)[keyof typeof AdminAuditActionValues];
 export interface AdminAuditLogDocument extends BaseDocument {
@@ -127,5 +182,60 @@ export declare const ADMIN_AUDIT_LOG_FIELDS: {
          * returns the existing row, which is not an act worth logging.
          */
         readonly DISPUTE_REASON_CREATE: "dispute_reason_create";
+        readonly DISPUTE_REASON_RETIRE: "dispute_reason_retire";
+        /**
+         * An admin changed a platform rate through `/admin/pricing`.
+         *
+         * 🛑 Recorded here as well as in `siteSettings.rateChanges`, and the two are
+         * not redundant. The rate log answers "when did THIS rate last move" and is
+         * capped, so it can lose its oldest entries; this answers "what have admins
+         * done lately" across every privileged act, and is the one that has to
+         * survive. Same split as `points_adjust` against its ledger.
+         *
+         * Every rate here is money the platform charges or withholds, so this is the
+         * same class as `coupon_update` and `payout_mark_paid`.
+         */
+        readonly PRICING_UPDATE: "pricing_update";
+        /**
+         * An admin granted or revoked `trustedSeller` on a store.
+         *
+         * 🛑 Its OWN action rather than folded into `store_status_change`, because
+         * "what changed about this store" and "who accepted this risk" are
+         * different questions. Trusting a seller means paying before delivery, so
+         * the platform carries a lost parcel and a non-delivery dispute — and when
+         * one of those lands, the question is who decided and when.
+         *
+         * Recorded on a real change only. Re-saving an unrelated field on an
+         * already-trusted store writes nothing; a log of non-events stops being
+         * read.
+         */
+        readonly STORE_TRUST_CHANGE: "store_trust_change";
+        /** A role's permission set changed — the definition of who can do what. */
+        readonly ROLE_CHANGE: "role_change";
+        /**
+         * A tax code's rate or HSN mapping changed.
+         *
+         * 🛑 The one STATUTORY thing an admin can edit, which is why
+         * `/admin/pricing` deliberately does not mirror it. A wrong rate here is a
+         * wrong return, so "who set this and when" is the question an assessment
+         * asks first.
+         */
+        readonly TAX_CODE_CHANGE: "tax_code_change";
+        /** Sessions forcibly revoked — the user is signed out everywhere, now. */
+        readonly SESSION_REVOKE: "session_revoke";
+        /** A bulk operation over many users at once. */
+        readonly USER_BULK_ACTION: "user_bulk_action";
+        /** A moderation report resolved, dismissed or actioned. */
+        readonly MODERATION_DECISION: "moderation_decision";
+        /** A payment case claimed or resolved — money a buyer says did not arrive. */
+        readonly PAYMENT_CASE_DECISION: "payment_case_decision";
+        /**
+         * A scammer profile edited.
+         *
+         * 🛑 Public-facing accusation. The profile names a person or a payment
+         * handle, so the wording and the status are reputational — and the one
+         * question that follows a complaint is who wrote it.
+         */
+        readonly SCAMMER_PROFILE_UPDATE: "scammer_profile_update";
     };
 };

package/dist/features/audit-log/schemas/firestore.js

@@ -57,6 +57,80 @@ export const AdminAuditActionValues = {
      * returns the existing row, which is not an act worth logging.
      */
     DISPUTE_REASON_CREATE: "dispute_reason_create",
+    /*
+     * Retiring is recorded and reactivating is not, which is deliberate rather
+     * than an omission. Retiring REMOVES an option buyers could pick, so "who
+     * narrowed the list, and when" is the question an audit of a dispute trend
+     * needs answered. Putting a row back restores the documented default, and a
+     * log of both would read as churn.
+     */
+    DISPUTE_REASON_RETIRE: "dispute_reason_retire",
+    /**
+     * An admin changed a platform rate through `/admin/pricing`.
+     *
+     * 🛑 Recorded here as well as in `siteSettings.rateChanges`, and the two are
+     * not redundant. The rate log answers "when did THIS rate last move" and is
+     * capped, so it can lose its oldest entries; this answers "what have admins
+     * done lately" across every privileged act, and is the one that has to
+     * survive. Same split as `points_adjust` against its ledger.
+     *
+     * Every rate here is money the platform charges or withholds, so this is the
+     * same class as `coupon_update` and `payout_mark_paid`.
+     */
+    PRICING_UPDATE: "pricing_update",
+    /**
+     * An admin granted or revoked `trustedSeller` on a store.
+     *
+     * 🛑 Its OWN action rather than folded into `store_status_change`, because
+     * "what changed about this store" and "who accepted this risk" are
+     * different questions. Trusting a seller means paying before delivery, so
+     * the platform carries a lost parcel and a non-delivery dispute — and when
+     * one of those lands, the question is who decided and when.
+     *
+     * Recorded on a real change only. Re-saving an unrelated field on an
+     * already-trusted store writes nothing; a log of non-events stops being
+     * read.
+     */
+    STORE_TRUST_CHANGE: "store_trust_change",
+    /*
+     * ── Part 14 / A5 ─────────────────────────────────────────────────────────
+     *
+     * `audit-privileged-write-unlogged` found 14 admin write paths that record
+     * nothing. These are the action values the ones being closed now need; the
+     * rest stay on the ratchet until each is given one deliberately.
+     *
+     * 🛑 Each is a SEPARATE value rather than a shared `admin_write`. The log's
+     * question is "what have admins done lately", and an undifferentiated value
+     * answers it with a row that says only "something". Filtering is the whole
+     * point of the collection.
+     */
+    /** A role's permission set changed — the definition of who can do what. */
+    ROLE_CHANGE: "role_change",
+    /**
+     * A tax code's rate or HSN mapping changed.
+     *
+     * 🛑 The one STATUTORY thing an admin can edit, which is why
+     * `/admin/pricing` deliberately does not mirror it. A wrong rate here is a
+     * wrong return, so "who set this and when" is the question an assessment
+     * asks first.
+     */
+    TAX_CODE_CHANGE: "tax_code_change",
+    /** Sessions forcibly revoked — the user is signed out everywhere, now. */
+    SESSION_REVOKE: "session_revoke",
+    /** A bulk operation over many users at once. */
+    USER_BULK_ACTION: "user_bulk_action",
+    /** A moderation report resolved, dismissed or actioned. */
+    MODERATION_DECISION: "moderation_decision",
+    /** A payment case claimed or resolved — money a buyer says did not arrive. */
+    PAYMENT_CASE_DECISION: "payment_case_decision",
+    /**
+     * A scammer profile edited.
+     *
+     * 🛑 Public-facing accusation. The profile names a person or a payment
+     * handle, so the wording and the status are reputational — and the one
+     * question that follows a complaint is who wrote it.
+     */
+    SCAMMER_PROFILE_UPDATE: "scammer_profile_update",
 };
 export const ADMIN_AUDIT_LOG_FIELDS = {
     ACTOR_UID: "actorUid",

package/dist/features/auth/actions/profile-actions.d.ts

@@ -23,6 +23,64 @@ export type UpdateProfileInput = {
 export declare function updateUserProfile(userId: string, input: UpdateProfileInput): Promise<UserDocument>;
 export declare function getUserProfile(userId: string): Promise<UserDocument | null>;
 export declare function getUserSessions(userId: string): Promise<import("..").SessionDocument[]>;
+/**
+ * What an account has actually DONE, counted from the collections that record
+ * it rather than read off `users/{uid}.stats`.
+ *
+ * 🛑 `users/{uid}.stats.*` HAS NO WRITER. Measured 2026-10-23: every occurrence
+ * of `stats.totalOrders` / `auctionsWon` / `itemsSold` / `reviewsCount` across
+ * both repos is a READ, and the only `stats.itemsSold` write in the codebase is
+ * `StoreRepository`'s, on the STORE document. So the stored numbers are
+ * whatever `users-seed-data.ts` hardcoded — the admin persona ships
+ * `{ totalOrders: 20, auctionsWon: 2, itemsSold: 200 }` — and a real signup gets
+ * `DEFAULT_USER_DATA.stats`, all zeros, which stay zero after twenty orders.
+ *
+ * A number nobody maintains is worse than no number: it is indistinguishable
+ * from a maintained one at every call site. These are counted live instead.
+ *
+ * ## Cost
+ *
+ * Three Firestore AGGREGATIONS, in parallel — billed at one read per 1000 index
+ * entries matched, so ~3 reads for any real account and flat as history grows.
+ * That is what makes this affordable on `GET /api/user/profile`, which the
+ * session hits on every page load. Never replace one with `findByUser(...).length`:
+ * that downloads the whole history to learn its size.
+ *
+ * ## Failure is `undefined`, never 0
+ *
+ * A failed count means "unknown", and 0 means "none" — Root Cause #72's rule.
+ * Callers render nothing for `undefined`, so a transient Firestore error hides
+ * a tile rather than telling a buyer with 30 orders that they have none.
+ */
+export interface BuyerActivityStats {
+    /** Orders this account placed, all lanes. */
+    totalOrders?: number;
+    /** Orders that came from winning (or buying out) an auction. */
+    auctionsWon?: number;
+    /** Reviews this account WROTE — the set `/user/reviews` lists. */
+    reviewsCount?: number;
+}
+/**
+ * 🛑 React.cache-wrapped: `/api/user/profile` and the public profile page can
+ * both ask for the same uid inside one request, and three aggregations is a
+ * cost worth paying once.
+ */
+export declare const getBuyerActivityStats: (uid: string) => Promise<BuyerActivityStats>;
+/**
+ * Buyer activity plus, for an account that owns a store, the one SELLER number
+ * that is genuinely maintained.
+ *
+ * `stores/{storeId}.stats.itemsSold` has real writers — `incrementItemsSold`
+ * from the fulfilment trigger and `setStats` from the nightly reconciliation —
+ * unlike its namesake on the user document. It is read here, from the store, so
+ * a seller's PUBLIC profile can keep showing it honestly.
+ *
+ * It deliberately does NOT reach the sidebar's own profile block, which is the
+ * buyer's view of their own account: see `AppLayoutShell`.
+ */
+export declare function getProfileStats(user: Pick<UserDocument, "uid" | "id" | "storeId">): Promise<BuyerActivityStats & {
+    itemsSold?: number;
+}>;
 /**
  * Resolve a profile by slug, then document id, then Auth uid.
  *
@@ -51,8 +109,18 @@ export declare function resolveProfileUser(identifier: string): Promise<UserDocu
  * page + generateMetadata pair is memoised per argument list, so the second call
  * is free. Note it caches the NARROW public projection, which is what both
  * callers want; anything needing the whole document still goes to the repository.
+ *
+ * 🛑 `stats` is DERIVED by `getProfileStats`, not `user.stats`. The stored field
+ * has no writer and is seed fiction — see `getBuyerActivityStats`. It is derived
+ * here as well as on the session endpoint deliberately: fixing only the sidebar
+ * would have left a signed-in user reading real counts in the nav and seeded
+ * ones on their own public profile, which is a worse state than both being wrong.
  */
-export declare const getPublicUserProfile: (userId: string) => Promise<Pick<UserDocument, "id" | "slug" | "displayName" | "photoURL" | "role" | "createdAt" | "storeId" | "storeSlug" | "publicProfile" | "stats"> | null>;
+export declare const getPublicUserProfile: (userId: string) => Promise<(Pick<UserDocument, "id" | "slug" | "displayName" | "photoURL" | "role" | "createdAt" | "storeId" | "storeSlug" | "publicProfile"> & {
+    stats: BuyerActivityStats & {
+        itemsSold?: number;
+    };
+}) | null>;
 /** Fetch approved reviews for a store. storeId === storeSlug in this project. */
 export declare function getSellerReviews(storeId: string): Promise<Review[]>;
 export declare function getProfileStoreProducts(storeId: string): Promise<import("../../products").ProductDocument[]>;

package/dist/features/auth/actions/profile-actions.js

@@ -12,6 +12,8 @@ import { sessionRepository } from "../repository/session.repository.js";
 import { productRepository } from "../../products/repository/products.repository.js";
 import { ProductStatusValues } from "../../products/schemas/index.js";
 import { reviewRepository } from "../../reviews/repository/reviews.repository.js";
+import { orderRepository } from "../../orders/repository/orders.repository.js";
+import { storeRepository } from "../../stores/repository/store.repository.js";
 export async function updateUserProfile(userId, input) {
     const finalPhotoURL = await finalizeStagedMediaField(input.photoURL);
     const data = finalPhotoURL !== undefined ? { ...input, photoURL: finalPhotoURL } : input;
@@ -23,6 +25,59 @@ export async function getUserProfile(userId) {
 export async function getUserSessions(userId) {
     return sessionRepository.findAllByUser(userId);
 }
+/**
+ * 🛑 React.cache-wrapped: `/api/user/profile` and the public profile page can
+ * both ask for the same uid inside one request, and three aggregations is a
+ * cost worth paying once.
+ */
+export const getBuyerActivityStats = cache(async function getBuyerActivityStats(uid) {
+    const route = "profile:buyer-activity-stats";
+    const [totalOrders, auctionsWon, reviewsCount] = await Promise.all([
+        safeRead(() => orderRepository.countForUser(uid), {
+            route,
+            key: "orders:total",
+            fallback: undefined,
+        }),
+        safeRead(() => orderRepository.countForUser(uid, "auction"), {
+            route,
+            key: "orders:auction",
+            fallback: undefined,
+        }),
+        safeRead(() => reviewRepository.countByUser(uid), {
+            route,
+            key: "reviews:written",
+            fallback: undefined,
+        }),
+    ]);
+    return { totalOrders, auctionsWon, reviewsCount };
+});
+/**
+ * Buyer activity plus, for an account that owns a store, the one SELLER number
+ * that is genuinely maintained.
+ *
+ * `stores/{storeId}.stats.itemsSold` has real writers — `incrementItemsSold`
+ * from the fulfilment trigger and `setStats` from the nightly reconciliation —
+ * unlike its namesake on the user document. It is read here, from the store, so
+ * a seller's PUBLIC profile can keep showing it honestly.
+ *
+ * It deliberately does NOT reach the sidebar's own profile block, which is the
+ * buyer's view of their own account: see `AppLayoutShell`.
+ */
+export async function getProfileStats(user) {
+    const uid = user.uid ?? user.id;
+    const [activity, itemsSold] = await Promise.all([
+        getBuyerActivityStats(uid),
+        user.storeId
+            ? safeRead(async () => (await storeRepository.findById(user.storeId))?.stats
+                ?.itemsSold, {
+                route: "profile:store-items-sold",
+                key: "store:itemsSold",
+                fallback: undefined,
+            })
+            : Promise.resolve(undefined),
+    ]);
+    return { ...activity, itemsSold };
+}
 /**
  * Resolve a profile by slug, then document id, then Auth uid.
  *
@@ -59,6 +114,12 @@ export async function resolveProfileUser(identifier) {
  * page + generateMetadata pair is memoised per argument list, so the second call
  * is free. Note it caches the NARROW public projection, which is what both
  * callers want; anything needing the whole document still goes to the repository.
+ *
+ * 🛑 `stats` is DERIVED by `getProfileStats`, not `user.stats`. The stored field
+ * has no writer and is seed fiction — see `getBuyerActivityStats`. It is derived
+ * here as well as on the session endpoint deliberately: fixing only the sidebar
+ * would have left a signed-in user reading real counts in the nav and seeded
+ * ones on their own public profile, which is a worse state than both being wrong.
  */
 export const getPublicUserProfile = cache(async function getPublicUserProfile(userId) {
     const user = await resolveProfileUser(userId);
@@ -74,7 +135,7 @@ export const getPublicUserProfile = cache(async function getPublicUserProfile(us
         storeId: user.storeId,
         storeSlug: user.storeSlug,
         publicProfile: user.publicProfile,
-        stats: user.stats,
+        stats: await getProfileStats(user),
     };
 });
 /** Fetch approved reviews for a store. storeId === storeSlug in this project. */