@plutocms/supabase 0.22.0 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.24.0](https://github.com/plutocms/supabase/compare/v0.23.0...v0.24.0) (2026-11-06)
+
+
+### Features
+
+* **supabase-blog:** tags and categories for posts ([#225](https://github.com/plutocms/supabase/issues/225)) ([36263de](https://github.com/plutocms/supabase/commit/36263def50c4f1e1a4226be5cd14b270d27bb097))
+
+## [0.23.0](https://github.com/plutocms/supabase/compare/v0.22.0...v0.23.0) (2026-11-03)
+
+
+### Features
+
+* keep the revisions of every content item, for the History of core (migration 011) ([#198](https://github.com/plutocms/supabase/issues/198)) ([9c1f3f4](https://github.com/plutocms/supabase/commit/9c1f3f43569afba62a959668d600afb09c82f855))
+
 ## [0.22.0](https://github.com/plutocms/supabase/compare/v0.21.0...v0.22.0) (2026-11-02)
 
 

package/FEATURES.md

@@ -16,7 +16,8 @@ policies shared by every project here.
   @.claude/skills/users-and-roles/SKILL.md
 - Content adapter: a Supabase/PostgREST-backed `PlutoContentAdapter`, plugging any layer's
   declared content type into `@plutocms/core`'s generic content routes. It supports query
-  filters, puts the timestamps on items, and reads the public API of core with an anonymous client.
+  filters (a filter on a `multiple` reference matches a list column) and `ids`, puts the timestamps on items, and reads the public API of core with an anonymous client.
+  It keeps the revisions of every item (`pluto_content_revisions`, migration 011) for the History of core.
   @.claude/skills/content-adapter/SKILL.md
 - Auth driver: plugs Supabase sign-in into the admin shell that pluto core owns (navbar, sign-in
   page, route guard), keeps the setup guard in the driver, and registers the backend badge

package/db/migrations/011_content_revisions.sql

@@ -0,0 +1,60 @@
+-- The saved versions of content items, for History in the edit form (the content-model skill of
+-- @plutocms/core, "Revisions"). The content adapter of this layer writes one row after each create
+-- and update, with the client of the signed-in user. Every content type of every layer shares this
+-- table. Every statement is idempotent.
+
+create table if not exists public.pluto_content_revisions (
+  id          bigint generated by default as identity not null,
+  created_at  timestamp with time zone not null default now(),
+  type        text not null,                -- the content type name
+  item_id     text not null,                -- the primary key of the item, as text
+  action      text null,                    -- create, update, publish or unpublish
+  data        jsonb not null,               -- the item after the save, by field name
+  author_id   uuid null default auth.uid() references auth.users (id) on delete set null,
+  author_name text null,                    -- the name at save time
+  capability  text null,                    -- the write capability of the type at save time
+  constraint pluto_content_revisions_pkey primary key (id),
+  constraint pluto_content_revisions_action_check check (
+    action is null or action in ('create', 'update', 'publish', 'unpublish', 'rename')
+  )
+);
+
+create index if not exists pluto_content_revisions_item_idx
+  on public.pluto_content_revisions (type, item_id, id desc);
+
+alter table public.pluto_content_revisions enable row level security;
+
+-- An editor of the type: the stored write capability, or any staff capability for a type with
+-- none. public.has_capability() folds in public.is_admin().
+drop policy if exists "pluto_content_revisions_select" on public.pluto_content_revisions;
+create policy "pluto_content_revisions_select"
+  on public.pluto_content_revisions for select
+  to authenticated
+  using (
+    (capability is null and exists (select 1 from public.my_capabilities()))
+    or public.has_capability(capability)
+  );
+
+drop policy if exists "pluto_content_revisions_insert" on public.pluto_content_revisions;
+create policy "pluto_content_revisions_insert"
+  on public.pluto_content_revisions for insert
+  to authenticated
+  with check (
+    author_id = auth.uid()
+    and (
+      (capability is null and exists (select 1 from public.my_capabilities()))
+      or public.has_capability(capability)
+    )
+  );
+
+drop policy if exists "pluto_content_revisions_delete" on public.pluto_content_revisions;
+create policy "pluto_content_revisions_delete"
+  on public.pluto_content_revisions for delete
+  to authenticated
+  using (
+    (capability is null and exists (select 1 from public.my_capabilities()))
+    or public.has_capability(capability)
+  );
+
+grant select, insert, delete on public.pluto_content_revisions to authenticated;
+grant select, insert, update, delete on public.pluto_content_revisions to service_role;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plutocms/supabase",
   "type": "module",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Supabase backend layer for Pluto",
   "author": "Victor Ribeiro",
   "homepage": "https://github.com/plutocms/supabase/tree/main/packages/supabase#readme",
@@ -30,7 +30,7 @@
   "dependencies": {
     "@nuxt/ui": "^4.12.0",
     "@nuxtjs/supabase": "^2.1.0",
-    "@plutocms/core": ">=0.48.0 <1.0.0",
+    "@plutocms/core": ">=0.58.0 <1.0.0",
     "@supabase/supabase-js": "^2.117.3",
     "postgres": "^3.4.9",
     "supabase": "^2.121.0",

package/server/utils/content-adapter.ts

@@ -3,6 +3,13 @@ import type { H3Event } from 'h3'
 import { createClient } from '@supabase/supabase-js'
 import { serverSupabaseClient } from '#supabase/server'
 import { requireCapability } from './capability-guard'
+import {
+  deleteRevisions,
+  getItemRevision,
+  listItemRevisions,
+  recordRevision,
+  updateAction,
+} from './content-revisions'
 
 /**
  * A Supabase client for one request, deliberately untyped.
@@ -246,15 +253,31 @@ function resolveFieldColumn(
   return fieldName
 }
 
+/** Whether a field stores a list in one column: a `multiple` reference. */
+function isListField(type: PlutoContentType, fieldName: string): boolean {
+  const field = type.fields.find((candidate) => candidate.name === fieldName)
+
+  return field?.type === 'reference' && field.multiple === true
+}
+
 async function list(
   ctx: PlutoContentContext,
   query: PlutoContentQuery
 ): Promise<PlutoContentListResult> {
+  // An empty id list matches no item: no query.
+  if (query.ids && query.ids.length === 0) {
+    return { data: [], total: 0 }
+  }
+
   const client = await getClient(ctx.event)
   const pkColumn = ctx.type.primaryKey ?? 'id'
 
   let builder = client.from(ctx.type.source).select('*', { count: 'exact' })
 
+  if (query.ids) {
+    builder = builder.in(pkColumn, query.ids)
+  }
+
   const statusColumn = resolveStatusColumn(ctx.type)
   if (statusColumn && query.includeUnpublished !== true) {
     const publishedValue =
@@ -263,7 +286,12 @@ async function list(
   }
 
   for (const [field, value] of Object.entries(query.filters ?? {})) {
-    builder = builder.eq(resolveFieldColumn(ctx.type, field, 'filter'), value)
+    const column = resolveFieldColumn(ctx.type, field, 'filter')
+
+    // A list column (a `multiple` reference) matches when it holds the value.
+    builder = isListField(ctx.type, field)
+      ? builder.contains(column, [value])
+      : builder.eq(column, value)
   }
 
   if (query.search) {
@@ -408,7 +436,9 @@ async function create(
     throw toContentError(error)
   }
 
-  return toItem(ctx.type, data)
+  const item = toItem(ctx.type, data)
+  await recordRevision(ctx, client, item, 'create')
+  return item
 }
 
 async function update(
@@ -435,21 +465,15 @@ async function update(
     row[updatedColumn] = new Date().toISOString()
   }
 
-  // Published-at preservation, generalizing supabase-blog's hand-written
-  // edit route: stamp published-at the first time a row is published, but
-  // never overwrite an already-set value on a later edit.
-  if (
-    statusColumn &&
-    ctx.type.status &&
-    ctx.type.status.publishedAtColumn &&
-    row[statusColumn] === ctx.type.status.publishedValue
-  ) {
-    const publishedAtColumn = ctx.type.status.publishedAtColumn
-    // Selects the whole row rather than the one dynamic column name:
-    // postgrest-js parses a `select()` argument at the type level, and a
-    // non-literal (runtime) column name resolves to its own
-    // `GenericStringError` type instead of a usable row shape.
-    const { data: existing, error: fetchError } = await client
+  // A payload with a status reads the stored row first: the published-at
+  // rule and the revision action need the old status. Selects the whole row
+  // rather than the one dynamic column name: postgrest-js parses a
+  // `select()` argument at the type level, and a non-literal (runtime)
+  // column name resolves to its own `GenericStringError` type instead of a
+  // usable row shape.
+  let existing: Record<string, unknown> | null = null
+  if (statusColumn && Object.hasOwn(values, 'status')) {
+    const { data: stored, error: fetchError } = await client
       .from(ctx.type.source)
       .select('*')
       .eq(pkColumn, id)
@@ -459,12 +483,21 @@ async function update(
       throw toContentError(fetchError)
     }
 
-    if (
-      existing &&
-      (existing as Record<string, unknown>)[publishedAtColumn] == null
-    ) {
-      row[publishedAtColumn] = new Date().toISOString()
-    }
+    existing = stored as Record<string, unknown> | null
+  }
+
+  // Published-at preservation, generalizing supabase-blog's hand-written
+  // edit route: stamp published-at the first time a row is published, but
+  // never overwrite an already-set value on a later edit.
+  if (
+    statusColumn &&
+    ctx.type.status &&
+    ctx.type.status.publishedAtColumn &&
+    row[statusColumn] === ctx.type.status.publishedValue &&
+    existing &&
+    existing[ctx.type.status.publishedAtColumn] == null
+  ) {
+    row[ctx.type.status.publishedAtColumn] = new Date().toISOString()
   }
 
   const { data, error } = await client
@@ -478,7 +511,20 @@ async function update(
     throw toContentError(error)
   }
 
-  return toItem(ctx.type, data)
+  const item = toItem(ctx.type, data)
+  await recordRevision(
+    ctx,
+    client,
+    item,
+    updateAction(
+      ctx.type,
+      existing && statusColumn ? existing[statusColumn] : undefined,
+      statusColumn && Object.hasOwn(values, 'status')
+        ? values.status
+        : undefined
+    )
+  )
+  return item
 }
 
 async function remove(
@@ -493,6 +539,36 @@ async function remove(
   if (error) {
     throw toContentError(error)
   }
+
+  await deleteRevisions(ctx, client, id)
+}
+
+/** The saved versions of one item, newest first. See `content-revisions.ts`. */
+async function listRevisions(
+  ctx: PlutoContentContext,
+  id: string | number,
+  query: { limit: number; cursor?: string }
+): Promise<PlutoContentRevisionPage> {
+  const client = await getClient(ctx.event)
+  try {
+    return await listItemRevisions(ctx, client, id, query)
+  } catch (error) {
+    throw toContentError(error as PostgrestError)
+  }
+}
+
+/** One item as it was at a revision. See `content-revisions.ts`. */
+async function getRevision(
+  ctx: PlutoContentContext,
+  id: string | number,
+  revisionId: string
+): Promise<PlutoContentItem | null> {
+  const client = await getClient(ctx.event)
+  try {
+    return await getItemRevision(ctx, client, id, revisionId)
+  } catch (error) {
+    throw toContentError(error as PostgrestError)
+  }
 }
 
 /**
@@ -541,5 +617,7 @@ export function createSupabaseContentAdapter(): PlutoContentAdapter {
     authorize,
     countCreated,
     timestampKeys,
+    listRevisions,
+    getRevision,
   }
 }

package/server/utils/content-revisions.ts

@@ -0,0 +1,219 @@
+import type { SupabaseClient } from '@supabase/supabase-js'
+import type { H3Event } from 'h3'
+import { serverSupabaseUser } from '#supabase/server'
+
+/**
+ * The saved versions of content items (011_content_revisions.sql). The content adapter writes one
+ * row after each create and update, with the client of the signed-in user, and core's History reads
+ * them through `listRevisions` and `getRevision`. See the content-adapter skill ("Revisions").
+ */
+
+export const REVISIONS_TABLE = 'pluto_content_revisions'
+
+/** The most revisions kept for one item. Older ones are deleted after an insert. */
+export const MAX_REVISIONS_PER_ITEM = 100
+
+type RevisionAction = 'create' | 'update' | 'publish' | 'unpublish'
+
+/**
+ * The action of an update: `publish` or `unpublish` when the status crosses the published value,
+ * else `update`. `before` is the stored status, `after` the status of the payload (undefined when
+ * the payload has none).
+ */
+export function updateAction(
+  type: PlutoContentType,
+  before: unknown,
+  after: unknown
+): RevisionAction {
+  if (!type.status || after === undefined) {
+    return 'update'
+  }
+  const published = type.status.publishedValue || 'published'
+  if (after === published && before !== published) {
+    return 'publish'
+  }
+  if (after !== published && before === published) {
+    return 'unpublish'
+  }
+  return 'update'
+}
+
+/** The name of the signed-in user for a revision: the profile name, else the email. */
+async function authorOf(
+  event: H3Event,
+  client: SupabaseClient
+): Promise<{
+  id: string
+  name: string | null
+} | null> {
+  const user = (await serverSupabaseUser(event)) as {
+    sub?: string
+    id?: string
+    email?: string
+  } | null
+  const id = user?.sub ?? user?.id
+  if (!id) {
+    return null
+  }
+  const { data } = await client
+    .from('profiles')
+    .select('display_name, username, email')
+    .eq('id', id)
+    .maybeSingle()
+  const profile = data as {
+    display_name?: string | null
+    username?: string | null
+    email?: string | null
+  } | null
+  return {
+    id,
+    name:
+      profile?.display_name ||
+      profile?.username ||
+      profile?.email ||
+      user?.email ||
+      null,
+  }
+}
+
+/**
+ * Writes one revision of `item` after a save, then deletes the revisions above
+ * `MAX_REVISIONS_PER_ITEM`. It never throws: a failed write (011 not applied yet, a policy) only
+ * logs a warning, because the save itself already worked.
+ */
+export async function recordRevision(
+  ctx: PlutoContentContext,
+  client: SupabaseClient,
+  item: PlutoContentItem,
+  action: RevisionAction
+): Promise<void> {
+  try {
+    const author = await authorOf(ctx.event, client)
+    if (!author) {
+      return
+    }
+    const itemId = String(item.id)
+    const { error } = await client.from(REVISIONS_TABLE).insert({
+      type: ctx.type.name,
+      item_id: itemId,
+      action,
+      data: item,
+      author_id: author.id,
+      author_name: author.name,
+      capability: ctx.type.capabilities?.write ?? null,
+    })
+    if (error) {
+      throw error
+    }
+
+    const { data: old, error: oldError } = await client
+      .from(REVISIONS_TABLE)
+      .select('id')
+      .eq('type', ctx.type.name)
+      .eq('item_id', itemId)
+      .order('id', { ascending: false })
+      .range(MAX_REVISIONS_PER_ITEM, MAX_REVISIONS_PER_ITEM + 99)
+    if (oldError) {
+      throw oldError
+    }
+    const ids = (old ?? []).map((row: { id: number }) => row.id)
+    if (ids.length > 0) {
+      await client.from(REVISIONS_TABLE).delete().in('id', ids)
+    }
+  } catch (error) {
+    console.warn(
+      `[content-adapter] Could not save a revision of ${ctx.type.name} "${String(item.id)}": ${(error as { message?: string }).message ?? String(error)}`
+    )
+  }
+}
+
+/** Deletes the revisions of a deleted item. Best effort, like `recordRevision`. */
+export async function deleteRevisions(
+  ctx: PlutoContentContext,
+  client: SupabaseClient,
+  id: string | number
+): Promise<void> {
+  const { error } = await client
+    .from(REVISIONS_TABLE)
+    .delete()
+    .eq('type', ctx.type.name)
+    .eq('item_id', String(id))
+  if (error) {
+    console.warn(
+      `[content-adapter] Could not delete the revisions of ${ctx.type.name} "${String(id)}": ${error.message}`
+    )
+  }
+}
+
+interface RevisionRow {
+  id: number
+  created_at: string
+  action: RevisionAction | null
+  author_name: string | null
+}
+
+/**
+ * The revisions of one item, newest first. The cursor is the id of the last revision of the page
+ * before (keyset paging). Row Level Security limits the rows to the editors of the type.
+ */
+export async function listItemRevisions(
+  ctx: PlutoContentContext,
+  client: SupabaseClient,
+  id: string | number,
+  query: {
+    limit: number
+    cursor?: string
+  }
+): Promise<PlutoContentRevisionPage> {
+  let builder = client
+    .from(REVISIONS_TABLE)
+    .select('id, created_at, action, author_name')
+    .eq('type', ctx.type.name)
+    .eq('item_id', String(id))
+    .order('id', { ascending: false })
+    .limit(query.limit + 1)
+  if (query.cursor && /^\d+$/.test(query.cursor)) {
+    builder = builder.lt('id', Number(query.cursor))
+  }
+  const { data, error } = await builder
+  if (error) {
+    throw error
+  }
+  const rows = (data ?? []) as RevisionRow[]
+  const page = rows.slice(0, query.limit)
+  return {
+    data: page.map((row) => ({
+      id: String(row.id),
+      createdAt: row.created_at,
+      ...(row.author_name && { author: { name: row.author_name } }),
+      ...(row.action && { action: row.action }),
+    })),
+    ...(rows.length > query.limit && {
+      nextCursor: String(page.at(-1)!.id),
+    }),
+  }
+}
+
+/** The item as it was at one revision, or `null`. */
+export async function getItemRevision(
+  ctx: PlutoContentContext,
+  client: SupabaseClient,
+  id: string | number,
+  revisionId: string
+): Promise<PlutoContentItem | null> {
+  if (!/^\d+$/.test(revisionId)) {
+    return null
+  }
+  const { data, error } = await client
+    .from(REVISIONS_TABLE)
+    .select('data')
+    .eq('id', Number(revisionId))
+    .eq('type', ctx.type.name)
+    .eq('item_id', String(id))
+    .maybeSingle()
+  if (error) {
+    throw error
+  }
+  const stored = (data as { data?: PlutoContentItem } | null)?.data
+  return stored ? { ...stored, id: stored.id ?? id } : null
+}