@actuate-media/cms-admin 0.15.0 → 0.16.1

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

@@ -0,0 +1,233 @@
+/**
+ * Page Editor service — data layer for the flat, section-based page
+ * editor (`/pages/:id/edit`).
+ *
+ * A page is a document in the `pages` collection. The editor reads and
+ * writes a single JSON field, `data.sections`, holding an ordered list of
+ * `PageSection`s. Save draft = `PUT` the sections (+ title/slug/SEO) with
+ * no status change; publish = the same payload plus `status: 'PUBLISHED'`.
+ *
+ * Persistence reuses the existing collection document API, so there is no
+ * new endpoint and no Prisma migration — `sections` is declared as a
+ * `type: 'json'` field on the `pages` collection so the field-access layer
+ * doesn't strip it on write.
+ *
+ * The section mutation helpers (`addSection`, `moveSection`, …) are pure
+ * functions over `PageSection[]` so the editor state and the unit tests
+ * share one implementation.
+ */
+import { cmsApi } from './api.js'
+import {
+  getSectionType,
+  createSection,
+  addSection,
+  removeSection,
+  duplicateSection,
+  toggleSectionVisibility,
+  moveSection,
+  reorderSections,
+  updateSectionContent,
+  updateSectionSettings,
+  updateSectionMeta,
+  coerceSections as coerceSectionsCore,
+  validateSectionContent,
+  type PageSection,
+} from '@actuate-media/cms-core/page-sections'
+
+export type { PageSection } from '@actuate-media/cms-core/page-sections'
+
+// Re-export the pure section helpers so existing editor imports
+// (`../../lib/page-editor-service.js`) keep working after the move to core.
+export {
+  createSection,
+  addSection,
+  removeSection,
+  duplicateSection,
+  toggleSectionVisibility,
+  moveSection,
+  reorderSections,
+  updateSectionContent,
+  updateSectionSettings,
+  updateSectionMeta,
+}
+
+export type PageStatus = 'DRAFT' | 'PUBLISHED' | 'SCHEDULED' | 'ARCHIVED'
+
+export const PAGES_COLLECTION = 'pages'
+
+export interface EditorPage {
+  id: string | null
+  title: string
+  slug: string
+  path: string
+  status: PageStatus
+  sections: PageSection[]
+  seoTitle: string
+  seoDescription: string
+  publishedAt: string | null
+  updatedAt: string | null
+}
+
+export interface ValidationResult {
+  /** blocking issues — publish is disabled while any exist */
+  errors: string[]
+  /** non-blocking advisories (e.g. SEO) */
+  warnings: string[]
+}
+
+// ─── Validation ──────────────────────────────────────────────────────
+
+function isBlank(v: unknown): boolean {
+  return v === undefined || v === null || (typeof v === 'string' && v.trim() === '')
+}
+
+/**
+ * Validate a page for save/publish. `forPublish` turns on the stricter
+ * rules (at least one visible section, required section fields, valid
+ * button URLs, image alt text). SEO gaps are surfaced as warnings.
+ *
+ * Per-section rules are delegated to the shared `validateSectionContent`
+ * in `@actuate-media/cms-core/page-sections`, so the editor and the
+ * server/MCP enforce identical content rules. Page-level rules
+ * (title/path, "at least one visible section", SEO) stay here because
+ * they operate on the whole `EditorPage`.
+ */
+export function validatePage(page: EditorPage, forPublish = false): ValidationResult {
+  const errors: string[] = []
+  const warnings: string[] = []
+
+  if (isBlank(page.title)) errors.push('Page title is required.')
+  if (isBlank(page.path)) errors.push('Page path is required.')
+
+  if (forPublish) {
+    const visible = page.sections.filter((s) => s.visible)
+    if (visible.length === 0) {
+      errors.push('Add at least one visible section before publishing.')
+    }
+
+    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}`)
+      }
+    }
+
+    if (isBlank(page.seoTitle)) warnings.push('Add an SEO title to improve search results.')
+    if (isBlank(page.seoDescription)) {
+      warnings.push('Add an SEO description to improve search results.')
+    }
+  }
+
+  return { errors, warnings }
+}
+
+// ─── API row mapping ─────────────────────────────────────────────────
+
+interface DocumentApiRow {
+  id: string
+  title: string | null
+  slug: string | null
+  status: PageStatus
+  publishedAt: string | null
+  updatedAt: string | null
+  data: Record<string, unknown> | null
+}
+
+function rowToEditorPage(doc: DocumentApiRow): EditorPage {
+  const data = doc.data ?? {}
+  const slug = doc.slug ?? ''
+  return {
+    id: doc.id,
+    title: doc.title ?? '',
+    slug,
+    path: typeof data.path === 'string' && data.path ? data.path : slug ? `/${slug}` : '/',
+    status: doc.status ?? 'DRAFT',
+    sections: coerceSectionsCore(data.sections),
+    seoTitle: typeof data.metaTitle === 'string' ? data.metaTitle : '',
+    seoDescription: typeof data.metaDescription === 'string' ? data.metaDescription : '',
+    publishedAt: doc.publishedAt ?? null,
+    updatedAt: doc.updatedAt ?? null,
+  }
+}
+
+// ─── API calls ───────────────────────────────────────────────────────
+
+export async function fetchPageForEditor(pageId: string): Promise<EditorPage> {
+  const res = await cmsApi<DocumentApiRow>(`/collections/${PAGES_COLLECTION}/${pageId}`)
+  if (res.error || !res.data) throw new Error(res.error ?? 'Failed to load page')
+  return rowToEditorPage(res.data)
+}
+
+interface PageWritePayload {
+  title: string
+  slug: string
+  path: string
+  sections: PageSection[]
+  metaTitle: string
+  metaDescription: string
+}
+
+function toWriteBody(page: EditorPage, extra?: Record<string, unknown>): string {
+  const payload: PageWritePayload & Record<string, unknown> = {
+    title: page.title,
+    slug: page.slug,
+    path: page.path,
+    sections: page.sections,
+    metaTitle: page.seoTitle,
+    metaDescription: page.seoDescription,
+    ...extra,
+  }
+  return JSON.stringify(payload)
+}
+
+/** Create a new page document, returning the new id. */
+export async function createPage(page: EditorPage): Promise<EditorPage> {
+  const res = await cmsApi<DocumentApiRow>(`/collections/${PAGES_COLLECTION}`, {
+    method: 'POST',
+    body: toWriteBody(page),
+  })
+  if (res.error || !res.data) throw new Error(res.error ?? 'Failed to create page')
+  return rowToEditorPage(res.data)
+}
+
+/** Save the current draft (no status change). */
+export async function savePageDraft(page: EditorPage): Promise<EditorPage> {
+  if (!page.id) return createPage(page)
+  const res = await cmsApi<DocumentApiRow>(`/collections/${PAGES_COLLECTION}/${page.id}`, {
+    method: 'PUT',
+    body: toWriteBody(page),
+  })
+  if (res.error || !res.data) throw new Error(res.error ?? 'Failed to save draft')
+  return rowToEditorPage(res.data)
+}
+
+/** Publish: persist the latest content and flip status to PUBLISHED. */
+export async function publishPage(page: EditorPage): Promise<EditorPage> {
+  const endpoint = page.id
+    ? `/collections/${PAGES_COLLECTION}/${page.id}`
+    : `/collections/${PAGES_COLLECTION}`
+  const res = await cmsApi<DocumentApiRow>(endpoint, {
+    method: page.id ? 'PUT' : 'POST',
+    body: toWriteBody(page, { status: 'PUBLISHED' }),
+  })
+  if (res.error || !res.data) throw new Error(res.error ?? 'Failed to publish page')
+  return rowToEditorPage(res.data)
+}
+
+/** A blank page scaffold for `/pages/new`. */
+export function emptyPage(): EditorPage {
+  return {
+    id: null,
+    title: '',
+    slug: '',
+    path: '',
+    status: 'DRAFT',
+    sections: [],
+    seoTitle: '',
+    seoDescription: '',
+    publishedAt: null,
+    updatedAt: null,
+  }
+}