@mohasinac/appkit 4.52.5 → 4.53.0

package/dist/features/media/upload/downscale-image.js

@@ -0,0 +1,150 @@
+/**
+ * downscaleImageFile — bound an image's pixel dimensions and re-encode it
+ * before it ever leaves the browser.
+ *
+ * ## Why this exists
+ *
+ * Until 2026-10-19 the ONLY client-side resize in the whole upload path was
+ * inside `ImageEditor` (`modals/ImageEditor.tsx`), which runs only when the
+ * user opens the crop editor. Everything else stored the original bytes: a 9 MB
+ * phone photo was stored at 9 MB, watermarked at 9 MB, and served at 9 MB into
+ * a 64px thumbnail, because `/api/media/[...slug]` resizes nothing and
+ * `next/image` optimisation was off.
+ *
+ * That is the shape of the cost that suspended this project with HTTP 402 for
+ * Fast Origin Transfer at 5.25x its cap (Root Cause #104). Bounding the master
+ * at upload is the one fix that helps every downstream consumer at once.
+ *
+ * ## Why 2048
+ *
+ * Measured (docs/research/competitor-crawl-2026-10/images.md): worldhobbyshop
+ * serves a 2048x2048 master to photoswipe for zoom, and WordPress's own
+ * `-scaled` threshold is 2560. 2048 survives our lightbox's 300% zoom over a
+ * ~680px display box with detail to spare, and is 1/4 the pixels of a 4096px
+ * phone capture.
+ *
+ * ## Four cases where it deliberately returns the ORIGINAL file
+ *
+ * 1. **Not a raster image we own the pipeline for** — anything outside
+ *    `CONVERTIBLE_MIMES`. SVG is never rasterised (it is also not in
+ *    `ALLOWED_IMAGE_MIMES`), and GIF is never touched because re-encoding an
+ *    animated GIF to a still WebP silently destroys the animation.
+ * 2. **Already small enough AND already a compact format** — re-encoding a
+ *    1200px WebP buys nothing and loses a generation of quality.
+ * 3. **The re-encode came out BIGGER.** A small, already-optimised JPEG can
+ *    grow under WebP q0.9. Shipping the larger file would make this helper a
+ *    pessimisation, so the original wins.
+ * 4. **Anything threw.** 🛑 Fail OPEN. A canvas decode failure, a tainted
+ *    canvas, a browser without `createImageBitmap` — none of those are a reason
+ *    to block a seller's upload. The server still enforces `MAX_BYTES[kind]`,
+ *    so the worst case is the pre-2026-10-19 behaviour, not a hole.
+ */
+import { normalizeError } from "../../../errors/normalize.js";
+/** Longest edge, in CSS pixels, of the stored master. */
+export const IMAGE_DOWNSCALE_MAX_EDGE = 2048;
+/** Output MIME for a re-encoded master. */
+export const IMAGE_DOWNSCALE_FORMAT = "image/webp";
+/** Output quality for a re-encoded master. */
+export const IMAGE_DOWNSCALE_QUALITY = 0.9;
+/**
+ * MIMEs this helper is willing to decode and re-encode.
+ *
+ * 🛑 Deliberately NOT derived from `ALLOWED_IMAGE_MIMES` — that list is about
+ * what the server will STORE, this one is about what a canvas may safely
+ * round-trip. `image/gif` is in the first and must stay out of the second
+ * (animation loss), and the two lists answering different questions is exactly
+ * why one must not be spelled in terms of the other.
+ */
+const CONVERTIBLE_MIMES = new Set(["image/jpeg", "image/jpg", "image/png", "image/webp"]);
+/** Formats already compact enough that a same-size re-encode is pointless. */
+const ALREADY_COMPACT = new Set(["image/webp", "image/avif"]);
+function replaceExtension(name, mime) {
+    const ext = mime.split("/")[1] || "webp";
+    const dot = name.lastIndexOf(".");
+    const stem = dot > 0 ? name.slice(0, dot) : name;
+    return `${stem}.${ext}`;
+}
+async function decode(file) {
+    if (typeof createImageBitmap === "function") {
+        const bitmap = await createImageBitmap(file);
+        return { width: bitmap.width, height: bitmap.height, source: bitmap, release: () => bitmap.close() };
+    }
+    const url = URL.createObjectURL(file);
+    try {
+        const img = await new Promise((resolve, reject) => {
+            const el = new Image();
+            el.onload = () => resolve(el);
+            el.onerror = () => reject(new Error("image decode failed"));
+            el.src = url;
+        });
+        return {
+            width: img.naturalWidth,
+            height: img.naturalHeight,
+            source: img,
+            release: () => URL.revokeObjectURL(url),
+        };
+    }
+    catch (err) {
+        URL.revokeObjectURL(url);
+        throw err;
+    }
+}
+export async function downscaleImageFile(file, options = {}) {
+    const maxEdge = options.maxEdge ?? IMAGE_DOWNSCALE_MAX_EDGE;
+    const format = options.format ?? IMAGE_DOWNSCALE_FORMAT;
+    const quality = options.quality ?? IMAGE_DOWNSCALE_QUALITY;
+    // Case 1 — not something we are willing to round-trip through a canvas.
+    if (!CONVERTIBLE_MIMES.has(file.type))
+        return file;
+    let decoded = null;
+    try {
+        decoded = await decode(file);
+        const { width, height, source } = decoded;
+        if (!width || !height)
+            return file;
+        const longest = Math.max(width, height);
+        const scale = longest > maxEdge ? maxEdge / longest : 1;
+        // Case 2 — small enough already, and re-encoding would only lose a generation.
+        if (scale === 1 && ALREADY_COMPACT.has(file.type))
+            return file;
+        const targetW = Math.max(1, Math.round(width * scale));
+        const targetH = Math.max(1, Math.round(height * scale));
+        const canvas = document.createElement("canvas");
+        canvas.width = targetW;
+        canvas.height = targetH;
+        const ctx = canvas.getContext("2d");
+        if (!ctx)
+            return file;
+        ctx.imageSmoothingQuality = "high";
+        ctx.drawImage(source, 0, 0, targetW, targetH);
+        const blob = await new Promise((resolve) => canvas.toBlob(resolve, format, quality));
+        if (!blob || blob.size === 0)
+            return file;
+        // Case 3 — the re-encode is bigger than what we started with.
+        if (blob.size >= file.size && scale === 1)
+            return file;
+        return new File([blob], replaceExtension(file.name, format), {
+            type: format,
+            lastModified: file.lastModified,
+        });
+    }
+    catch (err) {
+        void normalizeError(err);
+        /*
+         * Case 4 — fail open. See the header.
+         *
+         * Reported rather than swallowed silently: `normalizeError` fires the
+         * observability hook, so a browser that cannot decode what it just accepted
+         * is visible instead of merely producing a suspiciously large upload. The
+         * upload itself still proceeds, with the original file.
+         *
+         * 🛑 The call sits on the line directly below the `catch` on purpose —
+         * `audit-catch-normalize` only looks a few lines ahead, so putting this
+         * comment first was enough to make it read as an unnormalised catch.
+         */
+        return file;
+    }
+    finally {
+        decoded?.release();
+    }
+}

package/dist/features/messages/components/ConversationThreadView.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from "react";
+import { useSearchParams } from "next/navigation.js";
 import { useAuth } from "../../../react/contexts/SessionContext.js";
 import { useConversationThread, useSendMessage, useMarkConversationRead, useBlockConversation, } from "../hooks/useMessages.js";
 import { Div } from "../../../ui/components/Div.js";
@@ -10,6 +11,10 @@ import { Button } from "../../../ui/components/Button.js";
 import { FieldTextarea } from "../../../ui/forms/FieldTextarea.js";
 import { EmptyState } from "../../../ui/components/EmptyState.js";
 import { MediaImage } from "../../media/MediaImage.js";
+import { TextLink } from "../../../ui/components/TextLink.js";
+import { pluginFor } from "../../../_internal/shared/listing-types/_registry.js";
+import { isListingType } from "../../../_internal/shared/listing-types/feature-flags.js";
+import { formatCurrency } from "../../../utils/number.formatter.js";
 function newClientMessageId() {
     // crypto.randomUUID is available in every browser this app targets; a
     // retry reuses the SAME id generated at compose time, not a fresh one per
@@ -22,7 +27,32 @@ function MessageBubble({ message, isSelf }) {
     if (message.deletedAt) {
         return (_jsx(Row, { justify: isSelf ? "end" : "start", children: _jsx(Text, { size: "sm", color: "muted", className: "italic", children: "Message deleted" }) }));
     }
-    return (_jsx(Row, { justify: isSelf ? "end" : "start", children: _jsxs(Stack, { gap: "xs", surface: isSelf ? "interactive" : "muted", padding: "sm", rounded: "lg", className: "max-w-[75%]", children: [message.productRef && (_jsxs(Row, { gap: "sm", surface: "card", padding: "xs", rounded: "md", children: [message.productRef.image && (_jsx(Div, { className: "relative h-10 w-10 flex-shrink-0", rounded: "default", overflow: "hidden", children: _jsx(MediaImage, { src: message.productRef.image, alt: message.productRef.title, size: "thumbnail" }) })), _jsx(Text, { size: "xs", weight: "semibold", className: "truncate", children: message.productRef.title })] })), _jsx(Text, { size: "sm", className: "whitespace-pre-wrap break-words", children: message.body })] }) }));
+    return (_jsx(Row, { justify: isSelf ? "end" : "start", children: _jsxs(Stack, { gap: "xs", surface: isSelf ? "interactive" : "muted", padding: "sm", rounded: "lg", className: "max-w-[75%]", children: [message.productRef && (
+                /*
+                 * A LINK, and it shows the price.
+                 *
+                 * `MessageProductRef` captures `price` and this block ignored it —
+                 * a declared field with no reader (Root Cause #51's shape) — and the
+                 * card was not clickable, so the one thing a buyer and seller both
+                 * want from it (open the item) was missing. The snapshot is taken at
+                 * send time on purpose, so it keeps reading correctly after the
+                 * listing changes or is deleted.
+                 *
+                 * No `GatedPrice` here: chat requires auth, so there is no signed-out
+                 * viewer to gate, and the price shown is the one the buyer was
+                 * looking at when they asked.
+                 */
+                _jsx(TextLink, { variant: "inherit", href: String(
+                    /*
+                     * Narrowed, not cast. The snapshot stores `listingType` as a
+                     * plain `string` (a message written before the field existed has
+                     * none), and anything unrecognised falls back to the `standard`
+                     * route — the correct reading for those older rows and for a type
+                     * that has since been removed.
+                     */
+                    pluginFor(isListingType(message.productRef.listingType)
+                        ? message.productRef.listingType
+                        : "standard").detailRoute(message.productRef.productId)), layout: "flex-col", rounded: "md", children: _jsxs(Row, { gap: "sm", surface: "card", padding: "xs", rounded: "md", align: "center", children: [message.productRef.image && (_jsx(Div, { className: "relative h-10 w-10 flex-shrink-0", rounded: "default", overflow: "hidden", children: _jsx(MediaImage, { src: message.productRef.image, alt: message.productRef.title, size: "thumbnail" }) })), _jsxs(Stack, { gap: "none", className: "min-w-0", children: [_jsx(Text, { size: "xs", weight: "semibold", className: "truncate", children: message.productRef.title }), typeof message.productRef.price === "number" && (_jsx(Text, { size: "xs", color: "muted", children: formatCurrency(message.productRef.price, "INR") }))] })] }) })), _jsx(Text, { size: "sm", className: "whitespace-pre-wrap break-words", children: message.body })] }) }));
 }
 export function ConversationThreadView({ conversationId }) {
     const { user, loading } = useAuth();
@@ -31,6 +61,17 @@ export function ConversationThreadView({ conversationId }) {
     const markRead = useMarkConversationRead();
     const block = useBlockConversation();
     const [draft, setDraft] = useState("");
+    /*
+     * The listing the buyer arrived from, attached to the NEXT message and then
+     * cleared — so the card appears once, on the message that asked about it,
+     * rather than on every subsequent reply in the thread.
+     *
+     * Read from `?product=` rather than held on the conversation because the
+     * schema is explicit that a product belongs to a message: one thread per
+     * pair of people, however many items they discuss.
+     */
+    const searchParams = useSearchParams();
+    const [attachedProductId, setAttachedProductId] = useState(() => searchParams.get("product") ?? undefined);
     const markedRef = useRef(false);
     const bottomRef = useRef(null);
     useEffect(() => {
@@ -57,8 +98,10 @@ export function ConversationThreadView({ conversationId }) {
         if (!trimmed)
             return;
         const clientMessageId = newClientMessageId();
-        send({ body: trimmed, clientMessageId });
+        send({ body: trimmed, clientMessageId, productId: attachedProductId });
         setDraft("");
+        // Once attached, it is spent — the next message is a plain reply.
+        setAttachedProductId(undefined);
     };
     // Newest-first from the API, so reverse for display (oldest at top).
     const items = data ? [...data.items].reverse() : [];

package/dist/features/messages/components/MessageSellerButton.d.ts

@@ -1,5 +1,19 @@
 export interface MessageSellerButtonProps {
     storeId: string;
+    /**
+     * The listing this button was clicked from, carried into the thread so the
+     * buyer's first message renders as a PRODUCT CARD.
+     *
+     * 🛑 Without it the whole card pipeline is unreachable. `sendMessage` builds
+     * a `MessageProductRef` from a `productId`, `MessageBubble` renders it, and
+     * `POST /api/messages/[conversationId]` accepts it — but the ONLY caller of
+     * this button is the product detail page, which had the id right there and
+     * never passed it. So a buyer landed in a bare thread and had to TYPE which
+     * item they meant: a block of words where a card belongs. Root Cause #103's
+     * shape — a feature complete in every direction except the one that puts
+     * data in.
+     */
+    productId?: string;
     /** Render nothing when the viewer owns this store — comparing storeId
      * client-side is an optional convenience; the server refuses it either way. */
     isOwnStore?: boolean;
@@ -14,4 +28,4 @@ export interface MessageSellerButtonProps {
  * Absent entirely when chat is off or the viewer is the store's own owner —
  * never rendered-but-disabled, same discipline as the nav icon.
  */
-export declare function MessageSellerButton({ storeId, isOwnStore, className }: MessageSellerButtonProps): import("react").JSX.Element | null;
+export declare function MessageSellerButton({ storeId, productId, isOwnStore, className }: MessageSellerButtonProps): import("react").JSX.Element | null;

package/dist/features/messages/components/MessageSellerButton.js

@@ -16,7 +16,7 @@ import { ACTIONS } from "../../../_internal/shared/actions/action-registry.js";
  * Absent entirely when chat is off or the viewer is the store's own owner —
  * never rendered-but-disabled, same discipline as the nav icon.
  */
-export function MessageSellerButton({ storeId, isOwnStore, className }) {
+export function MessageSellerButton({ storeId, productId, isOwnStore, className }) {
     const router = useRouter();
     const { user } = useAuth();
     const { data: settings } = useSiteSettings();
@@ -26,7 +26,15 @@ export function MessageSellerButton({ storeId, isOwnStore, className }) {
     return (_jsx(Button, { action: ACTIONS.PRODUCT["message-seller"], size: "sm", isLoading: isPending, className: className, onClick: () => {
             mutate({ storeId }, {
                 onSuccess: (conversation) => {
-                    router.push(String(ROUTES.USER.MESSAGE_THREAD(conversation.id)));
+                    /*
+                     * `?product=` rather than a new conversation per listing. The
+                     * schema is explicit that a product attaches to a MESSAGE, never
+                     * to the thread — "a buyer with three questions about three items
+                     * wants one thread, not three" — so the id rides in the URL and
+                     * the composer attaches it to the next message sent.
+                     */
+                    const href = String(ROUTES.USER.MESSAGE_THREAD(conversation.id));
+                    router.push(productId ? `${href}?product=${encodeURIComponent(productId)}` : href);
                 },
             });
         } }));

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

@@ -44,6 +44,21 @@ export interface MessageProductRef {
     productId: string;
     title: string;
     image?: string;
+    /**
+     * 🛑 Required for the card to LINK anywhere correct.
+     *
+     * Nine listing types have five different detail routes
+     * (`/auctions/…`, `/pre-orders/…`, `/prize-draws/…`, `/classified/…`, …) and
+     * `pluginFor(type).detailRoute()` is the only thing that knows which. A card
+     * that hardcodes `/products/{slug}` sends an auction to the standard product
+     * page — which is Root Cause #48 exactly: a doc→card mapper dropping
+     * `listingType` and the link going wrong because of the one field it lost.
+     *
+     * Optional only because a message sent before this field existed has none;
+     * `normalizeListingType` resolves an absent value to `"standard"`, which is
+     * the correct reading for those rows.
+     */
+    listingType?: string;
     /** Omitted for a guest-gated listing snapshot taken while signed out is not
      * possible here — chat requires auth — but still optional: a product can be
      * archived/deleted between send and render. */

package/dist/features/orders/hooks/useOrders.js

@@ -18,8 +18,10 @@ export function useOrders(params = {}, opts) {
         sp.set("sort", params.sort);
     if (params.page)
         sp.set("page", String(params.page));
-    if (params.perPage)
-        sp.set("perPage", String(params.perPage));
+    // `pageSize` is what the route prefers; it keeps reading `perPage` only for
+    // links built before the rename, so there is no reason to emit the old name.
+    if (params.pageSize)
+        sp.set("pageSize", String(params.pageSize));
     const qs = sp.toString();
     // ORDER_ENDPOINTS.LIST ("/api/orders") has no GET route handler — every
     // real caller of this hook wants the current user's own orders, served by

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

@@ -2,7 +2,7 @@ import type { JsonValue } from "../../../schemas/types";
 import type { DocumentReference, WriteBatch } from "firebase-admin/firestore";
 import type { FirebaseSieveResult, SieveModel } from "../../../providers/db-firebase";
 import { BaseRepository, parseSieveDateValue } from "../../../providers/db-firebase";
-import { type OrderCreateInput, type OrderDocument, type OrderRefundEvent } from "../schemas";
+import { type OrderCreateInput, type OrderDocument, type OrderPlain, type OrderRefundEvent } from "../schemas";
 import { type HistoryActor, type FieldChange } from "../../../_internal/shared/history/index";
 import type { OrderStatus, PaymentStatus } from "../types";
 import { type PaymentReviewQueueMode } from "../constants/payment-window";
@@ -26,7 +26,6 @@ export interface OrderWriteContext {
 }
 declare class OrderRepository extends BaseRepository<OrderDocument> {
     constructor();
-    private decryptOrder;
     /**
      * Declared, not hand-rolled.
      *
@@ -39,8 +38,20 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
      * call.
      */
     protected piiFields: readonly ["userName", "userEmail", "sellerEmail"];
-    protected mapDoc<D = OrderDocument>(snap: import("../../../providers/db-firebase").DocumentSnapshot): D;
-    create(input: OrderCreateInput): Promise<OrderDocument>;
+    /** Plaintext PII. **Opt-in and named** — shows up in review and in a grep. */
+    revealOrder(doc: OrderDocument): OrderPlain;
+    /** As `revealOrder`, for a list read. */
+    revealOrders(docs: readonly OrderDocument[]): OrderPlain[];
+    /**
+     * Masked PII — **the default for any surface that only needs to identify a
+     * row to a human.** Decrypts first, then masks: the mask helpers refuse
+     * ciphertext by design, so passing a stored field straight in would return
+     * "Anonymous" for every row.
+     */
+    maskedOrder(doc: OrderDocument): OrderPlain;
+    /** As `maskedOrder`, for a list read. */
+    maskedOrders(docs: readonly OrderDocument[]): OrderPlain[];
+    createOrder(input: OrderCreateInput): Promise<OrderPlain>;
     findByUser(userId: string): Promise<OrderDocument[]>;
     findByProduct(productId: string): Promise<OrderDocument[]>;
     findByStatus(status: OrderStatus): Promise<OrderDocument[]>;

package/dist/features/orders/repository/orders.repository.js

@@ -3,7 +3,7 @@ import { planSearchTxt, beginSearchWindow, emptySearchResult, } from "../../../u
 import { normalizeError } from "../../../errors/normalize.js";
 import { DatabaseError, NotFoundError } from "../../../errors/index.js";
 import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
-import { decryptPiiFields, ORDER_PII_FIELDS, } from "../../../security/index.js";
+import { maskPii, revealPii, ORDER_PII_FIELDS, } from "../../../security/index.js";
 import { serverTimestamp, arrayUnion } from "../../../contracts/field-ops.js";
 import { createOrderId, ORDER_COLLECTION, ORDER_TRACKED_FIELDS, OrderStatusValues, } from "../schemas/index.js";
 import { withHistory } from "../../../_internal/shared/history/index.js";
@@ -37,18 +37,49 @@ class OrderRepository extends BaseRepository {
          */
         this.piiFields = ORDER_PII_FIELDS;
     }
-    decryptOrder(doc) {
-        return decryptPiiFields(doc, [
-            ...ORDER_PII_FIELDS,
-        ]);
+    /*
+     * 🛑 `mapDoc` is NOT overridden, and that absence IS the change.
+     *
+     * It used to decrypt on every read, so ciphertext never left the database
+     * and every caller handled plaintext without ever saying so. Following
+     * `SiteSettingsRepository`: reads return what Firestore holds, and plaintext
+     * requires one of the two named methods below.
+     *
+     * A convention would not hold this. `OrderDocument`'s PII fields are
+     * `Encrypted<string>`, assignable to nothing that wants a plain `string`, so
+     * a reader that skips both accessors is a compile error naming file and line.
+     */
+    /** Plaintext PII. **Opt-in and named** — shows up in review and in a grep. */
+    revealOrder(doc) {
+        return revealPii(doc, ORDER_PII_FIELDS);
     }
-    mapDoc(snap) {
-        const raw = super.mapDoc(snap);
-        return this.decryptOrder(raw);
+    /** As `revealOrder`, for a list read. */
+    revealOrders(docs) {
+        return docs.map((d) => this.revealOrder(d));
     }
-    async create(input) {
+    /**
+     * Masked PII — **the default for any surface that only needs to identify a
+     * row to a human.** Decrypts first, then masks: the mask helpers refuse
+     * ciphertext by design, so passing a stored field straight in would return
+     * "Anonymous" for every row.
+     */
+    maskedOrder(doc) {
+        return maskPii(doc, ORDER_PII_FIELDS);
+    }
+    /** As `maskedOrder`, for a list read. */
+    maskedOrders(docs) {
+        return docs.map((d) => this.maskedOrder(d));
+    }
+    /*
+     * 🛑 NOT an `override`. It returns the plaintext it was handed rather than
+     * re-reading (a read-after-write costs a Firestore read per order), so the
+     * return is `OrderPlain` — not assignable to the base's `Promise<T>`, and
+     * correctly so, because the two differ.
+     */
+    async createOrder(input) {
         const orderDate = new Date();
         const id = createOrderId(input.quantity, orderDate);
+        // Plain in, ciphertext out — `applyWriteHooks` encrypts below.
         const orderData = {
             ...input,
             orderDate,
@@ -116,6 +147,7 @@ class OrderRepository extends BaseRepository {
         });
         // `null` means no tracked field actually changed — write the patch as-is
         // so an untracked update never grows the array.
+        // Plain: this is a write payload and `update` encrypts.
         return this.update(orderId, (withEntry ?? patch));
     }
     async updateStatus(orderId, status, additionalData, ctx) {
@@ -172,7 +204,7 @@ class OrderRepository extends BaseRepository {
             .orderBy(ORDER_FIELDS.CREATED_AT, "asc")
             .limit(200)
             .get();
-        return snap.docs.map((doc) => this.decryptOrder({ id: doc.id, ...doc.data() }));
+        return snap.docs.map((doc) => ({ id: doc.id, ...doc.data() }));
     }
     async updatePaymentStatus(orderId, paymentStatus, paymentId, ctx) {
         return this.updateWithHistory(orderId, {
@@ -202,7 +234,7 @@ class OrderRepository extends BaseRepository {
             .where(ORDER_FIELDS.ORDER_DATE, ">=", new Date(now.getTime() - 90 * 24 * 60 * 60 * 1000))
             .orderBy(ORDER_FIELDS.ORDER_DATE, "desc")
             .get();
-        return snapshot.docs.map((doc) => this.decryptOrder({
+        return snapshot.docs.map((doc) => ({
             id: doc.id,
             ...doc.data(),
         }));
@@ -412,7 +444,7 @@ class OrderRepository extends BaseRepository {
             .where("paymentBatchId", "==", batchId)
             .limit(20)
             .get();
-        return snap.docs.map((d) => this.decryptOrder({ id: d.id, ...d.data() }));
+        return snap.docs.map((d) => ({ id: d.id, ...d.data() }));
     }
     /**
      * Fetch every order recorded against a single gateway payment id (e.g. a
@@ -428,7 +460,7 @@ class OrderRepository extends BaseRepository {
             .where(ORDER_FIELDS.PAYMENT_ID, "==", paymentId)
             .limit(20)
             .get();
-        return snap.docs.map((d) => this.decryptOrder({ id: d.id, ...d.data() }));
+        return snap.docs.map((d) => ({ id: d.id, ...d.data() }));
     }
     /**
      * Cloud Functions: find pending orders created before a timeout threshold.
@@ -447,7 +479,7 @@ class OrderRepository extends BaseRepository {
         return snap.docs.map((d) => ({
             id: d.id,
             ref: d.ref,
-            data: this.decryptOrder({ id: d.id, ...d.data() }),
+            data: { id: d.id, ...d.data() },
         }));
     }
     /**
@@ -470,7 +502,7 @@ class OrderRepository extends BaseRepository {
             .map((d) => ({
             id: d.id,
             ref: d.ref,
-            data: this.decryptOrder({ id: d.id, ...d.data() }),
+            data: { id: d.id, ...d.data() },
         }))
             .filter((entry) => !entry.data.paymentProofUrl);
     }
@@ -495,7 +527,7 @@ class OrderRepository extends BaseRepository {
             .map((d) => ({
             id: d.id,
             ref: d.ref,
-            data: this.decryptOrder({ id: d.id, ...d.data() }),
+            data: { id: d.id, ...d.data() },
         }))
             .filter((entry) => !!entry.data.paymentProofUrl && !entry.data.paymentReviewOutcome);
     }
@@ -537,7 +569,7 @@ class OrderRepository extends BaseRepository {
             .limit(PAYMENT_REVIEW_QUEUE_SCAN_LIMIT)
             .get();
         const matches = snap.docs
-            .map((d) => this.decryptOrder({ id: d.id, ...d.data() }))
+            .map((d) => ({ id: d.id, ...d.data() }))
             .filter((order) => MANUAL_PAYMENT_METHODS.includes(order.paymentMethod ?? ""))
             .filter((order) => mode === "awaiting_proof"
             ? !order.paymentProofUrl
@@ -573,7 +605,7 @@ class OrderRepository extends BaseRepository {
             .map((d) => ({
             id: d.id,
             ref: d.ref,
-            data: this.decryptOrder({ id: d.id, ...d.data() }),
+            data: { id: d.id, ...d.data() },
         }))
             .filter((o) => !o.data.emiEnabled || o.data.emiComplete);
     }
@@ -596,7 +628,7 @@ class OrderRepository extends BaseRepository {
             .map((d) => ({
             id: d.id,
             ref: d.ref,
-            data: this.decryptOrder({ id: d.id, ...d.data() }),
+            data: { id: d.id, ...d.data() },
         }))
             .filter((o) => !o.data.emiEnabled || o.data.emiComplete);
     }
@@ -616,7 +648,7 @@ class OrderRepository extends BaseRepository {
         return snap.docs.map((d) => ({
             id: d.id,
             ref: d.ref,
-            data: this.decryptOrder({ id: d.id, ...d.data() }),
+            data: { id: d.id, ...d.data() },
         }));
     }
     /**

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

@@ -8,6 +8,7 @@ import type { ListingType } from "../../products/types";
 import type { StatusChangeEntry } from "../../../_internal/shared/history/index";
 import type { ReturnReason } from "../../../_internal/shared/features/orders/return-reasons";
 import type { ReturnCustodyState } from "../../../_internal/shared/features/returns/custody";
+import type { Encrypted, Plaintext } from "../../../security/encrypted";
 export interface OrderSourceStandard {
     path: "standard";
     listPrice: number;
@@ -320,14 +321,24 @@ export interface AppliedOrderDiscount {
     scope?: "admin" | "seller";
     storeId?: string;
 }
+/**
+ * `OrderDocument` 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 OrderPlain = Plaintext<OrderDocument>;
 export interface OrderDocument extends BaseDocument {
     /** Word-prefix search tokens. Derived on write; never fed by a PII field. */
     searchTxt?: string[];
     productId: string;
     productTitle: string;
     userId: string;
-    userName: string;
-    userEmail: string;
+    userName: Encrypted<string>;
+    userEmail: Encrypted<string>;
     storeId?: string;
     storeName?: string;
     items?: OrderDocumentItem[];
@@ -778,9 +789,9 @@ export declare const ORDER_UPDATABLE_FIELDS: readonly ["notes", "shippingAddress
  * which is every single write — and exhaust the FIFO cap within days.
  */
 export declare const ORDER_TRACKED_FIELDS: readonly ["status", "paymentStatus", "paymentReviewOutcome", "trackingNumber", "cancellationReason"];
-export type OrderCreateInput = Omit<OrderDocument, "id" | "createdAt" | "updatedAt" | "orderDate">;
+export type OrderCreateInput = Omit<OrderPlain, "id" | "createdAt" | "updatedAt" | "orderDate">;
 export type OrderUpdateInput = Partial<Pick<OrderDocument, (typeof ORDER_UPDATABLE_FIELDS)[number]>>;
-export type OrderAdminUpdateInput = Partial<Omit<OrderDocument, "id" | "createdAt">>;
+export type OrderAdminUpdateInput = Partial<Omit<OrderPlain, "id" | "createdAt">>;
 export declare const orderQueryHelpers: {
     readonly byUser: (userId: string) => readonly ["userId", "==", string];
     readonly byStore: (storeId: string) => readonly ["storeId", "==", string];