@plutocms/supabase 0.15.5 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.17.0](https://github.com/plutocms/supabase/compare/v0.16.0...v0.17.0) (2026-10-30)
+
+
+### Features
+
+* media previews, sort and rename in the Supabase driver ([#139](https://github.com/plutocms/supabase/issues/139)) ([8cdf071](https://github.com/plutocms/supabase/commit/8cdf0715c5a11db8e99423751708d2ab0feea455))
+
+## [0.16.0](https://github.com/plutocms/supabase/compare/v0.15.5...v0.16.0) (2026-10-30)
+
+
+### Features
+
+* the Supabase driver of the core media library ([#135](https://github.com/plutocms/supabase/issues/135)) ([94aa31a](https://github.com/plutocms/supabase/commit/94aa31a5b13ed3866e17a9e074876aa79f2bdba8))
+
 ## [0.15.5](https://github.com/plutocms/supabase/compare/v0.15.4...v0.15.5) (2026-10-29)
 
 

package/db/migrations/009_media.sql

@@ -0,0 +1,95 @@
+-- The media library of core (the media skill of @plutocms/pluto), on Supabase.
+-- The table and the bucket were in @plutocms/supabase-storage, which retires.
+-- Every statement is idempotent, so a database with the old storage layer and a
+-- new database get the same result.
+
+create table if not exists public.media (
+  id           bigint generated by default as identity not null,
+  created_at   timestamp with time zone not null default now(),
+  name         character varying null,  -- the original file name, for people
+  alt          character varying null,
+  storage_path character varying null,  -- the object key in `bucket`
+  mime_type    character varying null,
+  size         bigint null,             -- in bytes
+  constraint media_pkey primary key (id)
+);
+
+-- The bucket of each file. New files go to `media`. Older files can stay in
+-- another bucket (the shop's `product-media`), so no bytes move.
+alter table public.media add column if not exists bucket text not null default 'media';
+alter table public.media add column if not exists width integer null;
+alter table public.media add column if not exists height integer null;
+
+create index if not exists media_created_at_idx on public.media (created_at desc);
+
+alter table public.media enable row level security;
+
+drop policy if exists "media_select_public" on public.media;
+create policy "media_select_public"
+  on public.media for select
+  using (true);
+
+drop policy if exists "media_insert_authenticated" on public.media;
+create policy "media_insert_authenticated"
+  on public.media for insert
+  with check (public.has_capability('media:manage'));
+
+drop policy if exists "media_update_authenticated" on public.media;
+create policy "media_update_authenticated"
+  on public.media for update
+  using (public.has_capability('media:manage'))
+  with check (public.has_capability('media:manage'));
+
+drop policy if exists "media_delete_authenticated" on public.media;
+create policy "media_delete_authenticated"
+  on public.media for delete
+  using (public.has_capability('media:delete'));
+
+grant select on public.media to anon;
+grant select, insert, update, delete on public.media to authenticated;
+grant select, insert, update, delete on public.media to service_role;
+
+-- The bucket: public read. A file name never changes, so it can be cached for ever.
+insert into storage.buckets (id, name, public)
+values ('media', 'media', true)
+on conflict (id) do nothing;
+
+drop policy if exists "media: public read" on storage.objects;
+create policy "media: public read"
+  on storage.objects for select
+  using (bucket_id = 'media');
+
+drop policy if exists "media: admin insert" on storage.objects;
+create policy "media: admin insert"
+  on storage.objects for insert
+  to authenticated
+  with check (bucket_id = 'media' and public.has_capability('media:manage'));
+
+drop policy if exists "media: admin update" on storage.objects;
+create policy "media: admin update"
+  on storage.objects for update
+  to authenticated
+  using (bucket_id = 'media' and public.has_capability('media:manage'))
+  with check (bucket_id = 'media' and public.has_capability('media:manage'));
+
+drop policy if exists "media: admin delete" on storage.objects;
+create policy "media: admin delete"
+  on storage.objects for delete
+  to authenticated
+  using (bucket_id = 'media' and public.has_capability('media:delete'));
+
+-- Older rows: the type and the size from the stored object. A 3D model often
+-- has no real type in Storage, so `.glb` gets its type from the name.
+update public.media m
+set
+  mime_type = coalesce(m.mime_type, nullif(o.metadata ->> 'mimetype', 'application/octet-stream')),
+  size = coalesce(m.size, (o.metadata ->> 'size')::bigint)
+from storage.objects o
+where o.bucket_id = m.bucket
+  and o.name = m.storage_path
+  and (m.mime_type is null or m.size is null);
+
+update public.media
+set mime_type = 'model/gltf-binary'
+where storage_path ilike '%.glb'
+  and mime_type is distinct from 'model/gltf-binary';

package/db/migrations/010_media_preview.sql

@@ -0,0 +1,7 @@
+-- The preview image of a file that is not an image (a 3D model), made in the
+-- browser by the kind of the file. Always in the `media` bucket, even for an
+-- older file in another bucket. See the media skill of @plutocms/pluto.
+
+alter table public.media add column if not exists preview_path text null;
+alter table public.media add column if not exists preview_width integer null;
+alter table public.media add column if not exists preview_height integer null;

package/nuxt.config.ts

@@ -5,6 +5,16 @@ import type { PlutoMigrationFile } from './shared/types/migrations'
 const plutoLayer = process.env.PLUTO_PLUTO_PATH || '@plutocms/pluto'
 const utilsLayer = process.env.PLUTO_UTILS_PATH || '@plutocms/utils'
 
+// The host of the Supabase project, at build time. `@nuxt/image` may only read
+// remote images of the hosts in `image.domains` (the media files are in Storage).
+function supabaseHost(): string {
+  try {
+    return new URL(process.env.SUPABASE_URL ?? '').host
+  } catch {
+    return ''
+  }
+}
+
 export default defineNuxtConfig({
   extends: [[plutoLayer, { install: true }], utilsLayer],
 
@@ -22,6 +32,10 @@ export default defineNuxtConfig({
     supabaseKey: process.env.SUPABASE_KEY,
     plutoRootDir: '',
     plutoLayerMigrations: {} as Record<string, PlutoMigrationFile[]>,
+    public: {
+      // The core media library uses the Supabase driver (server/utils/media-driver.ts).
+      plutoMedia: { driver: 'supabase' },
+    },
   },
 
   alias: {
@@ -45,6 +59,10 @@ export default defineNuxtConfig({
     },
   },
 
+  image: {
+    domains: supabaseHost() ? [supabaseHost()] : [],
+  },
+
   supabase: {
     types: '#shared/types/supabase',
     cookiePrefix: 'access_token',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plutocms/supabase",
   "type": "module",
-  "version": "0.15.5",
+  "version": "0.17.0",
   "trustedDependencies": [
     "@parcel/watcher",
     "@plutocms/pluto",
@@ -39,7 +39,7 @@
     "@nuxt/eslint": "^1.17.0",
     "@nuxt/ui": "^4.12.0",
     "@nuxtjs/supabase": "^2.1.0",
-    "@plutocms/pluto": ">=0.34.0 <1.0.0",
+    "@plutocms/pluto": ">=0.36.0 <1.0.0",
     "@plutocms/utils": ">=0.3.0 <1.0.0",
     "@supabase/supabase-js": "^2.117.3",
     "postgres": "^3.4.9",

package/server/plugins/media-driver.ts

@@ -0,0 +1,7 @@
+/**
+ * Registers the Supabase media driver with the core media library, at Nitro
+ * startup. See the media skill of `@plutocms/pluto`.
+ */
+export default defineNitroPlugin(() => {
+  registerMediaDriver(createSupabaseMediaDriver())
+})

package/server/utils/content-adapter.ts

@@ -39,6 +39,13 @@ async function getClient(event: H3Event): Promise<SupabaseClient> {
   return (await serverSupabaseClient(event)) as unknown as SupabaseClient
 }
 
+/**
+ * The client of a request: the anonymous client for a public read (no
+ * cookie, the same answer for everyone), else the client of the signed-in user.
+ * The media driver uses it too.
+ */
+export const supabaseRequestClient = getClient
+
 /** The anonymous client and the url/key pair it was built from. */
 let anonymousClient:
   { url: string; key: string; client: SupabaseClient } | undefined

package/server/utils/media-driver.ts

@@ -0,0 +1,304 @@
+import type { SupabaseClient } from '@supabase/supabase-js'
+import type { H3Event } from 'h3'
+import { requireCapability } from './capability-guard'
+import { supabaseRequestClient } from './content-adapter'
+
+/** The bucket of new files. Older files can be in another bucket (`media.bucket`). */
+export const MEDIA_BUCKET = 'media'
+
+interface MediaRow {
+  id: number
+  created_at: string
+  name: string | null
+  alt: string | null
+  bucket: string | null
+  storage_path: string | null
+  mime_type: string | null
+  size: number | null
+  width: number | null
+  height: number | null
+  preview_path: string | null
+  preview_width: number | null
+  preview_height: number | null
+}
+
+/** `<yyyy>/<mm>/<name>`: the object key of a file, by the month of its record. */
+function monthKey(createdAt: string, fileName: string): string {
+  const date = new Date(createdAt)
+  return `${date.getUTCFullYear()}/${String(date.getUTCMonth() + 1).padStart(2, '0')}/${fileName}`
+}
+
+/** The order of a list. The id breaks a tie, so pages stay stable. */
+const ORDER: Record<PlutoMediaSort, { column: string; ascending: boolean }> = {
+  newest: { column: 'created_at', ascending: false },
+  oldest: { column: 'created_at', ascending: true },
+  name: { column: 'name', ascending: true },
+  size: { column: 'size', ascending: false },
+}
+
+function toRecord(client: SupabaseClient, row: MediaRow): PlutoMedia {
+  const bucket = row.bucket || MEDIA_BUCKET
+  return {
+    id: String(row.id),
+    url: row.storage_path
+      ? client.storage.from(bucket).getPublicUrl(row.storage_path).data
+          .publicUrl
+      : '',
+    name: row.name ?? '',
+    mimeType: row.mime_type ?? 'application/octet-stream',
+    size: Number(row.size ?? 0),
+    width: row.width,
+    height: row.height,
+    alt: row.alt ?? '',
+    createdAt: row.created_at,
+    // A preview is always in the `media` bucket.
+    preview:
+      row.preview_path && row.preview_width && row.preview_height
+        ? {
+            url: client.storage.from(MEDIA_BUCKET).getPublicUrl(row.preview_path)
+              .data.publicUrl,
+            width: row.preview_width,
+            height: row.preview_height,
+          }
+        : null,
+  }
+}
+
+function failed(message: string, key: string): Error {
+  console.error('[media] Supabase answered with an error:', message)
+  return createPlutoError({ statusCode: 500, message: 'The media library failed.', key })
+}
+
+function notFound(): Error {
+  return createPlutoError({
+    statusCode: 404,
+    message: 'The file does not exist.',
+    key: 'pluto.media.errors.notFound',
+  })
+}
+
+function numericIds(ids: string[]): number[] {
+  return ids.map(Number).filter((id) => Number.isSafeInteger(id) && id > 0)
+}
+
+/**
+ * The media driver of the Supabase backend: the bytes in Supabase Storage,
+ * the record in `public.media` (db/migrations/009_media.sql). Row Level
+ * Security checks the capabilities again (`has_capability`). New files go to
+ * `media/<yyyy>/<mm>/<name>-<suffix>.<ext>`, and their previews next to them
+ * (`db/migrations/010_media_preview.sql`). See the media skill of
+ * `@plutocms/pluto`.
+ */
+export function createSupabaseMediaDriver(): PlutoMediaDriver {
+  async function readRow(client: SupabaseClient, id: string): Promise<MediaRow> {
+    const [numeric] = numericIds([id])
+    if (!numeric) {
+      throw notFound()
+    }
+    const { data, error } = await client
+      .from('media')
+      .select('*')
+      .eq('id', numeric)
+      .maybeSingle()
+    if (error) {
+      throw failed(error.message, 'pluto.media.errors.saveFailed')
+    }
+    if (!data) {
+      throw notFound()
+    }
+    return data as MediaRow
+  }
+
+  return {
+    name: 'supabase',
+
+    async authorize(event: H3Event, capability) {
+      await requireCapability(event, capability)
+    },
+
+    async list(event, query) {
+      const client = await supabaseRequestClient(event)
+      const order = ORDER[query.sort ?? 'newest']
+      let request = client
+        .from('media')
+        .select('*', { count: 'exact' })
+        .order(order.column, { ascending: order.ascending, nullsFirst: false })
+        .order('id', { ascending: order.ascending })
+        .range(query.offset, query.offset + query.limit - 1)
+      if (query.search) {
+        // Commas and brackets have a meaning in a PostgREST `or` filter.
+        const text = query.search.replace(/[,()*%\\]/g, ' ').trim()
+        if (text) {
+          request = request.or(`name.ilike.%${text}%,alt.ilike.%${text}%`)
+        }
+      }
+      if (query.type === 'image') {
+        request = request.like('mime_type', 'image/%')
+      } else if (query.type?.endsWith('/') || query.type?.endsWith('/*')) {
+        request = request.like('mime_type', `${query.type.replace(/\*$/, '')}%`)
+      } else if (query.type) {
+        request = request.eq('mime_type', query.type)
+      }
+      const { data, error, count } = await request
+      if (error) {
+        throw failed(error.message, 'pluto.media.loadFailed')
+      }
+      return {
+        data: (data as MediaRow[]).map((row) => toRecord(client, row)),
+        total: count ?? data.length,
+      }
+    },
+
+    async get(event, ids) {
+      const wanted = numericIds(ids)
+      if (wanted.length === 0) {
+        return []
+      }
+      const client = await supabaseRequestClient(event)
+      const { data, error } = await client.from('media').select('*').in('id', wanted)
+      if (error) {
+        throw failed(error.message, 'pluto.media.loadFailed')
+      }
+      return (data as MediaRow[]).map((row) => toRecord(client, row))
+    },
+
+    async upload(event, input) {
+      const client = await supabaseRequestClient(event)
+      const path = monthKey(input.createdAt, input.fileName)
+      const previewPath = input.preview
+        ? monthKey(input.createdAt, input.preview.fileName)
+        : null
+      const storage = client.storage.from(MEDIA_BUCKET)
+      const { error: uploadError } = await storage.upload(path, input.data, {
+        contentType: input.mimeType,
+        cacheControl: '31536000',
+        upsert: false,
+      })
+      if (uploadError) {
+        throw failed(uploadError.message, 'pluto.media.errors.saveFailed')
+      }
+      if (input.preview && previewPath) {
+        const { error: previewError } = await storage.upload(
+          previewPath,
+          input.preview.data,
+          { contentType: input.preview.mimeType, cacheControl: '31536000', upsert: true }
+        )
+        if (previewError) {
+          await storage.remove([path])
+          throw failed(previewError.message, 'pluto.media.errors.saveFailed')
+        }
+      }
+      const { data, error } = await client
+        .from('media')
+        .insert({
+          name: input.name,
+          alt: input.alt || null,
+          bucket: MEDIA_BUCKET,
+          storage_path: path,
+          mime_type: input.mimeType,
+          size: input.size,
+          width: input.width,
+          height: input.height,
+          created_at: input.createdAt,
+          preview_path: previewPath,
+          preview_width: input.preview?.width ?? null,
+          preview_height: input.preview?.height ?? null,
+        })
+        .select('*')
+        .single()
+      if (error) {
+        // No record without its file, and no file without its record.
+        const { error: cleanup } = await storage.remove(
+          previewPath ? [path, previewPath] : [path]
+        )
+        if (cleanup) {
+          console.warn('[media] could not remove the file of a failed upload:', path, cleanup.message)
+        }
+        throw failed(error.message, 'pluto.media.errors.saveFailed')
+      }
+      return toRecord(client, data as MediaRow)
+    },
+
+    async update(event, id, patch) {
+      const client = await supabaseRequestClient(event)
+      const row = await readRow(client, id)
+      const changes: Partial<MediaRow> = {}
+      if (patch.name !== undefined) {
+        changes.name = patch.name
+      }
+      if (patch.alt !== undefined) {
+        changes.alt = patch.alt || null
+      }
+      if (patch.width !== undefined) {
+        changes.width = patch.width
+      }
+      if (patch.height !== undefined) {
+        changes.height = patch.height
+      }
+      const { data, error } = await client
+        .from('media')
+        .update(changes)
+        .eq('id', row.id)
+        .select('*')
+        .single()
+      if (error) {
+        throw failed(error.message, 'pluto.media.errors.saveFailed')
+      }
+      return toRecord(client, data as MediaRow)
+    },
+
+    async setPreview(event, id, preview) {
+      const client = await supabaseRequestClient(event)
+      const row = await readRow(client, id)
+      const storage = client.storage.from(MEDIA_BUCKET)
+      const path = monthKey(row.created_at, preview.fileName)
+      const { error: uploadError } = await storage.upload(path, preview.data, {
+        contentType: preview.mimeType,
+        cacheControl: '31536000',
+        upsert: true,
+      })
+      if (uploadError) {
+        throw failed(uploadError.message, 'pluto.media.errors.saveFailed')
+      }
+      const { data, error } = await client
+        .from('media')
+        .update({
+          preview_path: path,
+          preview_width: preview.width,
+          preview_height: preview.height,
+        })
+        .eq('id', row.id)
+        .select('*')
+        .single()
+      if (error) {
+        throw failed(error.message, 'pluto.media.errors.saveFailed')
+      }
+      // An older preview with another name (another type) goes.
+      if (row.preview_path && row.preview_path !== path) {
+        await storage.remove([row.preview_path])
+      }
+      return toRecord(client, data as MediaRow)
+    },
+
+    async remove(event, id) {
+      const client = await supabaseRequestClient(event)
+      const row = await readRow(client, id)
+      // The file first: a retry after a failed delete of the row then finds no file, which is no error.
+      if (row.storage_path) {
+        const { error } = await client.storage
+          .from(row.bucket || MEDIA_BUCKET)
+          .remove([row.storage_path])
+        if (error) {
+          throw failed(error.message, 'pluto.media.errors.deleteFailed')
+        }
+      }
+      if (row.preview_path) {
+        await client.storage.from(MEDIA_BUCKET).remove([row.preview_path])
+      }
+      const { error } = await client.from('media').delete().eq('id', row.id)
+      if (error) {
+        throw failed(error.message, 'pluto.media.errors.deleteFailed')
+      }
+    },
+  }
+}