@actuate-media/cms-admin 0.15.0 → 0.16.0

package/src/lib/post-editor-service.ts

@@ -0,0 +1,342 @@
+/**
+ * Post Editor service — data layer for the flat, section-based Post editor
+ * (`/posts/:type/:id/edit`) and the per-type Post Template editor
+ * (`/posts/types/:slug/template`).
+ *
+ * A post is a document in its post-type collection (e.g. `blog`). The editor
+ * reads/writes the post's fields (title, slug, excerpt, featured image,
+ * body, SEO) plus a `data.sections` JSON list of `PageSection`s — the same
+ * flat model the Page Editor uses. New posts inherit their section list from
+ * the post type's template.
+ *
+ * A template is a single document per post type in the hidden
+ * `post-templates` collection, matched by `slug` == the post-type slug. It
+ * stores the design-driven header layout (`data.header`) and the default
+ * section list (`data.sections`).
+ *
+ * Persistence reuses the existing collection document API, so there is no
+ * new endpoint and no Prisma migration — `sections` is declared as `json`
+ * on each post-type collection (and `header`/`sections` on `post-templates`)
+ * so the field-access layer doesn't strip them on write.
+ */
+import { cmsApi } from './api.js'
+import {
+  getSectionType,
+  createSection,
+  addSection,
+  removeSection,
+  duplicateSection,
+  toggleSectionVisibility,
+  moveSection,
+  reorderSections,
+  updateSectionContent,
+  updateSectionSettings,
+  updateSectionMeta,
+  coerceSections,
+  coercePostHeader,
+  defaultPostHeader,
+  validateSectionContent,
+  type PageSection,
+  type PostHeaderConfig,
+} from '@actuate-media/cms-core/page-sections'
+
+export type { PageSection, PostHeaderConfig } from '@actuate-media/cms-core/page-sections'
+
+// Re-export the pure section helpers so the post editor imports them from
+// one place (mirrors page-editor-service).
+export {
+  createSection,
+  addSection,
+  removeSection,
+  duplicateSection,
+  toggleSectionVisibility,
+  moveSection,
+  reorderSections,
+  updateSectionContent,
+  updateSectionSettings,
+  updateSectionMeta,
+}
+
+export type PostStatus = 'DRAFT' | 'PUBLISHED' | 'SCHEDULED' | 'ARCHIVED'
+
+export const TEMPLATES_COLLECTION = 'post-templates'
+
+export interface EditorPost {
+  id: string | null
+  /** the post-type collection slug (e.g. "blog") */
+  postType: string
+  title: string
+  slug: string
+  excerpt: string
+  featuredImage: string
+  body: string
+  category: string
+  status: PostStatus
+  publishDate: string | null
+  sections: PageSection[]
+  seoTitle: string
+  seoDescription: string
+  publishedAt: string | null
+  updatedAt: string | null
+}
+
+export interface EditorPostTemplate {
+  /** template document id (null when the type has no saved template yet) */
+  docId: string | null
+  postType: string
+  header: PostHeaderConfig
+  sections: PageSection[]
+}
+
+export interface ValidationResult {
+  errors: string[]
+  warnings: string[]
+}
+
+// ─── Validation ──────────────────────────────────────────────────────
+
+function isBlank(v: unknown): boolean {
+  return v === undefined || v === null || (typeof v === 'string' && v.trim() === '')
+}
+
+/**
+ * Validate a post for save/publish. Section rules are delegated to the
+ * shared `validateSectionContent` so the editor and the server/MCP enforce
+ * identical content rules; post-level rules (title/slug, SEO) live here.
+ */
+export function validatePost(post: EditorPost, forPublish = false): ValidationResult {
+  const errors: string[] = []
+  const warnings: string[] = []
+
+  if (isBlank(post.title)) errors.push('Post title is required.')
+  if (isBlank(post.slug)) errors.push('Post slug is required.')
+
+  if (forPublish) {
+    const visible = post.sections.filter((s) => s.visible)
+    for (const section of visible) {
+      const def = getSectionType(section.sectionType)
+      const label = section.name || def?.name || 'Section'
+      const result = validateSectionContent(section.sectionType, section.content, section.settings)
+      for (const issue of result.errors) errors.push(`${label}: ${issue.message}`)
+      for (const issue of result.warnings) warnings.push(`${label}: ${issue.message}`)
+    }
+    if (isBlank(post.seoTitle)) warnings.push('Add an SEO title to improve search results.')
+    if (isBlank(post.seoDescription)) {
+      warnings.push('Add an SEO description to improve search results.')
+    }
+  }
+
+  return { errors, warnings }
+}
+
+/** Validate a template for save (section content only — no post fields). */
+export function validateTemplate(template: EditorPostTemplate): ValidationResult {
+  const errors: string[] = []
+  const warnings: string[] = []
+  for (const section of template.sections.filter((s) => s.visible)) {
+    const def = getSectionType(section.sectionType)
+    const label = section.name || def?.name || 'Section'
+    const result = validateSectionContent(section.sectionType, section.content, section.settings)
+    for (const issue of result.errors) errors.push(`${label}: ${issue.message}`)
+    for (const issue of result.warnings) warnings.push(`${label}: ${issue.message}`)
+  }
+  return { errors, warnings }
+}
+
+// ─── API row mapping ─────────────────────────────────────────────────
+
+interface DocumentApiRow {
+  id: string
+  collection?: string
+  title: string | null
+  slug: string | null
+  status: PostStatus
+  publishedAt: string | null
+  scheduledAt?: string | null
+  updatedAt: string | null
+  data: Record<string, unknown> | null
+}
+
+function dataStr(data: Record<string, unknown>, key: string): string {
+  const v = data[key]
+  return typeof v === 'string' ? v : ''
+}
+
+function rowToEditorPost(postType: string, doc: DocumentApiRow): EditorPost {
+  const data = doc.data ?? {}
+  return {
+    id: doc.id,
+    postType,
+    title: doc.title ?? dataStr(data, 'title'),
+    slug: doc.slug ?? dataStr(data, 'slug'),
+    excerpt: dataStr(data, 'excerpt'),
+    featuredImage: dataStr(data, 'featuredImage'),
+    body: dataStr(data, 'body'),
+    category: dataStr(data, 'category'),
+    status: doc.status ?? 'DRAFT',
+    publishDate: (data.publishDate as string) ?? doc.scheduledAt ?? null,
+    sections: coerceSections(data.sections),
+    seoTitle: dataStr(data, 'metaTitle'),
+    seoDescription: dataStr(data, 'metaDescription'),
+    publishedAt: doc.publishedAt ?? null,
+    updatedAt: doc.updatedAt ?? null,
+  }
+}
+
+// ─── Templates ───────────────────────────────────────────────────────
+
+interface ListEnvelope {
+  docs: DocumentApiRow[]
+  total: number
+}
+
+/**
+ * Load a post type's template. Looks up the single `post-templates` document
+ * whose slug matches the post type. Returns an unsaved default (centered
+ * header, empty section list) when the type has no template yet.
+ */
+export async function fetchTemplateForEditor(postType: string): Promise<EditorPostTemplate> {
+  const res = await cmsApi<ListEnvelope>(`/collections/${TEMPLATES_COLLECTION}?pageSize=200`)
+  const docs = res.data?.docs ?? []
+  const match = docs.find((d) => (d.slug ?? d.data?.slug) === postType)
+  if (!match) {
+    return { docId: null, postType, header: defaultPostHeader(), sections: [] }
+  }
+  const data = match.data ?? {}
+  return {
+    docId: match.id,
+    postType,
+    header: coercePostHeader(data.header),
+    sections: coerceSections(data.sections),
+  }
+}
+
+function templateWriteBody(template: EditorPostTemplate, extra?: Record<string, unknown>): string {
+  return JSON.stringify({
+    title: `${template.postType} template`,
+    slug: template.postType,
+    postType: template.postType,
+    header: template.header,
+    sections: template.sections,
+    ...extra,
+  })
+}
+
+/** Persist a post type's template (creates the doc on first save). */
+export async function saveTemplate(template: EditorPostTemplate): Promise<EditorPostTemplate> {
+  const endpoint = template.docId
+    ? `/collections/${TEMPLATES_COLLECTION}/${template.docId}`
+    : `/collections/${TEMPLATES_COLLECTION}`
+  const res = await cmsApi<DocumentApiRow>(endpoint, {
+    method: template.docId ? 'PUT' : 'POST',
+    body: templateWriteBody(template, { status: 'PUBLISHED' }),
+  })
+  if (res.error || !res.data) throw new Error(res.error ?? 'Failed to save template')
+  const data = res.data.data ?? {}
+  return {
+    docId: res.data.id,
+    postType: template.postType,
+    header: coercePostHeader(data.header),
+    sections: coerceSections(data.sections),
+  }
+}
+
+// ─── Posts ───────────────────────────────────────────────────────────
+
+export async function fetchPostForEditor(postType: string, id: string): Promise<EditorPost> {
+  const res = await cmsApi<DocumentApiRow>(`/collections/${encodeURIComponent(postType)}/${id}`)
+  if (res.error || !res.data) throw new Error(res.error ?? 'Failed to load post')
+  return rowToEditorPost(postType, res.data)
+}
+
+interface PostWritePayload {
+  title: string
+  slug: string
+  excerpt: string
+  featuredImage: string
+  body: string
+  category: string
+  publishDate: string | null
+  sections: PageSection[]
+  metaTitle: string
+  metaDescription: string
+}
+
+function toWriteBody(post: EditorPost, extra?: Record<string, unknown>): string {
+  const payload: PostWritePayload & Record<string, unknown> = {
+    title: post.title,
+    slug: post.slug,
+    excerpt: post.excerpt,
+    featuredImage: post.featuredImage,
+    body: post.body,
+    category: post.category,
+    publishDate: post.publishDate,
+    sections: post.sections,
+    metaTitle: post.seoTitle,
+    metaDescription: post.seoDescription,
+    ...extra,
+  }
+  return JSON.stringify(payload)
+}
+
+export async function createPost(post: EditorPost): Promise<EditorPost> {
+  const res = await cmsApi<DocumentApiRow>(`/collections/${encodeURIComponent(post.postType)}`, {
+    method: 'POST',
+    body: toWriteBody(post),
+  })
+  if (res.error || !res.data) throw new Error(res.error ?? 'Failed to create post')
+  return rowToEditorPost(post.postType, res.data)
+}
+
+export async function savePostDraft(post: EditorPost): Promise<EditorPost> {
+  if (!post.id) return createPost(post)
+  const res = await cmsApi<DocumentApiRow>(
+    `/collections/${encodeURIComponent(post.postType)}/${post.id}`,
+    { method: 'PUT', body: toWriteBody(post) },
+  )
+  if (res.error || !res.data) throw new Error(res.error ?? 'Failed to save draft')
+  return rowToEditorPost(post.postType, res.data)
+}
+
+export async function publishPost(post: EditorPost): Promise<EditorPost> {
+  const endpoint = post.id
+    ? `/collections/${encodeURIComponent(post.postType)}/${post.id}`
+    : `/collections/${encodeURIComponent(post.postType)}`
+  const res = await cmsApi<DocumentApiRow>(endpoint, {
+    method: post.id ? 'PUT' : 'POST',
+    body: toWriteBody(post, { status: 'PUBLISHED' }),
+  })
+  if (res.error || !res.data) throw new Error(res.error ?? 'Failed to publish post')
+  return rowToEditorPost(post.postType, res.data)
+}
+
+/** A blank post scaffold seeded with the post type's template sections. */
+export async function emptyPostFromTemplate(postType: string): Promise<EditorPost> {
+  let sections: PageSection[] = []
+  try {
+    const template = await fetchTemplateForEditor(postType)
+    // Clone with fresh ids so the post owns its own sections, decoupled from
+    // the template (editing the post never mutates the type template).
+    sections = template.sections.map((s) => ({ ...s, id: createSection(s.sectionType).id }))
+  } catch {
+    // No template / fetch failure → start from an empty section list.
+    sections = []
+  }
+  return {
+    id: null,
+    postType,
+    title: '',
+    slug: '',
+    excerpt: '',
+    featuredImage: '',
+    body: '',
+    category: '',
+    status: 'DRAFT',
+    publishDate: null,
+    sections,
+    seoTitle: '',
+    seoDescription: '',
+    publishedAt: null,
+    updatedAt: null,
+  }
+}

package/src/lib/posts-service.ts

@@ -0,0 +1,366 @@
+/**
+ * Posts service — thin client over the existing REST endpoints,
+ * shaped around the data the Posts admin area needs.
+ *
+ * V1 strategy: aggregate across post-typed collections client-side
+ * (one `/collections/:slug` call per type) and join authors via
+ * `/users`. Each view component pulls from `fetchPosts()` so when
+ * a server-side `/api/cms/posts` endpoint lands later, only this
+ * file changes — callers consume the same `Post[]` / `PostType[]`
+ * shapes.
+ *
+ * Why not a single `/collections/all` call?
+ *   - Each collection has its own access-control check, so listing
+ *     across collections must respect per-collection `read` rules.
+ *     The existing endpoint enforces this per-call; mixing them
+ *     server-side would need a new auth boundary.
+ *   - V1 traffic is small (the seed is 15 rows); a few extra
+ *     parallel requests are well under the rate-limit budget.
+ *
+ * Promote to a single endpoint when:
+ *   - Any post-type collection grows past ~5k rows, OR
+ *   - Page-load latency exceeds 300ms in the admin metrics.
+ */
+import { cmsApi } from './api.js'
+
+export type PostStatus = 'DRAFT' | 'PUBLISHED' | 'SCHEDULED' | 'ARCHIVED'
+
+export interface PostType {
+  id: string // == slug
+  slug: string
+  name: string // plural label
+  singularName: string
+  description: string | null
+  urlBase: string
+  accentColor: string | null
+  icon: string | null
+  postCount: number
+  fieldCount: number
+  active: boolean
+}
+
+export interface PostAuthor {
+  id: string
+  name: string
+  initials: string
+}
+
+export interface Post {
+  id: string
+  title: string
+  slug: string
+  postTypeId: string
+  postTypeName: string
+  postTypeAccentColor: string | null
+  authorId: string
+  authorName: string
+  authorInitials: string
+  status: PostStatus
+  publishDate: string | null
+  updatedDate: string
+  seoScore: number | null
+  createdAt: string
+  updatedAt: string
+}
+
+export interface PostsQuery {
+  search?: string
+  postType?: string | 'all'
+  status?: PostStatus | 'all'
+  author?: string | 'all'
+  sortBy?: 'title' | 'type' | 'author' | 'status' | 'date' | 'seo'
+  sortDirection?: 'asc' | 'desc'
+  page?: number
+  pageSize?: number
+}
+
+export interface PostsResult {
+  posts: Post[]
+  total: number
+  page: number
+  pageSize: number
+  types: PostType[]
+  authors: PostAuthor[]
+}
+
+// ─── Collections → Post Types ────────────────────────────────────────
+
+interface CollectionApiRow {
+  slug: string
+  labels: { singular: string; plural: string }
+  type: string
+  urlPrefix: string
+  description: string | null
+  icon: string | null
+  color: string | null
+  group: string | null
+  hidden: boolean
+  fieldCount: number
+}
+
+function isPostsCollection(c: CollectionApiRow): boolean {
+  return c.type === 'post' || (typeof c.group === 'string' && c.group.toLowerCase() === 'posts')
+}
+
+async function fetchPostCollections(): Promise<CollectionApiRow[]> {
+  const res = await cmsApi<CollectionApiRow[]>('/collections')
+  if (res.error || !res.data) return []
+  return res.data.filter((c) => !c.hidden && isPostsCollection(c))
+}
+
+export async function fetchPostTypes(): Promise<PostType[]> {
+  const cols = await fetchPostCollections()
+  // Counts are filled in by `fetchPosts` so the cards / tabs reflect
+  // the same numbers users see in the table. When called from a page
+  // that doesn't load posts (the New Post picker), the count stays
+  // at 0 until the next fetchPosts call.
+  return cols.map(collectionToPostType)
+}
+
+function collectionToPostType(c: CollectionApiRow, count = 0): PostType {
+  return {
+    id: c.slug,
+    slug: c.slug,
+    name: c.labels.plural,
+    singularName: c.labels.singular,
+    description: c.description ?? null,
+    urlBase: `/${c.urlPrefix || c.slug}`,
+    accentColor: c.color ?? null,
+    icon: c.icon ?? null,
+    postCount: count,
+    fieldCount: c.fieldCount,
+    active: true,
+  }
+}
+
+// ─── Users → Authors ─────────────────────────────────────────────────
+
+interface UserApiRow {
+  id: string
+  name?: string | null
+  email: string
+}
+
+function initialsFromName(name: string | null | undefined, email: string): string {
+  if (name && name.trim().length > 0) {
+    const parts = name.trim().split(/\s+/)
+    const first = parts[0]?.[0] ?? ''
+    const last = parts.length > 1 ? (parts[parts.length - 1]?.[0] ?? '') : ''
+    return (first + last).toUpperCase() || (email[0] ?? '?').toUpperCase()
+  }
+  return (email[0] ?? '?').toUpperCase()
+}
+
+async function fetchAuthorsMap(): Promise<Map<string, PostAuthor>> {
+  const res = await cmsApi<{ users: UserApiRow[] } | UserApiRow[]>('/users?pageSize=200')
+  const list: UserApiRow[] = Array.isArray(res.data)
+    ? res.data
+    : ((res.data as { users?: UserApiRow[] } | null)?.users ?? [])
+  const map = new Map<string, PostAuthor>()
+  for (const u of list) {
+    map.set(u.id, {
+      id: u.id,
+      name: u.name?.trim() || u.email,
+      initials: initialsFromName(u.name, u.email),
+    })
+  }
+  return map
+}
+
+// ─── Posts ───────────────────────────────────────────────────────────
+
+interface DocumentApiRow {
+  id: string
+  collection: string
+  title: string | null
+  slug: string | null
+  status: PostStatus
+  createdById: string | null
+  updatedById: string | null
+  publishedAt: string | null
+  scheduledAt: string | null
+  createdAt: string
+  updatedAt: string
+  data: Record<string, unknown> | null
+}
+
+function extractSeoScore(data: Record<string, unknown> | null): number | null {
+  if (!data) return null
+  const candidates = ['seoScore', 'seo_score', 'metaScore']
+  for (const k of candidates) {
+    const v = data[k]
+    if (typeof v === 'number' && Number.isFinite(v)) return v
+  }
+  return null
+}
+
+function pickDisplayDate(d: DocumentApiRow): string {
+  if (d.status === 'SCHEDULED' && d.scheduledAt) return d.scheduledAt
+  if (d.status === 'PUBLISHED' && d.publishedAt) return d.publishedAt
+  return d.updatedAt
+}
+
+interface ListEnvelope {
+  docs: DocumentApiRow[]
+  total: number
+}
+
+export async function fetchPosts(query: PostsQuery = {}): Promise<PostsResult> {
+  const cols = await fetchPostCollections()
+  const authorsMap = await fetchAuthorsMap()
+
+  // Pull every doc for each post type (cap at 500 to avoid runaway
+  // requests; pagination + filtering still happens client-side over
+  // this set). When a type grows past 500 docs we'll need the
+  // server-side aggregate endpoint described in this file's header.
+  const perTypeRaw = await Promise.all(
+    cols.map(async (c) => {
+      const res = await cmsApi<ListEnvelope>(
+        `/collections/${encodeURIComponent(c.slug)}?pageSize=500&sort=updatedAt&order=desc`,
+      )
+      const docs = (res.data?.docs ?? []) as DocumentApiRow[]
+      return { col: c, docs }
+    }),
+  )
+
+  // Map docs → Post objects.
+  const allPosts: Post[] = []
+  for (const { col, docs } of perTypeRaw) {
+    for (const d of docs) {
+      const author = (d.createdById && authorsMap.get(d.createdById)) ||
+        (d.updatedById && authorsMap.get(d.updatedById)) || {
+          id: '',
+          name: 'Unknown',
+          initials: '??',
+        }
+      allPosts.push({
+        id: d.id,
+        title: d.title ?? (d.data?.title as string) ?? '(untitled)',
+        slug: d.slug ?? (d.data?.slug as string) ?? '',
+        postTypeId: col.slug,
+        postTypeName: col.labels.singular,
+        postTypeAccentColor: col.color ?? null,
+        authorId: author.id,
+        authorName: author.name,
+        authorInitials: author.initials,
+        status: d.status,
+        publishDate: d.publishedAt ?? d.scheduledAt ?? null,
+        updatedDate: pickDisplayDate(d),
+        seoScore: extractSeoScore(d.data),
+        createdAt: d.createdAt,
+        updatedAt: d.updatedAt,
+      })
+    }
+  }
+
+  // Compute per-type counts BEFORE filtering — the tabs at the top
+  // of the page reflect the dataset, not the active query.
+  const countsBySlug = new Map<string, number>()
+  for (const p of allPosts) {
+    countsBySlug.set(p.postTypeId, (countsBySlug.get(p.postTypeId) ?? 0) + 1)
+  }
+  const types: PostType[] = cols.map((c) => collectionToPostType(c, countsBySlug.get(c.slug) ?? 0))
+
+  // Apply filters / search.
+  const search = (query.search ?? '').trim().toLowerCase()
+  const filtered = allPosts.filter((p) => {
+    if (query.postType && query.postType !== 'all' && p.postTypeId !== query.postType) return false
+    if (query.status && query.status !== 'all' && p.status !== query.status) return false
+    if (query.author && query.author !== 'all' && p.authorId !== query.author) return false
+    if (search) {
+      const haystack = `${p.title} ${p.slug} ${p.authorName} ${p.postTypeName}`.toLowerCase()
+      if (!haystack.includes(search)) return false
+    }
+    return true
+  })
+
+  // Sort.
+  const sortBy = query.sortBy ?? 'date'
+  const dir = query.sortDirection ?? 'desc'
+  filtered.sort((a, b) => {
+    const cmp = comparePostsFor(sortBy, a, b)
+    return dir === 'asc' ? cmp : -cmp
+  })
+
+  // Paginate.
+  const page = Math.max(1, query.page ?? 1)
+  const pageSize = Math.max(1, query.pageSize ?? 10)
+  const start = (page - 1) * pageSize
+  const paged = filtered.slice(start, start + pageSize)
+
+  // Unique authors from the full set (so the dropdown lists every
+  // contributor, not just the currently visible page).
+  const authorIds = new Set<string>()
+  const authors: PostAuthor[] = []
+  for (const p of allPosts) {
+    if (p.authorId && !authorIds.has(p.authorId)) {
+      authorIds.add(p.authorId)
+      authors.push({ id: p.authorId, name: p.authorName, initials: p.authorInitials })
+    }
+  }
+  authors.sort((a, b) => a.name.localeCompare(b.name))
+
+  return {
+    posts: paged,
+    total: filtered.length,
+    page,
+    pageSize,
+    types,
+    authors,
+  }
+}
+
+function comparePostsFor(by: NonNullable<PostsQuery['sortBy']>, a: Post, b: Post): number {
+  switch (by) {
+    case 'title':
+      return a.title.localeCompare(b.title)
+    case 'type':
+      return a.postTypeName.localeCompare(b.postTypeName)
+    case 'author':
+      return a.authorName.localeCompare(b.authorName)
+    case 'status':
+      return a.status.localeCompare(b.status)
+    case 'seo': {
+      const av = a.seoScore ?? -1
+      const bv = b.seoScore ?? -1
+      return av - bv
+    }
+    case 'date':
+    default:
+      return new Date(a.updatedDate).getTime() - new Date(b.updatedDate).getTime()
+  }
+}
+
+// ─── Bulk mutations ──────────────────────────────────────────────────
+
+export async function bulkUpdatePosts(
+  ids: Array<{ postTypeId: string; id: string }>,
+  payload: { status?: PostStatus },
+): Promise<{ ok: number; failed: number }> {
+  let ok = 0
+  let failed = 0
+  for (const { postTypeId, id } of ids) {
+    const res = await cmsApi(`/collections/${encodeURIComponent(postTypeId)}/${id}`, {
+      method: 'PUT',
+      body: JSON.stringify(payload),
+    })
+    if (res.error) failed++
+    else ok++
+  }
+  return { ok, failed }
+}
+
+export async function bulkDeletePosts(
+  ids: Array<{ postTypeId: string; id: string }>,
+): Promise<{ ok: number; failed: number }> {
+  let ok = 0
+  let failed = 0
+  for (const { postTypeId, id } of ids) {
+    const res = await cmsApi(`/collections/${encodeURIComponent(postTypeId)}/${id}`, {
+      method: 'DELETE',
+    })
+    if (res.error) failed++
+    else ok++
+  }
+  return { ok, failed }
+}