@sentry/junior-dashboard 0.276.0 → 0.278.0

package/src/client/conversations/queries.ts

@@ -1,9 +1,9 @@
-import { useDeferredValue, useEffect, useMemo, useRef } from "react";
+import { useDeferredValue, useEffect, useMemo, useRef, useState } from "react";
 import {
+  type QueryClient,
   queryOptions,
   useInfiniteQuery,
   useMutation,
-  useMutationState,
   useQuery,
   useQueryClient,
 } from "@tanstack/react-query";
@@ -12,13 +12,12 @@ import type {
   ConversationEventPage,
   ConversationFeed,
   ConversationPendingMessagesReport,
-  ConversationSummaryReport,
   InputImage,
 } from "@sentry/junior/api/schema";
 import {
   acceptedConversationMessageSchema,
+  CONVERSATION_DETAIL_VERSION_HEADER,
   webMessageId,
-  archiveConversationResponseSchema,
   cancelConversationPendingMessagesResponseSchema,
   conversationDetailReportSchema,
   conversationEventPageSchema,
@@ -28,11 +27,11 @@ import {
   stopConversationTurnResponseSchema,
 } from "@sentry/junior/api/schema";
 
+import { REVIEW_ITEMS_QUERY_KEY } from "../review-desk/queries";
 import {
   DashboardApiError,
   del,
   fetchDashboardJson,
-  patch,
   post,
   readDashboardResponse,
 } from "../http";
@@ -66,78 +65,13 @@ export function conversationDetailQueryKey(conversationId: string | undefined) {
   return ["conversation", conversationId, "detail"] as const;
 }
 
-function archivedConversationQueryKey(conversationId: string) {
-  return ["dashboard", "archived-conversation", conversationId] as const;
-}
-
-/** Read active/archived status from a dashboard conversations query key. */
-function conversationFeedStatus(
-  queryKey: readonly unknown[],
-): "active" | "archived" | undefined {
-  const status = queryKey[queryKey.length - 1];
-  return status === "active" || status === "archived" ? status : undefined;
-}
-
-type ArchivedConversationSnapshot = {
-  conversation: ConversationSummaryReport;
-  feedQueryHashes: string[];
-};
-
-const archiveConversationMutationKey = [
-  "dashboard",
-  "archive-conversation",
-] as const;
-
-type ArchiveConversationVariables = {
-  archived: boolean;
-  lastSeenAt: string;
-};
-
-type ArchiveConversationMutationContext = {
-  archivedQueryKey: ReturnType<typeof archivedConversationQueryKey>;
-  archivedSnapshot?: ArchivedConversationSnapshot;
-  detailQueryKey: ReturnType<typeof conversationDetailQueryKey>;
-  previousArchivedSnapshot?: ArchivedConversationSnapshot;
-  previousDetail?: ConversationDetailReport;
-  previousFeeds: Array<[readonly unknown[], ConversationFeed | undefined]>;
-};
-
-export type PendingArchiveConversationUpdate = {
-  archived: boolean;
-  conversation?: ConversationSummaryReport;
-  conversationId: string;
-};
-
-/** Read pending archive state so refetches cannot visually replace optimistic UI. */
-export function usePendingArchiveConversationUpdates() {
-  return useMutationState({
-    filters: {
-      mutationKey: archiveConversationMutationKey,
-      status: "pending",
-    },
-    select: (mutation) => {
-      const variables = mutation.state
-        .variables as ArchiveConversationVariables;
-      const context = mutation.state.context as
-        | ArchiveConversationMutationContext
-        | undefined;
-      const conversationId = mutation.options.mutationKey?.[2];
-      return {
-        archived: variables.archived,
-        conversation: context?.archivedSnapshot?.conversation,
-        conversationId:
-          typeof conversationId === "string" ? conversationId : "",
-      } satisfies PendingArchiveConversationUpdate;
-    },
-  });
-}
-
 // Right after a send, Junior usually reads the message within a few seconds.
 // Poll fast for that window only, then fall back to the normal live interval.
 const FAST_POLL_INTERVAL_MS = 500;
 const FAST_POLL_WINDOW_MS = 6_000;
 
-type ConversationSnapshot = ConversationDetailReport & {
+/** The cached detail report with its mailbox and revalidation ETag. */
+export type ConversationSnapshot = ConversationDetailReport & {
   mailbox?: ConversationPendingMessagesReport;
   detailEtag?: string;
 };
@@ -147,12 +81,44 @@ async function readConversationSnapshot(
   conversationId: string,
   signal?: AbortSignal,
   previous?: ConversationSnapshot,
+  unreadPage?: boolean,
 ): Promise<ConversationSnapshot> {
   const mailbox = await readConversationPendingMessages(conversationId, signal);
-  const detail = await readConversationData(conversationId, signal, previous);
+  const detail = await readConversationData(
+    conversationId,
+    signal,
+    previous,
+    unreadPage,
+  );
   return { ...detail, mailbox };
 }
 
+const CONVERSATION_SIDE_READS = ["agents", "memories", "watches"] as const;
+
+/**
+ * Key a read that shows beside the detail report, such as in the details
+ * panel. A detail change refreshes it.
+ */
+export function conversationSideReadQueryKey(
+  conversationId: string,
+  read: (typeof CONVERSATION_SIDE_READS)[number],
+) {
+  return ["conversation", conversationId, read] as const;
+}
+
+/** Refresh the side reads and Review items. Only mounted reads refetch. */
+function refreshConversationSideReads(
+  client: QueryClient,
+  conversationId: string,
+) {
+  for (const read of CONVERSATION_SIDE_READS) {
+    void client.invalidateQueries({
+      queryKey: conversationSideReadQueryKey(conversationId, read),
+    });
+  }
+  void client.invalidateQueries({ queryKey: REVIEW_ITEMS_QUERY_KEY });
+}
+
 /** Refresh history and mailbox as one visible snapshot, including idle input. */
 export function conversationDetailQueryOptions(
   conversationId: string | undefined,
@@ -160,19 +126,37 @@ export function conversationDetailQueryOptions(
     awaitingMessage?: boolean;
     /** Poll fast until this time so a new send reaches history quickly. */
     fastPollUntilMs?: number;
+    /** Also read the page around the read position. */
+    unreadPage?: boolean;
   },
 ) {
+  // `unreadPage` adds a page to one fetch. The detail in the cache is the
+  // same, so it stays out of the key.
+  // oxlint-disable-next-line @tanstack/query/exhaustive-deps
   return queryOptions({
     enabled: Boolean(conversationId),
     queryKey: conversationDetailQueryKey(conversationId),
-    queryFn: ({ signal, client }) =>
-      readConversationSnapshot(
+    queryFn: async ({ signal, client }) => {
+      const previous = client.getQueryData<ConversationSnapshot>(
+        conversationDetailQueryKey(conversationId),
+      );
+      const next = await readConversationSnapshot(
         conversationId!,
         signal,
-        client.getQueryData<ConversationSnapshot>(
-          conversationDetailQueryKey(conversationId),
-        ),
-      ),
+        previous,
+        options?.unreadPage,
+      );
+      // Side reads do not poll. A new ETag means the Conversation changed,
+      // so the details panel may be stale too.
+      if (
+        previous?.detailEtag &&
+        next.detailEtag &&
+        previous.detailEtag !== next.detailEtag
+      ) {
+        refreshConversationSideReads(client, conversationId!);
+      }
+      return next;
+    },
     structuralSharing: (previous, next) => {
       if (!next || typeof next !== "object") return next;
       if (!previous || typeof previous !== "object") return next;
@@ -199,7 +183,8 @@ export function conversationDetailQueryOptions(
 
 /**
  * Read positions only move forward. A poll that started before a read report
- * finished must not put an older position back in the cache.
+ * finished must not put an older position back in the cache, nor the unread
+ * cursor of that older position.
  */
 function keepLatestReadPosition(
   previous: ConversationSnapshot,
@@ -208,7 +193,8 @@ function keepLatestReadPosition(
   const kept = previous.readPosition;
   if (!kept) return next;
   if ((next.readPosition?.lastReadSeq ?? -1) >= kept.lastReadSeq) return next;
-  return { ...next, readPosition: kept };
+  const { unreadCursor: _olderCursor, ...rest } = next;
+  return { ...rest, readPosition: kept };
 }
 
 /** Create one dashboard conversation and refresh the personal feed. */
@@ -510,170 +496,29 @@ export function useStopConversationTurn(conversationId: string) {
   });
 }
 
-/** Archive or restore one conversation with an immediate reversible cache update. */
-export function useArchiveConversation(
-  conversationId: string,
+/** The open Conversation's data, from `useConversationData`. */
+export type ConversationData = ReturnType<typeof useConversationData>;
+
+/** Fetch a bounded conversation snapshot and older pages on demand. */
+export function useConversationData(
+  conversationId: string | undefined,
   options?: {
-    onError?(): void;
-    onSuccess?(archivedAt: string | null): void;
+    /**
+     * Ask the first fetch of this visit for the page around the read
+     * position. Polls do not ask, so the server reads that page once.
+     */
+    unreadPageAtOpen?: boolean;
   },
 ) {
   const queryClient = useQueryClient();
-  return useMutation({
-    mutationKey: [...archiveConversationMutationKey, conversationId],
-    mutationFn: (args: ArchiveConversationVariables) =>
-      patch(
-        archiveConversationResponseSchema,
-        `/api/conversations/${encodeURIComponent(conversationId)}/archive`,
-        args,
-      ),
-    onMutate: async (args) => {
-      const conversationQueries = { queryKey: ["dashboard", "conversations"] };
-      const detailQueryKey = conversationDetailQueryKey(conversationId);
-      const archivedQueryKey = archivedConversationQueryKey(conversationId);
-      await Promise.all([
-        queryClient.cancelQueries(conversationQueries),
-        queryClient.cancelQueries({ queryKey: detailQueryKey }),
-      ]);
-      const previousFeeds =
-        queryClient.getQueriesData<ConversationFeed>(conversationQueries);
-      const previousDetail =
-        queryClient.getQueryData<ConversationDetailReport>(detailQueryKey);
-      const previousArchivedSnapshot =
-        queryClient.getQueryData<ArchivedConversationSnapshot>(
-          archivedQueryKey,
-        );
-      const archivedAt = args.archived ? new Date().toISOString() : null;
-      // Snapshot from any loaded feed, including archived-only fixtures that
-      // were never archived through this client session.
-      const archivedSnapshot =
-        buildArchivedConversationSnapshot(previousFeeds, conversationId) ??
-        previousArchivedSnapshot;
-
-      previousFeeds.forEach(([queryKey, feed]) => {
-        if (!feed) return;
-        const conversationExists = feed.conversations.some(
-          (conversation) => conversation.conversationId === conversationId,
-        );
-        const feedStatus = conversationFeedStatus(queryKey);
-        const shouldRestore =
-          !args.archived &&
-          !conversationExists &&
-          Boolean(archivedSnapshot) &&
-          feedStatus !== "archived";
-        const conversations = shouldRestore
-          ? [
-              ...feed.conversations,
-              { ...archivedSnapshot!.conversation, archivedAt: null },
-            ].sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt))
-          : feed.conversations.map((conversation) =>
-              conversation.conversationId === conversationId
-                ? { ...conversation, archivedAt }
-                : conversation,
-            );
-        queryClient.setQueryData<ConversationFeed>(queryKey, {
-          ...feed,
-          conversations,
-        });
-      });
-      queryClient.setQueryData<ConversationSnapshot>(
-        detailQueryKey,
-        (detail) =>
-          detail ? { ...detail, archivedAt, detailEtag: undefined } : detail,
-      );
-      if (archivedSnapshot) {
-        queryClient.setQueryData(archivedQueryKey, archivedSnapshot);
-      }
-      return {
-        archivedQueryKey,
-        archivedSnapshot,
-        detailQueryKey,
-        previousArchivedSnapshot,
-        previousDetail,
-        previousFeeds,
-      } satisfies ArchiveConversationMutationContext;
-    },
-    onError: (_error, _args, context) => {
-      context?.previousFeeds.forEach(([queryKey, feed]) => {
-        queryClient.setQueryData(queryKey, feed);
-      });
-      if (context) {
-        queryClient.setQueryData(
-          context.detailQueryKey,
-          context.previousDetail,
-        );
-        if (context.previousArchivedSnapshot) {
-          queryClient.setQueryData(
-            context.archivedQueryKey,
-            context.previousArchivedSnapshot,
-          );
-        } else {
-          queryClient.removeQueries({
-            exact: true,
-            queryKey: context.archivedQueryKey,
-          });
-        }
-      }
-      options?.onError?.();
-    },
-    onSuccess: (result, args) => {
-      queryClient.setQueryData<ConversationSnapshot>(
-        conversationDetailQueryKey(conversationId),
-        (detail) =>
-          detail
-            ? {
-                ...detail,
-                archivedAt: result.archivedAt,
-                detailEtag: undefined,
-              }
-            : detail,
-      );
-      if (!args.archived) {
-        queryClient.removeQueries({
-          exact: true,
-          queryKey: archivedConversationQueryKey(conversationId),
-        });
-      }
-      options?.onSuccess?.(result.archivedAt);
-    },
-    onSettled: async () => {
-      await Promise.all([
-        queryClient.invalidateQueries({
-          queryKey: ["dashboard", "conversations"],
-        }),
-        queryClient.invalidateQueries({
-          queryKey: ["dashboard", "locations"],
-        }),
-        queryClient.invalidateQueries({ queryKey: ["dashboard", "people"] }),
-        queryClient.invalidateQueries({
-          exact: true,
-          queryKey: conversationDetailQueryKey(conversationId),
-        }),
-      ]);
-    },
-  });
-}
-
-function buildArchivedConversationSnapshot(
-  feeds: Array<[readonly unknown[], ConversationFeed | undefined]>,
-  conversationId: string,
-): ArchivedConversationSnapshot | undefined {
-  let conversation: ConversationSummaryReport | undefined;
-  const feedQueryHashes: string[] = [];
-  for (const [queryKey, feed] of feeds) {
-    const feedConversation = feed?.conversations.find(
-      (item) => item.conversationId === conversationId,
-    );
-    if (!feedConversation) continue;
-    conversation ??= feedConversation;
-    feedQueryHashes.push(JSON.stringify(queryKey));
+  // The shell keeps one hook across Conversations, so a new Conversation
+  // starts a new visit.
+  const [visit, setVisit] = useState({ conversationId, fetched: false });
+  if (visit.conversationId !== conversationId) {
+    setVisit({ conversationId, fetched: false });
   }
-  return conversation ? { conversation, feedQueryHashes } : undefined;
-}
-
-/** Fetch a bounded conversation snapshot and older pages on demand. */
-export function useConversationData(conversationId: string | undefined) {
-  const queryClient = useQueryClient();
+  const fetchedAtOpen =
+    visit.conversationId === conversationId && visit.fetched;
   const outbox = useQuery({
     enabled: Boolean(conversationId),
     // Local-only cache. Never replace optimistic rows with an empty fetch result.
@@ -711,11 +556,20 @@ export function useConversationData(conversationId: string | undefined) {
       fastPollUntilMs: latestSendAtMs
         ? latestSendAtMs + FAST_POLL_WINDOW_MS
         : undefined,
+      unreadPage: Boolean(options?.unreadPageAtOpen) && !fetchedAtOpen,
     }),
-    // A reopened Conversation shows the cached copy at once, but it can miss
-    // messages that arrived while the reader was away. Fetch it each visit.
-    refetchOnMount: "always",
   });
+  // A reopened Conversation shows the cached copy at once, but it can miss
+  // messages that arrived while the reader was away. Fetch it once at the
+  // start of each visit, even when the cached copy is still fresh. A fetch
+  // that is already running counts.
+  const refetchDetail = detail.refetch;
+  useEffect(() => {
+    if (conversationId) void refetchDetail({ cancelRefetch: false });
+  }, [conversationId, refetchDetail]);
+  if (!fetchedAtOpen && detail.isFetchedAfterMount && !detail.isFetching) {
+    setVisit({ conversationId, fetched: true });
+  }
   // Defer the whole server snapshot, not history alone. Queue removal and the
   // matching transcript must paint together while composer input stays urgent.
   const deferredDetail = useDeferredValue(detail.data);
@@ -869,7 +723,6 @@ export function useConversationData(conversationId: string | undefined) {
   const isLoadingPreviousPage =
     history.isFetchingNextPage || historyNeedsReconciliation;
 
-  const refetchDetail = detail.refetch;
   useEffect(() => {
     if (shouldRefreshDetail) void refetchDetail();
   }, [refetchDetail, shouldRefreshDetail]);
@@ -885,11 +738,18 @@ export function useConversationData(conversationId: string | undefined) {
 
   const fetchNextHistoryPage = history.fetchNextPage;
   useEffect(() => {
-    if (historyNeedsReconciliation) void fetchNextHistoryPage();
+    if (historyNeedsReconciliation) {
+      void fetchNextHistoryPage({ cancelRefetch: false });
+    }
   }, [fetchNextHistoryPage, historyNeedsReconciliation]);
 
   return {
     data,
+    /**
+     * The latest page alone, without earlier pages. It is not deferred, so it
+     * matches `fetchedDetail` and the read position that came with it.
+     */
+    latest: detail.data,
     error: detail.error,
     historyError,
     historyVersion: conversationHistoryVersion(historyPages ?? []),
@@ -897,6 +757,8 @@ export function useConversationData(conversationId: string | undefined) {
       ? history.hasNextPage
       : Boolean(detailData?.previousCursor),
     isPending: detail.isPending,
+    /** The first fetch of this visit has ended. */
+    fetchedAtOpen,
     /** The latest detail after a fetch in this visit, before it is deferred. */
     fetchedDetail:
       detail.isFetchedAfterMount && !detail.isFetching
@@ -922,8 +784,10 @@ export function useConversationData(conversationId: string | undefined) {
       const hasPreviousPage = history.data
         ? history.hasNextPage
         : Boolean(detailData?.previousCursor);
-      if (conversationId && hasPreviousPage && !history.isFetchingNextPage) {
-        void history.fetchNextPage();
+      if (conversationId && hasPreviousPage) {
+        // A second call joins the read in flight. By default it cancels
+        // that read and starts the same read again.
+        void history.fetchNextPage({ cancelRefetch: false });
       }
     },
   };
@@ -934,15 +798,22 @@ export async function readConversationData(
   conversationId: string,
   signal?: AbortSignal,
   previous?: ConversationSnapshot,
+  unreadPage?: boolean,
 ): Promise<ConversationSnapshot> {
   const response = await readDashboardResponse(
-    `/api/conversations/${encodeURIComponent(conversationId)}`,
+    `/api/conversations/${encodeURIComponent(conversationId)}${unreadPage ? "?unreadPage=true" : ""}`,
     signal,
-    previous?.detailEtag,
+    previous?.detailEtag
+      ? { [CONVERSATION_DETAIL_VERSION_HEADER]: previous.detailEtag }
+      : undefined,
   );
   if (response.status === 304 && previous) return previous;
   const report = conversationDetailReportSchema.parse(await response.json());
-  return { ...report, detailEtag: response.headers.get("etag") ?? undefined };
+  return {
+    ...report,
+    detailEtag:
+      response.headers.get(CONVERSATION_DETAIL_VERSION_HEADER) ?? undefined,
+  };
 }
 
 /** Read accepted mailbox messages that have not reached durable history yet. */

package/src/client/conversations/transcript.ts

@@ -13,22 +13,8 @@ export function buildConversationTranscript(
   detail: ConversationDetailReport,
   historyPages: ConversationHistoryPage[],
 ): ConversationDetailReport {
-  if (detail.eventHistory.status !== "available") {
-    return withoutModelUsage(detail);
-  }
-
-  const restrictedHistory = historyPages.find(
-    (page) => page.eventHistory.status !== "available",
-  );
-  if (restrictedHistory) {
-    return withoutModelUsage({
-      ...detail,
-      eventHistory: restrictedHistory.eventHistory,
-      events: restrictedHistory.events,
-      previousCursor: restrictedHistory.previousCursor,
-    });
-  }
-
+  const restricted = restrictedTranscript(detail, historyPages);
+  if (restricted) return restricted;
   if (historyPages.length === 0) return detail;
 
   return {
@@ -45,6 +31,30 @@ export function buildConversationTranscript(
   };
 }
 
+/**
+ * Build a transcript that opens at the read position.
+ *
+ * `pages` hold one unbroken range of events around the read position. The
+ * caller supplies `latestEvents` only when `pages` reach them, so the
+ * transcript never shows a gap between the two.
+ */
+export function buildUnreadConversationTranscript(
+  detail: ConversationDetailReport,
+  pages: ConversationEventPage[],
+  latestEvents: ConversationReportEvent[],
+): ConversationDetailReport {
+  const restricted = restrictedTranscript(detail, pages);
+  if (restricted) return restricted;
+  return {
+    ...detail,
+    events: orderedEvents([
+      ...pages.flatMap((page) => page.events),
+      ...latestEvents,
+    ]),
+    previousCursor: oldestPreviousCursor(pages),
+  };
+}
+
 /** Materialize one immutable detail snapshot through its exact history cursor chain. */
 export async function loadCompleteConversationTranscript(args: {
   detail: ConversationDetailReport;
@@ -198,6 +208,26 @@ function orderedEvents(
   );
 }
 
+/** Show only what restricted history allows, from detail or from a page. */
+function restrictedTranscript(
+  detail: ConversationDetailReport,
+  pages: ConversationEventPage[],
+): ConversationDetailReport | undefined {
+  if (detail.eventHistory.status !== "available") {
+    return withoutModelUsage(detail);
+  }
+  const restrictedPage = pages.find(
+    (page) => page.eventHistory.status !== "available",
+  );
+  if (!restrictedPage) return undefined;
+  return withoutModelUsage({
+    ...detail,
+    eventHistory: restrictedPage.eventHistory,
+    events: restrictedPage.events,
+    previousCursor: restrictedPage.previousCursor,
+  });
+}
+
 function withoutModelUsage(
   detail: ConversationDetailReport,
 ): ConversationDetailReport {