@mohasinac/appkit 4.41.0 → 4.41.1

package/dist/features/messages/actions/ping-rtdb.js

@@ -1,26 +0,0 @@
-/**
- * pingConversationRtdb — server-side fan-out for conversation updates.
- *
- * Writes `Date.now()` to each ping path so RTDB-subscribed clients refetch.
- * Best-effort: failures are logged and swallowed (clients fall back to focus /
- * explicit refetch).
- */
-import { getAdminRealtimeDb } from "../../../providers/db-firebase";
-import { serverLogger } from "../../../monitoring";
-import { buildConversationPingPaths, } from "../realtime";
-import { normalizeError } from "../../../errors/normalize";
-export async function pingConversationRtdb(targets) {
-    const paths = buildConversationPingPaths(targets);
-    try {
-        const db = getAdminRealtimeDb();
-        const now = Date.now();
-        await Promise.all(paths.filter(Boolean).map((p) => db.ref(p).set(now)));
-    }
-    catch (err) {
-        void normalizeError(err);
-        serverLogger.warn("conversations: RTDB ping failed", {
-            paths,
-            error: err instanceof Error ? err.message : String(err),
-        });
-    }
-}

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

@@ -1,22 +0,0 @@
-import { conversationPingPath, userConversationsPingPath } from "../realtime";
-import type { ConversationDocument } from "../schemas/firestore";
-/**
- * @deprecated Re-exported for backwards compat — import `conversationPingPath`
- * from `@mohasinac/appkit` instead.
- */
-export declare const CONVERSATIONS_PING_PATH: typeof conversationPingPath;
-/**
- * @deprecated Re-exported for backwards compat — import
- * `userConversationsPingPath` from `@mohasinac/appkit` instead.
- */
-export declare const CONVERSATIONS_PING_USER_PATH: typeof userConversationsPingPath;
-export interface UseConversationReturn {
-    conversation: ConversationDocument | null;
-    isLoading: boolean;
-    error: Error | null;
-    isConnected: boolean;
-    sendMessage: (body: string) => Promise<void>;
-    markRead: () => Promise<void>;
-    refetch: () => Promise<void>;
-}
-export declare function useConversation(conversationId: string | null): UseConversationReturn;

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

@@ -1,155 +0,0 @@
-"use client";
-/**
- * useConversation — load + subscribe to a single conversation.
- *
- * Strategy: Firestore is the canonical store; messages live embedded in the
- * conversation document. The realtime layer is a single RTDB "ping" path
- * (`chats/{conversationId}/lastUpdate`) that the send/mark-read API routes
- * bump on every write. This hook subscribes to that ping and re-fetches the
- * doc through the API on each tick. Zero RTDB schema duplication and the
- * canonical Firestore message ordering wins.
- */
-import { useCallback, useEffect, useState } from "react";
-import { acquireRealtimeSession } from "../../../contracts/realtime-session";
-// One scope for both message hooks, deliberately: /api/realtime/token issues a
-// SINGLE token covering all of this user's conversationIds, so a per-id scope
-// would make the list and the detail hook re-sign against each other on the
-// same page for no gain.
-//
-// 🛑 Known limitation, not fixed here: because the scope is constant, a
-// conversation created AFTER sign-in is not in the cached token's claims and
-// its subscription is denied until the token's expiry skew forces a re-sign.
-// The denial is now surfaced (see the error callback below) rather than
-// swallowed. The durable fix is to re-acquire on a permission denial.
-const MESSAGES_SCOPE = "messages";
-import { conversationPingPath, userConversationsPingPath, } from "../realtime";
-import { normalizeError } from "../../../errors/normalize";
-import { apiClient, ApiClientError } from "../../../http/ApiClient";
-import { CONVERSATION_ENDPOINTS, ADMIN_ENDPOINTS, } from "../../../constants/api-endpoints";
-/**
- * @deprecated Re-exported for backwards compat — import `conversationPingPath`
- * from `@mohasinac/appkit` instead.
- */
-export const CONVERSATIONS_PING_PATH = conversationPingPath;
-/**
- * @deprecated Re-exported for backwards compat — import
- * `userConversationsPingPath` from `@mohasinac/appkit` instead.
- */
-export const CONVERSATIONS_PING_USER_PATH = userConversationsPingPath;
-const DETAIL_ENDPOINT = CONVERSATION_ENDPOINTS.BY_ID;
-const SEND_ENDPOINT = CONVERSATION_ENDPOINTS.MESSAGES;
-const READ_ENDPOINT = CONVERSATION_ENDPOINTS.READ;
-async function fetchDetail(id) {
-    try {
-        return await apiClient.get(DETAIL_ENDPOINT(id));
-    }
-    catch (err) {
-        if (err instanceof ApiClientError && err.status === 404)
-            return null;
-        throw err;
-    }
-}
-export function useConversation(conversationId) {
-    const [conversation, setConversation] = useState(null);
-    const [isLoading, setIsLoading] = useState(false);
-    const [error, setError] = useState(null);
-    const [isConnected, setIsConnected] = useState(false);
-    const refetch = useCallback(async () => {
-        if (!conversationId) {
-            setConversation(null);
-            return;
-        }
-        setIsLoading(true);
-        setError(null);
-        try {
-            setConversation(await fetchDetail(conversationId));
-        }
-        catch (e) {
-            void normalizeError(e);
-            setError(e instanceof Error ? e : new Error(String(e)));
-        }
-        finally {
-            setIsLoading(false);
-        }
-    }, [conversationId]);
-    useEffect(() => {
-        void refetch();
-    }, [refetch]);
-    useEffect(() => {
-        if (!conversationId) {
-            setIsConnected(false);
-            return;
-        }
-        let unsubscribe;
-        let release;
-        let cancelled = false;
-        // 🛑 Sign in BEFORE subscribing. Without a session `auth == null`, and the
-        // `chats/$conversationId` rule requires
-        // `auth.token.conversationIds[$conversationId]` — a claim that, until this
-        // change, NOTHING issued (the token route only ever sent `chatIds`, from
-        // the unrelated `chatRooms` collection). Two stacked faults on one channel:
-        // no sign-in, and a claim with no issuer. The recipient of a message never
-        // saw it until they manually refreshed; the sender only saw their own
-        // because `send()` calls `refetch()` directly.
-        void (async () => {
-            try {
-                const lease = await acquireRealtimeSession(MESSAGES_SCOPE, () => apiClient.post(ADMIN_ENDPOINTS.REALTIME_TOKEN, {}));
-                release = lease.release;
-                if (cancelled) {
-                    release();
-                    return;
-                }
-                // Subscribe through the LEASE's provider — it is bound to the app this
-                // scope authenticated on. The global provider may be on a different app
-                // carrying another channel's claims.
-                unsubscribe = lease.provider.subscribe(conversationPingPath(conversationId), () => {
-                    setIsConnected(true);
-                    void refetch();
-                }, (err) => {
-                    void normalizeError(err);
-                    setIsConnected(false);
-                });
-            }
-            catch (_err) {
-                void normalizeError(_err);
-                // Provider unregistered or token fetch failed — falls back to the
-                // one-shot fetch above.
-                setIsConnected(false);
-            }
-        })();
-        return () => {
-            cancelled = true;
-            setIsConnected(false);
-            unsubscribe?.();
-            release?.();
-        };
-    }, [conversationId, refetch]);
-    const sendMessage = useCallback(async (body) => {
-        if (!conversationId)
-            return;
-        const trimmed = body.trim();
-        if (!trimmed)
-            return;
-        await apiClient.post(SEND_ENDPOINT(conversationId), { body: trimmed });
-        // RTDB ping will trigger refetch — but kick off one immediately in case
-        // the ping path isn't subscribed (e.g. provider not registered).
-        await refetch();
-    }, [conversationId, refetch]);
-    const markRead = useCallback(() => {
-        if (!conversationId)
-            return Promise.resolve();
-        return apiClient
-            .post(READ_ENDPOINT(conversationId))
-            .then(() => void refetch())
-            .catch((err) => void normalizeError(err));
-    }, [conversationId, refetch]);
-    return {
-        conversation,
-        isLoading,
-        error,
-        isConnected,
-        sendMessage,
-        markRead,
-        refetch,
-    };
-}

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

@@ -1,15 +0,0 @@
-import type { ConversationDocument } from "../schemas/firestore";
-export interface UseConversationsOptions {
-    /** Override the list endpoint — e.g. the seller-scoped /api/store/conversations. Defaults to the buyer endpoint. */
-    endpoint?: string;
-    /** Which per-conversation unread counter to sum into totalUnread. Defaults to "unreadBuyer". */
-    unreadField?: "unreadBuyer" | "unreadSeller";
-}
-export interface UseConversationsReturn {
-    conversations: ConversationDocument[];
-    isLoading: boolean;
-    error: Error | null;
-    totalUnread: number;
-    refetch: () => Promise<void>;
-}
-export declare function useConversations(userId: string | null | undefined, opts?: UseConversationsOptions): UseConversationsReturn;

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

@@ -1,104 +0,0 @@
-"use client";
-/**
- * useConversations — list the current buyer's conversations. Subscribes to a
- * single RTDB ping path so the list refreshes whenever any of the user's
- * conversations gets a new message.
- */
-import { useCallback, useEffect, useState } from "react";
-import { acquireRealtimeSession } from "../../../contracts/realtime-session";
-// One scope for both message hooks, deliberately: /api/realtime/token issues a
-// SINGLE token covering all of this user's conversationIds, so a per-id scope
-// would make the list and the detail hook re-sign against each other on the
-// same page for no gain.
-//
-// 🛑 Known limitation, not fixed here: because the scope is constant, a
-// conversation created AFTER sign-in is not in the cached token's claims and
-// its subscription is denied until the token's expiry skew forces a re-sign.
-// The denial is now surfaced (see the error callback below) rather than
-// swallowed. The durable fix is to re-acquire on a permission denial.
-const MESSAGES_SCOPE = "messages";
-import { userConversationsPingPath } from "../realtime";
-import { normalizeError } from "../../../errors/normalize";
-import { apiClient } from "../../../http/ApiClient";
-import { CONVERSATION_ENDPOINTS, ADMIN_ENDPOINTS } from "../../../constants/api-endpoints";
-const LIST_ENDPOINT = CONVERSATION_ENDPOINTS.LIST;
-async function fetchList(endpoint) {
-    const data = await apiClient.get(endpoint);
-    return data.items ?? [];
-}
-export function useConversations(userId, opts = {}) {
-    const { endpoint = LIST_ENDPOINT, unreadField = "unreadBuyer" } = opts;
-    const [conversations, setConversations] = useState([]);
-    const [isLoading, setIsLoading] = useState(false);
-    const [error, setError] = useState(null);
-    const refetch = useCallback(async () => {
-        if (!userId) {
-            setConversations([]);
-            return;
-        }
-        setIsLoading(true);
-        setError(null);
-        try {
-            setConversations(await fetchList(endpoint));
-        }
-        catch (e) {
-            void normalizeError(e);
-            setError(e instanceof Error ? e : new Error(String(e)));
-        }
-        finally {
-            setIsLoading(false);
-        }
-    }, [userId, endpoint]);
-    useEffect(() => {
-        void refetch();
-    }, [refetch]);
-    // Subscribe to the per-user ping path — any send/mark-read in any of the
-    // user's conversations bumps this and triggers a fresh list fetch.
-    useEffect(() => {
-        if (!userId)
-            return;
-        let unsubscribe;
-        let release;
-        let cancelled = false;
-        // 🛑 Sign in BEFORE subscribing. This hook used to call subscribe() with no
-        // authenticated session at all, so `auth == null` and the
-        // `chats/user/$userId` rule (`auth.uid == $userId`) could never pass. Every
-        // update was permission-denied and the error handler below was a literal
-        // `// ignore`, so the whole live-list channel was inert while looking wired.
-        void (async () => {
-            try {
-                const lease = await acquireRealtimeSession(MESSAGES_SCOPE, () => apiClient.post(ADMIN_ENDPOINTS.REALTIME_TOKEN, {}));
-                release = lease.release;
-                if (cancelled) {
-                    release();
-                    return;
-                }
-                // Subscribe through the LEASE's provider — see useConversation.
-                unsubscribe = lease.provider.subscribe(userConversationsPingPath(userId), () => {
-                    void refetch();
-                }, (err) => {
-                    // A denied subscription is a real defect — silence is what hid this
-                    // channel being dead for months — so it is logged, not swallowed.
-                    // (This comment previously claimed "Surfaced, not ignored" while the
-                    // body only called normalizeError, which classifies without
-                    // reporting. That was the same documentation-that-lies pattern this
-                    // workstream exists to remove, so it now actually logs.)
-                    void normalizeError(err);
-                    console.warn("[messages] conversations live-update subscription denied; list falls back to fetch-on-load");
-                });
-                // Provider unregistered or token fetch failed — non-fatal; the list
-                // still works via the one-shot fetch above, just without live updates.
-            }
-            catch (_err) {
-                void normalizeError(_err);
-            }
-        })();
-        return () => {
-            cancelled = true;
-            unsubscribe?.();
-            release?.();
-        };
-    }, [userId, refetch]);
-    const totalUnread = conversations.reduce((sum, c) => sum + (c[unreadField] ?? 0), 0);
-    return { conversations, isLoading, error, totalUnread, refetch };
-}

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

@@ -1,6 +0,0 @@
-export * from "./hooks/useConversations";
-export * from "./hooks/useConversation";
-export type { ConversationDocument, ConversationMessage, } from "./schemas/firestore";
-export { CONVERSATIONS_COLLECTION, CONVERSATIONS_INDEXED_FIELDS, } from "./schemas/firestore";
-export { conversationPingPath, userConversationsPingPath, buildConversationPingPaths, } from "./realtime";
-export type { ConversationPingTargets } from "./realtime";

package/dist/features/messages/index.js

@@ -1,4 +0,0 @@
-export * from "./hooks/useConversations";
-export * from "./hooks/useConversation";
-export { CONVERSATIONS_COLLECTION, CONVERSATIONS_INDEXED_FIELDS, } from "./schemas/firestore";
-export { conversationPingPath, userConversationsPingPath, buildConversationPingPaths, } from "./realtime";

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

@@ -1,32 +0,0 @@
-/**
- * Conversations realtime channel — shared between client hooks and server
- * routes. Lives in a non-`"use client"` module so server route handlers can
- * import the path builders without dragging the React hooks into a server
- * bundle.
- *
- * Strategy (D5 + VC7):
- *   - Firestore = canonical store; messages embedded in `conversations/{id}`.
- *   - RTDB = "ping" channel only — server writes Date.now() to two paths on
- *     every mutation, clients subscribe and refetch.
- *
- *     chats/{id}/lastUpdate              — single-conversation ping
- *     chats/user/{userId}/lastUpdate     — per-user fan-out ping
- *
- * Both ends import these constants instead of inlining the path strings.
- */
-/** RTDB path bumped on every write to a single conversation. */
-export declare function conversationPingPath(conversationId: string): string;
-/**
- * RTDB path bumped on every write across all of a user's conversations.
- * Subscribing to this is how the chat list / nav bell refresh without
- * subscribing to every individual conversation.
- */
-export declare function userConversationsPingPath(userId: string): string;
-/** All ping paths to bump on a single conversation write. */
-export interface ConversationPingTargets {
-    conversationId: string;
-    buyerId: string;
-    /** Resolved store-owner UID for the seller side; null when not known. */
-    sellerOwnerId: string | null;
-}
-export declare function buildConversationPingPaths(targets: ConversationPingTargets): string[];

package/dist/features/messages/realtime.js

@@ -1,39 +0,0 @@
-/**
- * Conversations realtime channel — shared between client hooks and server
- * routes. Lives in a non-`"use client"` module so server route handlers can
- * import the path builders without dragging the React hooks into a server
- * bundle.
- *
- * Strategy (D5 + VC7):
- *   - Firestore = canonical store; messages embedded in `conversations/{id}`.
- *   - RTDB = "ping" channel only — server writes Date.now() to two paths on
- *     every mutation, clients subscribe and refetch.
- *
- *     chats/{id}/lastUpdate              — single-conversation ping
- *     chats/user/{userId}/lastUpdate     — per-user fan-out ping
- *
- * Both ends import these constants instead of inlining the path strings.
- */
-const PING_KEY = "lastUpdate";
-/** RTDB path bumped on every write to a single conversation. */
-export function conversationPingPath(conversationId) {
-    return `chats/${conversationId}/${PING_KEY}`;
-}
-/**
- * RTDB path bumped on every write across all of a user's conversations.
- * Subscribing to this is how the chat list / nav bell refresh without
- * subscribing to every individual conversation.
- */
-export function userConversationsPingPath(userId) {
-    return `chats/user/${userId}/${PING_KEY}`;
-}
-export function buildConversationPingPaths(targets) {
-    const paths = [
-        conversationPingPath(targets.conversationId),
-        userConversationsPingPath(targets.buyerId),
-    ];
-    if (targets.sellerOwnerId) {
-        paths.push(userConversationsPingPath(targets.sellerOwnerId));
-    }
-    return paths;
-}

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

@@ -1,71 +0,0 @@
-/**
- * ConversationsRepository — buyer↔seller messaging.
- *
- * One document per buyer×storeId×productId tuple. Messages are embedded in
- * the document as an array (good up to ~200 entries; migrate to subcollection
- * later if threads explode).
- *
- * All mutations are transactional so concurrent writes don't drop messages
- * or unread counters.
- */
-import { type ConversationDocument, type ConversationMessage } from "../schemas/firestore";
-export declare class ConversationFullError extends Error {
-    readonly code: "CONVERSATION_FULL";
-}
-export declare class ConversationsRepository {
-    private collection;
-    /**
-     * Find an existing buyer×store×product conversation or create a new one.
-     * Idempotent — safe to call on every "Contact Seller" click.
-     */
-    findOrCreateByContext(params: {
-        buyerId: string;
-        buyerDisplayName: string;
-        storeId: string;
-        storeName: string;
-        sellerDisplayName: string;
-        productId?: string;
-        productTitle?: string;
-    }): Promise<ConversationDocument>;
-    findById(id: string): Promise<ConversationDocument | null>;
-    listByBuyer(buyerId: string): Promise<ConversationDocument[]>;
-    listByStore(storeId: string): Promise<ConversationDocument[]>;
-    /**
-     * Conversation ids this user may subscribe to, for the RTDB `conversationIds`
-     * custom-token claim.
-     *
-     * 🛑 This claim previously had NO ISSUER ANYWHERE. The `chats/$conversationId`
-     * rule requires `auth.token.conversationIds[$conversationId] == true`, but
-     * `/api/realtime/token` only ever issued `chatIds`, built by
-     * `chatRepository.getChatIdsForUser()` over the **`chatRooms`** collection —
-     * a different collection with different document ids. So the buyer↔seller
-     * live-message channel was denied for every user, and both subscribing hooks
-     * swallowed the permission error (one into `setIsConnected(false)`, one into
-     * a literal `// ignore`). Messages only ever appeared for the sender, via an
-     * unrelated `refetch()` after send.
-     *
-     * `.select()` with no fields fetches ids only — the document bodies are not
-     * needed and this runs on every token issue.
-     *
-     * @param limit hard cap. Firebase custom claims are limited to 1000 BYTES
-     *   total; each entry costs roughly `"<20-char id>":true,` ≈ 28 bytes, so a
-     *   user in hundreds of conversations would make `createCustomToken` throw
-     *   and take the whole route down (see the route's own comment).
-     */
-    getConversationIdsForUser(userId: string, storeIds?: readonly string[], limit?: number): Promise<string[]>;
-    /**
-     * Append a message to a conversation in a transaction. Bumps the counterparty
-     * unread counter; updates lastMessage / lastMessageAt / updatedAt.
-     */
-    appendMessage(conversationId: string, msg: Omit<ConversationMessage, "id" | "sentAt" | "isRead"> & {
-        id?: string;
-        sentAt?: Date;
-    }): Promise<ConversationDocument>;
-    /**
-     * Zero out the unread counter for one party. Also flips `isRead` on the
-     * embedded messages sent by the other party so the seller side can see what
-     * the buyer has already read.
-     */
-    markRead(conversationId: string, role: "buyer" | "seller"): Promise<void>;
-}
-export declare const conversationsRepository: ConversationsRepository;