@actuate-media/cms-admin 0.12.1 → 0.13.0

package/src/components/NotificationBell.tsx

@@ -5,10 +5,13 @@ import React, { useCallback, useEffect, useRef, useState } from 'react'
 import {
   type Notification,
   type NotificationOutcome,
+  type NotificationStreamHandle,
+  type NotificationStreamOptions,
   listNotifications as defaultListNotifications,
   markAllNotificationsRead as defaultMarkAllRead,
   markNotificationRead as defaultMarkRead,
   notificationSummary,
+  subscribeNotificationStream as defaultSubscribeStream,
   unreadCount as defaultUnreadCount,
 } from '../lib/notifications-client.js'
 
@@ -20,25 +23,41 @@ import {
  *
  * Design choices:
  *
- * - **Polling, not SSE.** Phase 3 already ships an SSE stream for live
- *   previews (Phase 2 / `/preview/stream`), but extending it to
- *   per-user notifications adds a non-trivial fan-out path and a fresh
- *   security surface (privacy-leak risk on misconfigured streams). The
- *   bell polls every `pollIntervalMs` (default 30s) and on dropdown
- *   open. A push-based extension is queued as a Phase 4 follow-up.
+ * - **SSE push, with poll fallback (Phase 7).** A persistent
+ *   `EventSource` subscribes to `/api/cms/notifications/stream` for
+ *   instant delivery; new notifications bump the badge immediately
+ *   instead of after the next 30 s poll tick. The poll loop is kept
+ *   alive at a back-pressure-friendly cadence (default 60 s — twice
+ *   the legacy 30 s value because SSE handles the common case) and
+ *   acts as a backstop for:
+ *     1. multi-node deployments where the in-process bus only
+ *        publishes to subscribers on the same node, and
+ *     2. proxies / browsers that silently drop the EventSource
+ *        without firing `onerror`.
  * - **Optimistic read state.** When the user clicks a notification we
  *   mark it read locally before the server confirms — so the bell
  *   counter feels instant. Server failures roll the state back via
  *   the `onError` toast.
  * - **API injection.** The dependency-injection seam matches the rest
  *   of the admin (`CommentSidePanel.api`) so unit tests can substitute
- *   in-memory fakes.
+ *   in-memory fakes — including the EventSource subscriber, which
+ *   isn't available in JSDOM by default.
  */
 export interface NotificationsApi {
   list: (opts: { includeRead?: boolean }) => Promise<NotificationOutcome<Notification[]>>
   unread: () => Promise<NotificationOutcome<number>>
   markRead: (id: string) => Promise<NotificationOutcome<Notification>>
   markAllRead: () => Promise<NotificationOutcome<number>>
+  /**
+   * Open a per-user SSE subscription. Implementations MUST always
+   * return a handle — even in environments without `EventSource`
+   * (SSR, JSDOM without a polyfill), where a no-op `{ close() {} }`
+   * is the right answer. The bell's effect calls `handle.close()`
+   * unconditionally on unmount; a `null` return would crash.
+   * Omitting the member entirely is the supported way to opt out of
+   * SSE (the bell then runs poll-only).
+   */
+  subscribe?: (opts: NotificationStreamOptions) => NotificationStreamHandle
 }
 
 const defaultApi: NotificationsApi = {
@@ -46,10 +65,16 @@ const defaultApi: NotificationsApi = {
   unread: () => defaultUnreadCount(),
   markRead: (id) => defaultMarkRead(id),
   markAllRead: () => defaultMarkAllRead(),
+  subscribe: (opts) => defaultSubscribeStream(opts),
 }
 
 export interface NotificationBellProps {
-  /** Polling cadence in milliseconds. Default 30,000. Pass 0 to disable. */
+  /**
+   * Polling cadence in milliseconds for the fallback loop. Default
+   * 60,000 (twice the pre-SSE value — push handles the common case).
+   * Pass 0 to disable polling entirely (relies on SSE only — only
+   * safe on single-node deployments).
+   */
   pollIntervalMs?: number
   /** Optional click hook — called with the notification when a row is clicked. */
   onSelect?: (notification: Notification) => void
@@ -61,7 +86,7 @@ export interface NotificationBellProps {
 }
 
 export function NotificationBell({
-  pollIntervalMs = 30_000,
+  pollIntervalMs = 60_000,
   onSelect,
   onError,
   api = defaultApi,
@@ -72,6 +97,15 @@ export function NotificationBell({
   const [items, setItems] = useState<Notification[]>([])
   const [loading, setLoading] = useState(false)
   const mountedRef = useRef(true)
+  // Set of notification IDs we've already rendered. The SSE handler
+  // consults this synchronously so duplicate deliveries (REST refresh
+  // + SSE push, or two SSE retries) don't double-bump the badge.
+  // Kept in sync with `items` via an effect — the items state is the
+  // source of truth; this ref is a derived O(1) lookup index.
+  const seenIdsRef = useRef<Set<string>>(new Set())
+  useEffect(() => {
+    seenIdsRef.current = new Set(items.map((n) => n.id))
+  }, [items])
   useEffect(() => {
     return () => {
       mountedRef.current = false
@@ -111,6 +145,34 @@ export function NotificationBell({
     return () => clearInterval(id)
   }, [refreshUnread, pollIntervalMs])
 
+  // SSE push subscription. Bumps the badge + prepends the new row to
+  // the open dropdown the instant the server publishes. Falls back
+  // silently when the api/runtime doesn't support EventSource — the
+  // poll loop above keeps the bell correct in that case.
+  useEffect(() => {
+    if (!api.subscribe) return
+    const handle = api.subscribe({
+      onNotification: (n) => {
+        if (!mountedRef.current) return
+        // Defensive: SSE events can race with REST refreshes (or with
+        // their own retries). The seen-id ref is updated
+        // synchronously so a second delivery of the same row is a
+        // no-op for BOTH `items` and the unread badge — guarding only
+        // setItems would still let the counter drift.
+        if (seenIdsRef.current.has(n.id)) return
+        seenIdsRef.current.add(n.id)
+        setItems((arr) => [n, ...arr])
+        if (!n.readAt) setUnread((v) => v + 1)
+      },
+      onError: () => {
+        // Don't surface every transient SSE disconnect as a UI error —
+        // the browser auto-reconnects, and the poll loop keeps state
+        // converging. We deliberately stay quiet here.
+      },
+    })
+    return () => handle.close()
+  }, [api])
+
   useEffect(() => {
     if (!open) return
     void refreshList(false)
@@ -138,14 +200,24 @@ export function NotificationBell({
   )
 
   const handleMarkAll = useCallback(async () => {
-    const previous = items.slice()
+    // Snapshot ONLY the previously-unread IDs (and their original
+    // readAt values, which are null by definition). On rollback we
+    // restore those specific rows and leave anything that arrived
+    // via SSE while the request was in flight alone — otherwise a
+    // failed mark-all-read would drop fresh notifications.
+    const previouslyUnreadIds = items.filter((n) => n.readAt === null).map((n) => n.id)
+    if (previouslyUnreadIds.length === 0) return
+    const ids = new Set(previouslyUnreadIds)
     const now = new Date().toISOString()
-    setItems(items.map((n) => ({ ...n, readAt: n.readAt ?? now })))
+    setItems((arr) => arr.map((n) => (ids.has(n.id) ? { ...n, readAt: n.readAt ?? now } : n)))
     setUnread(0)
     const out = await api.markAllRead()
     if (!out.ok) {
       onError?.(out.error)
-      setItems(previous)
+      // Functional rollback: only revert the rows we optimistically
+      // marked. Anything mid-flight (SSE arrivals, locally-added) is
+      // untouched.
+      setItems((arr) => arr.map((n) => (ids.has(n.id) ? { ...n, readAt: null } : n)))
       await refreshUnread()
     }
   }, [api, items, onError, refreshUnread])

package/src/lib/api.ts

@@ -6,6 +6,17 @@ export function setApiBase(path: string) {
   basePath = path
 }
 
+/**
+ * Current API base path. Exposed so non-`fetch` consumers (in
+ * particular `EventSource` for SSE channels) can resolve URLs against
+ * the same prefix configured via `setApiBase()`. Keep this read-only
+ * — mutation must always flow through `setApiBase()` so we never have
+ * two callers with diverging views of the base.
+ */
+export function getApiBase(): string {
+  return basePath
+}
+
 function getCsrfToken(): string {
   if (typeof document === 'undefined') return ''
   const match = document.cookie.match(/(?:^|;\s*)actuate_csrf=([^;]*)/)

package/src/lib/notifications-client.ts

@@ -11,7 +11,7 @@
  * (which carries Prisma types that don't belong in the admin bundle).
  */
 
-import { cmsApi } from './api.js'
+import { cmsApi, getApiBase } from './api.js'
 
 export type NotificationKind = 'comment_reply' | 'comment_resolved' | 'comment_mention'
 
@@ -125,6 +125,152 @@ export async function markAllNotificationsRead(): Promise<NotificationOutcome<nu
   return { ok: true, result: res.data.count }
 }
 
+/**
+ * Subscribe to the per-user SSE push channel that ships notifications
+ * the instant they're persisted server-side. Replaces the 30-second
+ * poll loop in the notification bell.
+ *
+ * The browser's native `EventSource` handles reconnection for us — on
+ * a server-initiated close (the stream caps at ~4 minutes by design),
+ * the connection re-opens automatically. We DO NOT abort the poll
+ * fallback in callers: SSE is a latency-win, the poll is what keeps
+ * multi-node deployments correct (each node only pushes to its own
+ * subscribers).
+ *
+ * Returns a `close()` function that callers MUST invoke on unmount —
+ * otherwise the browser keeps the connection open and we leak event
+ * listeners.
+ *
+ * `EventSource` itself isn't available in the JSDOM test environment;
+ * callers can inject a `factory` to substitute a test double. In
+ * production we fall back to the global `EventSource` when no factory
+ * is supplied.
+ */
+export interface NotificationStreamOptions {
+  /** Called for every `event: notification` frame. */
+  onNotification: (n: Notification) => void
+  /** Called once on the `event: ready` frame. */
+  onReady?: (payload: { userId: string }) => void
+  /** Called on connection errors. Useful for falling back to the poll loop. */
+  onError?: (event: Event) => void
+  /**
+   * Optional factory so unit tests can inject a fake `EventSource`,
+   * or a null sentinel when the environment lacks one (SSR, JSDOM
+   * without a polyfill). Production code can rely on the default
+   * (global `EventSource`).
+   */
+  factory?: (url: string) => EventSourceLike | null
+}
+
+/**
+ * Minimal subset of the `EventSource` interface our subscriber relies
+ * on. Browsers ship the full DOM type; the admin only needs add/remove
+ * event listeners plus `close()`.
+ */
+export interface EventSourceLike {
+  addEventListener: (type: string, listener: (event: MessageEvent | Event) => void) => void
+  removeEventListener?: (type: string, listener: (event: MessageEvent | Event) => void) => void
+  close: () => void
+}
+
+export interface NotificationStreamHandle {
+  /** Tear down the EventSource and stop receiving events. Idempotent. */
+  close: () => void
+}
+
+export function subscribeNotificationStream(
+  opts: NotificationStreamOptions,
+): NotificationStreamHandle {
+  // The `cmsApi()` helper handles base-path / origin resolution for
+  // fetch calls, but EventSource takes a raw URL. We mirror its
+  // logic locally — `/api/cms/notifications/stream` is correct for
+  // both the local dev server and any production deploy that mounts
+  // the CMS API at the default prefix. Custom prefixes are handled by
+  // the consumer override (factory).
+  // Resolve against `setApiBase()` so a consumer mounting the CMS at
+  // a non-default prefix (e.g. `/cms-api`) still hits the right SSE
+  // endpoint — `EventSource` doesn't go through `cmsApi()`, so we
+  // can't rely on its url-construction logic.
+  const url = `${getApiBase()}/notifications/stream`
+  const make = opts.factory ?? defaultEventSourceFactory
+  const source = make(url)
+  if (!source) {
+    // No EventSource available (SSR? JSDOM without polyfill? Or the
+    // injected factory deliberately returns null in tests). Return a
+    // no-op handle so callers can compose without conditional logic.
+    return { close: () => {} }
+  }
+  let closed = false
+
+  const onReady = (event: MessageEvent | Event) => {
+    if (!opts.onReady) return
+    const data = parseEventData(event)
+    if (data && typeof (data as { userId?: unknown }).userId === 'string') {
+      opts.onReady({ userId: (data as { userId: string }).userId })
+    }
+  }
+  const onNotification = (event: MessageEvent | Event) => {
+    const data = parseEventData(event)
+    if (data && isNotification(data)) {
+      opts.onNotification(data)
+    }
+  }
+  const onError = (event: Event) => {
+    opts.onError?.(event)
+  }
+
+  source.addEventListener('ready', onReady)
+  source.addEventListener('notification', onNotification)
+  source.addEventListener('error', onError)
+
+  return {
+    close: () => {
+      if (closed) return
+      closed = true
+      source.removeEventListener?.('ready', onReady)
+      source.removeEventListener?.('notification', onNotification)
+      source.removeEventListener?.('error', onError)
+      source.close()
+    },
+  }
+}
+
+function defaultEventSourceFactory(url: string): EventSourceLike | null {
+  if (typeof EventSource === 'undefined') return null
+  // `withCredentials: true` so the admin session cookie travels with
+  // the connection upgrade — every notification stream requires auth
+  // and the same-origin cookie is the only credential we trust here.
+  return new EventSource(url, { withCredentials: true }) as unknown as EventSourceLike
+}
+
+function parseEventData(event: MessageEvent | Event): unknown {
+  // EventSource emits MessageEvents with `data: string`. Plain
+  // `Event` (e.g. the `error` event) has no payload; ignore.
+  const data = (event as MessageEvent).data
+  if (typeof data !== 'string') return null
+  try {
+    return JSON.parse(data)
+  } catch {
+    return null
+  }
+}
+
+function isNotification(value: unknown): value is Notification {
+  if (!value || typeof value !== 'object') return false
+  const v = value as Record<string, unknown>
+  // Defensive: don't trust the wire blindly — verify the discriminant
+  // properties our consumers will read. A drift in the server-side
+  // wire format must surface as "missing fields" in the test suite,
+  // not as runtime errors deep in the bell's render path.
+  return (
+    typeof v.id === 'string' &&
+    typeof v.userId === 'string' &&
+    typeof v.createdAt === 'string' &&
+    !!v.payload &&
+    typeof (v.payload as { kind?: unknown }).kind === 'string'
+  )
+}
+
 /**
  * Cheap single-line summary for the bell list — the server gives us a
  * structured payload, but the dropdown wants one human-readable string