@mohasinac/appkit 4.47.0 → 4.48.1

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

@@ -0,0 +1,75 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { useAuth } from "../../../react/contexts/SessionContext.js";
+import { useConversationThread, useSendMessage, useMarkConversationRead, useBlockConversation, } from "../hooks/useMessages.js";
+import { Div } from "../../../ui/components/Div.js";
+import { Row, Stack } from "../../../ui/components/Layout.js";
+import { Heading, Span, Text } from "../../../ui/components/Typography.js";
+import { Button } from "../../../ui/components/Button.js";
+import { FieldTextarea } from "../../../ui/forms/FieldTextarea.js";
+import { EmptyState } from "../../../ui/components/EmptyState.js";
+import { MediaImage } from "../../media/MediaImage.js";
+function newClientMessageId() {
+    // crypto.randomUUID is available in every browser this app targets; a
+    // retry reuses the SAME id generated at compose time, not a fresh one per
+    // attempt, so the server resolves a retry as the same message.
+    return typeof crypto !== "undefined" && "randomUUID" in crypto
+        ? crypto.randomUUID()
+        : `cm-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function MessageBubble({ message, isSelf }) {
+    if (message.deletedAt) {
+        return (_jsx(Row, { justify: isSelf ? "end" : "start", children: _jsx(Text, { size: "sm", color: "muted", className: "italic", children: "Message deleted" }) }));
+    }
+    return (_jsx(Row, { justify: isSelf ? "end" : "start", children: _jsxs(Stack, { gap: "xs", surface: isSelf ? "interactive" : "muted", padding: "sm", rounded: "lg", className: "max-w-[75%]", children: [message.productRef && (_jsxs(Row, { gap: "sm", surface: "card", padding: "xs", rounded: "md", children: [message.productRef.image && (_jsx(Div, { className: "relative h-10 w-10 flex-shrink-0", rounded: "default", overflow: "hidden", children: _jsx(MediaImage, { src: message.productRef.image, alt: message.productRef.title, size: "thumbnail" }) })), _jsx(Text, { size: "xs", weight: "semibold", className: "truncate", children: message.productRef.title })] })), _jsx(Text, { size: "sm", className: "whitespace-pre-wrap break-words", children: message.body })] }) }));
+}
+export function ConversationThreadView({ conversationId }) {
+    const { user, loading } = useAuth();
+    const { data, isPending, isError, channelError } = useConversationThread(user ? conversationId : null);
+    const { mutate: send, isPending: isSending, pending, retry } = useSendMessage(conversationId);
+    const markRead = useMarkConversationRead();
+    const block = useBlockConversation();
+    const [draft, setDraft] = useState("");
+    const markedRef = useRef(false);
+    const bottomRef = useRef(null);
+    useEffect(() => {
+        if (!markedRef.current && conversationId && user) {
+            markedRef.current = true;
+            markRead.mutate({ conversationId });
+        }
+        // Reset the guard when the thread changes.
+        return () => {
+            markedRef.current = false;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [conversationId, user]);
+    useEffect(() => {
+        bottomRef.current?.scrollIntoView({ behavior: "smooth" });
+    }, [data?.items.length, pending.length]);
+    if (loading)
+        return null;
+    if (!user) {
+        return (_jsx(EmptyState, { title: "Sign in to view this conversation", actionLabel: "Sign in", actionHref: "/auth/login" }));
+    }
+    const handleSend = () => {
+        const trimmed = draft.trim();
+        if (!trimmed)
+            return;
+        const clientMessageId = newClientMessageId();
+        send({ body: trimmed, clientMessageId });
+        setDraft("");
+    };
+    // Newest-first from the API, so reverse for display (oldest at top).
+    const items = data ? [...data.items].reverse() : [];
+    return (_jsxs(Div, { layout: "flex-col", className: "max-w-2xl mx-auto h-full", children: [_jsxs(Row, { padding: "md", justify: "between", className: "border-b border-[var(--appkit-color-border-subtle)]", children: [_jsx(Heading, { level: 1, size: "lg", children: "Conversation" }), _jsx(Button, { variant: "ghost", size: "sm", isLoading: block.isPending, onClick: () => {
+                            if (confirm("Block this person from messaging you in this conversation?")) {
+                                block.mutate({ conversationId });
+                            }
+                        }, children: "Block" })] }), channelError && (_jsx(Div, { padding: "sm", surface: "warning-surface", children: _jsxs(Text, { size: "xs", color: "warning", children: [channelError, " New messages may not appear until you reload."] }) })), _jsxs(Div, { className: "flex-1", overflow: "y-auto", padding: "md", children: [isPending && _jsx(Text, { color: "muted", children: "Loading messages\u2026" }), isError && _jsx(Text, { color: "danger", children: "Could not load this conversation." }), _jsxs(Stack, { gap: "sm", children: [items.map((m) => (_jsx(MessageBubble, { message: m, isSelf: m.authorId === user.uid }, m.id))), pending.map((p) => (_jsx(Row, { justify: "end", children: _jsxs(Stack, { gap: "xs", surface: "interactive", padding: "sm", rounded: "lg", className: "max-w-[75%] opacity-70", children: [_jsx(Text, { size: "sm", className: "whitespace-pre-wrap break-words", children: p.body }), p.status === "failed" && (_jsx(Button, { variant: "ghost", size: "sm", onClick: () => retry(p), children: "Failed \u2014 tap to retry" })), p.status === "pending" && (_jsx(Span, { size: "xs", color: "muted", children: "Sending\u2026" }))] }) }, p.clientMessageId)))] }), _jsx(Div, { ref: bottomRef })] }), _jsxs(Row, { padding: "md", gap: "sm", className: "border-t border-[var(--appkit-color-border-subtle)]", children: [_jsx(Div, { className: "flex-1", children: _jsx(FieldTextarea, { name: "message-composer", "aria-label": "Message", value: draft, onChange: setDraft, onKeyDown: (e) => {
+                                if (e.key === "Enter" && !e.shiftKey) {
+                                    e.preventDefault();
+                                    handleSend();
+                                }
+                            }, maxLength: 2000, rows: 2, placeholder: "Write a message\u2026" }) }), _jsx(Button, { isLoading: isSending, disabled: !draft.trim(), onClick: handleSend, children: "Send" })] })] }));
+}

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

@@ -0,0 +1 @@
+export declare function ConversationsInboxView(): import("react").JSX.Element | null;

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

@@ -0,0 +1,39 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useAuth } from "../../../react/contexts/SessionContext.js";
+import { useConversations } from "../hooks/useMessages.js";
+import { Anchor } from "../../../ui/components/Anchor.js";
+import { Div } from "../../../ui/components/Div.js";
+import { Row, Stack } from "../../../ui/components/Layout.js";
+import { Heading, Span, Text } from "../../../ui/components/Typography.js";
+import { EmptyState } from "../../../ui/components/EmptyState.js";
+function formatRelative(at) {
+    const d = typeof at === "string" ? new Date(at) : at;
+    const diffMs = Date.now() - d.getTime();
+    const mins = Math.floor(diffMs / 60000);
+    if (mins < 1)
+        return "just now";
+    if (mins < 60)
+        return `${mins}m ago`;
+    const hours = Math.floor(mins / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ago`;
+}
+function ConversationRow({ conversation, selfId }) {
+    const unread = conversation.unread[selfId] ?? 0;
+    return (_jsx(Anchor, { href: `/messages/${conversation.id}`, underline: "none", className: "block", children: _jsxs(Row, { surface: unread > 0 ? "muted" : "default", padding: "md", gap: "md", className: "border-b border-[var(--appkit-color-border-subtle)]", children: [_jsxs(Stack, { gap: "xs", className: "flex-1 min-w-0", children: [_jsxs(Row, { gap: "sm", justify: "between", children: [_jsx(Text, { weight: unread > 0 ? "semibold" : "normal", className: "truncate", children: conversation.participantRoles[selfId] === "seller" ? "Buyer" : "Seller" }), conversation.lastMessageAt && (_jsx(Span, { size: "xs", color: "muted", children: formatRelative(conversation.lastMessageAt) }))] }), conversation.lastMessage && (_jsx(Text, { size: "sm", color: "muted", className: "truncate", children: conversation.lastMessage.hasAttachments && !conversation.lastMessage.body
+                                ? "Sent an attachment"
+                                : conversation.lastMessage.body }))] }), unread > 0 && (_jsx(Span, { size: "xs", weight: "semibold", color: "inverse", rounded: "full", className: "flex-shrink-0 bg-primary", padding: "x-sm", children: unread }))] }) }));
+}
+export function ConversationsInboxView() {
+    const { user, loading } = useAuth();
+    const { data, isPending, isError } = useConversations(20, Boolean(user));
+    if (loading)
+        return null;
+    if (!user) {
+        return (_jsx(EmptyState, { title: "Sign in to view your messages", description: "Conversations with buyers and sellers are only visible once you're signed in.", actionLabel: "Sign in", actionHref: "/auth/login" }));
+    }
+    return (_jsxs(Div, { className: "max-w-2xl mx-auto", children: [_jsx(Div, { padding: "md", className: "border-b border-[var(--appkit-color-border-subtle)]", children: _jsx(Heading, { level: 1, size: "lg", children: "Messages" }) }), isPending && (_jsx(Div, { padding: "lg", children: _jsx(Text, { color: "muted", children: "Loading conversations\u2026" }) })), isError && (_jsx(Div, { padding: "lg", children: _jsx(Text, { color: "danger", children: "Could not load your messages. Try reloading the page." }) })), data && data.items.length === 0 && (_jsx(EmptyState, { title: "No conversations yet", description: "Messages with buyers and sellers show up here." })), data && data.items.length > 0 && (_jsx(Stack, { gap: "none", children: data.items.map((c) => (_jsx(ConversationRow, { conversation: c, selfId: user.uid }, c.id))) }))] }));
+}

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

@@ -0,0 +1,17 @@
+export interface MessageSellerButtonProps {
+    storeId: string;
+    /** Render nothing when the viewer owns this store — comparing storeId
+     * client-side is an optional convenience; the server refuses it either way. */
+    isOwnStore?: boolean;
+    className?: string;
+}
+/**
+ * D11 — the gap tester-case authoring surfaced: the full create/open-
+ * conversation backend had no UI entry point anywhere. One real button, put
+ * wherever a page already knows a `storeId` — the product detail page's
+ * store card is the first and highest-value placement.
+ *
+ * Absent entirely when chat is off or the viewer is the store's own owner —
+ * never rendered-but-disabled, same discipline as the nav icon.
+ */
+export declare function MessageSellerButton({ storeId, isOwnStore, className }: MessageSellerButtonProps): import("react").JSX.Element | null;

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

@@ -0,0 +1,33 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRouter } from "next/navigation.js";
+import { useAuth } from "../../../react/contexts/SessionContext.js";
+import { useSiteSettings } from "../../../core/hooks/useSiteSettings.js";
+import { useOpenConversationWithSeller } from "../hooks/useMessages.js";
+import { Button } from "../../../ui/components/Button.js";
+import { ROUTES } from "../../../next/routing/route-map.js";
+import { ACTIONS } from "../../../_internal/shared/actions/action-registry.js";
+/**
+ * D11 — the gap tester-case authoring surfaced: the full create/open-
+ * conversation backend had no UI entry point anywhere. One real button, put
+ * wherever a page already knows a `storeId` — the product detail page's
+ * store card is the first and highest-value placement.
+ *
+ * Absent entirely when chat is off or the viewer is the store's own owner —
+ * never rendered-but-disabled, same discipline as the nav icon.
+ */
+export function MessageSellerButton({ storeId, isOwnStore, className }) {
+    const router = useRouter();
+    const { user } = useAuth();
+    const { data: settings } = useSiteSettings();
+    const { mutate, isPending } = useOpenConversationWithSeller();
+    if (!user || isOwnStore || settings?.chat?.enabled !== true)
+        return null;
+    return (_jsx(Button, { action: ACTIONS.PRODUCT["message-seller"], size: "sm", isLoading: isPending, className: className, onClick: () => {
+            mutate({ storeId }, {
+                onSuccess: (conversation) => {
+                    router.push(String(ROUTES.USER.MESSAGE_THREAD(conversation.id)));
+                },
+            });
+        } }));
+}

package/dist/features/messages/hooks/useConversationChannel.d.ts

@@ -0,0 +1,24 @@
+/**
+ * D9 — subscribe to `chat_events/{conversationId}` and fire `onPing` on every
+ * change. NOT `useRealtimeEvent`: that hook is shaped around a single
+ * terminal status (success/failed/timeout) for a one-shot job, while a chat
+ * channel is a CONTINUOUS ping — every new message writes to the same node,
+ * and there is no "done" state for an open thread.
+ *
+ * RTDB-ping-plus-REST: this channel carries no message content, only "a
+ * message arrived, refetch" — `firestore.rules` forbids a client Firestore
+ * listener entirely (`allow read, write: if false` on every document), so
+ * this plus the bounded cursor-paginated REST route is the only option.
+ *
+ * 🛑 Subscribes through the LEASED provider (`acquireRealtimeSession`), never
+ * the global one. The old feature's two bugs were both here: it never signed
+ * in at all (so every rule evaluated false and the channel was silently
+ * inert), and a shared sign-out tore one consumer's session out from under
+ * another's. Both are structurally impossible via the lease.
+ */
+export declare function useConversationChannel(conversationId: string | null, getToken: (conversationId: string) => Promise<{
+    customToken: string;
+    expiresAt: number;
+}>, onPing: () => void): {
+    error: string | null;
+};

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

@@ -0,0 +1,89 @@
+"use client";
+import { normalizeError } from "../../../errors/normalize.js";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { getClientRealtimeProvider } from "../../../contracts/client-realtime.js";
+import { acquireRealtimeSession } from "../../../contracts/realtime-session.js";
+import { RTDB_PATHS } from "../../../providers/db-firebase/rtdb-paths.js";
+/**
+ * D9 — subscribe to `chat_events/{conversationId}` and fire `onPing` on every
+ * change. NOT `useRealtimeEvent`: that hook is shaped around a single
+ * terminal status (success/failed/timeout) for a one-shot job, while a chat
+ * channel is a CONTINUOUS ping — every new message writes to the same node,
+ * and there is no "done" state for an open thread.
+ *
+ * RTDB-ping-plus-REST: this channel carries no message content, only "a
+ * message arrived, refetch" — `firestore.rules` forbids a client Firestore
+ * listener entirely (`allow read, write: if false` on every document), so
+ * this plus the bounded cursor-paginated REST route is the only option.
+ *
+ * 🛑 Subscribes through the LEASED provider (`acquireRealtimeSession`), never
+ * the global one. The old feature's two bugs were both here: it never signed
+ * in at all (so every rule evaluated false and the channel was silently
+ * inert), and a shared sign-out tore one consumer's session out from under
+ * another's. Both are structurally impossible via the lease.
+ */
+export function useConversationChannel(conversationId, getToken, onPing) {
+    const onPingRef = useRef(onPing);
+    useEffect(() => {
+        onPingRef.current = onPing;
+    });
+    const [error, setError] = useState(null);
+    const unsubscribeRef = useRef(null);
+    const releaseRef = useRef(null);
+    const cleanup = useCallback(() => {
+        unsubscribeRef.current?.();
+        unsubscribeRef.current = null;
+        releaseRef.current?.();
+        releaseRef.current = null;
+    }, []);
+    useEffect(() => {
+        if (!conversationId) {
+            cleanup();
+            return;
+        }
+        let cancelled = false;
+        setError(null);
+        (async () => {
+            try {
+                const token = await getToken(conversationId);
+                const lease = await acquireRealtimeSession(`chat:${conversationId}`, () => Promise.resolve(token));
+                if (cancelled) {
+                    lease.release();
+                    return;
+                }
+                releaseRef.current = lease.release;
+                const provider = lease.provider ?? getClientRealtimeProvider();
+                unsubscribeRef.current = provider.subscribe(
+                /*
+                 * 🛑 From RTDB_PATHS, not a literal — found by the G2 sweep. The
+                 * SERVER writes this ping via `RTDB_PATHS.CHAT_EVENTS` and the
+                 * client was subscribing to a hardcoded copy of the same string:
+                 * two owners of one path, where a rename on either side produces a
+                 * channel that connects, authenticates, and never fires. Exactly
+                 * Root Cause #42's shape on the realtime-path axis.
+                 */
+                `${RTDB_PATHS.CHAT_EVENTS}/${conversationId}`, (snapshot) => {
+                    if (!snapshot.exists())
+                        return;
+                    onPingRef.current();
+                }, (err) => {
+                    // 🛑 Surfaced, never swallowed — the old feature's `// ignore` on
+                    // this exact error is why it looked implemented and was inert.
+                    setError("Live updates are unavailable for this conversation.");
+                    void normalizeError(err);
+                });
+            }
+            catch (err) {
+                if (!cancelled) {
+                    setError("Could not connect to live updates.");
+                    void normalizeError(err);
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            cleanup();
+        };
+    }, [conversationId, getToken, cleanup]);
+    return { error };
+}

package/dist/features/messages/hooks/useMessages.d.ts

@@ -0,0 +1,347 @@
+import type { ConversationDocument, MessageDocument } from "../schemas/firestore";
+interface PagedResult<T> {
+    items: T[];
+    nextCursor: string | null;
+}
+/**
+ * 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 declare function useConversations(limit?: number, enabled?: boolean): import("@tanstack/react-query").UseQueryResult<PagedResult<ConversationDocument>, Error>;
+export declare function useOpenConversation(): import("@tanstack/react-query").UseMutationResult<ConversationDocument, unknown, {
+    otherUserId: string;
+}, unknown>;
+/** D11 — the entry point a product/store page actually has: a storeId, not
+ * the owner's uid. Resolution happens server-side. */
+export declare function useOpenConversationWithSeller(): import("@tanstack/react-query").UseMutationResult<ConversationDocument, unknown, {
+    storeId: string;
+}, unknown>;
+/**
+ * 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 declare function useConversationThread(conversationId: string | null): {
+    channelError: string | null;
+    data: PagedResult<MessageDocument>;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: true;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<PagedResult<MessageDocument>, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+} | {
+    channelError: string | null;
+    data: PagedResult<MessageDocument>;
+    error: null;
+    isError: false;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: false;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<PagedResult<MessageDocument>, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+} | {
+    channelError: string | null;
+    data: undefined;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: true;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<PagedResult<MessageDocument>, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+} | {
+    channelError: string | null;
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoading: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "pending";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<PagedResult<MessageDocument>, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+} | {
+    channelError: string | null;
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "pending";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isLoading: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<PagedResult<MessageDocument>, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+} | {
+    channelError: string | null;
+    data: PagedResult<MessageDocument>;
+    isError: false;
+    error: null;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: true;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<PagedResult<MessageDocument>, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+};
+export interface PendingMessage {
+    clientMessageId: string;
+    body: string;
+    status: "pending" | "failed";
+}
+/**
+ * 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 declare function useSendMessage(conversationId: string): {
+    pending: PendingMessage[];
+    retry: (p: PendingMessage) => void;
+    data: undefined;
+    variables: undefined;
+    error: null;
+    isError: false;
+    isIdle: true;
+    isPending: false;
+    isSuccess: false;
+    status: "idle";
+    mutate: import("@tanstack/react-query").UseMutateFunction<MessageDocument, unknown, {
+        body: string;
+        clientMessageId: string;
+        attachments?: string[];
+        productId?: string;
+    }, unknown>;
+    reset: () => void;
+    context: unknown;
+    failureCount: number;
+    failureReason: unknown;
+    isPaused: boolean;
+    submittedAt: number;
+    mutateAsync: import("@tanstack/react-query").UseMutateAsyncFunction<MessageDocument, unknown, {
+        body: string;
+        clientMessageId: string;
+        attachments?: string[];
+        productId?: string;
+    }, unknown>;
+} | {
+    pending: PendingMessage[];
+    retry: (p: PendingMessage) => void;
+    data: undefined;
+    variables: {
+        body: string;
+        clientMessageId: string;
+        attachments?: string[];
+        productId?: string;
+    };
+    error: null;
+    isError: false;
+    isIdle: false;
+    isPending: true;
+    isSuccess: false;
+    status: "pending";
+    mutate: import("@tanstack/react-query").UseMutateFunction<MessageDocument, unknown, {
+        body: string;
+        clientMessageId: string;
+        attachments?: string[];
+        productId?: string;
+    }, unknown>;
+    reset: () => void;
+    context: unknown;
+    failureCount: number;
+    failureReason: unknown;
+    isPaused: boolean;
+    submittedAt: number;
+    mutateAsync: import("@tanstack/react-query").UseMutateAsyncFunction<MessageDocument, unknown, {
+        body: string;
+        clientMessageId: string;
+        attachments?: string[];
+        productId?: string;
+    }, unknown>;
+} | {
+    pending: PendingMessage[];
+    retry: (p: PendingMessage) => void;
+    data: undefined;
+    error: unknown;
+    variables: {
+        body: string;
+        clientMessageId: string;
+        attachments?: string[];
+        productId?: string;
+    };
+    isError: true;
+    isIdle: false;
+    isPending: false;
+    isSuccess: false;
+    status: "error";
+    mutate: import("@tanstack/react-query").UseMutateFunction<MessageDocument, unknown, {
+        body: string;
+        clientMessageId: string;
+        attachments?: string[];
+        productId?: string;
+    }, unknown>;
+    reset: () => void;
+    context: unknown;
+    failureCount: number;
+    failureReason: unknown;
+    isPaused: boolean;
+    submittedAt: number;
+    mutateAsync: import("@tanstack/react-query").UseMutateAsyncFunction<MessageDocument, unknown, {
+        body: string;
+        clientMessageId: string;
+        attachments?: string[];
+        productId?: string;
+    }, unknown>;
+} | {
+    pending: PendingMessage[];
+    retry: (p: PendingMessage) => void;
+    data: MessageDocument;
+    error: null;
+    variables: {
+        body: string;
+        clientMessageId: string;
+        attachments?: string[];
+        productId?: string;
+    };
+    isError: false;
+    isIdle: false;
+    isPending: false;
+    isSuccess: true;
+    status: "success";
+    mutate: import("@tanstack/react-query").UseMutateFunction<MessageDocument, unknown, {
+        body: string;
+        clientMessageId: string;
+        attachments?: string[];
+        productId?: string;
+    }, unknown>;
+    reset: () => void;
+    context: unknown;
+    failureCount: number;
+    failureReason: unknown;
+    isPaused: boolean;
+    submittedAt: number;
+    mutateAsync: import("@tanstack/react-query").UseMutateAsyncFunction<MessageDocument, unknown, {
+        body: string;
+        clientMessageId: string;
+        attachments?: string[];
+        productId?: string;
+    }, unknown>;
+};
+export declare function useMarkConversationRead(): import("@tanstack/react-query").UseMutationResult<{
+    ok: boolean;
+}, unknown, {
+    conversationId: string;
+}, unknown>;
+export declare function useBlockConversation(): import("@tanstack/react-query").UseMutationResult<{
+    ok: boolean;
+}, unknown, {
+    conversationId: string;
+}, unknown>;
+/** The nav badge's source when the inbox itself is not mounted — never a
+ * second list query of its own. */
+export declare function useUnreadMessageCount(enabled: boolean): import("@tanstack/react-query").UseQueryResult<{
+    unread: number;
+}, Error>;
+export {};