@beechcms/api 0.5.0 → 0.6.0-preview.2

package/src/features/draft/draft.handler.ts

@@ -1,170 +1,195 @@
-/// <reference types="@cloudflare/workers-types" />
-import { Context, Hono } from 'hono'
-import { 
-  validateAndSanitizeSeedPayload, 
-  resolvePolicies 
-} from '@beechcms/core'
-import { publicProblem } from '../../public/problem-details'
-import { cleanStr } from '../../shared/query-utils'
-import { applyVisibility } from '../../shared/apply-policies'
-import { AppEnv } from '../../types'
-import { CONTENT_ERRORS } from '../content/constants'
-import { draftGuard } from './draft.middleware'
-
-const draftApp = new Hono<AppEnv>()
-
-
-function normalizeBody(raw: unknown): Record<string, unknown> {
-  return typeof raw === 'object' && raw !== null ? (raw as Record<string, unknown>) : {}
-}
-
-function logDraftActivity(
-  context: Context<AppEnv>,
-  id: string,
-  slug: string,
-  title: string,
-  note: 'draft saved' | 'draft published'
-) {
-  const actor = context.get('jwtPayload')
-  context.get('activityLogger').log({
-    action: 'update',
-    entityType: 'content',
-    entityId: id,
-    entitySlug: slug,
-    details: { title, note },
-    actor: {
-      id: actor.sub,
-      email: actor.email ?? 'unknown',
-      name: actor.name ?? null,
-    },
-  })
-}
-
-// PUT /:slug/:id/draft — Creates or overwrites the pending draft
-draftApp.put('/:slug/:id/draft', draftGuard, async (context) => {
-  const slug = context.req.param('slug')
-  const id = context.req.param('id')
-  const seed = context.get('getSeed')(slug)!
-
-  let body: Record<string, unknown>
-  try {
-    body = normalizeBody(await context.req.json<unknown>())
-  } catch {
-    return publicProblem(context, { 
-      type: 'content-invalid-json', 
-      title: 'Bad Request', 
-      status: 400, 
-      detail: CONTENT_ERRORS.INVALID_JSON_BODY 
-    })
-  }
-
-  const sensitiveAliases = Object.keys(body).filter((alias) => {
-    const branch = seed.branches.find((b) => b.alias === alias)
-    return branch != null && resolvePolicies(branch).privacy !== 'plain'
-  })
-  
-  if (sensitiveAliases.length > 0) {
-    return publicProblem(context, { 
-      type: 'content-sensitive-field-edit', 
-      title: 'Unprocessable Entity', 
-      status: 422, 
-      detail: `${CONTENT_ERRORS.SENSITIVE_FIELD_EDIT}: ${sensitiveAliases.join(', ')}` 
-    })
-  }
-
-  const validation = validateAndSanitizeSeedPayload(seed, body, {
-    operation: 'update', 
-    allowNull: true, 
-    requireAtLeastOneValidField: true, 
-    enforceRequiredFields: false,
-  })
-  
-  if (validation.dangerousFields.length > 0) {
-    return publicProblem(context, { 
-      type: 'content-dangerous-content', 
-      title: 'Unprocessable Entity', 
-      status: 422, 
-      detail: `Dangerous markup in field '${validation.dangerousFields[0]}'` 
-    })
-  }
-  
-  if (validation.details.length > 0) {
-    return publicProblem(context, { 
-      type: 'content-validation-failed', 
-      title: 'Bad Request', 
-      status: 400, 
-      detail: 'Validation failed', 
-      errors: validation.details 
-    })
-  }
-
-  const repository = context.get('repository')
-  await repository.saveDraft(seed, id, validation.data)
-
-  const displayTitle = cleanStr(validation.data[seed.displayNameAlias]) ?? id
-  logDraftActivity(context, id, slug, displayTitle, 'draft saved')
-
-  return context.json({ success: true })
-})
-
-// GET /:slug/:id/draft — Retrieves the pending draft
-draftApp.get('/:slug/:id/draft', draftGuard, async (context) => {
-  const slug = context.req.param('slug')
-  const id = context.req.param('id')
-  const seed = context.get('getSeed')(slug)!
-
-  const repository = context.get('repository')
-  const draft = await repository.getDraft(seed, id)
-
-  if (!draft) {
-    return publicProblem(context, { 
-      type: 'draft-not-found', 
-      title: 'Not Found', 
-      status: 404, 
-      detail: 'No pending draft for this entry' 
-    })
-  }
-
-  return context.json({ data: applyVisibility(draft, seed) })
-})
-
-// POST /:slug/:id/draft/publish — Atomically promotes draft to live
-draftApp.post('/:slug/:id/draft/publish', draftGuard, async (context) => {
-  const slug = context.req.param('slug')
-  const id = context.req.param('id')
-  const seed = context.get('getSeed')(slug)!
-
-  const repository = context.get('repository')
-  const draft = await repository.getDraft(seed, id)
-
-  if (!draft) {
-    return publicProblem(context, { 
-      type: 'draft-not-found', 
-      title: 'Not Found', 
-      status: 404, 
-      detail: 'No pending draft to publish' 
-    })
-  }
-
-  await repository.publishDraft(seed, id)
-
-  const displayValue = draft[seed.displayNameAlias]
-  const displayStr = typeof displayValue === 'string' ? displayValue : id
-  logDraftActivity(context, id, slug, displayStr, 'draft published')
-
-  return context.json({ success: true })
-})
-
-// DELETE /:slug/:id/draft — Discards the pending draft
-draftApp.delete('/:slug/:id/draft', draftGuard, async (context) => {
-  const slug = context.req.param('slug')
-  const id = context.req.param('id')
-  const seed = context.get('getSeed')(slug)!
-
-  const repository = context.get('repository')
-  await repository.deleteDraft(seed, id)
-
-  return context.json({ success: true })
-})
-
-export { draftApp }
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+/// <reference types="@cloudflare/workers-types" />
+import { Context, Hono } from 'hono'
+import {
+  validateAndSanitizeSeedPayload,
+  resolvePolicies,
+  RelationTargetNotFoundError,
+} from '@beechcms/core'
+import { publicProblem } from '../../public/problem-details'
+import { cleanStr } from '../../shared/query-utils'
+import { applyVisibility } from '../../shared/apply-policies'
+import { AppEnv } from '../../types'
+import { CONTENT_ERRORS } from '../content/constants'
+import { draftGuard } from './draft.middleware'
+
+const draftApp = new Hono<AppEnv>()
+
+// GET /drafts — Unified list of pending drafts across all draft-enabled seeds.
+draftApp.get('/drafts', async (context) => {
+  const seeds = context.get('seedRegistry').draftEnabled()
+  const repository = context.get('repository')
+  const drafts = await repository.findPendingDrafts(seeds)
+  return context.json(drafts)
+})
+
+function normalizeBody(raw: unknown): Record<string, unknown> {
+  return typeof raw === 'object' && raw !== null ? (raw as Record<string, unknown>) : {}
+}
+
+function logDraftActivity(
+  context: Context<AppEnv>,
+  id: string,
+  slug: string,
+  title: string,
+  note: 'draft saved' | 'draft published'
+) {
+  const actor = context.get('jwtPayload')
+  context.get('activityLogger').log({
+    action: 'update',
+    entityType: 'content',
+    entityId: id,
+    entitySlug: slug,
+    details: { title, note },
+    actor: {
+      id: actor.sub,
+      email: actor.email ?? 'unknown',
+      name: [actor.name, actor.surname].filter(Boolean).join(' ') || null,
+    },
+  })
+}
+
+// PUT /:slug/:id/draft — Creates or overwrites the pending draft
+draftApp.put('/:slug/:id/draft', draftGuard, async (context) => {
+  const slug = context.req.param('slug')
+  const id = context.req.param('id')
+  const seed = context.get('getSeed')(slug)!
+
+  let body: Record<string, unknown>
+  try {
+    body = normalizeBody(await context.req.json<unknown>())
+  } catch {
+    return publicProblem(context, { 
+      type: 'content-invalid-json', 
+      title: 'Bad Request', 
+      status: 400, 
+      detail: CONTENT_ERRORS.INVALID_JSON_BODY 
+    })
+  }
+
+  const sensitiveAliases = Object.keys(body).filter((alias) => {
+    const branch = seed.branches.find((b) => b.alias === alias)
+    return branch != null && resolvePolicies(branch).privacy !== 'plain'
+  })
+  
+  if (sensitiveAliases.length > 0) {
+    return publicProblem(context, { 
+      type: 'content-sensitive-field-edit', 
+      title: 'Unprocessable Entity', 
+      status: 422, 
+      detail: `${CONTENT_ERRORS.SENSITIVE_FIELD_EDIT}: ${sensitiveAliases.join(', ')}` 
+    })
+  }
+
+  const validation = validateAndSanitizeSeedPayload(seed, body, {
+    operation: 'update',
+    allowNull: true,
+    requireAtLeastOneValidField: true,
+    enforceRequiredFields: false,
+    idGenerator: context.get('idGenerator'),
+  })
+  
+  if (validation.dangerousFields.length > 0) {
+    return publicProblem(context, { 
+      type: 'content-dangerous-content', 
+      title: 'Unprocessable Entity', 
+      status: 422, 
+      detail: `Dangerous markup in field '${validation.dangerousFields[0]}'` 
+    })
+  }
+  
+  if (validation.details.length > 0) {
+    return publicProblem(context, { 
+      type: 'content-validation-failed', 
+      title: 'Bad Request', 
+      status: 400, 
+      detail: 'Validation failed', 
+      errors: validation.details 
+    })
+  }
+
+  const repository = context.get('repository')
+  await repository.saveDraft(seed, id, validation.data)
+
+  const displayTitle = cleanStr(validation.data[seed.displayNameAlias]) ?? id
+  logDraftActivity(context, id, slug, displayTitle, 'draft saved')
+
+  return context.json({ success: true })
+})
+
+// GET /:slug/:id/draft — Retrieves the pending draft
+draftApp.get('/:slug/:id/draft', draftGuard, async (context) => {
+  const slug = context.req.param('slug')
+  const id = context.req.param('id')
+  const seed = context.get('getSeed')(slug)!
+
+  const repository = context.get('repository')
+  const draft = await repository.getDraft(seed, id)
+
+  if (!draft) {
+    return publicProblem(context, { 
+      type: 'draft-not-found', 
+      title: 'Not Found', 
+      status: 404, 
+      detail: 'No pending draft for this entry' 
+    })
+  }
+
+  return context.json({ data: applyVisibility(draft, seed) })
+})
+
+// POST /:slug/:id/draft/publish — Atomically promotes draft to live
+draftApp.post('/:slug/:id/draft/publish', draftGuard, async (context) => {
+  const slug = context.req.param('slug')
+  const id = context.req.param('id')
+  const seed = context.get('getSeed')(slug)!
+
+  const repository = context.get('repository')
+  const draft = await repository.getDraft(seed, id)
+
+  if (!draft) {
+    return publicProblem(context, { 
+      type: 'draft-not-found', 
+      title: 'Not Found', 
+      status: 404, 
+      detail: 'No pending draft to publish' 
+    })
+  }
+
+  try {
+    await repository.publishDraft(seed, id)
+  } catch (err) {
+    if (err instanceof RelationTargetNotFoundError) {
+      return publicProblem(context, {
+        type: 'relation-target-not-found',
+        title: 'Relation Target Not Found',
+        status: 422,
+        detail: `Field '${err.alias}' references '${err.targetSeed}' id='${err.value}' which does not exist`,
+      })
+    }
+    throw err
+  }
+
+  const displayValue = draft[seed.displayNameAlias]
+  const displayStr = typeof displayValue === 'string' ? displayValue : id
+  logDraftActivity(context, id, slug, displayStr, 'draft published')
+
+  return context.json({ success: true })
+})
+
+// DELETE /:slug/:id/draft — Discards the pending draft
+draftApp.delete('/:slug/:id/draft', draftGuard, async (context) => {
+  const slug = context.req.param('slug')
+  const id = context.req.param('id')
+  const seed = context.get('getSeed')(slug)!
+
+  const repository = context.get('repository')
+  await repository.deleteDraft(seed, id)
+
+  return context.json({ success: true })
+})
+
+export { draftApp }

package/src/features/draft/draft.middleware.ts

@@ -1,62 +1,66 @@
-import { createMiddleware } from 'hono/factory'
-import { EntryNotFoundError } from '@beechcms/core'
-import { publicProblem } from '../../public/problem-details'
-import { CONTENT_ERRORS } from '../content/constants'
-import type { AppEnv } from '../../types'
-
-/**
- * Middleware that guards draft-related endpoints.
- * Responsibilities:
- * 1. Validates that the targeted Seed schema exists.
- * 2. Ensures the Seed configuration explicitly allows drafts.
- * 3. Confirms that the main live content entry exists in the repository.
- */
-export const draftGuard = createMiddleware<AppEnv>(async (context, next) => {
-  const slug = context.req.param('slug')
-  const id = context.req.param('id')
-
-  if (!slug || !id) {
-    return publicProblem(context, {
-      type: 'content-invalid-request',
-      title: 'Bad Request',
-      status: 400,
-      detail: 'Missing required route parameters',
-    })
-  }
-
-  const seed = context.get('getSeed')(slug)
-  if (!seed) {
-    return publicProblem(context, {
-      type: 'content-seed-not-found',
-      title: 'Not Found',
-      status: 404,
-      detail: CONTENT_ERRORS.SEED_NOT_FOUND,
-    })
-  }
-
-  if (!seed.allowDrafts) {
-    return publicProblem(context, {
-      type: 'draft-not-allowed',
-      title: 'Method Not Allowed',
-      status: 405,
-      detail: 'This content type does not support pending drafts. Set allowDrafts: true on the Seed to enable.',
-    })
-  }
-
-  const repository = context.get('repository')
-  try {
-    await repository.findById(seed, id)
-  } catch (error) {
-    if (error instanceof EntryNotFoundError) {
-      return publicProblem(context, {
-        type: 'content-not-found',
-        title: 'Not Found',
-        status: 404,
-        detail: CONTENT_ERRORS.NOT_FOUND,
-      })
-    }
-    throw error
-  }
-
-  await next()
-})
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+import { createMiddleware } from 'hono/factory'
+import { EntryNotFoundError } from '@beechcms/core'
+import { publicProblem } from '../../public/problem-details'
+import { CONTENT_ERRORS } from '../content/constants'
+import type { AppEnv } from '../../types'
+
+/**
+ * Middleware that guards draft-related endpoints.
+ * Responsibilities:
+ * 1. Validates that the targeted Seed schema exists.
+ * 2. Ensures the Seed configuration explicitly allows drafts.
+ * 3. Confirms that the main live content entry exists in the repository.
+ */
+export const draftGuard = createMiddleware<AppEnv>(async (context, next) => {
+  const slug = context.req.param('slug')
+  const id = context.req.param('id')
+
+  if (!slug || !id) {
+    return publicProblem(context, {
+      type: 'content-invalid-request',
+      title: 'Bad Request',
+      status: 400,
+      detail: 'Missing required route parameters',
+    })
+  }
+
+  const seed = context.get('getSeed')(slug)
+  if (!seed) {
+    return publicProblem(context, {
+      type: 'content-seed-not-found',
+      title: 'Not Found',
+      status: 404,
+      detail: CONTENT_ERRORS.SEED_NOT_FOUND,
+    })
+  }
+
+  if (!seed.allowDrafts) {
+    return publicProblem(context, {
+      type: 'draft-not-allowed',
+      title: 'Method Not Allowed',
+      status: 405,
+      detail: 'This content type does not support pending drafts. Set allowDrafts: true on the Seed to enable.',
+    })
+  }
+
+  const repository = context.get('repository')
+  try {
+    await repository.findById(seed, id)
+  } catch (error) {
+    if (error instanceof EntryNotFoundError) {
+      return publicProblem(context, {
+        type: 'content-not-found',
+        title: 'Not Found',
+        status: 404,
+        detail: CONTENT_ERRORS.NOT_FOUND,
+      })
+    }
+    throw error
+  }
+
+  await next()
+})

package/src/features/draft/index.ts

@@ -1 +1,5 @@
-export { draftApp } from './draft.handler'
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+export { draftApp } from './draft.handler'

package/src/features/email/email.provider.ts

@@ -1,38 +1,42 @@
-import type { OutboundEmail } from './email.types'
-
-/**
- * EmailProvider — formal contract for email sending providers.
- *
- * Every implementation (Resend, SendGrid, Mailgun, SMTP, ...) MUST comply
- * with this interface. It is the only point of coupling between the email module and
- * any third-party external service.
- *
- * ─── HOW TO CHANGE PROVIDER ──────────────────────────────────────────────────
- *  1. Create a new file under `providers/` (e.g., `providers/sendgrid.ts`).
- *  2. Export a class that implements this interface.
- *  3. In `email.service.ts`, replace the import and instantiation of the current
- *     provider with your new class in the `createProvider()` function.
- *  4. Update the necessary environment variables in `types.ts` and `wrangler.jsonc`.
- *  5. No other file in the project needs to be touched.
- * ─────────────────────────────────────────────────────────────────────────────
- */
-export interface EmailProvider {
-  /**
-   * Sends a single transactional email.
-   *
-   * @param email - The fully resolved message: sender, recipient,
-   *               subject, and HTML body. Use the builders in `templates/` to
-   *               construct this object correctly.
-   *
-   * @returns Promise that resolves when the provider has **accepted** the
-   *          message for delivery. Acceptance does not guarantee delivery
-   *          to the inbox — that depends on the recipient's server and the
-   *          provider's deliverability.
-   *
-   * @throws {Error} If the provider rejects the request (failed authentication,
-   *                 network error, invalid payload). The caller
-   *                 (`email.service.ts`) is responsible for catching and handling
-   *                 this error appropriately.
-   */
-  send(email: OutboundEmail): Promise<void>
-}
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+import type { OutboundEmail } from './email.types'
+
+/**
+ * EmailProvider — formal contract for email sending providers.
+ *
+ * Every implementation (Resend, SendGrid, Mailgun, SMTP, ...) MUST comply
+ * with this interface. It is the only point of coupling between the email module and
+ * any third-party external service.
+ *
+ * ─── HOW TO CHANGE PROVIDER ──────────────────────────────────────────────────
+ *  1. Create a new file under `providers/` (e.g., `providers/sendgrid.ts`).
+ *  2. Export a class that implements this interface.
+ *  3. In `email.service.ts`, replace the import and instantiation of the current
+ *     provider with your new class in the `createProvider()` function.
+ *  4. Update the necessary environment variables in `types.ts` and `wrangler.jsonc`.
+ *  5. No other file in the project needs to be touched.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+export interface EmailProvider {
+  /**
+   * Sends a single transactional email.
+   *
+   * @param email - The fully resolved message: sender, recipient,
+   *               subject, and HTML body. Use the builders in `templates/` to
+   *               construct this object correctly.
+   *
+   * @returns Promise that resolves when the provider has **accepted** the
+   *          message for delivery. Acceptance does not guarantee delivery
+   *          to the inbox — that depends on the recipient's server and the
+   *          provider's deliverability.
+   *
+   * @throws {Error} If the provider rejects the request (failed authentication,
+   *                 network error, invalid payload). The caller
+   *                 (`email.service.ts`) is responsible for catching and handling
+   *                 this error appropriately.
+   */
+  send(email: OutboundEmail): Promise<void>
+}