@plutocms/pluto 0.6.0 → 0.8.0

package/server/utils/pluto-content-handlers.ts

@@ -0,0 +1,168 @@
+import type { H3Event } from 'h3'
+import { createError } from 'h3'
+import { validateContentPayload } from '../../shared/utils/content-validate'
+import { getContentAdapter, getContentType } from './pluto-content'
+
+/**
+ * The real logic behind the generic content routes, kept in plain exported
+ * functions — not inline in a `server/api/**` route file — so it can be
+ * unit-tested by calling it directly, the same way this workspace already
+ * tests everything else: no live Nitro server, no `@nuxt/test-utils`.
+ */
+
+export function requireContentType(name: string): PlutoContentType {
+  const type = getContentType(name)
+
+  if (!type) {
+    throw createError({ statusCode: 404, statusMessage: `Content type "${name}" not found.` })
+  }
+
+  return type
+}
+
+export function requireContentAdapter(): PlutoContentAdapter {
+  const adapter = getContentAdapter()
+
+  if (!adapter) {
+    throw createError({ statusCode: 500, statusMessage: 'No content adapter is registered.' })
+  }
+
+  return adapter
+}
+
+/**
+ * Checks `capability` against `event`, but only when there is something to
+ * check against. Exported because both write handlers below share it, and
+ * a test exercises it indirectly through them.
+ *
+ * Fails open on purpose, in two cases:
+ * - `capability` is undefined (the content type declares no capability for
+ *   this operation): nothing to enforce, anyone who can reach the route
+ *   may proceed.
+ * - The registered adapter has no `authorize` method: the same fail-open
+ *   rule `usePlutoPermissions().can()` already documents for "no
+ *   permissions backend registered at all" — with no boundary to enforce,
+ *   the adapter's own backing store (RLS, or equivalent) is still the real
+ *   gate.
+ */
+export async function authorizeContentOperation(event: H3Event, capability: string | undefined): Promise<void> {
+  if (!capability) {
+    return
+  }
+
+  const adapter = requireContentAdapter()
+
+  if (!adapter.authorize) {
+    return
+  }
+
+  await adapter.authorize(event, capability)
+}
+
+/**
+ * Lists items for `ctx.type`. Never checks `type.capabilities.read` and
+ * never calls `adapter.authorize` — see the content-model skill for why:
+ * in short, "read" is not all-or-nothing for a type like `posts` (an
+ * anonymous visitor can read published posts; only drafts need a
+ * capability), and that distinction already lives in the adapter's backing
+ * store (RLS, for the one adapter that exists so far). This route always
+ * asks the adapter for everything, unfiltered by capability, because it is
+ * admin-surface-only in intent — a public-facing read path is a layer's
+ * own hand-written endpoint, not this generic one.
+ */
+export async function listContentItems(
+  ctx: PlutoContentContext,
+  query: {
+    limit?: number
+    offset?: number
+    search?: string
+  }
+): Promise<PlutoContentListResult> {
+  return requireContentAdapter().list(ctx, {
+    limit: query.limit,
+    offset: query.offset,
+    search: query.search,
+    sort: ctx.type.defaultSort,
+    includeUnpublished: true,
+  })
+}
+
+/** Gets one item by id or slug. No capability check — see `listContentItems`. */
+export async function getContentItem(ctx: PlutoContentContext, idOrSlug: string | number): Promise<PlutoContentItem> {
+  const item = await requireContentAdapter().get(ctx, idOrSlug)
+
+  if (!item) {
+    throw createError({ statusCode: 404, statusMessage: 'Not found.' })
+  }
+
+  return item
+}
+
+function requirePlainObjectBody(body: unknown): Record<string, unknown> {
+  if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+    throw createError({ statusCode: 400, statusMessage: 'Request body must be a JSON object.' })
+  }
+
+  return body as Record<string, unknown>
+}
+
+/**
+ * Creates one item. Validates the full payload (not partial), authorizes
+ * against `type.capabilities.write`, then calls the adapter, then runs
+ * `type.hooks.afterCreate` when one is registered. A hook error propagates
+ * — it is not swallowed.
+ */
+export async function createContentItem(ctx: PlutoContentContext, body: unknown): Promise<PlutoContentItem> {
+  const payload = requirePlainObjectBody(body)
+
+  const errors = validateContentPayload(ctx.type, payload)
+  if (errors.length > 0) {
+    throw createError({ statusCode: 400, statusMessage: 'Validation failed.', data: { errors } })
+  }
+
+  await authorizeContentOperation(ctx.event, ctx.type.capabilities?.write)
+
+  const item = await requireContentAdapter().create(ctx, payload)
+
+  if (ctx.type.hooks?.afterCreate) {
+    await ctx.type.hooks.afterCreate(ctx, item, payload)
+  }
+
+  return item
+}
+
+/**
+ * Updates one item. Validates the payload as a partial update, authorizes
+ * against `type.capabilities.write`, then calls the adapter, then runs
+ * `type.hooks.afterUpdate` when one is registered. A hook error propagates
+ * — it is not swallowed.
+ */
+export async function updateContentItem(
+  ctx: PlutoContentContext,
+  id: string | number,
+  body: unknown
+): Promise<PlutoContentItem> {
+  const payload = requirePlainObjectBody(body)
+
+  const errors = validateContentPayload(ctx.type, payload, { partial: true })
+  if (errors.length > 0) {
+    throw createError({ statusCode: 400, statusMessage: 'Validation failed.', data: { errors } })
+  }
+
+  await authorizeContentOperation(ctx.event, ctx.type.capabilities?.write)
+
+  const item = await requireContentAdapter().update(ctx, id, payload)
+
+  if (ctx.type.hooks?.afterUpdate) {
+    await ctx.type.hooks.afterUpdate(ctx, item, payload)
+  }
+
+  return item
+}
+
+/** Deletes one item. Authorizes against `type.capabilities.delete` before calling the adapter. */
+export async function deleteContentItem(ctx: PlutoContentContext, id: string | number): Promise<void> {
+  await authorizeContentOperation(ctx.event, ctx.type.capabilities?.delete)
+
+  await requireContentAdapter().remove(ctx, id)
+}

package/server/utils/pluto-content.ts

@@ -0,0 +1,44 @@
+/**
+ * The server-side content-type and adapter registry. Deliberately a plain
+ * module-scope singleton — NOT built like `usePlutoRegistry` (the client
+ * registry in `app/composables/pluto-registry.ts`), and that is on purpose,
+ * not an oversight.
+ *
+ * The client registry lives on `nuxtApp` instead of module scope because a
+ * module-scope object on the server would leak state between requests and
+ * between apps during SSR: one user's data could end up rendered into
+ * another user's response. That risk does not apply here, for three
+ * reasons:
+ *
+ * 1. Registration happens once, at Nitro startup, from a layer's own
+ *    `server/plugins/*.ts` file — not per request.
+ * 2. The registered values (`PlutoContentType`, `PlutoContentAdapter`) are
+ *    static definition objects. They hold zero per-request state.
+ * 3. Anything that actually varies per request — the caller's identity,
+ *    their session — travels in `PlutoContentContext.event`, which is
+ *    passed fresh into every adapter call. It never touches the registry.
+ *
+ * So a future reader who knows why the client registry avoids module scope
+ * should not assume the same warning applies here: it does not, because
+ * nothing stored here ever differs between two requests.
+ */
+
+const contentTypes = new Map<string, PlutoContentType>()
+let contentAdapter: PlutoContentAdapter | undefined
+
+export function registerContentType(type: PlutoContentType): void {
+  contentTypes.set(type.name, type)
+}
+
+export function getContentType(name: string): PlutoContentType | undefined {
+  return contentTypes.get(name)
+}
+
+/** Replaces whatever adapter was registered before. Last-registered wins, the same rule `mediaAdapters`/`settingsDrivers` use client-side. */
+export function registerContentAdapter(adapter: PlutoContentAdapter): void {
+  contentAdapter = adapter
+}
+
+export function getContentAdapter(): PlutoContentAdapter | undefined {
+  return contentAdapter
+}

package/shared/types/content.ts

@@ -1,3 +1,5 @@
+import type { H3Event } from 'h3'
+
 export type PlutoFieldType =
   | 'text'
   | 'textarea'
@@ -181,6 +183,19 @@ export interface PlutoContentType {
   basePath?: string
   navOrder?: number
   i18n?: PlutoContentI18n
+  /**
+   * Server-only lifecycle hooks, run by the generic write handlers
+   * (`server/utils/pluto-content-handlers.ts`) after the adapter call
+   * succeeds and before the response goes out. Lets a layer with extra
+   * logic around a write — for example `supabase-shop` reconciling
+   * `product_media` rows after a product write — hook in without a bespoke
+   * endpoint just for that, and without polluting the generic adapter
+   * contract with a per-layer concern.
+   */
+  hooks?: {
+    afterCreate?: (ctx: PlutoContentContext, item: PlutoContentItem, rawBody: Record<string, unknown>) => Promise<void> | void
+    afterUpdate?: (ctx: PlutoContentContext, item: PlutoContentItem, rawBody: Record<string, unknown>) => Promise<void> | void
+  }
 }
 
 /**
@@ -194,3 +209,45 @@ export interface PlutoContentType {
 export type PlutoContentItem = Record<string, unknown> & {
   id: string | number
 }
+
+/** Options for a generic list read. See `server/utils/pluto-content-handlers.ts`. */
+export interface PlutoContentQuery {
+  limit?: number
+  offset?: number
+  search?: string
+  sort?: {
+    field: string
+    direction: 'asc' | 'desc'
+  }
+  includeUnpublished?: boolean
+}
+
+export interface PlutoContentListResult {
+  data: PlutoContentItem[]
+  total?: number
+}
+
+/** Per-request context an adapter method receives: the H3 event, and the content type being read or written. */
+export interface PlutoContentContext {
+  event: H3Event
+  type: PlutoContentType
+}
+
+/**
+ * Lets a backend layer (`@plutocms/supabase`, and so on) plug its own
+ * storage into the generic content server routes, without core knowing
+ * which backend is in use — the same role `PlutoMediaAdapter` plays for
+ * media. Exactly one adapter is meaningful per app, registered through
+ * `registerContentAdapter` (see `server/utils/pluto-content.ts`).
+ */
+export interface PlutoContentAdapter {
+  id: string
+  list: (ctx: PlutoContentContext, query: PlutoContentQuery) => Promise<PlutoContentListResult>
+  get: (ctx: PlutoContentContext, idOrSlug: string | number) => Promise<PlutoContentItem | null>
+  create: (ctx: PlutoContentContext, values: Record<string, unknown>) => Promise<PlutoContentItem>
+  update: (ctx: PlutoContentContext, id: string | number, values: Record<string, unknown>) => Promise<PlutoContentItem>
+  remove: (ctx: PlutoContentContext, id: string | number) => Promise<void>
+  /** Throws when `event`'s caller does not hold `capability`. Optional — see the fail-open rule in the content-model skill. */
+  authorize?: (event: H3Event, capability: string) => Promise<void>
+  describe?: (ctx: PlutoContentContext) => Promise<string[] | null>
+}