@mohasinac/appkit 4.62.0 → 4.63.0

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

@@ -44,6 +44,76 @@ export declare const AdminAuditActionValues: {
      * same class as `payout_mark_paid` and `coupon_update`, which are both here.
      */
     readonly POINTS_ADJUST: "points_adjust";
+    /**
+     * Staff added a buyer-facing dispute reason.
+     *
+     * 🛑 Here because the list is POLICY VOCABULARY, even though no single row
+     * decides money. The reasons are what buyers are offered when something goes
+     * wrong, so the wording shapes what gets reported and how it is triaged —
+     * and a badly-worded or leading option is the kind of thing that is only
+     * ever noticed later, by which time "who added this, and when" is the
+     * question. `createdByName` on the row answers it for the list; this answers
+     * it in the one place an admin looks for "what have staff done lately".
+     *
+     * Recorded only on a REAL creation. Re-adding wording that already exists
+     * 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 {
@@ -97,5 +167,75 @@ export declare const ADMIN_AUDIT_LOG_FIELDS: {
          * same class as `payout_mark_paid` and `coupon_update`, which are both here.
          */
         readonly POINTS_ADJUST: "points_adjust";
+        /**
+         * Staff added a buyer-facing dispute reason.
+         *
+         * 🛑 Here because the list is POLICY VOCABULARY, even though no single row
+         * decides money. The reasons are what buyers are offered when something goes
+         * wrong, so the wording shapes what gets reported and how it is triaged —
+         * and a badly-worded or leading option is the kind of thing that is only
+         * ever noticed later, by which time "who added this, and when" is the
+         * question. `createdByName` on the row answers it for the list; this answers
+         * it in the one place an admin looks for "what have staff done lately".
+         *
+         * Recorded only on a REAL creation. Re-adding wording that already exists
+         * 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

@@ -42,6 +42,95 @@ export const AdminAuditActionValues = {
      * same class as `payout_mark_paid` and `coupon_update`, which are both here.
      */
     POINTS_ADJUST: "points_adjust",
+    /**
+     * Staff added a buyer-facing dispute reason.
+     *
+     * 🛑 Here because the list is POLICY VOCABULARY, even though no single row
+     * decides money. The reasons are what buyers are offered when something goes
+     * wrong, so the wording shapes what gets reported and how it is triaged —
+     * and a badly-worded or leading option is the kind of thing that is only
+     * ever noticed later, by which time "who added this, and when" is the
+     * question. `createdByName` on the row answers it for the list; this answers
+     * it in the one place an admin looks for "what have staff done lately".
+     *
+     * Recorded only on a REAL creation. Re-adding wording that already exists
+     * 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. */

package/dist/features/auth/permissions/constants.js

@@ -344,6 +344,19 @@ export const ROUTE_PERMISSION_MAP = {
     // Payment protection — admin-only, see the permission union's own 🛑 note.
     "/admin/money-cases": "admin:payment-cases:read",
     "/admin/protection-claims": "admin:protection-claims:read",
+    /*
+     * Phase 7 invoicing — the GSTR-1 draft export.
+     *
+     * 🛑 `settings:write` rather than a new permission, and that is a judgement
+     * worth stating. The page exports the company's tax position for a quarter
+     * plus every buyer's place of supply; the set of people who should see that
+     * is the set who can already change the GSTIN and the fee schedule, which is
+     * exactly what `settings:write` names. Minting
+     * `admin:invoicing:read` would add a permission with one route and one
+     * holder — a distinction with no decision behind it, which is how a
+     * permission union becomes unreadable.
+     */
+    "/admin/invoicing": "admin:settings:write",
 };
 /**
  * Every capability, as a runtime value.

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

@@ -126,12 +126,27 @@ export interface UserDocument extends BaseDocument {
         isVacationMode?: boolean;
         vacationMessage?: string;
     };
+    /**
+     * 🛑 LEGACY AND UNMAINTAINED — do not read these to answer "how many X does
+     * this account have". Nothing in either repo writes them: every occurrence
+     * across the codebase is a read, and the only `stats.itemsSold` write is
+     * `StoreRepository`'s, on the STORE document. The values present in Firestore
+     * today are seed literals.
+     *
+     * `getBuyerActivityStats` / `getProfileStats` count the real collections, and
+     * every surface that showed a number now goes through them.
+     *
+     * Kept on the schema because the documents still carry the field and a
+     * migration to strip it would buy nothing. `rating` was REMOVED outright: it
+     * had no writer AND no buyer-rating concept behind it, so its one reader
+     * (`/admin/users/[id]`) rendered a tile guarded on a value that could never
+     * be set.
+     */
     stats?: {
         totalOrders: number;
         auctionsWon: number;
         itemsSold: number;
         reviewsCount: number;
-        rating?: number;
     };
     metadata?: {
         lastSignInTime?: Date;
@@ -334,7 +349,6 @@ export declare const USER_FIELDS: {
         readonly AUCTIONS_WON: "stats.auctionsWon";
         readonly ITEMS_SOLD: "stats.itemsSold";
         readonly REVIEWS_COUNT: "stats.reviewsCount";
-        readonly RATING: "stats.rating";
     };
     readonly METADATA: "metadata";
     readonly META: {

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

@@ -150,7 +150,8 @@ export const USER_FIELDS = {
         AUCTIONS_WON: "stats.auctionsWon",
         ITEMS_SOLD: "stats.itemsSold",
         REVIEWS_COUNT: "stats.reviewsCount",
-        RATING: "stats.rating",
+        // `RATING` removed — `stats.rating` had no writer and no buyer-rating
+        // concept behind it anywhere in the codebase.
     },
     METADATA: "metadata",
     META: {

package/dist/features/blog/actions/blog-actions.d.ts

@@ -9,6 +9,7 @@ export declare const createBlogPostSchema: z.ZodObject<{
     category: z.ZodEnum<["news", "tips", "guides", "updates", "community"]>;
     tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     isFeatured: z.ZodDefault<z.ZodBoolean>;
+    isPinned: z.ZodDefault<z.ZodBoolean>;
     status: z.ZodDefault<z.ZodEnum<["draft", "published", "archived"]>>;
     coverImage: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodObject<{
         url: z.ZodEffects<z.ZodString, string, string>;
@@ -78,6 +79,7 @@ export declare const createBlogPostSchema: z.ZodObject<{
     isFeatured: boolean;
     excerpt: string;
     readTimeMinutes: number;
+    isPinned: boolean;
     additionalImages: {
         type: "video" | "image" | "file";
         url: string;
@@ -124,6 +126,7 @@ export declare const createBlogPostSchema: z.ZodObject<{
     authorId?: string | undefined;
     authorName?: string | undefined;
     readTimeMinutes?: number | undefined;
+    isPinned?: boolean | undefined;
     additionalImages?: {
         type: "video" | "image" | "file";
         url: string;
@@ -148,6 +151,7 @@ export declare const updateBlogPostSchema: z.ZodObject<{
     category: z.ZodOptional<z.ZodEnum<["news", "tips", "guides", "updates", "community"]>>;
     tags: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString, "many">>>;
     isFeatured: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    isPinned: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
     status: z.ZodOptional<z.ZodDefault<z.ZodEnum<["draft", "published", "archived"]>>>;
     coverImage: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodObject<{
         url: z.ZodEffects<z.ZodString, string, string>;
@@ -229,6 +233,7 @@ export declare const updateBlogPostSchema: z.ZodObject<{
     authorId?: string | undefined;
     authorName?: string | undefined;
     readTimeMinutes?: number | undefined;
+    isPinned?: boolean | undefined;
     additionalImages?: {
         type: "video" | "image" | "file";
         url: string;
@@ -263,6 +268,7 @@ export declare const updateBlogPostSchema: z.ZodObject<{
     authorId?: string | undefined;
     authorName?: string | undefined;
     readTimeMinutes?: number | undefined;
+    isPinned?: boolean | undefined;
     additionalImages?: {
         type: "video" | "image" | "file";
         url: string;