@mohasinac/appkit 4.29.1 → 4.30.0

package/dist/features/seller/components/SellerAnalyticsAlertsView.js

@@ -81,6 +81,7 @@ export function SellerAnalyticsAlertsView({ labels = {}, }) {
     });
     const alerts = data ?? [];
     const createMutation = useApiMutation({
+        errorMessage: "Failed to create alert",
         mutationFn: async () => {
             /*
              * Parsed against the SAME schema the route uses, before the request.
@@ -112,22 +113,21 @@ export function SellerAnalyticsAlertsView({ labels = {}, }) {
             setShowForm(false);
             setDraft(EMPTY_DRAFT);
         },
-        onError: (err) => showToast(err?.message ?? "Failed to create alert", "error"),
     });
     const toggleMutation = useApiMutation({
+        errorMessage: "Failed to update alert",
         mutationFn: async ({ id, isActive }) => apiClient.patch(SELLER_ENDPOINTS.ANALYTICS_ALERT_BY_ID(id), { isActive }),
         onSuccess: () => {
             void queryClient.invalidateQueries({ queryKey: ["seller", "analytics-alerts"] });
         },
-        onError: () => showToast("Failed to update alert", "error"),
     });
     const deleteMutation = useApiMutation({
+        errorMessage: "Failed to delete alert",
         mutationFn: async (id) => apiClient.delete(SELLER_ENDPOINTS.ANALYTICS_ALERT_BY_ID(id)),
         onSuccess: () => {
             showToast("Alert deleted", "success");
             void queryClient.invalidateQueries({ queryKey: ["seller", "analytics-alerts"] });
         },
-        onError: () => showToast("Failed to delete alert", "error"),
     });
     const toggleChannel = useCallback((ch) => {
         setDraft((d) => ({

package/dist/features/seller/components/SellerSidebar.js

@@ -62,13 +62,13 @@ function GroupsContent({ groups, activeHref, storeName, storeLogoURL, onItemClic
                         const hasActive = !!findActiveNavItem(group.items, activeHref);
                         return (_jsxs(Div, { className: "mb-0.5", children: [_jsx(Button, { type: "button", variant: "ghost", onClick: () => toggle(group.title), paddingX: "md", paddingY: "sm", weight: "semibold", rounded: "none", className: `w-full text-[0.6875rem] uppercase tracking-widest transition-colors ${hasActive && !isOpen
                                         ? CLS_NAV_ICON_ACTIVE
-                                        : "text-[var(--appkit-color-text-faint)] hover:text-[var(--appkit-color-text-muted)]"}`, children: _jsxs(Row, { align: "center", justify: "between", className: "w-full", children: [_jsx(Span, { children: group.title }), _jsx("svg", { className: `w-3 h-3 transition-transform duration-150 ${isOpen ? "rotate-180" : ""}`, fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2.5, d: "M19 9l-7 7-7-7" }) })] }) }), isOpen && (_jsx(Ul, { paddingX: "x-sm", paddingY: "y-bottom-xs", spacing: "2xs", children: group.items.map((item) => (_jsx(Li, { children: _jsx(NavLink, { item: item, isActive: activeItem?.href === item.href, onClick: onItemClick }) }, item.href))) }))] }, group.title));
+                                        : "text-[var(--appkit-color-text-faint)] hover:text-[var(--appkit-color-text-muted)]"}`, children: _jsxs(Row, { align: "center", justify: "between", className: "w-full", children: [_jsx(Span, { children: group.title }), _jsx("svg", { className: `w-3 h-3 transition-transform duration-150 ${isOpen ? "rotate-180" : ""} shrink-0`, fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2.5, d: "M19 9l-7 7-7-7" }) })] }) }), isOpen && (_jsx(Ul, { paddingX: "x-sm", paddingY: "y-bottom-xs", spacing: "2xs", children: group.items.map((item) => (_jsx(Li, { children: _jsx(NavLink, { item: item, isActive: activeItem?.href === item.href, onClick: onItemClick }) }, item.href))) }))] }, group.title));
                     })] })] }));
 }
 function DrawerPanel({ title, onClose, children }) {
     const { hand } = useHandMode();
     const { edgeClass, borderClass } = getSidebarOverlayClasses(hand);
-    return (_jsxs(Div, { className: "hidden lg:block", children: [_jsx(Div, { surface: "overlay-xs", className: "fixed inset-0 z-40 backdrop-blur-sm", onClick: onClose, "aria-hidden": "true" }), _jsxs(Stack, { border: "default", shadow: "2xl", role: "dialog", "aria-modal": "true", "aria-label": title, className: `fixed top-0 ${edgeClass} z-50 h-full w-64 ${borderClass}`, surface: "default", children: [_jsxs(Row, { border: "bottom-subtle", paddingY: "y-sm-tall", className: "shrink-0", padding: "x-md", align: "center", justify: "between", children: [_jsx(Span, { size: "xs", weight: "semibold", transform: "uppercase", color: "muted", children: title }), _jsx(IconButton, { "aria-label": "Close", variant: "ghost", size: "sm", onClick: onClose, icon: _jsx("svg", { className: "w-4 h-4", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M6 18L18 6M6 6l12 12" }) }) })] }), _jsx(Div, { className: `flex-1 ${__O.yAuto}`, children: children })] })] }));
+    return (_jsxs(Div, { className: "hidden lg:block", children: [_jsx(Div, { surface: "overlay-xs", className: "fixed inset-0 z-40 backdrop-blur-sm", onClick: onClose, "aria-hidden": "true" }), _jsxs(Stack, { border: "default", shadow: "2xl", role: "dialog", "aria-modal": "true", "aria-label": title, className: `fixed top-0 ${edgeClass} z-50 h-full w-64 ${borderClass}`, surface: "default", children: [_jsxs(Row, { border: "bottom-subtle", paddingY: "y-sm-tall", className: "shrink-0", padding: "x-md", align: "center", justify: "between", children: [_jsx(Span, { size: "xs", weight: "semibold", transform: "uppercase", color: "muted", children: title }), _jsx(IconButton, { "aria-label": "Close", variant: "ghost", size: "sm", onClick: onClose, icon: _jsx("svg", { className: "w-4 h-4 shrink-0", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M6 18L18 6M6 6l12 12" }) }) })] }), _jsx(Div, { className: `flex-1 ${__O.yAuto}`, children: children })] })] }));
 }
 export function StoreSidebar({ items, groups, activeHref, storeName, storeLogoURL, mobileOpen = false, desktopOpen = false, variant = "overlay", onCloseMobile, onToggle, renderFooter, }) {
     const close = onCloseMobile ?? (() => { });

package/dist/features/store-extensions/components/ReviewDecisionModal.js

@@ -44,7 +44,7 @@ import { Stack } from "../../../ui/components/Layout";
 import { Form } from "../../../ui/components/Form";
 import { FieldTextarea } from "../../../ui/forms/FieldTextarea";
 import { FormErrorSummary } from "../../../ui/forms/FormErrorSummary";
-import { applyZodIssues } from "../../../ui/forms/FormShell";
+import { applyZodIssues } from "../../../ui/forms/apply-zod-issues";
 import { useToast } from "../../../ui/components/Toast";
 import { normalizeError } from "../../../errors/normalize";
 export function ReviewDecisionModal({ isOpen, onClose, title, schema, status, noteField, noteLabel, noteHelp, notePlaceholder, confirmLabel, confirmVariant = "primary", onConfirm, }) {

package/dist/features/stores/repository/store.repository.d.ts

@@ -19,6 +19,27 @@ export declare class StoreRepository extends BaseRepository<StoreDocument> {
     private encryptSecrets;
     private decryptSecrets;
     protected mapDoc<D = StoreDocument>(snap: DocumentSnapshot): D;
+    /**
+     * LIST reads never carry the WhatsApp token — not even encrypted.
+     *
+     * `mapDoc` above decrypts it, and `listStores(model, activeOnly)` backs the
+     * PUBLIC `/stores` page. Once `sieveQuery` started routing list rows through
+     * `mapDoc` (it previously mapped documents itself and skipped every
+     * override), that decrypt would have put a plaintext Meta OAuth bearer token
+     * on a public listing — the exact shape of Root Cause #70.
+     *
+     * So the list path deliberately does NOT call `decryptSecrets`, and drops
+     * `accessToken` outright: a list has no legitimate use for it, and a value
+     * that is never in the payload cannot be leaked by a projection someone
+     * forgets to write.
+     *
+     * Detail reads are unchanged — `findBySlug`/`findById` still decrypt, so the
+     * WhatsApp settings and catalog-sync routes keep working exactly as before.
+     * Removing the decrypt from `mapDoc` itself is a separate, riskier change
+     * that CLAUDE.md explicitly defers; this closes the public-exposure half
+     * without touching the encryption round-trip at all.
+     */
+    protected mapDocForList<D = StoreDocument>(snap: DocumentSnapshot): D;
     update(id: string, data: Partial<StoreDocument>): Promise<StoreDocument>;
     /**
      * Create a new store.

package/dist/features/stores/repository/store.repository.js

@@ -36,6 +36,33 @@ export class StoreRepository extends BaseRepository {
     mapDoc(snap) {
         return this.decryptSecrets(super.mapDoc(snap));
     }
+    /**
+     * LIST reads never carry the WhatsApp token — not even encrypted.
+     *
+     * `mapDoc` above decrypts it, and `listStores(model, activeOnly)` backs the
+     * PUBLIC `/stores` page. Once `sieveQuery` started routing list rows through
+     * `mapDoc` (it previously mapped documents itself and skipped every
+     * override), that decrypt would have put a plaintext Meta OAuth bearer token
+     * on a public listing — the exact shape of Root Cause #70.
+     *
+     * So the list path deliberately does NOT call `decryptSecrets`, and drops
+     * `accessToken` outright: a list has no legitimate use for it, and a value
+     * that is never in the payload cannot be leaked by a projection someone
+     * forgets to write.
+     *
+     * Detail reads are unchanged — `findBySlug`/`findById` still decrypt, so the
+     * WhatsApp settings and catalog-sync routes keep working exactly as before.
+     * Removing the decrypt from `mapDoc` itself is a separate, riskier change
+     * that CLAUDE.md explicitly defers; this closes the public-exposure half
+     * without touching the encryption round-trip at all.
+     */
+    mapDocForList(snap) {
+        const doc = super.mapDoc(snap);
+        if (!doc.whatsappConfig)
+            return doc;
+        const { accessToken: _dropped, ...safeConfig } = doc.whatsappConfig;
+        return { ...doc, whatsappConfig: safeConfig };
+    }
     async update(id, data) {
         return super.update(id, this.encryptSecrets(data));
     }
@@ -179,6 +206,11 @@ export class StoreRepository extends BaseRepository {
             baseQuery,
             model,
             fields: sieveFields,
+            // Called DIRECTLY, not through `sieveQuery`, so the mapper has to be
+            // passed by hand — and it is the list mapper, never `mapDoc`. With
+            // `activeOnly` this is the public /stores listing; `mapDoc` decrypts the
+            // WhatsApp bearer token and a list has no use for it.
+            mapDoc: (snap) => this.mapDocForList(snap),
         });
     }
     /**

package/dist/features/whatsapp-bot/components/SellerWhatsAppSettingsView.js

@@ -123,7 +123,6 @@ export function SellerWhatsAppSettingsView({ hasCapability }) {
         },
         onError: (err) => {
             const msg = err instanceof Error ? err.message : "Failed to save settings";
-            showToast(msg, "error");
         },
     });
     // Catalog sync mutation (push: site → WhatsApp)
@@ -136,7 +135,6 @@ export function SellerWhatsAppSettingsView({ hasCapability }) {
         },
         onError: (err) => {
             const msg = err instanceof Error ? err.message : "Sync failed";
-            showToast(msg, "error");
         },
     });
     // Catalog import (pull: WhatsApp → site). Runs as the `whatsappCatalogImport`

package/dist/index.d.ts

@@ -411,7 +411,7 @@ export { unitOfWork } from "./core/index";
 export { useSiteSettings } from "./core/index";
 export type { ActionMiddleware } from "./core/index";
 export type { ActionMiddlewareContext } from "./core/index";
-export type { ActionResult } from "./core/index";
+export type { ActionResult } from "./_internal/shared/types/action-result";
 export { handleActionError } from "./utils/action-response";
 export type { CacheEntry } from "./core/index";
 export type { CacheOptions } from "./core/index";
@@ -799,6 +799,7 @@ export { createPiiRedactorMiddleware } from "./next/index";
 export { createRouteHandler } from "./next/index";
 export { createRouteMap } from "./next/index";
 export { errorResponse } from "./next/index";
+export { buildErrorEnvelope, toApiIssues, codeForStatus, type ApiErrorEnvelope, } from "./errors/error-envelope";
 export { getBooleanParam } from "./next/index";
 export { getNumberParam } from "./next/index";
 export { getOptionalSessionCookie } from "./next/index";
@@ -3139,7 +3140,7 @@ export { formatMonthYear } from "./utils/date.formatter";
 export { generateMediaFilename } from "./utils/id-generators";
 export { deriveContextTypeFromFilename } from "./utils/id-generators";
 export type { MediaFilenameContext } from "./utils/id-generators";
-export { resolveMediaUrl, resolveVideoUrl, FIREBASE_STORAGE_HOST, GCS_HOST } from "./utils/media-url";
+export { resolveMediaUrl, resolveVideoUrl, FIREBASE_STORAGE_HOST, GCS_HOST, isStoredMediaRef, MEDIA_PROXY_PREFIX, MEDIA_URL_MAX_LENGTH, MEDIA_URL_MESSAGE, APPROVED_MEDIA_DOMAINS, } from "./utils/media-url";
 export { generateFAQId } from "./utils/id-generators";
 export type { GenerateFAQIdInput } from "./utils/id-generators";
 export { generateCroppedImageFilename } from "./utils/id-generators";

package/dist/index.js

@@ -1640,6 +1640,9 @@ export { createRouteMap } from "./next/index";
 // [SERVER-ONLY]-Server-only â€" uses Node.js, Next.js server internals, or third-party server SDKs (auth, email, payment, shipping).
 // errorResponse - Model for error response.
 export { errorResponse } from "./next/index";
+// The one error-body shape, plus the Zod-issue narrower every route needs to
+// put field errors on the wire under the key ApiClientError actually reads.
+export { buildErrorEnvelope, toApiIssues, codeForStatus, } from "./errors/error-envelope";
 // [SERVER-ONLY]-Server-only â€" uses Node.js, Next.js server internals, or third-party server SDKs (auth, email, payment, shipping).
 // getBooleanParam - Helper for get boolean param.
 export { getBooleanParam } from "./next/index";
@@ -5550,7 +5553,7 @@ export { formatCurrency, formatFileSize } from "./utils/number.formatter";
 export { formatMonthYear } from "./utils/date.formatter";
 export { generateMediaFilename } from "./utils/id-generators"; // generateProductImageFilename already exported from "./utils/id-generators";
 export { deriveContextTypeFromFilename } from "./utils/id-generators";
-export { resolveMediaUrl, resolveVideoUrl, FIREBASE_STORAGE_HOST, GCS_HOST } from "./utils/media-url";
+export { resolveMediaUrl, resolveVideoUrl, FIREBASE_STORAGE_HOST, GCS_HOST, isStoredMediaRef, MEDIA_PROXY_PREFIX, MEDIA_URL_MAX_LENGTH, MEDIA_URL_MESSAGE, APPROVED_MEDIA_DOMAINS, } from "./utils/media-url";
 export { generateFAQId } from "./utils/id-generators";
 export { generateCroppedImageFilename } from "./utils/id-generators";
 // Messages / Conversations feature schemas

package/dist/next/api/api-response.d.ts

@@ -6,25 +6,42 @@
  */
 import { NextResponse } from "next/server";
 import type { JsonValue } from "@mohasinac/appkit";
+import type { ApiIssue } from "../../client/api/ApiError";
+import { type ApiErrorEnvelope } from "../../errors/error-envelope";
 export interface ApiSuccessResponse<T = unknown> {
     success: true;
     data?: T;
     message?: string;
     meta?: Record<string, JsonValue>;
 }
-export interface ApiErrorResponse {
-    success: false;
-    error: string;
-    details?: unknown;
-}
+export type ApiErrorResponse = ApiErrorEnvelope;
 export declare function successResponse<T>(data?: T, message?: string, status?: number, meta?: Record<string, JsonValue>): NextResponse<ApiSuccessResponse<T>>;
-export declare function errorResponse(error: string, status?: number, details?: unknown): NextResponse<ApiErrorResponse>;
+/**
+ * Options for an error response.
+ *
+ * This replaced a bare `details?: unknown` third positional argument that was
+ * carrying three mutually incompatible things across the codebase — a stable
+ * code string, an array of Zod issues, and arbitrary server-side context —
+ * all serialised under a `details` key that no client ever read. Narrowing the
+ * type is what let `tsc` enumerate every call site so each could be given the
+ * meaning it actually intended.
+ *
+ * Server-side context does NOT belong here: it goes to `serverLogger`. Only
+ * things the client can act on cross the wire.
+ */
+export interface ErrorResponseOptions {
+    /** Stable machine code. Defaults to one derived from `status`. */
+    code?: string;
+    /** Field-level validation issues — routed to inline field errors by `surfaceError`. */
+    issues?: ApiIssue[];
+    requestId?: string;
+}
+export declare function errorResponse(error: string, status?: number, opts?: ErrorResponseOptions): NextResponse<ApiErrorResponse>;
 /** Pre-built shorthand factories for common HTTP error responses. */
 export declare const ApiErrors: {
-    unauthorized: (message?: string) => NextResponse<ApiErrorResponse>;
-    forbidden: (message?: string) => NextResponse<ApiErrorResponse>;
-    notFound: (resource?: string) => NextResponse<ApiErrorResponse>;
-    badRequest: (message?: string, details?: unknown) => NextResponse<ApiErrorResponse>;
-    internalError: (message?: string) => NextResponse<ApiErrorResponse>;
-    validationError: (details: Error) => NextResponse<ApiErrorResponse>;
+    unauthorized: (message?: string) => NextResponse<ApiErrorEnvelope>;
+    forbidden: (message?: string) => NextResponse<ApiErrorEnvelope>;
+    notFound: (resource?: string) => NextResponse<ApiErrorEnvelope>;
+    badRequest: (message?: string, opts?: ErrorResponseOptions) => NextResponse<ApiErrorEnvelope>;
+    internalError: (message?: string) => NextResponse<ApiErrorEnvelope>;
 };

package/dist/next/api/api-response.js

@@ -5,6 +5,7 @@
  * No app-specific dependencies — safe to use in any project.
  */
 import { NextResponse } from "next/server";
+import { buildErrorEnvelope, } from "../../errors/error-envelope";
 export function successResponse(data, message, status = 200, meta) {
     return NextResponse.json({
         success: true,
@@ -13,12 +14,8 @@ export function successResponse(data, message, status = 200, meta) {
         ...(meta && { meta }),
     }, { status });
 }
-export function errorResponse(error, status = 400, details) {
-    return NextResponse.json({
-        success: false,
-        error,
-        ...(details !== undefined && { details }),
-    }, 
+export function errorResponse(error, status = 400, opts) {
+    return NextResponse.json(buildErrorEnvelope({ message: error, status, ...opts }), 
     // `no-store` — without this, Vercel's edge CDN can cache a transient
     // error response (cold-start 500, not-yet-synced 404) on a public GET
     // route indefinitely. Same root cause as the /media 404-caching bug.
@@ -29,7 +26,11 @@ export const ApiErrors = {
     unauthorized: (message = "Unauthorized") => errorResponse(message, 401),
     forbidden: (message = "Forbidden") => errorResponse(message, 403),
     notFound: (resource = "Resource") => errorResponse(`${resource} not found`, 404),
-    badRequest: (message = "Bad request", details) => errorResponse(message, 400, details),
+    badRequest: (message = "Bad request", opts) => errorResponse(message, 400, opts),
     internalError: (message = "Internal server error") => errorResponse(message, 500),
-    validationError: (details) => errorResponse("Validation failed", 422, details),
+    // `validationError` used to live here as a 422 taking a raw `Error`. It had
+    // ZERO call sites, and its status disagreed with every other validation
+    // producer (`apiHandler`, `routeHandler` and `mapToHttpError` all use 400).
+    // Deleted rather than aligned — a fourth spelling of "the body was invalid"
+    // is what this whole file is trying to stop having.
 };

package/dist/next/api/apiHandler.d.ts

@@ -1,3 +1,4 @@
+import type { ApiIssue } from "../../client/api/ApiError";
 interface SafeParseSchema<TInput> {
     safeParse: (input: unknown) => {
         success: true;
@@ -40,7 +41,11 @@ export interface ApiHandlerFactoryDeps<TRole, TRateLimitConfig, TUser> {
     applyRateLimit: (request: Request, config: TRateLimitConfig) => Promise<ApiRateLimitResult>;
     requireAuthFromRequest: (request: Request) => Promise<TUser>;
     requireRoleFromRequest: (request: Request, roles: TRole[]) => Promise<TUser>;
-    errorResponse: (message: string, status: number, issues?: unknown) => Response;
+    errorResponse: (message: string, status: number, opts?: {
+        code?: string;
+        issues?: ApiIssue[];
+        requestId?: string;
+    }) => Response;
     handleApiError: (error: unknown) => Response;
     getRateLimitExceededMessage: () => string;
     logTiming: (entry: {

package/dist/next/api/apiHandler.js

@@ -1,4 +1,6 @@
 import { normalizeError } from "../../errors/normalize";
+import { toApiIssues } from "../../errors/error-envelope";
+import { HTTP_ERROR_CODES } from "../../errors/error-mapping";
 async function validateSchema(request, schema) {
     if (typeof schema.safeParse === "function") {
         const body = await request.json();
@@ -49,7 +51,17 @@ async function applyRateLimitCheck(request, config, applyRateLimit, getRateLimit
 async function applySchemaValidation(request, schema, errorResponse) {
     const schemaResult = await validateSchema(request, schema);
     if (schemaResult.validationError) {
-        return { invalid: true, response: errorResponse("Validation failed", 400, schemaResult.issues) };
+        // The issues travel as `issues`, which is the key ApiClientError reads.
+        // They used to be passed positionally and serialised under `details`,
+        // where nothing read them — so every schema rejection on every route
+        // reached the user as a bare "Validation failed" with no field name.
+        return {
+            invalid: true,
+            response: errorResponse("Validation failed", 400, {
+                code: HTTP_ERROR_CODES.VALIDATION_FAILED,
+                issues: toApiIssues(schemaResult.issues),
+            }),
+        };
     }
     return { invalid: false, data: schemaResult.data };
 }

package/dist/next/api/routeHandler.js

@@ -32,6 +32,7 @@ import { NextResponse } from "next/server.js";
 import { getProviders } from "../../contracts";
 import { isEffectiveAdminUser } from "../../features/auth/role-predicates";
 import { mapToHttpError, HTTP_ERROR_CODES } from "../../errors/error-mapping";
+import { buildErrorEnvelope, toApiIssues } from "../../errors/error-envelope";
 import { serverErrorsRepository } from "../../features/server-errors/repository/server-errors.repository";
 import { userRepository } from "../../repositories";
 import { SCHEMAS } from "../../schemas/registry";
@@ -121,14 +122,13 @@ function resolveBodySchema(schema) {
  * this helper and the audit re-runs to enforce the cleanup.
  */
 function errorJson(status, code, message, requestId, issues) {
-    return NextResponse.json({
-        ok: false,
-        success: false, // deprecated — for compat during the migration sweep
+    return NextResponse.json(buildErrorEnvelope({
+        message,
+        status,
         code,
-        error: message,
-        ...(issues ? { issues } : {}),
+        issues: toApiIssues(issues),
         requestId,
-    }, {
+    }), {
         status,
         // `no-store` on every error envelope — without this, Vercel's edge CDN
         // can cache a transient failure (cold-start 500, not-yet-synced 404)

package/dist/next/middleware/pii-scrubber.js

@@ -1,8 +1,11 @@
 import { normalizeError } from "../../errors/normalize";
 import { NextResponse } from "next/server";
-const ENC_PREFIX = "enc:v1:";
+import { hasEncPrefix } from "../../security/pii-mask";
+// Scrubbing wants EVERY `enc:v1:` value gone, whichever of the two crypto
+// systems wrote it and even if malformed — so `hasEncPrefix`, not
+// `isPiiEncrypted`, which is now specifically the PII format.
 function scrubValue(value) {
-    if (typeof value === "string" && value.startsWith(ENC_PREFIX)) {
+    if (hasEncPrefix(value)) {
         return "[encrypted]";
     }
     if (Array.isArray(value))

package/dist/providers/db-firebase/base.repository.d.ts

@@ -7,6 +7,20 @@ export declare abstract class BaseRepository<T extends DocumentData> {
     protected get db(): Firestore;
     protected getCollection(): CollectionReference<DocumentData, DocumentData>;
     protected mapDoc<D = T>(snap: DocumentSnapshot): D;
+    /**
+     * How a row is mapped on a LIST read (anything through `sieveQuery`).
+     *
+     * Defaults to `mapDoc`, so a repository that overrides `mapDoc` to decrypt,
+     * project or normalise now gets that on list reads too — Sieve used to map
+     * documents itself and never call `mapDoc` at all, which is why
+     * `/api/admin/users` served ciphertext emails.
+     *
+     * It is a SEPARATE hook because a list is not a detail read. A repository
+     * whose `mapDoc` decrypts a secret must not hand that secret to a list —
+     * `StoreRepository` overrides this to drop the WhatsApp token, since
+     * `listStores(activeOnly)` backs the PUBLIC /stores page.
+     */
+    protected mapDocForList<D = T>(snap: DocumentSnapshot): D;
     findById(id: string): Promise<T | null>;
     findByIdOrFail(id: string): Promise<T>;
     findBy(field: string, value: unknown): Promise<T[]>;

package/dist/providers/db-firebase/base.repository.js

@@ -34,6 +34,22 @@ export class BaseRepository {
             ...(snap.data() ?? {}),
         });
     }
+    /**
+     * How a row is mapped on a LIST read (anything through `sieveQuery`).
+     *
+     * Defaults to `mapDoc`, so a repository that overrides `mapDoc` to decrypt,
+     * project or normalise now gets that on list reads too — Sieve used to map
+     * documents itself and never call `mapDoc` at all, which is why
+     * `/api/admin/users` served ciphertext emails.
+     *
+     * It is a SEPARATE hook because a list is not a detail read. A repository
+     * whose `mapDoc` decrypts a secret must not hand that secret to a list —
+     * `StoreRepository` overrides this to drop the WhatsApp token, since
+     * `listStores(activeOnly)` backs the PUBLIC /stores page.
+     */
+    mapDocForList(snap) {
+        return this.mapDoc(snap);
+    }
     async findById(id) {
         try {
             const doc = await this.getCollection().doc(id).get();
@@ -219,6 +235,12 @@ export class BaseRepository {
             model,
             fields,
             options: sieveOptions,
+            // Load-bearing. Without this every Sieve-backed read silently skips the
+            // subclass's mapDoc — decryption, projection and normalisation all lost.
+            // audit-repository-fields asserts this argument stays here, because one
+            // edit removing it would unwire all 14 affected repositories at once
+            // while the per-file rule still passed.
+            mapDoc: (snap) => this.mapDocForList(snap),
         });
     }
     /**

package/dist/providers/db-firebase/sieve.d.ts

@@ -66,7 +66,7 @@
  * Add nested-field indexes explicitly; Firestore does not auto-index nested
  * paths in composite indexes declared at the root level.
  */
-import type { CollectionReference, DocumentData, Query } from "firebase-admin/firestore";
+import type { CollectionReference, DocumentData, Query, QueryDocumentSnapshot } from "firebase-admin/firestore";
 import { FirebaseRepository } from "./base";
 import { expandFilterAliases as _expandFilterAliases, type SieveFilterAlias, type SieveFilterAliases } from "./filter-aliases";
 export { _expandFilterAliases as expandFilterAliases, type SieveFilterAlias, type SieveFilterAliases, };
@@ -153,6 +153,19 @@ export declare function applySieveToFirestore<T extends DocumentData>(params: {
     model: SieveModel;
     fields: SieveFields;
     options?: SieveOptions;
+    /**
+     * Row mapper. Defaults to the same plain `deserializeTimestamps({id, ...data})`
+     * this function always did — so it is a provable no-op for the ~40
+     * repositories that don't override `mapDoc`.
+     *
+     * It exists because this function mapped documents ITSELF and never called
+     * the repository's `mapDoc`, so every read that went through Sieve skipped
+     * whatever that override did: decryption, projection, normalisation. The
+     * visible consequence was `/api/admin/users` serving `enc:v1:…` ciphertext
+     * as each user's email address, since `UserRepository.mapDoc` is what
+     * decrypts and `list()` goes through here.
+     */
+    mapDoc?: (snap: QueryDocumentSnapshot) => T;
 }): Promise<SieveResult<T>>;
 export declare abstract class FirebaseSieveRepository<T extends DocumentData> extends FirebaseRepository<T> {
     /**

package/dist/providers/db-firebase/sieve.js

@@ -189,7 +189,9 @@ export async function applySieveToFirestore(params) {
     // the full Sieve DSL from the base.
     const pagedQ = filteredQ.offset((page - 1) * pageSize).limit(pageSize);
     const snap = await pagedQ.get();
-    const items = snap.docs.map((d) => deserializeTimestamps({ id: d.id, ...d.data() }));
+    const items = snap.docs.map((d) => params.mapDoc
+        ? params.mapDoc(d)
+        : deserializeTimestamps({ id: d.id, ...d.data() }));
     const totalPages = total === 0 ? 0 : Math.max(1, Math.ceil(total / pageSize));
     return {
         items,

package/dist/security/pii-encrypt.d.ts

@@ -22,10 +22,6 @@ export declare function decryptValue(ciphertext: string): string;
  */
 export declare function hmacBlindIndex(value: string): string;
 export declare function encryptPiiFields<T extends object>(doc: T, piiFields: string[]): T;
-/**
- * Decrypt specified PII fields in a Firestore document.
- * Fields that are not encrypted (no `enc:v1:` prefix) are passed through.
- */
 export declare function decryptPiiFields<T extends object>(doc: T, piiFields: string[]): T;
 /** Alias for encryptValue — encrypts a PII plaintext string. */
 export declare function encryptPii(plaintext: string | null | undefined): string | null | undefined;