@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/features/business-documents/repository/business-documents.repository.js

@@ -0,0 +1,54 @@
+/**
+ * BusinessDocumentsRepository — thin wrapper over the `businessDocuments`
+ * collection. See `../schemas/firestore.ts` for the doc shape and for why the
+ * bytes are not in Firestore.
+ */
+import { BaseRepository, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
+import { BUSINESS_DOCUMENTS_COLLECTION, } from "../schemas/firestore.js";
+export class BusinessDocumentsRepository extends BaseRepository {
+    constructor() {
+        super(BUSINESS_DOCUMENTS_COLLECTION);
+    }
+    async list(model) {
+        return this.sieveQuery(model, BusinessDocumentsRepository.SIEVE_FIELDS, { defaultPageSize: 25, maxPageSize: 100 });
+    }
+    /**
+     * The current document of a given kind — newest `uploadedAt` wins.
+     *
+     * Re-uploading a re-issued certificate is normal and both copies are kept:
+     * the superseded one is the evidence of what was true at the time, which is
+     * the entire point of keeping a registration document. So this resolves the
+     * current one rather than assuming a single row per kind.
+     *
+     * 🛑 Ordered by `createdAt`, NOT `uploadedAt`, even though the latter reads
+     * more naturally here. `BaseRepository.create()` stamps `createdAt` on every
+     * document it writes, so it is guaranteed present; `uploadedAt` is set by the
+     * caller and a single write path that forgot it would make that row vanish
+     * from this query — a Firestore `orderBy` on a field a document lacks is a
+     * silent `WHERE field IS NOT NULL` (Root Cause #100). The two are written in
+     * the same operation and agree, so there is nothing to gain by taking the
+     * field that can be missed.
+     */
+    async findCurrentByKind(kind) {
+        const result = await this.list({
+            filters: `kind==${kind}`,
+            sorts: "-createdAt",
+            page: 1,
+            pageSize: 1,
+        });
+        return result.items[0] ?? null;
+    }
+}
+BusinessDocumentsRepository.SIEVE_FIELDS = {
+    id: { canFilter: true, canSort: false },
+    kind: { canFilter: true, canSort: true },
+    fileName: { canFilter: true, canSort: true },
+    uploadedBy: { canFilter: true, canSort: false },
+    // Timestamp fields that are filterable MUST carry parseValue, or an ISO
+    // string reaches Firestore as a string, the type does not match the stored
+    // Timestamp, and the query matches ZERO documents with no error anywhere
+    // (Root Cause #47).
+    uploadedAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+    createdAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+};
+export const businessDocumentsRepository = new BusinessDocumentsRepository();

package/dist/features/business-documents/schemas/firestore.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Business Documents Firestore Document Types & Constants
+ *
+ * Collection: businessDocuments
+ * Document ID: Firestore auto-ID (no slug prefix — same convention as
+ * `adminAuditLog` / `notifications` / `sessions` / `jobs`; see CLAUDE.md's
+ * "True Firestore auto-IDs" list).
+ *
+ * The statutory registration documents of the business itself — GST
+ * certificate, Udyam registration, bank passbook. These are NOT product media
+ * and NOT user uploads; there is exactly one current document per `kind`.
+ *
+ * ## 🛑 Metadata only. The bytes are never in Firestore.
+ *
+ * A Firestore document is capped at 1 MiB and the Udyam certificate alone is
+ * 680 KB, which base64-encodes to ~907 KB — so an "encrypt the PDF into a
+ * string field" design is one slightly larger certificate away from an
+ * unrecoverable write failure, at upload time, after the user has handed over
+ * the document. The ciphertext lives in Storage; this collection records where.
+ *
+ * ## 🛑 Why `storagePath` must never be served through /api/media
+ *
+ * `GET /api/media/[...slug]` applies NO authentication — deliberately, because
+ * its job is serving public product photography through a watermarker — and
+ * `storage.rules` is `allow read: if true` for every object in the bucket. So
+ * the only thing standing between these documents and the public internet is
+ * that nothing routes them there, and that they carry no `mediaAssets` row (the
+ * row IS the public `/media/<shortId>` slug, so no row means no public URL).
+ *
+ * Read them through `GET /api/admin/business-documents/[id]` and nothing else.
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+export declare const BUSINESS_DOCUMENTS_COLLECTION = "businessDocuments";
+export declare const BusinessDocumentKindValues: {
+    readonly GST_CERTIFICATE: "gst_certificate";
+    readonly UDYAM_CERTIFICATE: "udyam_certificate";
+    readonly BANK_PASSBOOK: "bank_passbook";
+};
+export type BusinessDocumentKind = (typeof BusinessDocumentKindValues)[keyof typeof BusinessDocumentKindValues];
+export declare const ALL_BUSINESS_DOCUMENT_KINDS: readonly BusinessDocumentKind[];
+/**
+ * A `Record<BusinessDocumentKind, string>` rather than a lookup with a
+ * fallback, so adding a fourth kind is a COMPILE error here instead of
+ * rendering as a raw snake_case id in the admin list.
+ */
+export declare const BUSINESS_DOCUMENT_KIND_LABELS: Record<BusinessDocumentKind, string>;
+export interface BusinessDocumentDocument extends BaseDocument {
+    kind: BusinessDocumentKind;
+    /**
+     * Path inside the Storage bucket, e.g.
+     * `private/business-documents/3f2a…-gst-certificate.pdf`.
+     *
+     * 🛑 Never returned by any API, to anyone. The download route resolves it
+     * server-side and streams the decrypted bytes; handing the path to a client
+     * would let it be fetched straight from Storage, where the rules permit any
+     * read.
+     */
+    storagePath: string;
+    /** Original filename as uploaded — shown in the admin list and used for Content-Disposition. */
+    fileName: string;
+    /** Verified against the file's magic bytes at upload; never trusted from the client. */
+    contentType: string;
+    /** Size of the PLAINTEXT, before the envelope. What an admin expects to see downloaded. */
+    sizeBytes: number;
+    /**
+     * Whether the stored object carries the `enc:v1:` binary envelope.
+     *
+     * Always `true` for anything this codebase writes — `encryptBuffer` throws
+     * rather than degrading when `SETTINGS_ENCRYPTION_KEY` is unset, so there is
+     * no path that produces a plaintext object. It is recorded anyway because
+     * the download route must not GUESS: a future hand-uploaded object would
+     * otherwise be fed to `decryptBuffer` and throw an envelope error that
+     * describes the crypto rather than the upload.
+     */
+    encrypted: boolean;
+    /** Auth UID of the admin who uploaded it. */
+    uploadedBy: string;
+    uploadedAt: Date;
+}
+export declare const BUSINESS_DOCUMENT_FIELDS: {
+    readonly KIND: "kind";
+    readonly STORAGE_PATH: "storagePath";
+    readonly FILE_NAME: "fileName";
+    readonly CONTENT_TYPE: "contentType";
+    readonly SIZE_BYTES: "sizeBytes";
+    readonly ENCRYPTED: "encrypted";
+    readonly UPLOADED_BY: "uploadedBy";
+    readonly UPLOADED_AT: "uploadedAt";
+    readonly CREATED_AT: "createdAt";
+    readonly KIND_VALUES: {
+        readonly GST_CERTIFICATE: "gst_certificate";
+        readonly UDYAM_CERTIFICATE: "udyam_certificate";
+        readonly BANK_PASSBOOK: "bank_passbook";
+    };
+};
+/** Storage prefix. Mirrors `private/digital-content/` — outside any public read path. */
+export declare const BUSINESS_DOCUMENTS_STORAGE_PREFIX = "private/business-documents";
+/**
+ * Accepted upload types. PDFs and scans only.
+ *
+ * Checked against the file's MAGIC BYTES, not the declared Content-Type: a
+ * declared type is a claim by the uploader, and an HTML document served from
+ * this origin would be stored XSS against a signed-in admin.
+ */
+export declare const BUSINESS_DOCUMENT_ALLOWED_TYPES: readonly ["application/pdf", "image/jpeg", "image/png", "image/webp"];

package/dist/features/business-documents/schemas/firestore.js

@@ -0,0 +1,75 @@
+/**
+ * Business Documents Firestore Document Types & Constants
+ *
+ * Collection: businessDocuments
+ * Document ID: Firestore auto-ID (no slug prefix — same convention as
+ * `adminAuditLog` / `notifications` / `sessions` / `jobs`; see CLAUDE.md's
+ * "True Firestore auto-IDs" list).
+ *
+ * The statutory registration documents of the business itself — GST
+ * certificate, Udyam registration, bank passbook. These are NOT product media
+ * and NOT user uploads; there is exactly one current document per `kind`.
+ *
+ * ## 🛑 Metadata only. The bytes are never in Firestore.
+ *
+ * A Firestore document is capped at 1 MiB and the Udyam certificate alone is
+ * 680 KB, which base64-encodes to ~907 KB — so an "encrypt the PDF into a
+ * string field" design is one slightly larger certificate away from an
+ * unrecoverable write failure, at upload time, after the user has handed over
+ * the document. The ciphertext lives in Storage; this collection records where.
+ *
+ * ## 🛑 Why `storagePath` must never be served through /api/media
+ *
+ * `GET /api/media/[...slug]` applies NO authentication — deliberately, because
+ * its job is serving public product photography through a watermarker — and
+ * `storage.rules` is `allow read: if true` for every object in the bucket. So
+ * the only thing standing between these documents and the public internet is
+ * that nothing routes them there, and that they carry no `mediaAssets` row (the
+ * row IS the public `/media/<shortId>` slug, so no row means no public URL).
+ *
+ * Read them through `GET /api/admin/business-documents/[id]` and nothing else.
+ */
+export const BUSINESS_DOCUMENTS_COLLECTION = "businessDocuments";
+export const BusinessDocumentKindValues = {
+    GST_CERTIFICATE: "gst_certificate",
+    UDYAM_CERTIFICATE: "udyam_certificate",
+    BANK_PASSBOOK: "bank_passbook",
+};
+export const ALL_BUSINESS_DOCUMENT_KINDS = Object.values(BusinessDocumentKindValues);
+/**
+ * A `Record<BusinessDocumentKind, string>` rather than a lookup with a
+ * fallback, so adding a fourth kind is a COMPILE error here instead of
+ * rendering as a raw snake_case id in the admin list.
+ */
+export const BUSINESS_DOCUMENT_KIND_LABELS = {
+    [BusinessDocumentKindValues.GST_CERTIFICATE]: "GST Certificate",
+    [BusinessDocumentKindValues.UDYAM_CERTIFICATE]: "Udyam Registration Certificate",
+    [BusinessDocumentKindValues.BANK_PASSBOOK]: "Bank Passbook",
+};
+export const BUSINESS_DOCUMENT_FIELDS = {
+    KIND: "kind",
+    STORAGE_PATH: "storagePath",
+    FILE_NAME: "fileName",
+    CONTENT_TYPE: "contentType",
+    SIZE_BYTES: "sizeBytes",
+    ENCRYPTED: "encrypted",
+    UPLOADED_BY: "uploadedBy",
+    UPLOADED_AT: "uploadedAt",
+    CREATED_AT: "createdAt",
+    KIND_VALUES: BusinessDocumentKindValues,
+};
+/** Storage prefix. Mirrors `private/digital-content/` — outside any public read path. */
+export const BUSINESS_DOCUMENTS_STORAGE_PREFIX = "private/business-documents";
+/**
+ * Accepted upload types. PDFs and scans only.
+ *
+ * Checked against the file's MAGIC BYTES, not the declared Content-Type: a
+ * declared type is a claim by the uploader, and an HTML document served from
+ * this origin would be stored XSS against a signed-in admin.
+ */
+export const BUSINESS_DOCUMENT_ALLOWED_TYPES = [
+    "application/pdf",
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+];

package/dist/features/cart/actions/cart-actions.js

@@ -15,6 +15,7 @@ import { CART_LANE, activeLane, canAddNewItems, } from "../../../_internal/share
 import { CART_MAX_ITEMS } from "../../../constants/limits.js";
 import { getExpandedDecrements, validateCartItemStock, } from "../../../_internal/server/features/checkout/bundle-expansion.js";
 import { safeRead } from "../../../errors/safe-read.js";
+import { checkGroupRules, readGroupRules, } from "../../../_internal/shared/features/products/group-rules.js";
 /**
  * Product documents don't always carry a denormalized `storeName` — the
  * create routes only set it when the caller explicitly passes one, so
@@ -133,7 +134,13 @@ export async function addGroupLineToCart(userId, input) {
         if (!rule.cartEligible) {
             throw new ValidationError(`"${product.title}" can't be added to the cart. ${rule.cartIneligibleHint ?? ""}`.trim());
         }
-        if ((product.availableQuantity ?? 0) < m.quantity) {
+        /*
+         * 🛑 Made to order: no stock CHECK for this member. Nothing is held in
+         * reserve — it is printed or built when the order arrives — so the only
+         * honest answer to "how many are left" is "as many as you want". The
+         * decrement still happens at checkout; see `validateCartItemStock`.
+         */
+        if (product.madeToOrder !== true && (product.availableQuantity ?? 0) < m.quantity) {
             throw new ValidationError(`Only ${product.availableQuantity ?? 0} left of "${product.title}".`);
         }
         resolved.push({
@@ -141,7 +148,7 @@ export async function addGroupLineToCart(userId, input) {
             quantity: m.quantity,
             unitPrice: product.price,
             title: product.title,
-            image: product.images?.[0] ?? product.mainImage,
+            image: product.images?.[0]?.url ?? product.mainImage,
             gstRate: product.gstRate,
             hsnCode: product.hsnCode,
             listingType,
@@ -164,7 +171,7 @@ export async function addGroupLineToCart(userId, input) {
         return addItemToCart(userId, {
             productId: first.id,
             productTitle: first.title,
-            productImage: first.images?.[0] ?? first.mainImage,
+            productImage: first.images?.[0]?.url ?? first.mainImage,
             price: first.price,
             currency: first.currency,
             quantity: resolved[0].quantity,
@@ -192,6 +199,25 @@ export async function addGroupLineToCart(userId, input) {
         throw new ValidationError(`Only ${shortfall.availableQty} left of "${short?.title ?? shortfall.productId}" once your cart is counted.`);
     }
     const groupTitle = await resolveGroupTitle(groupId, groupSource, first ?? null);
+    /*
+     * 🛑 SERVER-SIDE ENFORCEMENT OF THE GROUP'S OWN RULES.
+     *
+     * `GroupMemberPicker` mirrors this so a buyer is not told "no" only after
+     * submitting — but the picker is a convenience and this is the boundary. The
+     * two share `checkGroupRules`, so they cannot disagree about what a valid
+     * selection is; only about WHEN the buyer finds out.
+     *
+     * It throws on the FIRST violation while the picker shows all of them
+     * together, which is each surface doing the right thing for its own job: a
+     * form lists everything to fix, an API answers one reason.
+     */
+    const rules = await resolveGroupRules(groupId, groupSource, first ?? null);
+    const violations = checkGroupRules(rules, resolved.map((r) => ({ productId: r.productId, quantity: r.quantity, title: r.title })));
+    if (violations.length > 0) {
+        throw Object.assign(new ValidationError(violations[0].message), {
+            code: violations[0].code,
+        });
+    }
     return cartRepository.addGroupLine(userId, {
         productId: groupId,
         productTitle: groupTitle,
@@ -208,9 +234,51 @@ export async function addGroupLineToCart(userId, input) {
         groupId,
         groupSlug: groupSource === "product-group" ? groupId : undefined,
         groupTitle,
+        /*
+         * Snapshotted at add time — see `CartItemDocument.groupDiscountPercent`.
+         * Omitted entirely when there is no discount, so a line with no group
+         * pricing carries no field rather than a zero that reads as "0% off".
+         */
+        ...(rules.groupDiscountPercent !== undefined && rules.groupDiscountPercent > 0
+            ? { groupDiscountPercent: rules.groupDiscountPercent }
+            : {}),
         groupMembers: resolved,
     });
 }
+/**
+ * The group's selection rules, from whichever of the two homes owns them.
+ *
+ * 🛑 ONE resolver, because there are TWO homes: a product group keeps them on
+ * its PARENT PRODUCT (identified by the parent's slug, which IS the groupId),
+ * while a `groupedListing` keeps them on its own document. Reading them at each
+ * call site is how the picker and the server come to disagree.
+ *
+ * Fails OPEN — an unreadable group yields no rules rather than refusing the
+ * add. A transient Firestore error must not look like "your selection is
+ * invalid", which is a statement about the buyer's choice and would send them
+ * to change something that was already correct.
+ */
+async function resolveGroupRules(groupId, groupSource, sample) {
+    if (groupSource === "grouped-listing") {
+        const { groupedListingsRepository } = await import("../../grouped/repository/grouped-listings.repository.js");
+        const group = await safeRead(() => groupedListingsRepository.findById(groupId), {
+            route: "/cart", key: "groupedListings.rules", fallback: null,
+        });
+        return readGroupRules(group);
+    }
+    /*
+     * A product group's rules live on the PARENT, and `sample` is an arbitrary
+     * member — so the parent has to be fetched unless the sample happens to BE
+     * it. `groupId` is the parent's slug and products are pure slugs
+     * (`id === slug`), so `findById` resolves it directly.
+     */
+    if (sample?.isGroupParent && sample.id === groupId)
+        return readGroupRules(sample);
+    const parent = await safeRead(() => productRepository.findById(groupId), {
+        route: "/cart", key: "products.groupParentRules", fallback: null,
+    });
+    return readGroupRules(parent);
+}
 /** Is this product listed on that `groupedListings` document? */
 async function isGroupedListingMember(groupId, productId) {
     const { groupedListingsRepository } = await import("../../grouped/repository/grouped-listings.repository.js");
@@ -263,14 +331,23 @@ export async function mergeGuestCart(userId, items) {
         const product = await productRepository.findById(item.productId);
         if (!product || product.status !== "published")
             continue;
-        if (product.availableQuantity < 1)
+        /*
+         * A made-to-order row survives the guest-cart merge at its full requested
+         * quantity. Dropping it (or clamping it to 0) would silently delete the
+         * line a signed-out visitor had chosen, which reads as the cart losing
+         * items on login — and there is no stock level for the clamp to clamp to.
+         */
+        const unlimited = product.madeToOrder === true;
+        if (!unlimited && product.availableQuantity < 1)
             continue;
-        const safeQty = Math.min(item.quantity, product.availableQuantity);
+        const safeQty = unlimited
+            ? item.quantity
+            : Math.min(item.quantity, product.availableQuantity);
         const storeName = await resolveStoreName(product.storeId, product.storeName);
         await cartRepository.addItem(userId, {
             productId: product.id,
             productTitle: product.title,
-            productImage: product.images?.[0] ?? "",
+            productImage: product.images?.[0]?.url ?? "",
             price: product.price,
             currency: product.currency ?? getDefaultCurrency(),
             quantity: safeQty,

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

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

package/dist/features/cart/repository/cart.repository.js

@@ -162,10 +162,33 @@ export class CartRepository extends BaseRepository {
      * subtotals all compute `price × quantity`, and a grouped line pins
      * `quantity` to 1, so all four stay correct with no changes of their own.
      */
-    deriveLinePrice(members) {
+    deriveLinePrice(members, discountPercent) {
         const raw = members.reduce((sum, m) => sum + m.unitPrice * m.quantity, 0);
+        /*
+         * 🛑 THE GROUP DISCOUNT IS APPLIED HERE AND NOWHERE ELSE.
+         *
+         * This function is the only writer of `item.price` on a multi-member line,
+         * and `item.price` is what `getSubtotal`, the cart page's per-seller
+         * subtotal, both lane subtotals, `unitPriceFor` and
+         * `expandCartLineToOrderRows`' per-member GST proration (via
+         * `allocateAcrossMembers`) all read. So discounting here reaches every one
+         * of them with no change of their own — and discounting anywhere else means
+         * the cart total and the invoice are computed from two different numbers,
+         * which is exactly what Root Cause #75 cost.
+         *
+         * In particular `allocateAcrossMembers` prorates the LOCKED line price
+         * across members for tax, so a discount applied after it would under- or
+         * over-report GST against the amount actually charged.
+         *
+         * Clamped 0–100 rather than trusted: the percent is a snapshot copied off a
+         * seller-editable rule, and a negative value would silently INFLATE the
+         * line while a value over 100 would make it negative.
+         */
+        const pct = Math.min(100, Math.max(0, discountPercent ?? 0));
+        // audit-money-units-ok: pct/100 is a PERCENTAGE divisor (0-100 -> 0-1 fraction), not a paise conversion — raw/discounted are decimal rupees throughout.
+        const discounted = pct > 0 ? raw * (1 - pct / 100) : raw;
         // audit-money-units-ok: decimal rupees throughout; rounding to 2dp, not paise conversion.
-        return Math.round(raw * 100) / 100;
+        return Math.round(discounted * 100) / 100;
     }
     /**
      * Create a multi-member line. Deliberately never merges into an existing
@@ -182,7 +205,7 @@ export class CartRepository extends BaseRepository {
                 productId: input.productId,
                 productTitle: input.productTitle,
                 productImage: input.productImage,
-                price: this.deriveLinePrice(input.groupMembers),
+                price: this.deriveLinePrice(input.groupMembers, input.groupDiscountPercent),
                 currency: input.currency,
                 quantity: input.quantity,
                 storeId: input.storeId,
@@ -264,7 +287,12 @@ export class CartRepository extends BaseRepository {
             items[itemIndex] = {
                 ...target,
                 groupMembers: nextMembers,
-                price: this.deriveLinePrice(nextMembers),
+                /*
+                 * The line's OWN stored percent, so changing a member quantity
+                 * preserves the discount the buyer was quoted. Re-resolving the rule
+                 * here would silently reprice a line mid-edit.
+                 */
+                price: this.deriveLinePrice(nextMembers, target.groupDiscountPercent),
                 updatedAt: new Date(),
             };
             const updatedCart = { ...cart, items, updatedAt: new Date() };

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

@@ -148,6 +148,24 @@ export interface CartItemDocument {
     groupSlug?: string;
     /** Display snapshot of the group/bundle name. */
     groupTitle?: string;
+    /**
+     * The group discount, as a percentage, AS QUOTED WHEN THIS LINE WAS ADDED.
+     *
+     * 🛑 Stored on the line rather than resolved at read time, and that is not
+     * the mirror-drift mistake it resembles (Root Cause #42). It has to be here
+     * for a mechanical reason — `updateGroupMembers` recomputes `price` from
+     * `groupMembers` and holds only the CART, so with nothing on the line a
+     * buyer changing a quantity would silently lose the discount — and for a
+     * commercial one: this is the basis of the price the buyer was shown.
+     *
+     * 🛑 Because it is a snapshot it is RE-VALIDATED at checkout against the
+     * group's current rule, and a disagreement is REPORTED, never silently
+     * resolved either way. Honouring a stale percent would charge less than the
+     * seller now offers; re-deriving silently would change a total the buyer has
+     * already read. Same discipline as `revalidateAppliedCoupons`, which drops a
+     * lapsed coupon and tells the caller.
+     */
+    groupDiscountPercent?: number;
     /**
      * The members of a multi-member line, AUTHORITATIVE over `bundleProductIds`.
      * See `CartLineMember` for the quantity invariant.
@@ -300,6 +318,8 @@ export type AddToCartInput = {
     groupId?: string;
     groupSlug?: string;
     groupTitle?: string;
+    /** See `CartItemDocument.groupDiscountPercent` — a quoted-at-add snapshot. */
+    groupDiscountPercent?: number;
     groupMembers?: CartLineMember[];
 };
 /**

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

@@ -174,8 +174,8 @@ export declare const cartSummarySchema: z.ZodObject<{
         sessionId?: string | undefined;
         addedAt?: string | undefined;
     }[];
-    itemCount: number;
     subtotal: number;
+    itemCount: number;
 }, {
     items: {
         id: string;
@@ -193,7 +193,7 @@ export declare const cartSummarySchema: z.ZodObject<{
         sessionId?: string | undefined;
         addedAt?: string | undefined;
     }[];
-    itemCount: number;
     subtotal: number;
+    itemCount: number;
     currency?: string | undefined;
 }>;

package/dist/features/catalogue/components/PublicCatalogueItemDetailView.js

@@ -29,5 +29,5 @@ export function PublicCatalogueItemDetailView({ ownerSlug, itemId }) {
     }
     const { owner, item, linkedProductHref } = data;
     const images = item.images.length > 0 ? item.images : item.mainImage ? [item.mainImage] : [];
-    return (_jsx(Main, { children: _jsxs(Container, { size: "lg", padding: "y-lg", children: [_jsxs(Row, { className: "mb-4", align: "center", gap: "xs", textSize: "xs", color: "muted", children: [_jsx(Link, { href: "/", className: "hover:text-primary-600 transition-colors", children: "Home" }), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: `${ROUTES.PUBLIC.PROFILE(ownerSlug)}/catalogue`, className: "hover:text-primary-600 transition-colors", children: owner.displayName ?? "Catalogue" }), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Span, { className: "truncate max-w-[200px]", color: "muted", children: item.title })] }), _jsxs(Grid, { cols: 2, gap: "lg", children: [images.length > 0 ? (_jsx(Div, { className: `relative aspect-square w-full ${__O.hidden}`, rounded: "xl", surface: "muted", children: _jsx(MediaImage, { src: images[0], alt: item.title, size: "hero", objectFit: "contain" }) })) : (_jsx(Div, { className: "relative aspect-square w-full", rounded: "xl", surface: "muted" })), images.length > 1 && (_jsx(Row, { gap: "sm", wrap: true, className: "col-span-2", children: images.slice(1).map((src, i) => (_jsx(Div, { className: `relative h-20 w-20 ${__O.hidden}`, rounded: "lg", surface: "muted", children: _jsx(MediaImage, { src: src, alt: `${item.title} photo ${i + 2}`, size: "thumbnail", objectFit: "cover" }) }, i))) })), _jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 1, size: "2xl", weight: "bold", color: "primary", children: item.title }), typeof item.price === "number" && item.price > 0 && (_jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "2xl", weight: "bold", color: "primary", children: _jsx(GatedPrice, { label: "Sign in to see the estimated value", children: formatCurrency(item.price) }) }), _jsx(Text, { size: "xs", color: "muted", children: "Estimated value \u2014 not for direct sale from this page." })] })), _jsxs(Row, { gap: "sm", wrap: true, children: [item.condition && (_jsx(Span, { size: "xs", weight: "medium", padding: "pill-sm", rounded: "full", surface: "subtle", color: "muted", children: item.condition })), typeof item.quantity === "number" && (_jsxs(Span, { size: "xs", weight: "medium", padding: "pill-sm", rounded: "full", surface: "subtle", color: "muted", children: ["Qty: ", item.quantity] }))] }), item.description && (_jsx(Text, { color: "muted", className: "whitespace-pre-line", children: item.description })), owner.displayName && (_jsxs(Div, { border: "subtle", rounded: "xl", surface: "muted", padding: "md", children: [_jsx(Text, { className: "text-[10px] tracking-wide mb-0.5", color: "faint", transform: "uppercase", children: "Owned by" }), _jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: owner.displayName })] })), linkedProductHref && (_jsx(Link, { href: linkedProductHref, className: "inline-flex w-fit items-center rounded-lg bg-primary px-[var(--appkit-space-4)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] font-semibold text-white transition-colors hover:opacity-90", children: "View live listing \u2192" }))] })] })] }) }));
+    return (_jsx(Main, { children: _jsxs(Container, { size: "lg", padding: "y-lg", children: [_jsxs(Row, { className: "mb-4", align: "center", gap: "xs", textSize: "xs", color: "muted", children: [_jsx(Link, { href: "/", className: "hover:text-primary-600 dark:hover:text-primary-400 transition-colors", children: "Home" }), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: `${ROUTES.PUBLIC.PROFILE(ownerSlug)}/catalogue`, className: "hover:text-primary-600 dark:hover:text-primary-400 transition-colors", children: owner.displayName ?? "Catalogue" }), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Span, { className: "truncate max-w-[200px]", color: "muted", children: item.title })] }), _jsxs(Grid, { cols: 2, gap: "lg", children: [images.length > 0 ? (_jsx(Div, { className: `relative aspect-square w-full ${__O.hidden}`, rounded: "xl", surface: "muted", children: _jsx(MediaImage, { src: images[0], alt: item.title, size: "hero", objectFit: "contain" }) })) : (_jsx(Div, { className: "relative aspect-square w-full", rounded: "xl", surface: "muted" })), images.length > 1 && (_jsx(Row, { gap: "sm", wrap: true, className: "col-span-2", children: images.slice(1).map((src, i) => (_jsx(Div, { className: `relative h-20 w-20 ${__O.hidden}`, rounded: "lg", surface: "muted", children: _jsx(MediaImage, { src: src, alt: `${item.title} photo ${i + 2}`, size: "thumbnail", objectFit: "cover" }) }, i))) })), _jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 1, size: "2xl", weight: "bold", color: "primary", children: item.title }), typeof item.price === "number" && item.price > 0 && (_jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "2xl", weight: "bold", color: "primary", children: _jsx(GatedPrice, { label: "Sign in to see the estimated value", children: formatCurrency(item.price) }) }), _jsx(Text, { size: "xs", color: "muted", children: "Estimated value \u2014 not for direct sale from this page." })] })), _jsxs(Row, { gap: "sm", wrap: true, children: [item.condition && (_jsx(Span, { size: "xs", weight: "medium", padding: "pill-sm", rounded: "full", surface: "subtle", color: "muted", children: item.condition })), typeof item.quantity === "number" && (_jsxs(Span, { size: "xs", weight: "medium", padding: "pill-sm", rounded: "full", surface: "subtle", color: "muted", children: ["Qty: ", item.quantity] }))] }), item.description && (_jsx(Text, { color: "muted", className: "whitespace-pre-line", children: item.description })), owner.displayName && (_jsxs(Div, { border: "subtle", rounded: "xl", surface: "muted", padding: "md", children: [_jsx(Text, { className: "text-[10px] tracking-wide mb-0.5", color: "faint", transform: "uppercase", children: "Owned by" }), _jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: owner.displayName })] })), linkedProductHref && (_jsx(Link, { href: linkedProductHref, className: "inline-flex w-fit items-center rounded-lg bg-primary px-[var(--appkit-space-4)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] font-semibold text-white transition-colors hover:opacity-90", children: "View live listing \u2192" }))] })] })] }) }));
 }

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

@@ -1,4 +1,3 @@
-import type { DocumentSnapshot } from "firebase-admin/firestore";
 /**
  * Personal Catalogue Repository (Feature B).
  */
@@ -14,16 +13,17 @@ export interface CatalogueWriteContext {
 }
 export declare class CatalogueRepository extends BaseRepository<CatalogueItemDocument> {
     /**
-     * `ownerEmail` only — NOT `ownerName`.
+     * 🛑 DEAD as written: `CatalogueItemDocument` has no `ownerEmail`.
      *
-     * Per decision D1 names stay partial-match searchable, and catalogue items are
-     * searchable by owner in the admin approvals queue. `CATALOGUE_HISTORY_PII_FIELDS`
-     * lists both, but that constant scrubs status *history*, which has no search
-     * requirement — the two lists are intentionally different.
+     * Kept rather than deleted because it is the declaration that would start
+     * working the moment an owner email is added to the document, and deleting
+     * it would hand that future field plaintext storage by default. The reasoning
+     * it used to carry — "`ownerEmail` only, NOT `ownerName`, because D1 keeps
+     * names searchable" — described a choice between two fields that neither
+     * exist nor can arrive through `CatalogueItemCreateInput`.
      */
     protected piiFields: readonly ["ownerEmail"];
     /** Decrypt on read so callers see the shape they wrote. */
-    protected mapDoc<D = CatalogueItemDocument>(snap: DocumentSnapshot): D;
     constructor();
     create(input: CatalogueItemCreateInput): Promise<CatalogueItemDocument>;
     /**

package/dist/features/catalogue/repository/catalogue.repository.js

@@ -1,4 +1,3 @@
-import { decryptPiiFields } from "../../../security/pii-encrypt.js";
 /**
  * Personal Catalogue Repository (Feature B).
  */
@@ -7,19 +6,38 @@ import { CATALOGUE_COLLECTION, CATALOGUE_FIELDS, CATALOGUE_TRACKED_FIELDS, CATAL
 import { withHistory } from "../../../_internal/shared/history/index.js";
 export class CatalogueRepository extends BaseRepository {
     /** Decrypt on read so callers see the shape they wrote. */
-    mapDoc(snap) {
-        const raw = super.mapDoc(snap);
-        return decryptPiiFields(raw, [...this.piiFields]);
-    }
+    /*
+     * 🛑 `mapDoc` is NOT overridden — it used to call `decryptPiiFields`, and
+     * that call had ALWAYS BEEN A NO-OP.
+     *
+     * Measured 2026-10-17: `CatalogueItemDocument` declares `ownerId` and
+     * `ownerRole` and NO owner name or email. `CatalogueItemCreateInput` is
+     * `Omit<CatalogueItemDocument, …>`, so `ownerEmail` cannot arrive through
+     * the create path either — the `piiFields` override below encrypts a field
+     * that is never present, and the decrypt undid nothing.
+     *
+     * So this repository gets NO `reveal*`/`masked*` accessors: there is no PII
+     * on the document to reveal or to mask, and adding a pair for fields that do
+     * not exist would be the same fiction one level up — a named method whose
+     * name is the only evidence it does anything (Root Cause #92).
+     *
+     * `CATALOGUE_HISTORY_PII_FIELDS` is a different and legitimate thing: it is
+     * the scrub list passed to `withHistory` below, and a history entry listing
+     * PII keys it does not currently carry is DEFENSIVE by design — § "Status
+     * History" requires every adopter to pass the list explicitly so the next
+     * field added has to be triaged rather than defaulting in silently.
+     */
     constructor() {
         super(CATALOGUE_COLLECTION);
         /**
-         * `ownerEmail` only — NOT `ownerName`.
+         * 🛑 DEAD as written: `CatalogueItemDocument` has no `ownerEmail`.
          *
-         * Per decision D1 names stay partial-match searchable, and catalogue items are
-         * searchable by owner in the admin approvals queue. `CATALOGUE_HISTORY_PII_FIELDS`
-         * lists both, but that constant scrubs status *history*, which has no search
-         * requirement — the two lists are intentionally different.
+         * Kept rather than deleted because it is the declaration that would start
+         * working the moment an owner email is added to the document, and deleting
+         * it would hand that future field plaintext storage by default. The reasoning
+         * it used to carry — "`ownerEmail` only, NOT `ownerName`, because D1 keeps
+         * names searchable" — described a choice between two fields that neither
+         * exist nor can arrive through `CatalogueItemCreateInput`.
          */
         this.piiFields = ["ownerEmail"];
     }

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

@@ -10,10 +10,21 @@ import { type GenerateCatalogueItemIdInput } from "../../../utils/id-generators"
 import type { StatusChangeEntry } from "../../../_internal/shared/history/types";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 import type { ProductDraftFields } from "../../shipments/schemas/firestore";
+import type { Plaintext } from "../../../security/encrypted";
 export declare const CATALOGUE_COLLECTION: "catalogueItems";
 export type CatalogueVisibility = "public" | "private";
 export type CatalogueOwnerRole = "user" | "seller" | "admin";
 export type CatalogueListingStatus = "not_listed" | "pending_admin_approval" | "listed" | "rejected";
+/**
+ * `CatalogueItemDocument` with its PII as plain `string` — what the named repository
+ * accessors return, and what a WRITE path accepts (the repository encrypts).
+ *
+ * `Plaintext<T>` is the one definition of this shape; see `security/encrypted.ts`.
+ * It is deliberately NOT distinguishable from a MASKED value — `maskPii`
+ * returns plain strings too, and no type can express "these characters are
+ * asterisks". The distinction is which named method you called.
+ */
+export type CatalogueItemPlain = Plaintext<CatalogueItemDocument>;
 export interface CatalogueItemDocument extends BaseDocument, Partial<Omit<ProductDraftFields, "title" | "images" | "mainImage">> {
     ownerId: string;
     ownerRole: CatalogueOwnerRole;