@mohasinac/appkit 4.52.5 → 4.53.1

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

@@ -1,5 +1,6 @@
 export * from "./firestore";
 import { z } from "zod";
+import type { ListingType } from "../types/index";
 export declare const productImageSchema: z.ZodObject<{
     url: z.ZodString;
     thumbnailUrl: z.ZodOptional<z.ZodString>;
@@ -46,19 +47,6 @@ export declare const printMetaSchema: z.ZodObject<{
     finish?: string | undefined;
     editionSize?: number | undefined;
 }>;
-/**
- * Base Zod schema for a product item.
- * Apps can extend this to add their own fields:
- *
- * @example
- * import { productItemSchema } from "@mohasinac/feat-products";
- *
- * const myProductSchema = productItemSchema.extend({
- *   brand: z.string(),
- *   auctionEndDate: z.string().optional(),
- * });
- * type MyProduct = z.infer<typeof myProductSchema>;
- */
 export declare const productItemSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
@@ -130,7 +118,8 @@ export declare const productItemSchema: z.ZodObject<{
     sellerAvatar: z.ZodOptional<z.ZodString>;
     status: z.ZodEnum<["draft", "published", "in_review", "archived"]>;
     condition: z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken", "graded"]>>;
-    listingType: z.ZodOptional<z.ZodEnum<["standard", "auction", "pre-order", "prize-draw", "classified", "digital-code", "live"]>>;
+    madeToOrder: z.ZodOptional<z.ZodBoolean>;
+    listingType: z.ZodOptional<z.ZodEnum<[ListingType, ...ListingType[]]>>;
     maxPerUser: z.ZodOptional<z.ZodNumber>;
     partOfBundleIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     partOfBundleTitles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -337,7 +326,7 @@ export declare const productItemSchema: z.ZodObject<{
     } | undefined;
     createdAt?: string | undefined;
     updatedAt?: string | undefined;
-    listingType?: "classified" | "standard" | "auction" | "pre-order" | "prize-draw" | "digital-code" | "live" | undefined;
+    listingType?: ListingType | undefined;
     category?: string | undefined;
     categorySlug?: string | undefined;
     storeId?: string | undefined;
@@ -359,6 +348,7 @@ export declare const productItemSchema: z.ZodObject<{
     description?: string | undefined;
     subcategory?: string | undefined;
     availableQuantity?: number | undefined;
+    madeToOrder?: boolean | undefined;
     mainImage?: string | undefined;
     images?: string[] | undefined;
     featured?: boolean | undefined;
@@ -476,7 +466,7 @@ export declare const productItemSchema: z.ZodObject<{
     } | undefined;
     createdAt?: string | undefined;
     updatedAt?: string | undefined;
-    listingType?: "classified" | "standard" | "auction" | "pre-order" | "prize-draw" | "digital-code" | "live" | undefined;
+    listingType?: ListingType | undefined;
     category?: string | undefined;
     categorySlug?: string | undefined;
     storeId?: string | undefined;
@@ -498,6 +488,7 @@ export declare const productItemSchema: z.ZodObject<{
     description?: string | undefined;
     subcategory?: string | undefined;
     availableQuantity?: number | undefined;
+    madeToOrder?: boolean | undefined;
     mainImage?: string | undefined;
     images?: string[] | undefined;
     featured?: boolean | undefined;
@@ -612,7 +603,7 @@ export declare const productListParamsSchema: z.ZodObject<{
     minPrice: z.ZodOptional<z.ZodNumber>;
     maxPrice: z.ZodOptional<z.ZodNumber>;
     inStock: z.ZodOptional<z.ZodBoolean>;
-    listingType: z.ZodOptional<z.ZodEnum<["standard", "auction", "pre-order", "prize-draw", "classified", "digital-code", "live"]>>;
+    listingType: z.ZodOptional<z.ZodEnum<[ListingType, ...ListingType[]]>>;
     storeId: z.ZodOptional<z.ZodString>;
     sort: z.ZodOptional<z.ZodString>;
     page: z.ZodOptional<z.ZodNumber>;
@@ -623,8 +614,7 @@ export declare const productListParamsSchema: z.ZodObject<{
     status?: "published" | "draft" | "in_review" | "archived" | undefined;
     page?: number | undefined;
     q?: string | undefined;
-    perPage?: number | undefined;
-    listingType?: "classified" | "standard" | "auction" | "pre-order" | "prize-draw" | "digital-code" | "live" | undefined;
+    listingType?: ListingType | undefined;
     category?: string | undefined;
     storeId?: string | undefined;
     featured?: boolean | undefined;
@@ -632,13 +622,13 @@ export declare const productListParamsSchema: z.ZodObject<{
     minPrice?: number | undefined;
     maxPrice?: number | undefined;
     inStock?: boolean | undefined;
+    perPage?: number | undefined;
 }, {
     sort?: string | undefined;
     status?: "published" | "draft" | "in_review" | "archived" | undefined;
     page?: number | undefined;
     q?: string | undefined;
-    perPage?: number | undefined;
-    listingType?: "classified" | "standard" | "auction" | "pre-order" | "prize-draw" | "digital-code" | "live" | undefined;
+    listingType?: ListingType | undefined;
     category?: string | undefined;
     storeId?: string | undefined;
     featured?: boolean | undefined;
@@ -646,4 +636,5 @@ export declare const productListParamsSchema: z.ZodObject<{
     minPrice?: number | undefined;
     maxPrice?: number | undefined;
     inStock?: boolean | undefined;
+    perPage?: number | undefined;
 }>;

package/dist/features/products/schemas/index.js

@@ -1,6 +1,7 @@
 export * from "./firestore.js";
 import { z } from "zod";
 import { mediaFieldSchema } from "../../media/types/index.js";
+import { ALL_LISTING_TYPES } from "../../../_internal/shared/listing-types/feature-flags.js";
 import { PRIZE_DRAW_DURATION_DAYS_MIN, PRIZE_DRAW_DURATION_DAYS_MAX, } from "../../../_internal/shared/checkout/rules/_limits.js";
 // --- Sub-schemas --------------------------------------------------------------
 export const productImageSchema = z.object({
@@ -35,6 +36,25 @@ export const printMetaSchema = z.object({
  * });
  * type MyProduct = z.infer<typeof myProductSchema>;
  */
+/**
+ * The `ListingType` union as a Zod enum, DERIVED.
+ *
+ * 🛑 Two hand-written copies of this lived in this file and BOTH had drifted to
+ * seven of nine — `art` and `stickers` were missing from the item schema and
+ * from the query schema. Consequence: `productItemSchema.parse()` stripped
+ * `listingType` off every art and sticker row (the field is `.optional()`, so a
+ * value outside the enum is a parse FAILURE, and a caller using `safeParse` or
+ * `.partial()` loses it silently), and `?listingType=art` on any route
+ * validating against the query schema was rejected as an invalid value.
+ *
+ * `z.enum` needs a non-empty literal tuple, hence the cast — `ALL_LISTING_TYPES`
+ * is derived from `Record<ListingType, true>`, so its CONTENTS are
+ * compile-checked against the union even though its length is not.
+ *
+ * Registered in `audit-listing-type-tab-coverage`'s STAYS_DERIVED so nobody
+ * re-expands it into a literal for readability.
+ */
+const LISTING_TYPE_ENUM = z.enum(ALL_LISTING_TYPES);
 export const productItemSchema = z.object({
     id: z.string(),
     title: z.string(),
@@ -78,9 +98,8 @@ export const productItemSchema = z.object({
     ])
         .optional(),
     // SB1-G Phase 4 — canonical discriminator (legacy `isAuction`/`isPreOrder` booleans removed).
-    listingType: z
-        .enum(["standard", "auction", "pre-order", "prize-draw", "classified", "digital-code", "live"])
-        .optional(),
+    madeToOrder: z.boolean().optional(),
+    listingType: LISTING_TYPE_ENUM.optional(),
     // SB1-C — prize-draw + bundle fields. All optional.
     maxPerUser: z.number().int().positive().optional(),
     partOfBundleIds: z.array(z.string()).optional(),
@@ -229,9 +248,7 @@ export const productListParamsSchema = z.object({
     minPrice: z.coerce.number().optional(),
     maxPrice: z.coerce.number().optional(),
     inStock: z.coerce.boolean().optional(),
-    listingType: z
-        .enum(["standard", "auction", "pre-order", "prize-draw", "classified", "digital-code", "live"])
-        .optional(),
+    listingType: LISTING_TYPE_ENUM.optional(),
     storeId: z.string().optional(),
     sort: z.string().optional(),
     page: z.coerce.number().optional(),

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

@@ -11,12 +11,34 @@ export type ProductCondition = "new" | "like_new" | "good" | "fair" | "poor" | "
  * accepts legacy alias tokens (`preorder` → `pre-order`, `product` → `standard`)
  * but stored values are always one of these five.
  */
-export type ListingType = "standard" | "auction" | "pre-order" | "prize-draw" | "classified" | "digital-code" | "live" | "art" | "stickers";
+export type ListingType = "standard" | "auction" | "pre-order" | "prize-draw" | "classified" | "digital-code" | "live" | "art" | "stickers" | "spares";
+/**
+ * One gallery image — THE single definition, used by both the Firestore
+ * document and the client shape.
+ *
+ * 🛑 This interface already existed here, barrel-exported as public API, with
+ * ZERO consumers anywhere and `Product.images` declared `string[]` beside it:
+ * a speculative type describing a shape nothing produced or read. Plan A6
+ * resurrected it rather than declaring a second `ProductImage` in
+ * `schemas/firestore.ts`, which is what the first draft did — two same-named
+ * types in one package is a defect even when both look plausible, and the
+ * barrel's choice between them is invisible at every call site (Root Cause
+ * #36). `schemas/firestore.ts` imports this one.
+ *
+ * `alt` is the point: measured across the fifteen-site competitor crawl,
+ * per-image alt coverage is ~0% (0/151, 0/306, 0/317; tcgrepublic's 37/63 is
+ * the best anyone manages). `width`/`height` let `next/image` reserve space so
+ * a gallery does not reflow as each image lands — optional because we do not
+ * always know them at write time, and a guessed aspect ratio is worse than
+ * none.
+ */
 export interface ProductImage {
     url: string;
     thumbnailUrl?: string;
     alt?: string;
     order?: number;
+    width?: number;
+    height?: number;
 }
 export interface ProductSeo {
     title?: string;
@@ -78,6 +100,28 @@ export interface ProductItem {
     sublistingIcon?: string;
     isOnSale?: boolean;
     isSold?: boolean;
+    /**
+     * Printed or built when ordered, so stock does not gate it. Per-LISTING, not
+     * implied by `listingType` — a seller can hold a finite run of pre-cut sheets
+     * and also offer a print-on-demand one.
+     *
+     * On the client this drives three things: the PDP says "made to order"
+     * instead of a stock line, the group picker uncaps that member's stepper, and
+     * `baseAvailable` keeps the row in the default scope at quantity 0.
+     */
+    madeToOrder?: boolean;
+    /**
+     * Self-assembled-selection rules, present only on a group PARENT. See
+     * `_internal/shared/features/products/group-rules.ts` for the shape, the
+     * resolver and the single enforcement point — these fields exist here only
+     * so the admin editor (`GroupSettingsPanel`'s `groupRules` prop) can seed its
+     * form from the product it is already showing, with no second fetch.
+     */
+    groupMinMembers?: number;
+    groupMaxMembers?: number;
+    groupMaxUnitsPerMember?: number;
+    groupRequiredMemberIds?: string[];
+    groupDiscountPercent?: number;
     inStock?: boolean;
     stockCount?: number;
     rating?: number;
@@ -205,7 +249,7 @@ export interface ProductListParams {
     storeId?: string;
     sort?: string;
     page?: number;
-    perPage?: number;
+    pageSize?: number;
     featured?: boolean;
     /** Auction-specific: current bid range */
     minBid?: number;

package/dist/features/products/utils/group-member-image.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The thumbnail for one product-group member, from whichever shape the caller
+ * supplied.
+ *
+ * ── 🛑 WHY `image` IS TRIED FIRST ──────────────────────────────────────────
+ *
+ * `toPublicGroupMember` is an ALLOW-LIST projection: it emits the singular
+ * `image` (`images[0].url ?? mainImage`) and no `images[]` array at all. So a
+ * component reading only `images[0]` resolves `undefined` for every member
+ * served by the public endpoint and renders a placeholder tile.
+ *
+ * That was live on every product-group page — all seven BX-53 members showed
+ * a grey box while their images sat in Storage serving HTTP 200. Nothing
+ * errors, because an empty `src` is a legal `MediaImage`.
+ *
+ * The `images[0]` fallback stays for callers that pass a raw document rather
+ * than the projection.
+ *
+ * ── 🛑 WHY ITS OWN MODULE, AND NOT EITHER COMPONENT ────────────────────────
+ *
+ * `ShowGroupSection` renders `GroupMemberPicker`, so the import edge between
+ * them already runs one way. Putting the shared helper in either file and
+ * importing it from the other closes a CYCLE — which is exactly what
+ * `audit-import-cycles` caught when the first version of this fix exported it
+ * from `ShowGroupSection`.
+ *
+ * A helper used by two components belongs beside neither (Root Cause #18:
+ * import from the module that DEFINES the symbol). One definition, two
+ * importers, no edge between them — and one rule reachable by copy-paste is
+ * one that gets copied wrong (Root Cause #75), which is how the two spellings
+ * diverged in the first place.
+ */
+export interface GroupMemberImageSource {
+    /** The public projection's single thumbnail. */
+    image?: string;
+    /** A raw document's gallery. Only read when `image` is absent. */
+    images?: string[];
+}
+export declare function resolveGroupMemberImage(m: GroupMemberImageSource): string;

package/dist/features/products/utils/group-member-image.js

@@ -0,0 +1,3 @@
+export function resolveGroupMemberImage(m) {
+    return m.image ?? m.images?.[0] ?? "";
+}

package/dist/features/products/utils/listing-badge-variant.js

@@ -15,6 +15,10 @@ import { isListingType } from "./listing-type.js";
  */
 export const LISTING_BADGE_VARIANT = {
     standard: "default",
+    // Shares `primary` with art/stickers: all three are "a thing we make or
+    // salvage ourselves" rather than a mechanism (auction) or a promise
+    // (pre-order), and the badge LABEL is what distinguishes them.
+    spares: "primary",
     auction: "warning",
     "pre-order": "secondary",
     "prize-draw": "primary",

package/dist/features/promotions/api/route.js

@@ -64,7 +64,7 @@ export async function GET(request) {
             filters,
             sort,
             page,
-            perPage: pageSize,
+            pageSize: pageSize,
         });
         const totalPages = Math.max(1, Math.ceil(result.total / pageSize));
         const body = {

package/dist/features/reviews/actions/review-actions.d.ts

@@ -5,7 +5,7 @@
  * Auth and rate-limit stay in consumer server-action wrappers.
  */
 import type { FirebaseSieveResult } from "../../../providers/db-firebase";
-import type { ReviewDocument } from "../schemas";
+import type { ReviewPlain, ReviewDocument } from "../schemas";
 export interface CreateReviewActionInput {
     productId: string;
     rating: number;
@@ -22,7 +22,7 @@ export interface UpdateReviewActionInput {
     images?: string[];
     videoUrl?: string | null;
 }
-export declare function createReview(userId: string, input: CreateReviewActionInput): Promise<ReviewDocument>;
+export declare function createReview(userId: string, input: CreateReviewActionInput): Promise<ReviewPlain>;
 export declare function updateReview(userId: string, reviewId: string, input: UpdateReviewActionInput): Promise<ReviewDocument | null>;
 export declare function deleteReview(userId: string, reviewId: string): Promise<void>;
 export declare function adminUpdateReview(adminId: string, reviewId: string, input: UpdateReviewActionInput): Promise<ReviewDocument | null>;
@@ -35,13 +35,13 @@ export declare function voteReviewHelpful(reviewId: string, helpful: boolean, us
     counted: boolean;
     helpfulCount: number;
 }>;
-export declare function listReviewsByProduct(productId: string, page?: number, pageSize?: number): Promise<FirebaseSieveResult<ReviewDocument>>;
+export declare function listReviewsByProduct(productId: string, page?: number, pageSize?: number): Promise<FirebaseSieveResult<ReviewPlain>>;
 export declare function listAdminReviews(params?: {
     filters?: string;
     sorts?: string;
     page?: number;
     pageSize?: number;
-}): Promise<FirebaseSieveResult<ReviewDocument>>;
-export declare function listReviewsBySeller(sellerId: string): Promise<ReviewDocument[]>;
-export declare function getHomepageReviews(): Promise<ReviewDocument[]>;
+}): Promise<FirebaseSieveResult<ReviewPlain>>;
+export declare function listReviewsBySeller(sellerId: string): Promise<ReviewPlain[]>;
+export declare function getHomepageReviews(): Promise<ReviewPlain[]>;
 export declare function getReviewById(id: string): Promise<ReviewDocument | null>;

package/dist/features/reviews/actions/review-actions.js

@@ -7,7 +7,6 @@
 import { sortBy } from "@mohasinac/appkit";
 import { AuthorizationError, NotFoundError, ValidationError, } from "../../../errors/index.js";
 import { serverLogger } from "../../../monitoring/index.js";
-import { maskPublicReview } from "../../../security/index.js";
 import { finalizeStagedMediaArray, finalizeStagedMediaUrl, } from "../../media/finalize.js";
 import { reviewRepository } from "../repository/reviews.repository.js";
 import { safeRead } from "../../../errors/safe-read.js";
@@ -29,7 +28,7 @@ export async function createReview(userId, input) {
         uid: userId,
         productId: input.productId,
     });
-    return reviewRepository.create({
+    return reviewRepository.createReview({
         productId: input.productId,
         productTitle: product.title,
         listingType: product.listingType,
@@ -162,10 +161,14 @@ export async function listReviewsByProduct(productId, page = 1, pageSize = 10) {
         page,
         pageSize,
     });
-    return {
-        ...result,
-        items: result.items.map((item) => maskPublicReview(item)),
-    };
+    /*
+     * No second mask. `reviewRepository.listAll` returns `ReviewPlain` already
+     * masked by `maskSieveResult`, so `maskPublicReview` here would mask an
+     * already-masked name — and worse, it was being handed ciphertext before
+     * that method was converted, where `maskName`'s `hasEncPrefix` guard answers
+     * "Anonymous" for every row.
+     */
+    return result;
 }
 export async function listAdminReviews(params) {
     const sieve = {
@@ -199,11 +202,22 @@ export async function listReviewsBySeller(sellerId) {
     return reviewBatches
         .flat()
         .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime())
-        .map((item) => maskPublicReview(item));
+        /*
+         * `maskedReview`, not `maskPublicReview`.
+         *
+         * These come from `findApprovedByStore`, a `find*` method that returns raw
+         * documents — only the three `list*` methods mask. `maskPublicReview`
+         * calls `maskName`, which refuses ciphertext by design and answers
+         * "Anonymous", so this public list showed every reviewer as Anonymous.
+         * `maskedReview` decrypts first, then masks.
+         */
+        .map((item) => reviewRepository.maskedReview(item));
 }
 export async function getHomepageReviews() {
     const reviews = await reviewRepository.findFeatured(18);
-    return reviews.map((item) => maskPublicReview(item));
+    // `findFeatured` returns raw documents — see the note above on why
+    // `maskPublicReview` cannot be used on them.
+    return reviews.map((item) => reviewRepository.maskedReview(item));
 }
 export async function getReviewById(id) {
     return reviewRepository.findById(id);

package/dist/features/reviews/components/ReviewDetailPageView.js

@@ -11,7 +11,19 @@ export async function ReviewDetailPageView({ id }) {
     // become the same `null` a removed review produces, which the "Review not
     // found" branch below already handles.
     const doc = await reviewRepository.findById(id);
-    const review = doc;
+    /*
+     * 🛑 MASKED, not the raw document.
+     *
+     * `findById` returns ciphertext since `mapDoc` stopped decrypting, and
+     * `ReviewDetailShell` calls `maskName(review.userName)` — which refuses
+     * ciphertext by design and answers "Anonymous". So this page rendered every
+     * reviewer as "Anonymous". `maskedReview` decrypts and then masks, which is
+     * what the shell was always assuming it had been handed.
+     *
+     * The `as Review` cast is what hid it: it erased the brand, so nothing in
+     * the type system could object.
+     */
+    const review = (doc ? reviewRepository.maskedReview(doc) : null);
     // storeId === storeSlug for stores in this project (pure slug IDs)
     const storeSlug = doc?.storeId ?? null;
     if (!review || review.status !== "approved") {

package/dist/features/reviews/components/ReviewsIndexPageView.js

@@ -31,20 +31,37 @@ function buildReviewFilters(params) {
         parts.push(sieveFilter("createdAt", SIEVE_OP.GTE, dateFrom));
     if (dateTo)
         parts.push(sieveFilter("createdAt", SIEVE_OP.LTE, dateTo));
-    const q = sp(params, "q");
-    if (q)
-        parts.push(`productTitle@=*${q}`);
+    /*
+     * 🛑 `q` is deliberately NOT a filter clause, and emitting it as one was a
+     * live defect rather than an untidy spelling.
+     *
+     * `productTitle@=*` is a case-insensitive operator the Firebase adapter
+     * THROWS on, and the Sieve processor runs `throwExceptions: false` — so the
+     * throw became silence and **every clause and the sort were discarded with
+     * it**. `/reviews?q=anything` therefore returned the whole table, newest-ish,
+     * ignoring rating, verified, date range and vote filters too.
+     *
+     * `/api/reviews` fixed exactly this and passes `q` to `listAll` as a
+     * `{ search }` OPT (array-contains over `searchTxt`, which Sieve cannot
+     * express). This SSR view queries the same collection and never got the
+     * back-port — Root Cause #99, which says in as many words: when fixing a
+     * filter in an API route, grep for the SSR view that queries the same
+     * collection. It is also why the view could not self-correct: it hands its
+     * result down as `initialData`, and `staleTime: Infinity` freezes an
+     * unfiltered first paint for that query key forever (Root Cause #30).
+     */
     return parts.join(",");
 }
 export async function ReviewsIndexPageView({ searchParams = {} }) {
     const sort = sp(searchParams, "sort") || "-createdAt";
     const page = Number(sp(searchParams, "page")) || 1;
     const filters = buildReviewFilters(searchParams);
+    const q = sp(searchParams, "q");
     // audit-public-test-data-ok: `ReviewDocument` carries no `isTestData` field —
     // tsc rejects the filter outright, which is the honest signal that reviews
     // have no sandbox concept to strip. A review OF a sandbox product is not
     // flagged today; that is a seed-schema gap, not something a cast should hide.
-    const result = await safeRead(() => reviewRepository.listAll({ filters, sorts: sort, page, pageSize: 12 }), { route: "/reviews", key: "reviews.listAll", fallback: null });
+    const result = await safeRead(() => reviewRepository.listAll({ filters, sorts: sort, page, pageSize: 12 }, q ? { search: q } : undefined), { route: "/reviews", key: "reviews.listAll", fallback: null });
     const initialData = result
         ? {
             items: result.items,

package/dist/features/reviews/components/ReviewsList.js

@@ -29,7 +29,7 @@ export function ReviewCard({ review, context = "general", className = "" }) {
     const showProductLink = context !== "listing" && !!productHref;
     const showProfileLink = !!profileHref;
     const hasFooter = showStoreLink || showProductLink || showProfileLink;
-    return (_jsxs(Stack, { padding: "5", shadow: "hover-md", className: `group h-full border border-neutral-200 transition ${className}`, rounded: "xl", surface: "default", children: [_jsxs(Link, { href: reviewHref, className: "flex flex-col flex-1 min-h-0", children: [_jsxs(Row, { align: "start", gap: "3", children: [review.userAvatar ? (_jsx(Div, { className: "relative h-9 w-9 flex-shrink-0", rounded: "full", overflow: "hidden", children: _jsx(MediaImage, { src: review.userAvatar, alt: displayName, size: "avatar" }) })) : (_jsx(Row, { textWeight: "medium", textSize: "sm", className: "h-9 w-9 flex-shrink-0 bg-neutral-200 text-[var(--appkit-color-text-muted)]", align: "center", justify: "center", rounded: "full", children: initials })), _jsxs(Div, { className: "flex-1 min-w-0", children: [_jsxs(Row, { wrap: true, gap: "sm", children: [_jsx(Span, { color: "inverse", weight: "medium", className: "text-[var(--appkit-color-text)] dark:", children: displayName }), review.verified && (_jsx(Span, { color: "success", surface: "success-surface", size: "xs", weight: "medium", rounded: "full", padding: "pill-xs", children: "Verified" })), date && (_jsx(Span, { size: "xs", color: "muted", children: date }))] }), _jsx(Div, { className: "mt-1", children: _jsx(StarRating, { value: review.rating, size: "sm", readOnly: true }) })] })] }), review.title && (_jsx(Heading, { color: "inverse", level: 4, className: "mt-3 text-[var(--appkit-color-text)] dark:", weight: "semibold", children: review.title })), review.comment && (_jsx(RichText, { html: normalizeRichTextHtml(review.comment), proseClass: "prose prose-sm max-w-none dark:prose-invert prose-p:my-0", className: "mt-2 text-[length:var(--appkit-text-sm)] leading-relaxed text-[var(--appkit-color-text-muted)] text-[var(--appkit-color-text-muted)]" })), review.images && review.images.length > 0 && (_jsx(Row, { wrap: true, gap: "sm", className: "mt-3", children: review.images.map((img, i) => (_jsx(Div, { className: "relative h-16 w-16 flex-shrink-0 border border-neutral-100", rounded: "lg", overflow: "hidden", children: _jsx(MediaImage, { src: img, alt: `Review image ${i + 1}`, size: "thumbnail" }) }, i))) })), (review.helpfulCount ?? 0) > 0 && (_jsxs(Text, { className: "mt-3", color: "faint", size: "xs", children: [review.helpfulCount, " found this helpful"] }))] }), hasFooter && (_jsxs(Stack, { gap: "xs", className: "mt-3 border-t border-neutral-100", padding: "t-sm", children: [showStoreLink && (_jsxs(Link, { href: String(ROUTES.PUBLIC.STORE_DETAIL(review.storeSlug)), className: "flex items-center gap-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-medium text-primary hover:underline", children: [_jsx(Span, { "aria-hidden": "true", children: "\uD83C\uDFEA" }), _jsx(Span, { truncate: true, children: review.storeName })] })), showProductLink && (_jsxs(Link, { href: productHref, className: "flex items-center gap-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] text-[var(--appkit-color-text-muted)] hover:text-neutral-700 hover:text-[var(--appkit-color-text-muted)]", children: [_jsx(Span, { "aria-hidden": "true", children: "\uD83D\uDCE6" }), _jsx(Span, { truncate: true, children: review.productTitle ?? "View Product" }), _jsx(Span, { "aria-hidden": "true", className: "ml-auto text-primary group-hover:translate-x-0.5 transition-transform", children: "\u2192" })] })), showProfileLink && (_jsxs(Link, { href: profileHref, className: "flex items-center gap-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] text-[var(--appkit-color-text-muted)] hover:text-neutral-700 hover:text-[var(--appkit-color-text-muted)]", children: [_jsx(Span, { "aria-hidden": "true", children: "\uD83D\uDC64" }), _jsx(Span, { truncate: true, children: displayName })] }))] }))] }));
+    return (_jsxs(Stack, { padding: "5", shadow: "hover-md", className: `group h-full border border-neutral-200 transition ${className}`, rounded: "xl", surface: "default", children: [_jsxs(Link, { href: reviewHref, className: "flex flex-col flex-1 min-h-0", children: [_jsxs(Row, { align: "start", gap: "3", children: [review.userAvatar ? (_jsx(Div, { className: "relative h-9 w-9 flex-shrink-0", rounded: "full", overflow: "hidden", children: _jsx(MediaImage, { src: review.userAvatar, alt: displayName, size: "avatar" }) })) : (_jsx(Row, { textWeight: "medium", textSize: "sm", className: "h-9 w-9 flex-shrink-0 bg-neutral-200 text-[var(--appkit-color-text-muted)]", align: "center", justify: "center", rounded: "full", children: initials })), _jsxs(Div, { className: "flex-1 min-w-0", children: [_jsxs(Row, { wrap: true, gap: "sm", children: [_jsx(Span, { color: "inverse", weight: "medium", className: "text-[var(--appkit-color-text)] dark:", children: displayName }), review.verified && (_jsx(Span, { color: "success", surface: "success-surface", size: "xs", weight: "medium", rounded: "full", padding: "pill-xs", children: "Verified" })), date && (_jsx(Span, { size: "xs", color: "muted", children: date }))] }), _jsx(Div, { className: "mt-1", children: _jsx(StarRating, { value: review.rating, size: "sm", readOnly: true }) })] })] }), review.title && (_jsx(Heading, { color: "inverse", level: 4, className: "mt-3 text-[var(--appkit-color-text)] dark:", weight: "semibold", children: review.title })), review.comment && (_jsx(RichText, { html: normalizeRichTextHtml(review.comment), proseClass: "prose prose-sm max-w-none dark:prose-invert prose-p:my-0", className: "mt-2 text-[length:var(--appkit-text-sm)] leading-relaxed text-[var(--appkit-color-text-muted)] text-[var(--appkit-color-text-muted)]" })), review.images && review.images.length > 0 && (_jsx(Row, { wrap: true, gap: "sm", className: "mt-3", children: review.images.map((img, i) => (_jsx(Div, { className: "relative h-16 w-16 flex-shrink-0 border border-neutral-100", rounded: "lg", overflow: "hidden", children: _jsx(MediaImage, { src: img, alt: `Review image ${i + 1}`, size: "thumbnail" }) }, i))) })), (review.helpfulCount ?? 0) > 0 && (_jsxs(Text, { className: "mt-3", color: "faint", size: "xs", children: [review.helpfulCount, " found this helpful"] }))] }), hasFooter && (_jsxs(Stack, { gap: "xs", className: "mt-3 border-t border-neutral-100", padding: "t-sm", children: [showStoreLink && (_jsxs(Link, { href: String(ROUTES.PUBLIC.STORE_DETAIL(review.storeSlug)), className: "flex items-center gap-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-medium text-primary hover:underline", children: [_jsx(Span, { "aria-hidden": "true", children: "\uD83C\uDFEA" }), _jsx(Span, { truncate: true, children: review.storeName })] })), showProductLink && (_jsxs(Link, { href: productHref, className: "flex items-center gap-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] hover:text-[var(--appkit-color-text)]", children: [_jsx(Span, { "aria-hidden": "true", children: "\uD83D\uDCE6" }), _jsx(Span, { truncate: true, children: review.productTitle ?? "View Product" }), _jsx(Span, { "aria-hidden": "true", className: "ml-auto text-primary group-hover:translate-x-0.5 transition-transform", children: "\u2192" })] })), showProfileLink && (_jsxs(Link, { href: profileHref, className: "flex items-center gap-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] hover:text-[var(--appkit-color-text)]", children: [_jsx(Span, { "aria-hidden": "true", children: "\uD83D\uDC64" }), _jsx(Span, { truncate: true, children: displayName })] }))] }))] }));
 }
 export function ReviewsList({ reviews, context = "general", isLoading, totalPages = 1, currentPage = 1, onPageChange, emptyLabel = "No reviews yet", }) {
     if (isLoading) {

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

@@ -1,7 +1,7 @@
 import type { JsonValue } from "../../../schemas/types";
 import type { FirebaseSieveResult, SieveModel } from "../../../providers/db-firebase";
 import { BaseRepository, parseSieveDateValue } from "../../../providers/db-firebase";
-import { type ReviewCreateInput, type ReviewDocument } from "../schemas";
+import { type ReviewCreateInput, type ReviewDocument, type ReviewPlain } from "../schemas";
 import type { ReviewStatus } from "../types";
 export interface ReviewRatingAggregate {
     count: number;
@@ -9,7 +9,7 @@ export interface ReviewRatingAggregate {
 }
 declare class ReviewRepository extends BaseRepository<ReviewDocument> {
     constructor();
-    private decryptSieveResult;
+    private maskSieveResult;
     /**
      * Declared, not hand-rolled.
      *
@@ -24,8 +24,20 @@ declare class ReviewRepository extends BaseRepository<ReviewDocument> {
     protected piiFields: readonly ["userName"];
     protected piiIndexMap: Record<string, string>;
     protected mapDoc<D = ReviewDocument>(snap: import("../../../providers/db-firebase").DocumentSnapshot): D;
-    create(input: ReviewCreateInput): Promise<ReviewDocument>;
-    update(reviewId: string, data: Partial<ReviewDocument>): Promise<ReviewDocument>;
+    /** Plaintext PII. **Opt-in and named** — shows up in review and in a grep. */
+    revealReview(doc: ReviewDocument): ReviewPlain;
+    /** As `revealReview`, for a list read. */
+    revealReviews(docs: readonly ReviewDocument[]): ReviewPlain[];
+    /**
+     * Masked PII — **the default for any public surface.** Decrypts first, then
+     * masks: `maskName` returns "Anonymous" for a ciphertext input by design, so
+     * handing it a stored `userName` would anonymise every reviewer.
+     */
+    maskedReview(doc: ReviewDocument): ReviewPlain;
+    /** As `maskedReview`, for a list read. */
+    maskedReviews(docs: readonly ReviewDocument[]): ReviewPlain[];
+    createReview(input: ReviewCreateInput): Promise<ReviewPlain>;
+    update(reviewId: string, data: Partial<ReviewPlain>): Promise<ReviewDocument>;
     findByProduct(productId: string): Promise<ReviewDocument[]>;
     /**
      * Approved reviews for a product, newest first.
@@ -196,8 +208,8 @@ declare class ReviewRepository extends BaseRepository<ReviewDocument> {
             parseValue: typeof parseSieveDateValue;
         };
     };
-    listForProduct(productId: string, model: SieveModel): Promise<FirebaseSieveResult<ReviewDocument>>;
-    listForStore(storeId: string, model: SieveModel): Promise<FirebaseSieveResult<ReviewDocument>>;
+    listForProduct(productId: string, model: SieveModel): Promise<FirebaseSieveResult<ReviewPlain>>;
+    listForStore(storeId: string, model: SieveModel): Promise<FirebaseSieveResult<ReviewPlain>>;
     /**
      * Derived on every write path via `applyWriteHooks`.
      *
@@ -207,7 +219,7 @@ declare class ReviewRepository extends BaseRepository<ReviewDocument> {
     protected buildSearchTxtFor(data: Record<string, JsonValue>): string[] | null;
     listAll(model: SieveModel, opts?: {
         search?: string;
-    }): Promise<FirebaseSieveResult<ReviewDocument>>;
+    }): Promise<FirebaseSieveResult<ReviewPlain>>;
 }
 declare const reviewRepository: ReviewRepository;
 export { ReviewRepository, reviewRepository };