@actuate-media/cms-admin 0.12.0 → 0.13.0

package/src/lib/comments-client.ts

@@ -0,0 +1,208 @@
+/**
+ * Comments REST client — thin, typed wrapper around the
+ * `/documents/:id/comments` + `/comments/:id` endpoints shipped in slice 4
+ * of Phase 3 (see `packages/cms-core/src/realtime/comments.ts`).
+ *
+ * The client lives in `cms-admin` so the side panel, the bubble-menu
+ * "comment on selection" action, and any future MCP/AI hooks all share one
+ * request path, error model, and DTO shape.
+ *
+ * Mirrors the server contract:
+ *   POST   /documents/:documentId/comments     -> { body, anchor?, parentId? }
+ *   GET    /documents/:documentId/comments?…   -> { data: CommentDTO[] }
+ *   PATCH  /comments/:id                       -> { body }
+ *   POST   /comments/:id/resolve               -> 200 with updated DTO
+ *   POST   /comments/:id/reopen                -> 200 with updated DTO
+ *   DELETE /comments/:id                       -> 200 with soft-deleted DTO
+ */
+
+import { cmsApi } from './api.js'
+
+/**
+ * Yjs relative-position anchor returned by the server. The encoding is
+ * intentionally opaque on the wire (Base64 of `Y.encodeRelativePosition`);
+ * `lib/comment-anchor.ts` handles the round-trip when slice 5 paints a
+ * highlight in the editor.
+ */
+export interface CommentAnchor {
+  from: string
+  to: string
+}
+
+/**
+ * Public DTO returned by every comments endpoint. Mirrors `CommentDTO` in
+ * `@actuate-media/cms-core/realtime`; we duplicate the shape here so
+ * `cms-admin` doesn't take a hard dependency on the server-side service
+ * layer (which carries Prisma types we don't want pulled into the bundle).
+ */
+export interface Comment {
+  id: string
+  documentId: string
+  parentId: string | null
+  userId: string | null
+  body: string
+  anchor: CommentAnchor | null
+  resolvedAt: string | null
+  resolvedById: string | null
+  deletedAt: string | null
+  createdAt: string
+  updatedAt: string
+  isResolved: boolean
+}
+
+export type CommentOutcome<T> =
+  | { ok: true; result: T }
+  | { ok: false; error: string; status: number }
+
+export interface CreateCommentInput {
+  documentId: string
+  body: string
+  anchor?: CommentAnchor | null
+  parentId?: string | null
+}
+
+export interface ListCommentsOptions {
+  /** Default: false. Resolved threads are filtered out unless requested. */
+  includeResolved?: boolean
+  /** Default: false. Admin-only; the server rejects non-admin callers. */
+  includeDeleted?: boolean
+  /** Default: server-side cap (100). Hard upper bound is 200. */
+  pageSize?: number
+}
+
+function encodeOptions(opts: ListCommentsOptions = {}): string {
+  const params = new URLSearchParams()
+  if (opts.includeResolved) params.set('includeResolved', 'true')
+  if (opts.includeDeleted) params.set('includeDeleted', 'true')
+  if (opts.pageSize !== undefined) params.set('pageSize', String(opts.pageSize))
+  const qs = params.toString()
+  return qs ? `?${qs}` : ''
+}
+
+function failure(error: string, status: number): { ok: false; error: string; status: number } {
+  return { ok: false, error, status }
+}
+
+function envelope<T>(res: { data?: unknown; error?: string; status: number }): CommentOutcome<T> {
+  if (res.error || res.data === undefined) {
+    return failure(res.error ?? `Request failed (${res.status})`, res.status)
+  }
+  return { ok: true, result: res.data as T }
+}
+
+/**
+ * Create a top-level comment or a reply. Pass `parentId` to thread the
+ * comment under an existing one — the server enforces single-level
+ * threading (replies cannot themselves be parents).
+ */
+export async function createComment(input: CreateCommentInput): Promise<CommentOutcome<Comment>> {
+  if (typeof input.documentId !== 'string' || input.documentId.length === 0) {
+    return failure('documentId is required', 0)
+  }
+  if (typeof input.body !== 'string' || input.body.trim().length === 0) {
+    return failure('Comment cannot be empty', 0)
+  }
+
+  const body: Record<string, unknown> = { body: input.body.trim() }
+  if (input.anchor) body.anchor = input.anchor
+  if (input.parentId) body.parentId = input.parentId
+
+  const res = await cmsApi<Comment>(`/documents/${encodeURIComponent(input.documentId)}/comments`, {
+    method: 'POST',
+    body: JSON.stringify(body),
+  })
+  return envelope<Comment>(res)
+}
+
+/**
+ * List comments for a document. Active comments (not resolved, not deleted)
+ * are returned by default; pass `includeResolved` to keep resolved threads
+ * in the response. The server rejects `includeDeleted` for non-admins.
+ */
+export async function listComments(
+  documentId: string,
+  opts: ListCommentsOptions = {},
+): Promise<CommentOutcome<Comment[]>> {
+  if (typeof documentId !== 'string' || documentId.length === 0) {
+    return failure('documentId is required', 0)
+  }
+  const path = `/documents/${encodeURIComponent(documentId)}/comments${encodeOptions(opts)}`
+  const res = await cmsApi<Comment[]>(path, { method: 'GET' })
+  return envelope<Comment[]>(res)
+}
+
+/** Edit a comment body. Only the author or an admin is permitted. */
+export async function updateComment(id: string, body: string): Promise<CommentOutcome<Comment>> {
+  if (!id) return failure('comment id is required', 0)
+  if (typeof body !== 'string' || body.trim().length === 0) {
+    return failure('Comment cannot be empty', 0)
+  }
+  const res = await cmsApi<Comment>(`/comments/${encodeURIComponent(id)}`, {
+    method: 'PATCH',
+    body: JSON.stringify({ body: body.trim() }),
+  })
+  return envelope<Comment>(res)
+}
+
+/** Resolve a thread. Write-role or the author may resolve. */
+export async function resolveComment(id: string): Promise<CommentOutcome<Comment>> {
+  if (!id) return failure('comment id is required', 0)
+  const res = await cmsApi<Comment>(`/comments/${encodeURIComponent(id)}/resolve`, {
+    method: 'POST',
+    body: '{}',
+  })
+  return envelope<Comment>(res)
+}
+
+/** Re-open a resolved thread. Same permission as resolve. */
+export async function reopenComment(id: string): Promise<CommentOutcome<Comment>> {
+  if (!id) return failure('comment id is required', 0)
+  const res = await cmsApi<Comment>(`/comments/${encodeURIComponent(id)}/reopen`, {
+    method: 'POST',
+    body: '{}',
+  })
+  return envelope<Comment>(res)
+}
+
+/**
+ * Soft-delete a comment. The row is preserved so its replies don't lose
+ * their thread root — the server simply stops returning it from the list
+ * endpoint unless an admin asks for `includeDeleted`.
+ */
+export async function deleteComment(id: string): Promise<CommentOutcome<Comment>> {
+  if (!id) return failure('comment id is required', 0)
+  const res = await cmsApi<Comment>(`/comments/${encodeURIComponent(id)}`, {
+    method: 'DELETE',
+  })
+  return envelope<Comment>(res)
+}
+
+/**
+ * Sort comments into thread groups suitable for rendering. Roots are
+ * returned in chronological order; replies are ordered the same way and
+ * attached to their root. Replies whose root is missing (e.g. the root was
+ * filtered out by `includeResolved=false`) are dropped — the UI can fetch
+ * them explicitly if it needs to render orphaned replies.
+ */
+export interface CommentThread {
+  root: Comment
+  replies: Comment[]
+}
+
+export function groupCommentsIntoThreads(comments: readonly Comment[]): CommentThread[] {
+  const roots = new Map<string, CommentThread>()
+  const sorted = [...comments].sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt))
+
+  for (const c of sorted) {
+    if (c.parentId === null) {
+      roots.set(c.id, { root: c, replies: [] })
+    }
+  }
+  for (const c of sorted) {
+    if (c.parentId !== null) {
+      const root = roots.get(c.parentId)
+      if (root) root.replies.push(c)
+    }
+  }
+  return Array.from(roots.values())
+}

package/src/lib/notifications-client.ts

@@ -0,0 +1,292 @@
+/**
+ * Notifications REST client — typed wrapper around the slice-6 endpoints
+ * (`/notifications`, `/notifications/unread-count`,
+ * `/notifications/:id/read`, `/notifications/read-all`).
+ *
+ * Lives in `cms-admin` so the bell, the toast layer, and any future
+ * background sync agent share one request path, error model, and DTO
+ * shape. The wire format mirrors `NotificationDTO` in
+ * `@actuate-media/cms-core/realtime/notifications.ts`; we duplicate the
+ * shape here to avoid taking a hard dependency on the server module
+ * (which carries Prisma types that don't belong in the admin bundle).
+ */
+
+import { cmsApi, getApiBase } from './api.js'
+
+export type NotificationKind = 'comment_reply' | 'comment_resolved' | 'comment_mention'
+
+export interface CommentReplyPayload {
+  kind: 'comment_reply'
+  actorId: string | null
+  actorName: string | null
+  excerpt: string
+}
+
+export interface CommentResolvedPayload {
+  kind: 'comment_resolved'
+  actorId: string | null
+  actorName: string | null
+  rootExcerpt: string
+}
+
+export interface CommentMentionPayload {
+  kind: 'comment_mention'
+  actorId: string | null
+  actorName: string | null
+  excerpt: string
+}
+
+export type NotificationPayload =
+  | CommentReplyPayload
+  | CommentResolvedPayload
+  | CommentMentionPayload
+
+export interface Notification {
+  id: string
+  userId: string
+  kind: NotificationKind
+  documentId: string | null
+  commentId: string | null
+  payload: NotificationPayload
+  readAt: string | null
+  createdAt: string
+}
+
+export type NotificationOutcome<T> =
+  | { ok: true; result: T }
+  | { ok: false; error: string; status: number }
+
+export interface ListNotificationsOptions {
+  /** Default: false. When true the response includes already-read rows. */
+  includeRead?: boolean
+  /** Default: server-side cap. Hard upper bound is 200. */
+  pageSize?: number
+}
+
+function failure(error: string, status: number): { ok: false; error: string; status: number } {
+  return { ok: false, error, status }
+}
+
+function envelope<T>(res: {
+  data?: unknown
+  error?: string
+  status: number
+}): NotificationOutcome<T> {
+  if (res.error || res.data === undefined) {
+    return failure(res.error ?? `Request failed (${res.status})`, res.status)
+  }
+  return { ok: true, result: res.data as T }
+}
+
+function buildQuery(opts: ListNotificationsOptions = {}): string {
+  const params = new URLSearchParams()
+  if (opts.includeRead) params.set('includeRead', 'true')
+  if (opts.pageSize !== undefined) params.set('pageSize', String(opts.pageSize))
+  const qs = params.toString()
+  return qs ? `?${qs}` : ''
+}
+
+export async function listNotifications(
+  opts: ListNotificationsOptions = {},
+): Promise<NotificationOutcome<Notification[]>> {
+  const res = await cmsApi<Notification[]>(`/notifications${buildQuery(opts)}`, {
+    method: 'GET',
+  })
+  return envelope<Notification[]>(res)
+}
+
+export async function unreadCount(): Promise<NotificationOutcome<number>> {
+  const res = await cmsApi<{ count: number }>(`/notifications/unread-count`, {
+    method: 'GET',
+  })
+  if (res.error || !res.data) {
+    return failure(res.error ?? `Request failed (${res.status})`, res.status)
+  }
+  return { ok: true, result: res.data.count }
+}
+
+export async function markNotificationRead(id: string): Promise<NotificationOutcome<Notification>> {
+  if (!id) return failure('notification id is required', 0)
+  const res = await cmsApi<Notification>(`/notifications/${encodeURIComponent(id)}/read`, {
+    method: 'POST',
+    body: '{}',
+  })
+  return envelope<Notification>(res)
+}
+
+export async function markAllNotificationsRead(): Promise<NotificationOutcome<number>> {
+  const res = await cmsApi<{ count: number }>(`/notifications/read-all`, {
+    method: 'POST',
+    body: '{}',
+  })
+  if (res.error || !res.data) {
+    return failure(res.error ?? `Request failed (${res.status})`, res.status)
+  }
+  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
+ * per row. Falls back to `Notification` when an unknown kind sneaks in
+ * (defensive against future server-side additions).
+ */
+export function notificationSummary(notification: Notification): string {
+  const actor = notification.payload.actorName ?? 'Someone'
+  switch (notification.payload.kind) {
+    case 'comment_reply':
+      return `${actor} replied: "${notification.payload.excerpt}"`
+    case 'comment_resolved':
+      return `${actor} resolved your thread: "${notification.payload.rootExcerpt}"`
+    case 'comment_mention':
+      return `${actor} mentioned you: "${notification.payload.excerpt}"`
+    default:
+      return 'Notification'
+  }
+}

package/src/lib/slash-command.ts

@@ -0,0 +1,67 @@
+import { COAUTHOR_ACTIONS, isCoauthorAction, type CoauthorAction } from './coauthor-client.js'
+
+/**
+ * Cmd+K slash-command parsing for the AI co-author.
+ *
+ * Recognized syntax (case-insensitive, leading whitespace tolerated):
+ *
+ *     /ai <action> [text...]
+ *
+ * `<action>` is one of `COAUTHOR_ACTIONS`. `text` is the payload handed to
+ * `/ai/coauthor`; it may be empty while the user is still typing.
+ *
+ * The parser is pure so we can unit-test every edge case (case folding,
+ * trailing whitespace, partial input, unknown actions) without spinning up
+ * `cmdk` or the rest of the palette.
+ */
+
+export interface AiSlashCommand {
+  action: CoauthorAction
+  text: string
+}
+
+const SLASH_HEAD = /^\s*\/\s*ai(?:\s+|$)/i
+
+/**
+ * Returns the matched `{ action, text }` when `input` is a complete
+ * slash command (`/ai rewrite ...`), or `null` otherwise. `text` may be
+ * empty when the user has typed `/ai rewrite` with no payload yet.
+ */
+export function parseAiSlashCommand(input: string): AiSlashCommand | null {
+  if (typeof input !== 'string') return null
+  if (!SLASH_HEAD.test(input)) return null
+  const after = input.replace(SLASH_HEAD, '')
+  if (after.length === 0) return null
+
+  const firstWhitespace = after.search(/\s/)
+  const head = (firstWhitespace === -1 ? after : after.slice(0, firstWhitespace)).toLowerCase()
+  if (!isCoauthorAction(head)) return null
+
+  const tail = firstWhitespace === -1 ? '' : after.slice(firstWhitespace + 1)
+  return { action: head, text: tail.trim() }
+}
+
+/**
+ * Returns true when `input` looks like the start of an AI slash command
+ * — even when the action isn't typed yet (`/`, `/a`, `/ai`, `/ai re`).
+ * The palette uses this to switch into "AI mode" (hide nav results,
+ * show the four action suggestions).
+ */
+export function isAiSlashCommandInput(input: string): boolean {
+  if (typeof input !== 'string') return false
+  const trimmed = input.trim()
+  if (trimmed.length === 0) return false
+  if (trimmed === '/') return true
+  return /^\/\s*a(i\b|i?[a-z]*|)?(\s.*)?$/i.test(trimmed)
+}
+
+/**
+ * Ordered list of actions to show in AI mode. When the user has typed a
+ * valid command, that command's action is hoisted to the top so it gets
+ * the default keyboard focus (and Enter runs it).
+ */
+export function orderedAiActions(input: string): CoauthorAction[] {
+  const parsed = parseAiSlashCommand(input)
+  if (!parsed) return [...COAUTHOR_ACTIONS]
+  return [parsed.action, ...COAUTHOR_ACTIONS.filter((a) => a !== parsed.action)]
+}