@mohasinac/appkit 4.47.0 → 4.48.0

package/dist/features/messages/hooks/useMessages.js

@@ -0,0 +1,113 @@
+"use client";
+import { useCallback, useMemo, useState } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { apiClient } from "../../../http/ApiClient.js";
+import { useApiMutation } from "../../../client/api/useApiMutation.js";
+import { MESSAGE_ENDPOINTS } from "../../../constants/api-endpoints.js";
+import { useConversationChannel } from "./useConversationChannel.js";
+/**
+ * The inbox list. Bounded (<=50), newest-first — this IS the query the
+ * unread badge also sums over, so there is no second "just for the count"
+ * query anywhere (D9 spec: "not a second global poll").
+ */
+export function useConversations(limit = 20, enabled = true) {
+    return useQuery({
+        queryKey: ["conversations", limit],
+        queryFn: () => apiClient.get(MESSAGE_ENDPOINTS.LIST({ limit })),
+        staleTime: 30000,
+        enabled,
+    });
+}
+export function useOpenConversation() {
+    return useApiMutation({
+        mutationFn: ({ otherUserId }) => apiClient.post(MESSAGE_ENDPOINTS.OPEN, { otherUserId }),
+        errorMessage: "Could not open the conversation.",
+    });
+}
+/** D11 — the entry point a product/store page actually has: a storeId, not
+ * the owner's uid. Resolution happens server-side. */
+export function useOpenConversationWithSeller() {
+    return useApiMutation({
+        mutationFn: ({ storeId }) => apiClient.post(MESSAGE_ENDPOINTS.OPEN_WITH_SELLER, { storeId }),
+        errorMessage: "Could not message this seller.",
+    });
+}
+/**
+ * One thread. Combines the bounded REST page with the RTDB ping channel —
+ * a ping triggers `refetch()`, never a client Firestore listener
+ * (`firestore.rules` forbids one entirely).
+ */
+export function useConversationThread(conversationId) {
+    const queryClient = useQueryClient();
+    const queryKey = useMemo(() => ["conversation-messages", conversationId], [conversationId]);
+    const query = useQuery({
+        queryKey,
+        queryFn: () => apiClient.get(MESSAGE_ENDPOINTS.THREAD(conversationId, { limit: 30 })),
+        enabled: Boolean(conversationId),
+        staleTime: 10000,
+    });
+    const getToken = useCallback((id) => apiClient.post(MESSAGE_ENDPOINTS.TOKEN(id), {}), []);
+    const onPing = useCallback(() => {
+        void queryClient.invalidateQueries({ queryKey });
+    }, [queryClient, queryKey]);
+    const { error: channelError } = useConversationChannel(conversationId, getToken, onPing);
+    return { ...query, channelError };
+}
+/**
+ * Optimistic send with an explicit pending/failed state and retry — a silent
+ * failure is how the old feature hid (D9 spec). `clientMessageId` is a stable
+ * uuid generated by the CALLER at compose time (not on each attempt), so a
+ * retry reuses the same id and the server resolves it as the same message
+ * rather than a duplicate.
+ */
+export function useSendMessage(conversationId) {
+    const queryClient = useQueryClient();
+    const [pending, setPending] = useState([]);
+    const queryKey = useMemo(() => ["conversation-messages", conversationId], [conversationId]);
+    const mutation = useApiMutation({
+        mutationFn: (vars) => apiClient.post(MESSAGE_ENDPOINTS.THREAD(conversationId), vars),
+        onMutate: (vars) => {
+            setPending((prev) => [
+                ...prev.filter((p) => p.clientMessageId !== vars.clientMessageId),
+                { clientMessageId: vars.clientMessageId, body: vars.body, status: "pending" },
+            ]);
+        },
+        onSuccess: (_data, vars) => {
+            setPending((prev) => prev.filter((p) => p.clientMessageId !== vars.clientMessageId));
+            void queryClient.invalidateQueries({ queryKey });
+        },
+        onError: (_err, vars) => {
+            setPending((prev) => prev.map((p) => p.clientMessageId === vars.clientMessageId ? { ...p, status: "failed" } : p));
+        },
+        errorMessage: "Message not sent. Tap to retry.",
+    });
+    const retry = useCallback((p) => {
+        mutation.mutate({ body: p.body, clientMessageId: p.clientMessageId });
+    }, [mutation]);
+    return { ...mutation, pending, retry };
+}
+export function useMarkConversationRead() {
+    const queryClient = useQueryClient();
+    return useApiMutation({
+        mutationFn: ({ conversationId }) => apiClient.post(MESSAGE_ENDPOINTS.READ(conversationId), {}),
+        onSuccess: () => void queryClient.invalidateQueries({ queryKey: ["conversations"] }),
+    });
+}
+export function useBlockConversation() {
+    const queryClient = useQueryClient();
+    return useApiMutation({
+        mutationFn: ({ conversationId }) => apiClient.post(MESSAGE_ENDPOINTS.BLOCK(conversationId), {}),
+        successMessage: "Blocked. They can no longer message you in this conversation.",
+        onSuccess: (_d, vars) => void queryClient.invalidateQueries({ queryKey: ["conversation-messages", vars.conversationId] }),
+    });
+}
+/** The nav badge's source when the inbox itself is not mounted — never a
+ * second list query of its own. */
+export function useUnreadMessageCount(enabled) {
+    return useQuery({
+        queryKey: ["messages-unread-count"],
+        queryFn: () => apiClient.get(MESSAGE_ENDPOINTS.UNREAD_COUNT),
+        staleTime: 60000,
+        enabled,
+    });
+}

package/dist/features/messages/repository/conversations.repository.d.ts

@@ -0,0 +1,44 @@
+import { BaseRepository, type DocumentSnapshot } from "../../../providers/db-firebase";
+import { type ConversationDocument, type ConversationLastMessage, type ParticipantRole } from "../schemas/firestore";
+/**
+ * Top-level `conversations` collection. PII encryption: `lastMessage.body`
+ * (dot-path form — see `encryptPiiFields`), applied via `piiFields` so every
+ * mutating method inherits it (Root Cause #9 — never bypass repo hooks).
+ */
+export declare class ConversationsRepository extends BaseRepository<ConversationDocument> {
+    constructor();
+    protected piiFields: readonly ["lastMessage.body"];
+    protected mapDoc<D = ConversationDocument>(snap: DocumentSnapshot): D;
+    /**
+     * Find the (at most one) existing thread between two users. Participant
+     * pairs are unordered — `array-contains` on one id, then an in-memory check
+     * of the other, since Firestore has no "array contains both" operator and a
+     * composite `array-contains-any` would also match threads with only one of
+     * the two.
+     */
+    findBetween(userIdA: string, userIdB: string): Promise<ConversationDocument | null>;
+    createBetween(userIdA: string, userIdB: string, roles: Record<string, ParticipantRole>): Promise<ConversationDocument>;
+    /**
+     * Cursor-paginated, newest-first. Bounded by construction — the absence of
+     * a `.limit()` is literally what turned 20 messages into ~1,600 reads the
+     * first time this feature existed.
+     */
+    listForUser(userId: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: ConversationDocument[];
+        nextCursor: string | null;
+    }>;
+    /**
+     * After a message write: bump the denormalized preview, the per-recipient
+     * unread counter, and `messageCount` — all in one update so a reader never
+     * observes `lastMessage` ahead of `unread`.
+     */
+    applyNewMessage(conversationId: string, authorId: string, recipientId: string, lastMessage: ConversationLastMessage): Promise<void>;
+    markRead(conversationId: string, userId: string): Promise<void>;
+    blockParticipant(conversationId: string, blockerId: string): Promise<void>;
+    archiveStale(before: Date, limit: number): Promise<ConversationDocument[]>;
+    findDeletable(before: Date, limit: number): Promise<ConversationDocument[]>;
+}
+export declare const conversationsRepository: ConversationsRepository;

package/dist/features/messages/repository/conversations.repository.js

@@ -0,0 +1,173 @@
+import { normalizeError } from "../../../errors/normalize.js";
+import { DatabaseError } from "../../../errors/index.js";
+import { BaseRepository, prepareForFirestore, } from "../../../providers/db-firebase/index.js";
+import { arrayUnion, increment } from "../../../contracts/field-ops.js";
+import { CONVERSATION_PII_FIELDS, decryptPiiFields } from "../../../security/index.js";
+import { CONVERSATIONS_COLLECTION, CONVERSATION_FIELDS, } from "../schemas/firestore.js";
+/**
+ * Top-level `conversations` collection. PII encryption: `lastMessage.body`
+ * (dot-path form — see `encryptPiiFields`), applied via `piiFields` so every
+ * mutating method inherits it (Root Cause #9 — never bypass repo hooks).
+ */
+export class ConversationsRepository extends BaseRepository {
+    constructor() {
+        super(CONVERSATIONS_COLLECTION);
+        this.piiFields = CONVERSATION_PII_FIELDS;
+    }
+    /*
+     * Every caller of findById/findBetween/listForUser is reached ONLY through
+     * _internal/server/features/messages/actions.ts, which calls
+     * requireConversation()+assertParticipant() before a document ever crosses a
+     * route boundary — unlike the 14 staged repos (admin listings, bulk
+     * exports) that can hand a decrypted doc to an operator who never needed to
+     * see it, a conversation's lastMessage.body preview is BY DESIGN shown only
+     * to its two participants, and that gate already lives one layer up. No
+     * route, view or admin surface reads this repository directly.
+     */
+    // audit-pii-coverage-ok: gated one layer up in actions.ts, see comment above
+    mapDoc(snap) {
+        const raw = super.mapDoc(snap);
+        return decryptPiiFields(raw, [...CONVERSATION_PII_FIELDS]);
+    }
+    /**
+     * Find the (at most one) existing thread between two users. Participant
+     * pairs are unordered — `array-contains` on one id, then an in-memory check
+     * of the other, since Firestore has no "array contains both" operator and a
+     * composite `array-contains-any` would also match threads with only one of
+     * the two.
+     */
+    async findBetween(userIdA, userIdB) {
+        try {
+            const snap = await this.getCollection()
+                .where(CONVERSATION_FIELDS.PARTICIPANT_IDS, "array-contains", userIdA)
+                .get();
+            const match = snap.docs.find((d) => {
+                const ids = d.data().participantIds ?? [];
+                return ids.includes(userIdB);
+            });
+            return match ? this.mapDoc(match) : null;
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(`Failed to look up conversation between ${userIdA} and ${userIdB}`, error);
+        }
+    }
+    async createBetween(userIdA, userIdB, roles) {
+        const now = new Date();
+        const data = {
+            participantIds: [userIdA, userIdB],
+            participantRoles: roles,
+            lastReadAt: {},
+            unread: { [userIdA]: 0, [userIdB]: 0 },
+            status: "active",
+            messageCount: 0,
+            createdAt: now,
+            updatedAt: now,
+        };
+        const docRef = this.getCollection().doc();
+        const hooked = this.applyWriteHooks(data);
+        await docRef.set(prepareForFirestore(hooked));
+        const created = await this.findById(docRef.id);
+        if (!created) {
+            throw new DatabaseError(`Conversation ${docRef.id} not readable immediately after create`, null);
+        }
+        return created;
+    }
+    /**
+     * Cursor-paginated, newest-first. Bounded by construction — the absence of
+     * a `.limit()` is literally what turned 20 messages into ~1,600 reads the
+     * first time this feature existed.
+     */
+    async listForUser(userId, opts = {}) {
+        const limit = Math.min(opts.limit ?? 20, 50);
+        try {
+            let query = this.getCollection()
+                .where(CONVERSATION_FIELDS.PARTICIPANT_IDS, "array-contains", userId)
+                .orderBy(CONVERSATION_FIELDS.LAST_MESSAGE_AT, "desc")
+                .limit(limit + 1);
+            if (opts.cursor) {
+                const cursorDoc = await this.getCollection().doc(opts.cursor).get();
+                if (cursorDoc.exists)
+                    query = query.startAfter(cursorDoc);
+            }
+            const snap = await query.get();
+            const docs = snap.docs.slice(0, limit);
+            const items = docs.map((d) => this.mapDoc(d));
+            const nextCursor = snap.docs.length > limit ? docs[docs.length - 1].id : null;
+            return { items, nextCursor };
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(`Failed to list conversations for ${userId}`, error);
+        }
+    }
+    /**
+     * After a message write: bump the denormalized preview, the per-recipient
+     * unread counter, and `messageCount` — all in one update so a reader never
+     * observes `lastMessage` ahead of `unread`.
+     */
+    async applyNewMessage(conversationId, authorId, recipientId, lastMessage) {
+        try {
+            const hooked = this.applyWriteHooks({ lastMessage });
+            // `messageCount` and `unread.{recipientId}` are real Firestore
+            // increments, not a read-modify-write, so two near-simultaneous sends
+            // cannot lose a count the way `item-requests/[id]/replies` once did.
+            await this.getCollection()
+                .doc(conversationId)
+                .update(prepareForFirestore({
+                lastMessage: hooked.lastMessage,
+                lastMessageAt: lastMessage.at,
+                [`unread.${recipientId}`]: increment(1),
+                messageCount: increment(1),
+                updatedAt: new Date(),
+            }));
+            void authorId;
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(`Failed to apply new message to conversation ${conversationId}`, error);
+        }
+    }
+    async markRead(conversationId, userId) {
+        await this.getCollection()
+            .doc(conversationId)
+            .update({
+            [`lastReadAt.${userId}`]: new Date().toISOString(),
+            [`unread.${userId}`]: 0,
+            updatedAt: new Date(),
+        });
+    }
+    async blockParticipant(conversationId, blockerId) {
+        await this.getCollection()
+            .doc(conversationId)
+            .update({ blockedBy: arrayUnion(blockerId), updatedAt: new Date() });
+    }
+    async archiveStale(before, limit) {
+        try {
+            const snap = await this.getCollection()
+                .where(CONVERSATION_FIELDS.STATUS, "==", "active")
+                .where(CONVERSATION_FIELDS.LAST_MESSAGE_AT, "<", before)
+                .limit(limit)
+                .get();
+            return snap.docs.map((d) => this.mapDoc(d));
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError("Failed to list conversations due for archive", error);
+        }
+    }
+    async findDeletable(before, limit) {
+        try {
+            const snap = await this.getCollection()
+                .where(CONVERSATION_FIELDS.LAST_MESSAGE_AT, "<", before)
+                .limit(limit)
+                .get();
+            return snap.docs.map((d) => this.mapDoc(d));
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError("Failed to list conversations due for deletion", error);
+        }
+    }
+}
+export const conversationsRepository = new ConversationsRepository();

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

@@ -0,0 +1,42 @@
+import { type MessageDocument } from "../schemas/firestore";
+export interface CreateMessageInput {
+    conversationId: string;
+    authorId: string;
+    body: string;
+    clientMessageId: string;
+    attachments?: string[];
+    productRef?: MessageDocument["productRef"];
+}
+/**
+ * Idempotent on `(conversationId, clientMessageId)` — a retry on a flaky
+ * connection must not double-post. The doc id IS the client message id, so a
+ * duplicate `set()` (non-merge) on an existing id throws `ALREADY_EXISTS`
+ * rather than silently overwriting a different author's message that happened
+ * to reuse an id (which cannot happen across conversations since this is
+ * scoped under one, but a malicious resend of someone else's id must not
+ * silently replace it either).
+ */
+export declare function createMessage(input: CreateMessageInput): Promise<MessageDocument>;
+/**
+ * Cursor-paginated, newest-first, `limit(30)` — the absence of a limit is
+ * literally what made the old feature expensive (20 messages -> ~1,600 reads
+ * across both participants' list refetches).
+ */
+export declare function listMessages(conversationId: string, opts?: {
+    limit?: number;
+    cursor?: string;
+}): Promise<{
+    items: MessageDocument[];
+    nextCursor: string | null;
+}>;
+/** Tombstone, never a hard delete of a single message — see schema comment. */
+export declare function softDeleteMessage(conversationId: string, messageId: string, deletedBy: string): Promise<void>;
+/**
+ * Retention — delete every message in a conversation being pruned. Bounded
+ * batches, never a whole-subcollection snapshot in one go for a thread that
+ * somehow grew very large.
+ */
+export declare function deleteAllMessages(conversationId: string): Promise<number>;
+/** All attachment URLs across a conversation's messages — for retention's
+ * "attachments die before the document" step. */
+export declare function listAllAttachmentUrls(conversationId: string): Promise<string[]>;

package/dist/features/messages/repository/messages.repository.js

@@ -0,0 +1,142 @@
+import { getAdminDb } from "../../../providers/db-firebase/admin.js";
+import { normalizeError } from "../../../errors/normalize.js";
+import { DatabaseError } from "../../../errors/index.js";
+import { encryptPiiFields, decryptPiiFields, MESSAGE_PII_FIELDS } from "../../../security/index.js";
+import { CONVERSATIONS_COLLECTION, MESSAGES_SUBCOLLECTION, MESSAGE_FIELDS, } from "../schemas/firestore.js";
+/**
+ * `conversations/{id}/messages/{msgId}` — a SUBCOLLECTION, not an embedded
+ * array. `supportTickets` embeds `messages[]` and appends with
+ * `arrayUnion(prepareForFirestore(msg))`, which is correct for a ticket (a
+ * bounded, closable record) and wrong here: a thread has no natural ceiling,
+ * and a subcollection is concurrency-safe without `arrayUnion` — two replies
+ * at once are two documents, never a lost write (the `item-requests/[id]/
+ * replies` read-modify-write bug this avoids by construction).
+ *
+ * Plain functional module over `getAdminDb()`, matching the digital-code pool
+ * precedent (`_internal/server/features/digital-code/pool.ts`) — BaseRepository
+ * assumes a top-level collection and has no subcollection form.
+ */
+function messagesRef(conversationId) {
+    return getAdminDb()
+        .collection(CONVERSATIONS_COLLECTION)
+        .doc(conversationId)
+        .collection(MESSAGES_SUBCOLLECTION);
+}
+function encryptMessage(data) {
+    return encryptPiiFields(data, [...MESSAGE_PII_FIELDS]);
+}
+function decryptMessage(doc) {
+    return decryptPiiFields(doc, [...MESSAGE_PII_FIELDS]);
+}
+/**
+ * Idempotent on `(conversationId, clientMessageId)` — a retry on a flaky
+ * connection must not double-post. The doc id IS the client message id, so a
+ * duplicate `set()` (non-merge) on an existing id throws `ALREADY_EXISTS`
+ * rather than silently overwriting a different author's message that happened
+ * to reuse an id (which cannot happen across conversations since this is
+ * scoped under one, but a malicious resend of someone else's id must not
+ * silently replace it either).
+ */
+export async function createMessage(input) {
+    const ref = messagesRef(input.conversationId).doc(input.clientMessageId);
+    try {
+        const existing = await ref.get();
+        if (existing.exists) {
+            // Idempotent replay: the client retried, the server already has it.
+            return decryptMessage({ id: existing.id, ...existing.data() });
+        }
+        const now = new Date();
+        const data = {
+            conversationId: input.conversationId,
+            authorId: input.authorId,
+            body: input.body,
+            clientMessageId: input.clientMessageId,
+            createdAt: now,
+            updatedAt: now,
+            ...(input.attachments && input.attachments.length > 0 ? { attachments: input.attachments } : {}),
+            ...(input.productRef ? { productRef: input.productRef } : {}),
+        };
+        await ref.create(encryptMessage(data));
+        return { id: ref.id, ...data };
+    }
+    catch (error) {
+        void normalizeError(error);
+        throw new DatabaseError(`Failed to create message in conversation ${input.conversationId}`, error);
+    }
+}
+/**
+ * Cursor-paginated, newest-first, `limit(30)` — the absence of a limit is
+ * literally what made the old feature expensive (20 messages -> ~1,600 reads
+ * across both participants' list refetches).
+ */
+export async function listMessages(conversationId, opts = {}) {
+    const limit = Math.min(opts.limit ?? 30, 50);
+    try {
+        let query = messagesRef(conversationId)
+            .orderBy(MESSAGE_FIELDS.CREATED_AT, "desc")
+            .limit(limit + 1);
+        if (opts.cursor) {
+            const cursorDoc = await messagesRef(conversationId).doc(opts.cursor).get();
+            if (cursorDoc.exists)
+                query = query.startAfter(cursorDoc);
+        }
+        const snap = await query.get();
+        const docs = snap.docs.slice(0, limit);
+        const items = docs.map((d) => decryptMessage({ id: d.id, ...d.data() }));
+        const nextCursor = snap.docs.length > limit ? docs[docs.length - 1].id : null;
+        return { items, nextCursor };
+    }
+    catch (error) {
+        void normalizeError(error);
+        throw new DatabaseError(`Failed to list messages for conversation ${conversationId}`, error);
+    }
+}
+/** Tombstone, never a hard delete of a single message — see schema comment. */
+export async function softDeleteMessage(conversationId, messageId, deletedBy) {
+    try {
+        await messagesRef(conversationId).doc(messageId).update({
+            deletedAt: new Date(),
+            deletedBy,
+            body: "",
+            updatedAt: new Date(),
+        });
+    }
+    catch (error) {
+        void normalizeError(error);
+        throw new DatabaseError(`Failed to delete message ${messageId}`, error);
+    }
+}
+/**
+ * Retention — delete every message in a conversation being pruned. Bounded
+ * batches, never a whole-subcollection snapshot in one go for a thread that
+ * somehow grew very large.
+ */
+export async function deleteAllMessages(conversationId) {
+    const BATCH_SIZE = 400;
+    const db = getAdminDb();
+    let deleted = 0;
+    for (;;) {
+        const snap = await messagesRef(conversationId).limit(BATCH_SIZE).get();
+        if (snap.empty)
+            break;
+        const batch = db.batch();
+        snap.docs.forEach((d) => batch.delete(d.ref));
+        await batch.commit();
+        deleted += snap.size;
+        if (snap.size < BATCH_SIZE)
+            break;
+    }
+    return deleted;
+}
+/** All attachment URLs across a conversation's messages — for retention's
+ * "attachments die before the document" step. */
+export async function listAllAttachmentUrls(conversationId) {
+    const snap = await messagesRef(conversationId).get();
+    const urls = [];
+    for (const d of snap.docs) {
+        const data = d.data();
+        if (data.attachments)
+            urls.push(...data.attachments);
+    }
+    return urls;
+}

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

@@ -0,0 +1,99 @@
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+/**
+ * D9 — chat, rebuilt properly.
+ *
+ * One inbox. A conversation is between exactly TWO users; a product is
+ * attached to a MESSAGE as a card (the WhatsApp-reply-quoting shape), never
+ * to the thread — a buyer with three questions about three items wants one
+ * thread, not three. Not listing-scoped.
+ *
+ * 🛑 `firestore.rules` is `allow read, write: if false` on every document —
+ * there is deliberately no client-side Firestore access anywhere in this
+ * codebase. Every mutation here goes through a server route using the Admin
+ * SDK; the client never reads Firestore directly for chat, only the RTDB
+ * ping channel (see `chat_events` in `database.rules.json`) plus the REST
+ * routes it triggers a refetch against.
+ */
+export declare const CONVERSATIONS_COLLECTION: "conversations";
+export declare const MESSAGES_SUBCOLLECTION: "messages";
+export type ConversationStatus = "active" | "archived";
+export type ParticipantRole = "buyer" | "seller";
+export interface ConversationLastMessage {
+    /** Truncated preview — the full body lives only on the message document. */
+    body: string;
+    authorId: string;
+    at: Date;
+    hasAttachments: boolean;
+    productId?: string;
+}
+export interface ConversationDocument extends BaseDocument {
+    /** Exactly two. `array-contains` query, bounded by construction. */
+    participantIds: string[];
+    participantRoles: Record<string, ParticipantRole>;
+    lastMessage?: ConversationLastMessage;
+    lastMessageAt?: Date;
+    /** Read receipts, NOT per-message flags — one timestamp per participant. */
+    lastReadAt: Record<string, string>;
+    unread: Record<string, number>;
+    status: ConversationStatus;
+    /** Uids who have blocked the OTHER participant in this thread. */
+    blockedBy?: string[];
+    messageCount: number;
+}
+export interface MessageProductRef {
+    productId: string;
+    title: string;
+    image?: 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. */
+    price?: number;
+}
+export interface MessageDocument extends BaseDocument {
+    conversationId: string;
+    authorId: string;
+    /** <=2000 chars, PII-stripped and encrypted at rest. */
+    body: string;
+    /**
+     * Client-generated idempotency key. A retry on a flaky connection must not
+     * double-post — every chat system has this. Unique per (conversationId,
+     * clientMessageId); a duplicate send resolves to the existing message.
+     */
+    clientMessageId: string;
+    /** `/media/` proxy URLs, finalized before the write (never tmp/). */
+    attachments?: string[];
+    productRef?: MessageProductRef;
+    /** Tombstone — removing a message must not renumber the thread under the
+     * other participant's read cursor. */
+    deletedAt?: Date;
+    deletedBy?: string;
+}
+export declare const CONVERSATION_FIELDS: {
+    readonly ID: "id";
+    readonly PARTICIPANT_IDS: "participantIds";
+    readonly PARTICIPANT_ROLES: "participantRoles";
+    readonly LAST_MESSAGE: "lastMessage";
+    readonly LAST_MESSAGE_AT: "lastMessageAt";
+    readonly LAST_READ_AT: "lastReadAt";
+    readonly UNREAD: "unread";
+    readonly STATUS: "status";
+    readonly BLOCKED_BY: "blockedBy";
+    readonly MESSAGE_COUNT: "messageCount";
+    readonly CREATED_AT: "createdAt";
+    readonly UPDATED_AT: "updatedAt";
+};
+export declare const MESSAGE_FIELDS: {
+    readonly ID: "id";
+    readonly CONVERSATION_ID: "conversationId";
+    readonly AUTHOR_ID: "authorId";
+    readonly BODY: "body";
+    readonly CLIENT_MESSAGE_ID: "clientMessageId";
+    readonly ATTACHMENTS: "attachments";
+    readonly PRODUCT_REF: "productRef";
+    readonly DELETED_AT: "deletedAt";
+    readonly DELETED_BY: "deletedBy";
+    readonly CREATED_AT: "createdAt";
+};
+/** Retention stages, measured from `lastMessageAt`. Folded into `notificationPrune`. */
+export declare const CONVERSATION_ACTIVE_DAYS = 30;
+export declare const CONVERSATION_ARCHIVE_DAYS: number;

package/dist/features/messages/schemas/firestore.js

@@ -0,0 +1,46 @@
+/**
+ * D9 — chat, rebuilt properly.
+ *
+ * One inbox. A conversation is between exactly TWO users; a product is
+ * attached to a MESSAGE as a card (the WhatsApp-reply-quoting shape), never
+ * to the thread — a buyer with three questions about three items wants one
+ * thread, not three. Not listing-scoped.
+ *
+ * 🛑 `firestore.rules` is `allow read, write: if false` on every document —
+ * there is deliberately no client-side Firestore access anywhere in this
+ * codebase. Every mutation here goes through a server route using the Admin
+ * SDK; the client never reads Firestore directly for chat, only the RTDB
+ * ping channel (see `chat_events` in `database.rules.json`) plus the REST
+ * routes it triggers a refetch against.
+ */
+export const CONVERSATIONS_COLLECTION = "conversations";
+export const MESSAGES_SUBCOLLECTION = "messages";
+export const CONVERSATION_FIELDS = {
+    ID: "id",
+    PARTICIPANT_IDS: "participantIds",
+    PARTICIPANT_ROLES: "participantRoles",
+    LAST_MESSAGE: "lastMessage",
+    LAST_MESSAGE_AT: "lastMessageAt",
+    LAST_READ_AT: "lastReadAt",
+    UNREAD: "unread",
+    STATUS: "status",
+    BLOCKED_BY: "blockedBy",
+    MESSAGE_COUNT: "messageCount",
+    CREATED_AT: "createdAt",
+    UPDATED_AT: "updatedAt",
+};
+export const MESSAGE_FIELDS = {
+    ID: "id",
+    CONVERSATION_ID: "conversationId",
+    AUTHOR_ID: "authorId",
+    BODY: "body",
+    CLIENT_MESSAGE_ID: "clientMessageId",
+    ATTACHMENTS: "attachments",
+    PRODUCT_REF: "productRef",
+    DELETED_AT: "deletedAt",
+    DELETED_BY: "deletedBy",
+    CREATED_AT: "createdAt",
+};
+/** Retention stages, measured from `lastMessageAt`. Folded into `notificationPrune`. */
+export const CONVERSATION_ACTIVE_DAYS = 30;
+export const CONVERSATION_ARCHIVE_DAYS = 7 * 30; // ~7 months