@mohasinac/appkit 4.47.0 → 4.48.0

package/dist/_internal/server/features/products/list-public.js

@@ -41,6 +41,7 @@ import { PRODUCT_FIELDS } from "../../../../constants/field-names.js";
 import { TABLE_KEYS } from "../../../../constants/table-keys.js";
 import { sortBy } from "../../../../constants/sort.js";
 import { SIEVE_OP, sieveAnd, sieveFilter, expandSieveParam, } from "../../../../utils/sieve-builder.js";
+import { planSearchTxt } from "../../../../utils/search-txt-query.js";
 import { ALL_LISTING_TYPES } from "../../../shared/listing-types/feature-flags.js";
 import { isListingRowAvailable, unavailableClausesFor, } from "../../../shared/listing-types/_registry.js";
 import { AVAILABILITY_VALUES, isAvailabilityFilter, } from "../../../../constants/field-names.js";
@@ -241,7 +242,15 @@ export function parsePublicProductParams(params, defaults) {
  * index in an order nobody declares — it fails with FAILED_PRECONDITION, which
  * upstream reads as a bare "no results".
  */
-function buildFirestoreSafeFilters(input) {
+/**
+ * The Firestore-safe Sieve filter string.
+ *
+ * `omitCategory` exists for the one query Firestore cannot express as written:
+ * a search term inside a category. Both are array operators and Firestore
+ * permits one, so the category leaves `filters` and travels as `categoriesIn`,
+ * where the repository refines it in memory over the search window.
+ */
+function buildFirestoreSafeFilters(input, opts) {
     const parts = [];
     // Published-only unless the caller explicitly asks otherwise. Without this
     // default, any refetch that omits `status` leaks drafts (Root Cause #30).
@@ -253,7 +262,7 @@ function buildFirestoreSafeFilters(input) {
     if (types.length > 0) {
         parts.push(sieveFilter(PRODUCT_FIELDS.LISTING_TYPE, SIEVE_OP.EQ, types.join("|")));
     }
-    if (input.category) {
+    if (input.category && !opts?.omitCategory) {
         parts.push(expandSieveParam(PRODUCT_FIELDS.CATEGORY_SLUGS, input.category, SIEVE_OP.CONTAINS));
     }
     if (input.brand)
@@ -373,7 +382,15 @@ async function defaultExecutor(query) {
     // Without this second argument the repository's searchTxt read path is
     // unreachable on the default executor, which is what every SSR listing view
     // uses. It was implemented and simply never called.
-    query.search ? { search: query.search } : undefined);
+    //
+    // `categoriesIn` rides along for the one query Firestore cannot express as
+    // two array clauses — a search inside a category. See `PublicProductQuery`.
+    query.search || query.categoriesIn?.length
+        ? {
+            ...(query.search ? { search: query.search } : {}),
+            ...(query.categoriesIn?.length ? { categoriesIn: [...query.categoriesIn] } : {}),
+        }
+        : undefined);
     return {
         items: result.items,
         total: result.total,
@@ -415,6 +432,38 @@ export async function listPublicProducts(input, opts) {
     const sorts = input.sorts || DEFAULT_SORTS;
     const requestedSortField = sorts.replace(/^-/, "");
     const sortDesc = sorts.startsWith("-");
+    /*
+     * 🛑 THE EMPTY GUARD, HERE RATHER THAN ONLY IN THE REPOSITORY — measured
+     * live: `/api/products?q=!!!` returned the WHOLE CATALOGUE (50+, capped),
+     * which is A2's bug still reachable in production.
+     *
+     * `productRepository.list` has carried this guard for a while, but this
+     * function prefers the colocated `listingProcessor` Function on the one
+     * route that serves `/api/products`, and that Function has no such guard: it
+     * is handed a filter string with no search clause in it and answers with an
+     * unfiltered page. So the rule has to live where BOTH executors pass, which
+     * is here.
+     *
+     * `parseSearchTxtQuery` normalises punctuation away, so `"!!!"`, `"—"` and
+     * `"@#$"` all reduce to no usable token — and a query that produced none
+     * must return NOTHING. Falling through to the other filters is what turns a
+     * one-character search into "here is everything".
+     */
+    if (planSearchTxt(input.q).empty) {
+        return {
+            items: [],
+            total: 0,
+            page: 1,
+            pageSize: 0,
+            totalPages: 0,
+            hasMore: false,
+            cursor: null,
+            // Not truncated — this is an exact zero, not a saturated window.
+            truncated: false,
+            filters: "",
+            sorts: input.sorts || DEFAULT_SORTS,
+        };
+    }
     const availability = input.availability ?? AVAILABILITY_VALUES.ALL;
     const wantAvailable = availability === AVAILABILITY_VALUES.AVAILABLE;
     const wantUnavailable = availability === AVAILABILITY_VALUES.UNAVAILABLE;
@@ -423,7 +472,43 @@ export async function listPublicProducts(input, opts) {
     // Firestore DOES accept one inequality when the query sorts by that same
     // field, so a matching date facet can still be pushed down.
     const canPushDate = hasDateRange && !wantAvailable && requestedSortField === dateField;
-    const safeFilters = buildFirestoreSafeFilters(input);
+    /*
+     * 🛑 A SEARCH INSIDE A CATEGORY CANNOT RUN ON THE REMOTE EXECUTOR, and
+     * measured against the live container it returned **zero rows**, not a wrong
+     * set — which reads as "this category has nothing matching" and is the most
+     * convincing way to be wrong.
+     *
+     * The reason is Firestore's one-array-operator rule meeting two array
+     * clauses: the category travels inside `filters` as `categorySlugs @= …`
+     * (array-contains) and the search term becomes a second `array-contains` on
+     * `searchTxt` inside the repository. One of the two has to be refined in
+     * memory, and the colocated Function CANNOT do that — it is handed a filter
+     * string and returns a page.
+     *
+     * So when both are present this query runs on the DEFAULT executor, which
+     * holds the repository's refine (`beginSearchWindow` + the `categoriesIn`
+     * predicate). Measured live before the fix: `?q=dragoon` → 30,
+     * `?category=category-spinning-tops` → 50+, and the two together → 0.
+     *
+     * 🛑 The alternative — moving the category OUT of `filters` so the Function
+     * only sees the search — is strictly worse: the Function would then return
+     * the UNSCOPED catalogue and the page would silently widen instead of
+     * silently emptying. Same family as Root Cause #85: one handler reachable
+     * through two paths with different capabilities, where an env var decides
+     * which one answers.
+     */
+    const needsMemoryRefine = Boolean(input.q && input.category);
+    const executor = needsMemoryRefine ? defaultExecutor : (opts?.executor ?? defaultExecutor);
+    /*
+     * The category ids, as the repository's `categoriesIn` option rather than as
+     * a Sieve clause. Products carry their FULL ancestor chain, so a page passing
+     * its own id still matches its whole subtree — the refine and the pushdown
+     * agree by construction.
+     */
+    const categoriesIn = needsMemoryRefine
+        ? input.category.split("|").filter(Boolean)
+        : undefined;
+    const safeFilters = buildFirestoreSafeFilters(input, { omitCategory: needsMemoryRefine });
     const dateClauses = [
         ...(canPushDate && input.dateFrom
             ? [sieveFilter(dateField, SIEVE_OP.GTE, input.dateFrom)]
@@ -432,7 +517,6 @@ export async function listPublicProducts(input, opts) {
             ? [sieveFilter(dateField, SIEVE_OP.LTE, input.dateTo)]
             : []),
     ];
-    const executor = opts?.executor ?? defaultExecutor;
     const types = asListingTypes(input.listingTypes);
     // ── Path B: one type whose unavailability IS a pushable inequality, and the
     //    caller is already sorting by that field. Ended auctions sorted by end
@@ -465,6 +549,7 @@ export async function listPublicProducts(input, opts) {
             pageSize,
             cursor: input.cursor ?? null,
             search: input.q,
+            categoriesIn,
         });
         if (!result)
             return null;
@@ -502,6 +587,7 @@ export async function listPublicProducts(input, opts) {
                 pageSize: PUBLIC_PRODUCT_MAX_PAGE_SIZE,
                 cursor: null,
                 search: input.q,
+                categoriesIn,
             });
         }));
         // One failed branch must not blank the whole scope — but it is already
@@ -617,6 +703,7 @@ export async function listPublicProducts(input, opts) {
         pageSize: inMemory ? windowSize : pageSize,
         cursor: inMemory ? null : (input.cursor ?? null),
         search: input.q,
+        categoriesIn,
     });
     if (!result)
         return null;

package/dist/_internal/server/features/products/og.d.ts

@@ -18,4 +18,11 @@ export declare function renderProductOg(doc: ProductDocLike | null | undefined,
     baseUrl?: string;
 }): ReactElement;
 export declare function renderProductOgImage(data: ProductOgData, siteName: string): ReactElement;
+export interface CityOgData {
+    city: string;
+    state: string;
+    /** Exact listing count, or `null` when the read saturated its cap. */
+    listingCount: number | null;
+}
+export declare function renderCityOg(data: CityOgData, siteName: string): ReactElement;
 export {};

package/dist/_internal/server/features/products/og.js

@@ -1,3 +1,4 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { renderOgLayout } from "../seo/og-layout.js";
 import { resolveOgImageUrl } from "../seo/og.js";
 /** High-level OG renderer — accepts the raw product document from `getProductForDetail`. */
@@ -20,3 +21,40 @@ export function renderProductOgImage(data, siteName) {
         accentSlot: null,
     });
 }
+export function renderCityOg(data, siteName) {
+    const { city, state, listingCount } = data;
+    const sub = listingCount === null
+        ? "Classified listings — meet the seller, inspect, pay in person"
+        : listingCount === 0
+            ? "No classified listings here right now — everything on site ships nationwide"
+            : `${listingCount} classified listing${listingCount === 1 ? "" : "s"} — meet the seller, inspect, pay in person`;
+    return (_jsxs("div", { style: {
+            display: "flex",
+            width: "100%",
+            height: "100%",
+            background: "#0f172a",
+            fontFamily: "sans-serif",
+            position: "relative",
+            overflow: "hidden",
+            alignItems: "center",
+            justifyContent: "center",
+        }, children: [_jsx("div", { style: {
+                    position: "absolute",
+                    inset: 0,
+                    background: "linear-gradient(135deg, #0f172a 0%, #1e293b 100%)",
+                } }), _jsxs("div", { style: {
+                    position: "relative",
+                    display: "flex",
+                    flexDirection: "column",
+                    alignItems: "center",
+                    gap: 24,
+                    padding: "60px",
+                    textAlign: "center",
+                }, children: [_jsx("div", { style: {
+                            fontSize: 18,
+                            color: "#94a3b8",
+                            fontWeight: 500,
+                            letterSpacing: 2,
+                            textTransform: "uppercase",
+                        }, children: siteName }), _jsx("div", { style: { fontSize: 68, fontWeight: 800, color: "#f1f5f9", lineHeight: 1.1 }, children: city }), _jsx("div", { style: { fontSize: 28, color: "#cbd5e1", fontWeight: 600 }, children: state }), _jsx("div", { style: { fontSize: 24, color: "#94a3b8", maxWidth: 820, lineHeight: 1.5 }, children: sub })] })] }));
+}

package/dist/_internal/server/features/site-settings/adapters.d.ts

@@ -37,7 +37,7 @@ import type { PublicSiteSettings } from "../../../shared/features/site-settings/
  * was traced to a call site; anything without one belongs in the private list,
  * because an unused public field is pure attack surface.
  */
-export declare const PUBLIC_SITE_SETTINGS_FIELDS: readonly ["contact", "payment", "listings", "notificationChannels", "announcementBar", "navConfig", "actionConfig", "background", "watermark", "disabledRoutes"];
+export declare const PUBLIC_SITE_SETTINGS_FIELDS: readonly ["contact", "payment", "listings", "notificationChannels", "announcementBar", "navConfig", "actionConfig", "background", "watermark", "disabledRoutes", "chat"];
 /** Everything else, with the reason it stays server-side. */
 export declare const PRIVATE_SITE_SETTINGS_FIELDS: readonly ["id", "createdAt", "updatedAt", "credentials", "emailSettings", "legalPages", "commissions", "emi", "gst", "laborRate", "adSettings", "integrations", "platformLimits", "auctionConfig", "siteName", "tagline", "motto", "logo", "favicon", "seo", "socialLinks", "features", "shipping", "returns", "faq", "aboutContent", "navbarConfig", "footerConfig", "theme", "featuredResults", "messaging"];
 export interface ToPublicSiteSettingsOptions {

package/dist/_internal/server/features/site-settings/adapters.js

@@ -33,6 +33,10 @@ export const PUBLIC_SITE_SETTINGS_FIELDS = [
      * alternative is putting a per-request Firestore read back on the Edge.
      */
     "disabledRoutes",
+    // D9 — a signed-out visitor's listing/detail view needs to know whether to
+    // render a "Message seller" CTA at all. Narrowed to `enabled` only; there is
+    // nothing else in the group.
+    "chat",
 ];
 /** Everything else, with the reason it stays server-side. */
 export const PRIVATE_SITE_SETTINGS_FIELDS = [
@@ -106,5 +110,7 @@ export function toPublicSiteSettings(doc, opts) {
         // and leave the next person wondering whether the projection ran at all.
         disabledRoutes: doc.disabledRoutes ?? [],
         effectiveWatermark: opts?.effectiveWatermark,
+        // D9 — undefined reads as OFF, never a default-true `??`.
+        chat: { enabled: doc.chat?.enabled === true },
     };
 }

package/dist/_internal/server/jobs/core/cleanupRtdbEvents.js

@@ -13,6 +13,9 @@ const BULK_STALE_MS = 15 * 60 * 1000;
  * exist to prevent.
  */
 const EMAIL_STALE_MS = 60 * 60 * 1000;
+/** Long enough for an open thread to notice a ping before it prunes; the
+ * message itself lives in Firestore regardless — this only clears the ping. */
+const CHAT_STALE_MS = 15 * 60 * 1000;
 const JOBS_TTL_DAYS = 30;
 export async function runCleanupRtdbEvents(ctx) {
     ctx.logger.info("Starting RTDB events cleanup");
@@ -108,6 +111,31 @@ export async function runCleanupRtdbEvents(ctx) {
         void normalizeError(emailErr);
         ctx.logger.error("Email events cleanup failed (non-fatal)", emailErr);
     }
+    /*
+     * D9 — chat new-message pings. Its own file says it: "an unpruned RTDB
+     * channel is precisely the thing that quietly accumulates… Do not make it
+     * the second" (see the email block above, which is the first). The message
+     * content never lived here — only a ping — so pruning this touches nothing
+     * a thread needs; the Firestore conversation/message documents are handled
+     * by `notificationPrune`'s retention stages, entirely separately.
+     */
+    try {
+        const chatSnap = await rtdb.ref(RTDB_PATHS.CHAT_EVENTS).get();
+        if (chatSnap.exists()) {
+            const allChatEvents = chatSnap.val();
+            const staleChatIds = Object.entries(allChatEvents)
+                .filter(([, node]) => (node.updatedAt ?? 0) < now - CHAT_STALE_MS)
+                .map(([id]) => id);
+            if (staleChatIds.length > 0) {
+                await Promise.all(staleChatIds.map((id) => rtdb.ref(`${RTDB_PATHS.CHAT_EVENTS}/${id}`).remove()));
+                ctx.logger.info("Chat event pings removed", { count: staleChatIds.length });
+            }
+        }
+    }
+    catch (chatErr) {
+        void normalizeError(chatErr);
+        ctx.logger.error("Chat events cleanup failed (non-fatal)", chatErr);
+    }
     try {
         const staleJobRefs = await jobsRepository.getStaleFinishedRefs(JOBS_TTL_DAYS);
         if (staleJobRefs.length > 0) {

package/dist/_internal/server/jobs/core/notificationPrune.js

@@ -1,13 +1,97 @@
+import { normalizeError } from "../../../../errors/normalize.js";
 import { notificationRepository } from "../../../../repositories/index.js";
+import { conversationsRepository } from "../../../../features/messages/repository/conversations.repository.js";
+import { CONVERSATION_ACTIVE_DAYS, CONVERSATION_ARCHIVE_DAYS, } from "../../../../features/messages/schemas/firestore.js";
+import { deleteAllMessages, listAllAttachmentUrls, } from "../../../../features/messages/repository/messages.repository.js";
+import { mediaAssetsRepository } from "../../../../features/media/repository/media-assets.repository.js";
+import { getAdminStorageLite } from "../../../../providers/db-firebase/admin-storage-lite.js";
 import { NOTIFICATION_TTL_DAYS } from "../handlers/messages.js";
 import { batchDelete } from "../handlers/_helpers.js";
+const RETENTION_BATCH_LIMIT = 100;
+const PROXY_URL_PREFIX = "/media/";
+/**
+ * Delete a chat attachment's STORAGE OBJECT, then its `mediaAssets` doc.
+ *
+ * 🛑 Attachments die BEFORE the Firestore conversation document — the same
+ * class of defect as the missing TTL that got the feature deleted the first
+ * time: `mediaTmpCleanup` only sweeps `tmp/`, so a finalized `media/*` object
+ * would survive this prune as a permanent orphan if the document went first
+ * and nothing remembered which assets belonged to it.
+ */
+async function deleteAttachmentByProxyUrl(ctx, url) {
+    if (!url.startsWith(PROXY_URL_PREFIX))
+        return;
+    const shortId = url.slice(PROXY_URL_PREFIX.length);
+    if (shortId.includes("/"))
+        return;
+    try {
+        const asset = await mediaAssetsRepository.findById(shortId);
+        if (!asset)
+            return;
+        await getAdminStorageLite().bucket().file(asset.storagePath).delete({ ignoreNotFound: true });
+        await mediaAssetsRepository.delete(shortId);
+    }
+    catch (err) {
+        void normalizeError(err);
+        ctx.logger.warn("notificationPrune: failed to delete chat attachment (non-fatal)", { url });
+    }
+}
+/**
+ * D9 retention, folded into this job per its own "prune user-facing records
+ * past retention" charter — query-based with `.limit()`, never a
+ * whole-collection snapshot.
+ *
+ * | Stage | Age since lastMessageAt | Action |
+ * |---|---|---|
+ * | Active | 0–30d | normal |
+ * | Archived | 30d–7mo | hidden from the default inbox, read-only |
+ * | Deleted | >7mo | document + subcollection + attachments |
+ */
+async function runChatRetention(ctx) {
+    const now = Date.now();
+    const archiveCutoff = new Date(now - CONVERSATION_ACTIVE_DAYS * 24 * 60 * 60 * 1000);
+    const deleteCutoff = new Date(now - CONVERSATION_ARCHIVE_DAYS * 24 * 60 * 60 * 1000);
+    try {
+        const toArchive = await conversationsRepository.archiveStale(archiveCutoff, RETENTION_BATCH_LIMIT);
+        for (const conv of toArchive) {
+            await conversationsRepository.update(conv.id, { status: "archived" });
+        }
+        if (toArchive.length > 0) {
+            ctx.logger.info("Conversations archived", { count: toArchive.length });
+        }
+    }
+    catch (err) {
+        void normalizeError(err);
+        ctx.logger.error("Chat archive stage failed (non-fatal)", err);
+    }
+    try {
+        const toDelete = await conversationsRepository.findDeletable(deleteCutoff, RETENTION_BATCH_LIMIT);
+        for (const conv of toDelete) {
+            const attachmentUrls = await listAllAttachmentUrls(conv.id);
+            for (const url of attachmentUrls) {
+                await deleteAttachmentByProxyUrl(ctx, url);
+            }
+            await deleteAllMessages(conv.id);
+            await conversationsRepository.delete(conv.id);
+        }
+        if (toDelete.length > 0) {
+            ctx.logger.info("Conversations deleted past retention", { count: toDelete.length });
+        }
+    }
+    catch (err) {
+        void normalizeError(err);
+        ctx.logger.error("Chat delete stage failed (non-fatal)", err);
+    }
+}
 export async function runNotificationPrune(ctx) {
     ctx.logger.info(`Pruning read notifications older than ${NOTIFICATION_TTL_DAYS} days`);
     const refs = await notificationRepository.getOldReadRefs(NOTIFICATION_TTL_DAYS);
     if (refs.length === 0) {
         ctx.logger.info("No stale read notifications found");
-        return;
     }
-    const deleted = await batchDelete(ctx, refs);
-    ctx.logger.info("Notification prune complete", { deleted });
+    else {
+        const deleted = await batchDelete(ctx, refs);
+        ctx.logger.info("Notification prune complete", { deleted });
+    }
+    await runChatRetention(ctx);
 }

package/dist/_internal/server/jobs/core/priceIndexRollup.js

@@ -43,6 +43,7 @@
  */
 import { orderRepository, productRepository } from "../../../../repositories/index.js";
 import { priceIndexRepository, } from "../../../../features/categories/repository/price-index.repository.js";
+import { normaliseColourway } from "../../../../features/parts/utils/colourway-match.js";
 /** How far back a band looks. */
 export const PRICE_INDEX_WINDOW_DAYS = 90;
 /**
@@ -160,6 +161,28 @@ function toBand(samples) {
     for (const [condition, bucket] of byConditionSamples) {
         byCondition[condition] = toConditionBand(bucket);
     }
+    /*
+     * The per-COLOURWAY slice (I9), on exactly the same terms as the condition
+     * slice above — skipped when unrecorded, omitted rather than emitted empty.
+     *
+     * 🛑 It earns an axis because for a part it is a BIGGER price variable than
+     * condition: the silver Metal Ball and the transparent-black one are the same
+     * mould with the same stats, and one is rare and costly while the other is
+     * ordinary. One band over both reports a median that describes neither.
+     */
+    const byColourwaySamples = new Map();
+    for (const s of samples) {
+        const key = normaliseColourway(s.colourway);
+        if (!key)
+            continue;
+        const bucket = byColourwaySamples.get(key) ?? [];
+        bucket.push(s);
+        byColourwaySamples.set(key, bucket);
+    }
+    const byColourway = {};
+    for (const [colourway, bucket] of byColourwaySamples) {
+        byColourway[colourway] = toConditionBand(bucket);
+    }
     return {
         min: amounts[0],
         median: median(amounts),
@@ -168,6 +191,7 @@ function toBand(samples) {
         sampleSize: samples.length,
         byPath,
         ...(Object.keys(byCondition).length > 0 ? { byCondition } : {}),
+        ...(Object.keys(byColourway).length > 0 ? { byColourway } : {}),
         ...(latest ? { lastSold: { amount: latest.amount, at: latest.at, via: latest.via } } : {}),
     };
 }
@@ -198,6 +222,7 @@ export async function runPriceIndexRollup(ctx) {
     const leafOf = new Map();
     const typeOf = new Map();
     const conditionOf = new Map();
+    const colourwayOf = new Map();
     for (const p of rows) {
         if (!p.id)
             continue;
@@ -208,6 +233,8 @@ export async function runPriceIndexRollup(ctx) {
             typeOf.set(p.id, p.listingType);
         if (p.condition)
             conditionOf.set(p.id, p.condition);
+        if (p.colourway)
+            colourwayOf.set(p.id, p.colourway);
     }
     const delivered = (await orderRepository.findByStatus("delivered"));
     /** leafId → listingType → samples */
@@ -259,8 +286,16 @@ export async function runPriceIndexRollup(ctx) {
              * the map only answers for orders written before that.
              */
             const condition = item.condition ?? (item.productId ? conditionOf.get(item.productId) : undefined);
+            // Snapshot first, join second — same rule, same reason as `condition`.
+            const colourway = item.colourway ?? (item.productId ? colourwayOf.get(item.productId) : undefined);
             const samples = types.get(listingType) ?? [];
-            samples.push({ amount, at, via, ...(condition ? { condition } : {}) });
+            samples.push({
+                amount,
+                at,
+                via,
+                ...(condition ? { condition } : {}),
+                ...(colourway ? { colourway } : {}),
+            });
             types.set(listingType, samples);
             byLeaf.set(leaf, types);
             considered += 1;

package/dist/_internal/shared/actions/action-registry.js

@@ -160,6 +160,14 @@ export const ACTIONS = {
             description: "Open the native share sheet or copy the listing URL.",
             kind: "ghost",
         },
+        "message-seller": {
+            iconKey: "message",
+            id: "product.message-seller",
+            label: "Message Seller",
+            ariaLabel: "Message this listing's seller",
+            description: "Open or start a conversation with the seller. Absent entirely when chat is off.",
+            kind: "ghost",
+        },
         "compare": {
             iconKey: "analytics",
             id: "product.compare",

package/dist/_internal/shared/features/notifications/action-url.js

@@ -97,6 +97,12 @@ export function resolveNotificationActionUrl(relatedType, relatedId, audience) {
             return audience === "admin"
                 ? String(ROUTES.ADMIN.STORE_DETAIL(relatedId))
                 : String(ROUTES.STORE.DASHBOARD);
+        case "conversation":
+            // D9 — one universal inbox, reachable from any portal; there is no
+            // admin-specific thread view (admins moderate via reports, not a
+            // parallel inbox route). Lives under ROUTES.USER, same precedent as
+            // WISHLIST/CART — a real top-level path, not /user/messages.
+            return String(ROUTES.USER.MESSAGE_THREAD(relatedId));
         default: {
             /*
              * Exhaustiveness. A new `relatedType` cannot compile without an answer
@@ -164,4 +170,6 @@ export const TYPE_AUDIENCE = {
      */
     support_ticket_update: "buyer",
     scam_report_update: "buyer",
+    // D9 — one universal inbox; which human reads it is not role-dependent.
+    message_received: "buyer",
 };

package/dist/_internal/shared/features/notifications/email-eligibility.js

@@ -111,6 +111,9 @@ export const EMAIL_ELIGIBLE_TYPES = {
     // digest. This was the second 100-way fan-out — `onScamReportCreate` sent one
     // notification per employee, up to 100, for every report filed.
     scam_report_update: false,
+    // D9 — the conversation lives in the UI, same reasoning as
+    // support_ticket_update. A chat message is not a deadline.
+    message_received: false,
 };
 /**
  * Prefer this over indexing the map directly — the lookup is `boolean`, and a

package/dist/_internal/shared/features/site-settings/types.d.ts

@@ -38,6 +38,10 @@ export interface PublicSiteSettings {
     listings: {
         listingTypes?: NonNullable<SiteSettingsDocument["listings"]>["listingTypes"];
     };
+    /** D9 — off by default; `enabled: false` is emitted rather than omitted, same `always-present` reasoning as `disabledRoutes` below. */
+    chat?: {
+        enabled: boolean;
+    };
     notificationChannels?: NotificationChannelConfig;
     announcementBar?: SiteSettingsDocument["announcementBar"];
     navConfig?: SiteSettingsDocument["navConfig"];

package/dist/client.d.ts

@@ -300,6 +300,16 @@ export { useActiveAd } from "./features/homepage/hooks/useActiveAd";
 export type { ActiveAdRecord, ActiveAdCreative } from "./features/homepage/hooks/useActiveAd";
 export { registerAdSlot, registerAdSlots, unregisterAdSlot, clearAdRegistry, setAdConsentGranted, isAdConsentGranted, isAdSlotRenderable, } from "./features/homepage/ad-registry";
 export type { AdSlotId, AdProvider, AdSlotConfig } from "./features/homepage/ad-registry";
+/**
+ * D9 — chat. Client-only (every hook here is "use client"); the write path
+ * (actions) is server-only and lives in server.ts, never here.
+ */
+export { ConversationsInboxView } from "./features/messages/components/ConversationsInboxView";
+export { ConversationThreadView } from "./features/messages/components/ConversationThreadView";
+export { MessageSellerButton } from "./features/messages/components/MessageSellerButton";
+export type { MessageSellerButtonProps } from "./features/messages/components/MessageSellerButton";
+export { useConversations, useOpenConversation, useOpenConversationWithSeller, useConversationThread, useSendMessage, useMarkConversationRead, useBlockConversation, useUnreadMessageCount, } from "./features/messages/hooks/useMessages";
+export type { PendingMessage } from "./features/messages/hooks/useMessages";
 export { WishlistView, useGuestWishlist, useWishlistWithGuest } from "./features/wishlist/index";
 export type { WishlistViewProps, GuestWishlistItem, WishlistItem, WishlistResponse, WishlistProductData, EnrichedWishlistItem } from "./features/wishlist/index";
 export { WishlistCapWatcher } from "./features/wishlist/components/WishlistCapWatcher";

package/dist/client.js

@@ -332,6 +332,14 @@ export { UserSettingsView } from "./features/account/index.js";
 export { AdSlot } from "./features/homepage/components/AdSlot.js";
 export { useActiveAd } from "./features/homepage/hooks/useActiveAd.js";
 export { registerAdSlot, registerAdSlots, unregisterAdSlot, clearAdRegistry, setAdConsentGranted, isAdConsentGranted, isAdSlotRenderable, } from "./features/homepage/ad-registry.js";
+/**
+ * D9 — chat. Client-only (every hook here is "use client"); the write path
+ * (actions) is server-only and lives in server.ts, never here.
+ */
+export { ConversationsInboxView } from "./features/messages/components/ConversationsInboxView.js";
+export { ConversationThreadView } from "./features/messages/components/ConversationThreadView.js";
+export { MessageSellerButton } from "./features/messages/components/MessageSellerButton.js";
+export { useConversations, useOpenConversation, useOpenConversationWithSeller, useConversationThread, useSendMessage, useMarkConversationRead, useBlockConversation, useUnreadMessageCount, } from "./features/messages/hooks/useMessages.js";
 export { WishlistView, useGuestWishlist, useWishlistWithGuest } from "./features/wishlist/index.js";
 export { WishlistCapWatcher } from "./features/wishlist/components/WishlistCapWatcher.js";
 // The single wishlist heart. Exported here too because it is a "use client"

package/dist/constants/api-endpoints.d.ts

@@ -312,6 +312,22 @@ export declare const CONTACT_ENDPOINTS: {
 export declare const AD_ENDPOINTS: {
     readonly ACTIVE_BY_SLOT: (slotId: string) => string;
 };
+export declare const MESSAGE_ENDPOINTS: {
+    readonly LIST: (opts?: {
+        limit?: number;
+        cursor?: string;
+    }) => string;
+    readonly OPEN: "/api/messages";
+    readonly OPEN_WITH_SELLER: "/api/messages/with-seller";
+    readonly THREAD: (conversationId: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }) => string;
+    readonly READ: (conversationId: string) => string;
+    readonly BLOCK: (conversationId: string) => string;
+    readonly TOKEN: (conversationId: string) => string;
+    readonly UNREAD_COUNT: "/api/messages/unread-count";
+};
 export declare const EVENT_ENDPOINTS: {
     readonly LIST: "/api/events";
     readonly BY_ID: (id: string) => string;
@@ -799,6 +815,22 @@ export declare const API_ENDPOINTS: {
     readonly ADS: {
         readonly ACTIVE_BY_SLOT: (slotId: string) => string;
     };
+    readonly MESSAGES: {
+        readonly LIST: (opts?: {
+            limit?: number;
+            cursor?: string;
+        }) => string;
+        readonly OPEN: "/api/messages";
+        readonly OPEN_WITH_SELLER: "/api/messages/with-seller";
+        readonly THREAD: (conversationId: string, opts?: {
+            limit?: number;
+            cursor?: string;
+        }) => string;
+        readonly READ: (conversationId: string) => string;
+        readonly BLOCK: (conversationId: string) => string;
+        readonly TOKEN: (conversationId: string) => string;
+        readonly UNREAD_COUNT: "/api/messages/unread-count";
+    };
     readonly EVENTS: {
         readonly LIST: "/api/events";
         readonly BY_ID: (id: string) => string;
@@ -1285,6 +1317,22 @@ export declare const API_ROUTES: {
     readonly ADS: {
         readonly ACTIVE_BY_SLOT: (slotId: string) => string;
     };
+    readonly MESSAGES: {
+        readonly LIST: (opts?: {
+            limit?: number;
+            cursor?: string;
+        }) => string;
+        readonly OPEN: "/api/messages";
+        readonly OPEN_WITH_SELLER: "/api/messages/with-seller";
+        readonly THREAD: (conversationId: string, opts?: {
+            limit?: number;
+            cursor?: string;
+        }) => string;
+        readonly READ: (conversationId: string) => string;
+        readonly BLOCK: (conversationId: string) => string;
+        readonly TOKEN: (conversationId: string) => string;
+        readonly UNREAD_COUNT: "/api/messages/unread-count";
+    };
     readonly EVENTS: {
         readonly LIST: "/api/events";
         readonly BY_ID: (id: string) => string;