@actuate-media/cms-admin 0.12.1 → 0.14.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/mention-picker.ts

@@ -0,0 +1,180 @@
+/**
+ * Mention picker client logic + REST helper.
+ *
+ * Two responsibilities, deliberately separated so each can be unit
+ * tested without rendering React or hitting fetch:
+ *
+ * 1. `searchMentionUsers(query)` — typed wrapper over the new
+ *    `GET /api/cms/users/search` endpoint introduced in Phase 7.
+ *    Returns up to 10 `{ id, name, email }` rows matching the query.
+ * 2. `detectMentionContext(value, caret)` — pure parser that scans a
+ *    text input value backwards from the caret to decide whether the
+ *    user is currently typing a `@`-mention, and if so what the
+ *    query fragment is. Returns `null` when no active mention.
+ *
+ * Wire format note: the picker INSERTS `@<userId>` tokens at the
+ * cursor (matching the server-side `extractMentionedUserIds` regex
+ * in `cms-core/realtime/notifications.ts`). The user sees the chosen
+ * user's *name* in the picker but the textarea always holds the id.
+ * Rendering names back in the comment view is a separate slice that
+ * can ship later without breaking the wire format.
+ */
+import { cmsApi } from './api.js'
+
+export interface MentionUser {
+  id: string
+  name: string
+  email: string
+}
+
+export type MentionSearchOutcome =
+  | { ok: true; result: MentionUser[] }
+  | { ok: false; error: string; status: number }
+
+export async function searchMentionUsers(query: string): Promise<MentionSearchOutcome> {
+  const trimmed = query.trim()
+  if (trimmed.length === 0) {
+    // Mirror the server's contract: an empty query returns an empty
+    // array. We short-circuit here so the picker doesn't spend a
+    // round-trip on a guaranteed-empty response.
+    return { ok: true, result: [] }
+  }
+  const res = await cmsApi<MentionUser[]>(`/users/search?q=${encodeURIComponent(trimmed)}`, {
+    method: 'GET',
+  })
+  if (res.error || !res.data) {
+    return { ok: false, error: res.error ?? `Request failed (${res.status})`, status: res.status }
+  }
+  return { ok: true, result: res.data }
+}
+
+/**
+ * Description of an active `@`-mention being typed in a textarea / input.
+ *
+ *  - `start` and `end` are character offsets into the field value: the
+ *    `@` itself sits at `start`, and `end` is the caret position
+ *    (exclusive end of the query slice).
+ *  - `query` is the substring between the `@` and the caret — exactly
+ *    what we should pass to `searchMentionUsers()`.
+ *
+ * Callers replace `value.slice(start, end)` with the chosen token
+ * (`@<userId> `, including the trailing space) to commit a selection.
+ */
+export interface MentionContext {
+  start: number
+  end: number
+  query: string
+}
+
+/**
+ * Find an active mention at the caret. Mirrors the server-side
+ * `extractMentionedUserIds` regex
+ * (`/(^|\s)@[a-zA-Z0-9_-]{3,64}\b/g`) so the picker's intuition
+ * about what counts as a mention can never disagree with the
+ * server's notification routing.
+ *
+ * Returns `null` whenever:
+ *   - the caret is at offset 0,
+ *   - there is no `@` between the caret and the previous whitespace
+ *     boundary,
+ *   - the `@` is preceded by a non-whitespace, non-newline character
+ *     (so an email address mid-word like `foo@bar` does NOT open
+ *     the picker), or
+ *   - the candidate query contains a character outside the mention
+ *     charset (`[a-zA-Z0-9_-]`).
+ *
+ * The picker DOES open with a 0–2 character query — that's the
+ * "you've started typing a mention" UX. But it can NEVER commit
+ * such a token: `insertMentionToken` only fires for a `MentionUser`
+ * which always has an id of at least 3 chars, matching the server
+ * regex's min-length requirement.
+ */
+export function detectMentionContext(value: string, caret: number): MentionContext | null {
+  if (typeof value !== 'string') return null
+  if (caret <= 0 || caret > value.length) return null
+
+  // Walk back from the caret looking for a `@`. Stop early on any
+  // character that is neither a valid mention char nor `@`. This
+  // means a typed space, newline, punctuation, etc. terminates the
+  // mention candidate the user was building.
+  let i = caret - 1
+  while (i >= 0) {
+    const ch = value.charCodeAt(i)
+    if (ch === 64 /* @ */) break
+    if (!isMentionChar(ch)) return null
+    i -= 1
+  }
+  if (i < 0) return null
+
+  // The `@` must sit at the start of the field or be preceded by
+  // whitespace / newline. Otherwise we're mid-word (think `foo@bar`),
+  // which is not a mention.
+  if (i > 0) {
+    const prev = value.charCodeAt(i - 1)
+    if (!isBoundary(prev)) return null
+  }
+
+  const query = value.slice(i + 1, caret)
+  // Server caps queries at 64 chars; the picker simply stops
+  // suggesting once the typed query exceeds that — extra typing
+  // closes the picker so the user can complete an email or other
+  // long token without staring at a dead dropdown.
+  if (query.length > 64) return null
+
+  return { start: i, end: caret, query }
+}
+
+function isMentionChar(code: number): boolean {
+  // [a-zA-Z0-9_-] — keep this in lock-step with the regex in
+  // `cms-core/realtime/notifications.ts:extractMentionedUserIds`.
+  if (code === 95 /* _ */ || code === 45 /* - */) return true
+  if (code >= 48 && code <= 57) return true // 0-9
+  if (code >= 65 && code <= 90) return true // A-Z
+  if (code >= 97 && code <= 122) return true // a-z
+  return false
+}
+
+function isBoundary(code: number): boolean {
+  // ASCII space, tab, line-feed, or carriage-return. We deliberately
+  // do NOT widen this to the full Unicode whitespace class — the
+  // server-side `extractMentionedUserIds` regex in
+  // `cms-core/realtime/notifications.ts` uses `\s` which DOES match
+  // Unicode whitespace, but its `^` anchor means the only realistic
+  // mid-string boundaries in practice are these four ASCII chars
+  // (a CMS comment body containing U+00A0 NBSP before an `@` would
+  // be both unusual and not worth opening the picker for).
+  return code === 32 || code === 9 || code === 10 || code === 13
+}
+
+/**
+ * Apply a mention selection to a text value. Returns the new value
+ * plus the caret position where the next keystroke should land.
+ *
+ * Inserts `@<userId> ` (trailing space) so the user can keep typing
+ * without manually moving the cursor past the token. If the caret
+ * already sits before a space, we don't insert a duplicate space.
+ */
+export interface MentionInsertion {
+  value: string
+  caret: number
+}
+
+export function insertMentionToken(
+  value: string,
+  context: MentionContext,
+  userId: string,
+): MentionInsertion {
+  const hasTrailingSpace = value.charAt(context.end) === ' '
+  // If the user already has a space immediately after the mention
+  // region, reuse it (don't double-space) but still advance the
+  // caret past that space so the next keystroke continues naturally
+  // rather than landing back in front of the space.
+  const trailingSpace = hasTrailingSpace ? '' : ' '
+  const token = `@${userId}${trailingSpace}`
+  const before = value.slice(0, context.start)
+  const after = value.slice(context.end)
+  return {
+    value: `${before}${token}${after}`,
+    caret: context.start + token.length + (hasTrailingSpace ? 1 : 0),
+  }
+}

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