@trieb.work/payload-plugin-backup-mongodb 0.1.5 → 0.2.0

package/README.md

@@ -1,59 +1,172 @@
-> Experimental. Originated in the [Payblocks](https://www.shadcnblocks.com/payload-cms) template, now maintained as a standalone package. Running in production at 20+ projects from TRWK agency. Feedback and PRs welcome.
+> Experimental. Originated in the
+> [Payblocks](https://www.shadcnblocks.com/payload-cms) template, now maintained
+> as a standalone package. Running in production at 20+ projects from TRWK
+> agency. Feedback and PRs welcome.
 
 # @trieb.work/payload-plugin-backup-mongodb
 
 [![npm](https://img.shields.io/npm/v/@trieb.work/payload-plugin-backup-mongodb)](https://www.npmjs.com/package/@trieb.work/payload-plugin-backup-mongodb)
 
-A **Payload CMS v3** plugin for **MongoDB only** — not Postgres, SQLite, or other database adapters. It handles Mongo + media backup, restore, and scheduled retention with zero meta-database and a built-in admin UI. Backups live directly in Vercel Blob Storage, so a fresh install can list and restore any prior backup without bootstrapping a database first.
+A **Payload CMS v3** plugin for **MongoDB only** — not Postgres, SQLite, or
+other database adapters. It handles Mongo + media backup, restore, and scheduled
+retention with zero meta-database and a built-in admin UI. Backups live in
+**Vercel Blob Storage** (default) or **AWS S3 / S3-compatible stores** (R2,
+MinIO, etc.), so a fresh install can list and restore any prior backup without
+bootstrapping a database first.
 
 ![Backup dashboard embedded in the Payload admin panel](./docs/screenshots/dashboard.png)
 
-A first-class **Backups** section lives right below the Payload dashboard: browse every archive
-sorted by creation time, see at a glance which host and database it belongs to, whether media is
-bundled and how big it is, then download, restore or delete any backup with one click. Read more on how it originated at [TRWK> Case Study](https://trwk.de/case-studies/payload-plugin-mongodb-backup-restore).
+A first-class **Backups** section lives right below the Payload dashboard:
+browse every archive sorted by creation time, see at a glance which host and
+database it belongs to, whether media is bundled and how big it is, then
+download, restore or delete any backup with one click. Read more on how it
+originated at
+[TRWK> Case Study](https://trwk.de/case-studies/payload-plugin-mongodb-backup-restore).
 
 ---
 
 ## Highlights
 
-- **No meta database.** Every backup is self-describing in its blob name (`type---db---host---{collectionCount}-{timestampMs}.{ext}`). A brand new project can list and restore any backup straight from blob storage.
-- **Scheduled (cron) and on-demand backups.** Wire `/api/backup-mongodb/cron/run` to Vercel Cron or any HTTP scheduler. Retention is configurable (N most recent cron backups are kept; older ones are pruned automatically).
-- **Full database coverage.** Dumps **every** MongoDB collection via the Payload mongoose adapter — including hidden system collections like `users`, `payload-preferences`, `payload-migrations`. Individual collections can be excluded per backup from the UI or via API.
-- **Optional media bundling.** Cron or manual backups can include Payload `media` blobs in a `.tar.gz` archive alongside the MongoDB dump.
-- **Restore with filters.** Restore any backup with an optional collection blacklist and `mergeData` upsert mode. Partial restores keep the running admin session / tasks collection intact.
-- **Native admin dashboard.** Adds a `BackupDashboard` widget to the Payload admin (`afterDashboard`): list / sort / filter / search backups, trigger manual backups or restores, configure retention and storage, and live-poll long-running tasks.
-- **Payload REST, not Next.js route files.** All endpoints are registered as Payload custom endpoints and served by the default `/api/[...slug]` handler — you do not add `app/.../route.ts` files for this plugin.
-- **Pluggable blob storage.** Uses `BLOB_READ_WRITE_TOKEN` by default (the same store you often use with `@payloadcms/storage-vercel-blob`), or point backups at a dedicated Vercel Blob store in the admin. Both **public** and **private** access stores are supported; a validation step detects which modes the store accepts.
-- **Resumable long-running tasks.** Manual backups, restores, and seed runs are tracked in a hidden `backup-tasks` collection (TTL, 30 min). The UI polls progress with a short-lived `pollSecret` so long jobs stay observable even across reloads.
-- **Demo/seed support.** Optional `seedDemoDumpUrl` registers a one-click seed endpoint for templates and starters.
-- **Tested.** Vitest covers archive, backup, restore, task progress, blob I/O, endpoint auth, cron parsing, and blob-name helpers.
+- **No meta database.** Every backup is self-describing in its blob name
+  (`type---db---host---{collectionCount}-{timestampMs}.{ext}`). A brand new
+  project can list and restore any backup straight from blob storage.
+- **Scheduled (cron) and on-demand backups.** Wire
+  `/api/backup-mongodb/cron/run` to Vercel Cron or any HTTP scheduler. Retention
+  is configurable (N most recent cron backups are kept; older ones are pruned
+  automatically).
+- **Full database coverage.** Dumps **every** MongoDB collection via the Payload
+  mongoose adapter — including hidden system collections like `users`,
+  `payload-preferences`, `payload-migrations`. Individual collections can be
+  excluded per backup from the UI or via API.
+- **Optional media bundling.** Cron or manual backups can include Payload
+  `media` blobs in a `.tar.gz` archive alongside the MongoDB dump.
+- **Restore with filters.** Restore any backup with an optional collection
+  blacklist and `mergeData` upsert mode. Partial restores keep the running admin
+  session / tasks collection intact.
+- **Native admin dashboard.** Adds a `BackupDashboard` widget to the Payload
+  admin (`afterDashboard`): list / sort / filter / search backups, trigger
+  manual backups or restores, configure retention and storage, and live-poll
+  long-running tasks.
+- **Payload REST, not Next.js route files.** All endpoints are registered as
+  Payload custom endpoints and served by the default `/api/[...slug]` handler —
+  you do not add `app/.../route.ts` files for this plugin.
+- **Pluggable blob storage.** Uses `BLOB_READ_WRITE_TOKEN` by default (the same
+  store you often use with `@payloadcms/storage-vercel-blob`), or point backups
+  at a dedicated Vercel Blob store in the admin. Alternatively set
+  `BACKUP_STORAGE=s3` and use AWS S3, Cloudflare R2, MinIO, etc. Both **public**
+  and **private** access stores are supported; a validation step detects which
+  modes the store accepts.
+- **Resumable long-running tasks.** Manual backups and restores are tracked in a
+  hidden `backup-tasks` collection (TTL, 30 min). The UI polls progress with a
+  short-lived `pollSecret` so long jobs stay observable even across reloads.
+- **Tested.** Vitest covers archive, backup, restore, task progress, blob I/O,
+  endpoint auth, cron parsing, and blob-name helpers.
 
 ---
 
 ## Requirements
 
+- **Node.js 20.9+** (Node 18 is no longer supported).
 - Payload **v3+** (same major as your other `@payloadcms/*` packages).
 - MongoDB with Payload’s mongoose adapter (`@payloadcms/db-mongodb`).
 - MongoDB server (any version supported by that adapter).
-- A Vercel Blob read/write token (`BLOB_READ_WRITE_TOKEN`). Vercel hosting is **not** required — any Node runtime that can reach Vercel Blob works.
+- A backup target:
+  - **Vercel Blob:** `BLOB_READ_WRITE_TOKEN` (the default target). Vercel
+    hosting is **not** required — any Node runtime that can reach Vercel Blob
+    works.
+  - **S3:** `BACKUP_STORAGE=s3` plus `BACKUP_S3_BUCKET` (and optionally
+    credentials). Requires Node 20+ for the optional AWS SDK peer packages. See
+    [Choosing a backup target](#choosing-a-backup-target-vercel-blob-or-s3).
 - Next.js **15+** and React **19+** (the usual Payload 3 + App Router stack).
 
 ### Environment variables
 
-| Variable                       | Required | Purpose                                                                                                                                                                                                                                                                                                                |
-| ------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MONGODB_URI`                  | yes      | MongoDB connection string (used by Payload and to label backups with the DB name).                                                                                                                                                                                                                                     |
-| `BLOB_READ_WRITE_TOKEN`        | yes      | Default Vercel Blob store for backups and media. Can be overridden in admin settings.                                                                                                                                                                                                                                  |
-| `CRON_SECRET`                  | for cron | Bearer token for every `/api/backup-mongodb/cron/*` call. Vercel Cron can supply this.                                                                                                                                                                                                                                 |
-| `NEXT_PUBLIC_SERVER_URL`       | optional | Used to label backups with the current host. Falls back to `VERCEL_URL` when set.                                                                                                                                                                                                                                      |
-| `BACKUPS_TO_KEEP`              | optional | Default retention for cron backups if the settings document has not been edited. Default `10`.                                                                                                                                                                                                                         |
-| `PAYLOAD_BACKUP_ALLOWED_ROLES` | optional | Comma-separated role slugs that may see the **Backups** dashboard (case-insensitive). Use `*` to allow any authenticated user. When unset, the plugin falls back to requiring a `role` with slug `admin`, or allows everyone when the users collection has no `roles` field. Overridden by the `access` plugin option. |
+| Variable                       | Required        | Purpose                                                                                                                                                                                                                                                                                                                |
+| ------------------------------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MONGODB_URI`                  | yes             | MongoDB connection string (used by Payload and to label backups with the DB name).                                                                                                                                                                                                                                     |
+| `BACKUP_STORAGE`               | optional        | Backup target: `vercel-blob` (default) or `s3`. See [Choosing a backup target](#choosing-a-backup-target-vercel-blob-or-s3).                                                                                                                                                                                           |
+| `BLOB_READ_WRITE_TOKEN`        | for Vercel Blob | Default Vercel Blob store for backups and media. Required when `BACKUP_STORAGE=vercel-blob` (the default). Can be overridden in admin settings.                                                                                                                                                                        |
+| `CRON_SECRET`                  | for cron        | Bearer token for every `/api/backup-mongodb/cron/*` call. Vercel Cron can supply this.                                                                                                                                                                                                                                 |
+| `NEXT_PUBLIC_SERVER_URL`       | optional        | Used to label backups with the current host. Falls back to `VERCEL_URL` when set.                                                                                                                                                                                                                                      |
+| `BACKUPS_TO_KEEP`              | optional        | Default retention for cron backups if the settings document has not been edited. Default `10`.                                                                                                                                                                                                                         |
+| `PAYLOAD_BACKUP_ALLOWED_ROLES` | optional        | Comma-separated role slugs that may see the **Backups** dashboard (case-insensitive). Use `*` to allow any authenticated user. When unset, the plugin falls back to requiring a `role` with slug `admin`, or allows everyone when the users collection has no `roles` field. Overridden by the `access` plugin option. |
+
+---
+
+## Choosing a backup target (Vercel Blob or S3)
+
+Backups can be stored in **Vercel Blob** (default) or **AWS S3**. The S3 target
+also works with any S3-compatible store — **Cloudflare R2**, **MinIO**, etc. —
+because they share the same API; only the configuration differs, never the
+plugin code.
+
+Select the target with `BACKUP_STORAGE`. When unset it stays `vercel-blob`, so
+existing deployments are unaffected.
+
+### Using S3
+
+S3 is enabled when `BACKUP_STORAGE=s3`. Install the AWS SDK (declared as
+optional peer dependencies, so Vercel-only installs don't pull it in):
+
+```bash
+pnpm add @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
+```
+
+| Variable                      | Required | Purpose                                                                                                               |
+| ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `BACKUP_STORAGE`              | yes      | Set to `s3`.                                                                                                          |
+| `BACKUP_S3_BUCKET`            | yes      | Target bucket name.                                                                                                   |
+| `BACKUP_S3_REGION`            | optional | Region. Falls back to `AWS_REGION`, then `us-east-1`.                                                                 |
+| `BACKUP_S3_ENDPOINT`          | optional | Custom endpoint for S3-compatible stores (R2, MinIO). Omit for AWS S3.                                                |
+| `BACKUP_S3_FORCE_PATH_STYLE`  | optional | Path-style addressing. Defaults to `true` when an endpoint is set (needed for MinIO and some R2 setups).              |
+| `BACKUP_S3_PREFIX`            | optional | Key namespace prepended to every object (for sharing a bucket). Backups still list/restore by their `backups/…` name. |
+| `BACKUP_S3_ACCESS_KEY_ID`     | optional | Access key. Falls back to `AWS_ACCESS_KEY_ID`. Omit to use the AWS default credential chain (IAM roles, etc.).        |
+| `BACKUP_S3_SECRET_ACCESS_KEY` | optional | Secret key. Falls back to `AWS_SECRET_ACCESS_KEY`.                                                                    |
+| `BACKUP_S3_SESSION_TOKEN`     | optional | Session token for temporary credentials. Falls back to `AWS_SESSION_TOKEN`.                                           |
+
+Credentials are optional: when omitted, the AWS SDK's default provider chain is
+used (environment, shared config, or instance/role credentials — recommended on
+AWS).
+
+**AWS S3**
+
+```bash
+BACKUP_STORAGE=s3
+BACKUP_S3_BUCKET=my-payload-backups
+BACKUP_S3_REGION=eu-central-1
+# Credentials via IAM role (recommended) or:
+# BACKUP_S3_ACCESS_KEY_ID=...
+# BACKUP_S3_SECRET_ACCESS_KEY=...
+```
+
+**Cloudflare R2**
+
+```bash
+BACKUP_STORAGE=s3
+BACKUP_S3_BUCKET=my-payload-backups
+BACKUP_S3_REGION=auto
+BACKUP_S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
+BACKUP_S3_FORCE_PATH_STYLE=true
+BACKUP_S3_ACCESS_KEY_ID=<r2-access-key-id>
+BACKUP_S3_SECRET_ACCESS_KEY=<r2-secret-access-key>
+```
+
+Backups are stored under the same `backups/…` keys (see
+[Blob naming](#blob-naming)), so listing and restore work identically across
+targets. Downloads stream through the plugin's authenticated endpoint, so the
+bucket does **not** need to be public.
+
+> **Note on media:** the "include media" option bundles files from your Payload
+> **Vercel Blob upload store** (`BLOB_READ_WRITE_TOKEN`). The configurable
+> target above governs where backup **archives** live only; media is always read
+> from and restored to the upload store, even when `BACKUP_STORAGE=s3`.
 
 ---
 
 ## Installation and getting started
 
-Use this flow when **adding the plugin to an existing Payload 3 + Next.js app** that already has MongoDB and (typically) Vercel Blob configured.
+Use this flow when **adding the plugin to an existing Payload 3 + Next.js app**
+that already has MongoDB and a blob/S3 store configured.
 
 ### 1. Add the package
 
@@ -63,7 +176,9 @@ pnpm add @trieb.work/payload-plugin-backup-mongodb
 # yarn add @trieb.work/payload-plugin-backup-mongodb
 ```
 
-Peer dependencies: **`@payloadcms/db-mongodb`**, **`payload`**, **`@payloadcms/ui`**, **`next`**, and **`react`**. (all expected in a Payload 3 + MongoDB + Next.js app).
+Peer dependencies: **`@payloadcms/db-mongodb`**, **`payload`**,
+**`@payloadcms/ui`**, **`next`**, and **`react`**. (all expected in a Payload
+3 + MongoDB + Next.js app).
 
 ### 2. Register the plugin
 
@@ -82,7 +197,10 @@ export default buildConfig({
 })
 ```
 
-The plugin will register the backup collections, mount the dashboard, and add `/api/backup-mongodb/*` endpoints. Import paths resolve to a **published or linked** `dist/` build; after local changes to the package, run `pnpm build` in the plugin repo (or reinstall) so `dist/` is up to date.
+The plugin will register the backup collections, mount the dashboard, and add
+`/api/backup-mongodb/*` endpoints. Import paths resolve to a **published or
+linked** `dist/` build; after local changes to the package, run `pnpm build` in
+the plugin repo (or reinstall) so `dist/` is up to date.
 
 ### 3. Regenerate types and the import map
 
@@ -95,7 +213,8 @@ pnpm payload generate:importmap
 
 ### 4. (Optional) Schedule cron backups
 
-**Vercel:** add a cron in `vercel.json`. Path must match your API; default is under `/api/…`:
+**Vercel:** add a cron in `vercel.json`. Path must match your API; default is
+under `/api/…`:
 
 ```json
 {
@@ -108,7 +227,9 @@ pnpm payload generate:importmap
 }
 ```
 
-Vercel Cron sends header `Authorization: Bearer $CRON_SECRET`. **Other hosts** (k8s, GitHub Actions, etc.): `GET` the same URL on your schedule with that same authorization header.
+Vercel Cron sends header `Authorization: Bearer $CRON_SECRET`. **Other hosts**
+(k8s, GitHub Actions, etc.): `GET` the same URL on your schedule with that same
+authorization header.
 
 ### Checklist
 
@@ -116,33 +237,49 @@ Vercel Cron sends header `Authorization: Bearer $CRON_SECRET`. **Other hosts** (
 - [ ] `backupMongodbPlugin` in `plugins` array
 - [ ] `generate:types` and `generate:importmap` run
 - [ ] `MONGODB_URI` and `BLOB_READ_WRITE_TOKEN` set in the environment
-- [ ] (Optional) `CRON_SECRET` and cron job (vercel.json) if you want scheduled backups
+- [ ] (Optional) `CRON_SECRET` and cron job (vercel.json) if you want scheduled
+      backups
 
-Start your dev server, open `/admin`, sign in as an admin, and you should see **Backups** below the dashboard.
+Start your dev server, open `/admin`, sign in as an admin, and you should see
+**Backups** below the dashboard.
 
 ---
 
 ## Admin UI
 
-After the first login as an admin user, a **Backups** section appears below the default Payload
-dashboard. Day-to-day tasks — create, download, restore, delete, schedule — all happen in the UI below.
+After the first login as an admin user, a **Backups** section appears below the
+default Payload dashboard. Day-to-day tasks — create, download, restore, delete,
+schedule — all happen in the UI below.
 
 **Who can see it?** The visibility rules, in precedence order:
 
-1. If the plugin is registered with an `access` function, it wins (see [Plugin options](#plugin-options)).
-2. Otherwise, if `PAYLOAD_BACKUP_ALLOWED_ROLES` is set, it is used as a comma-separated allow-list of role slugs (case-insensitive). Use `*` for "any authenticated user". Example: `PAYLOAD_BACKUP_ALLOWED_ROLES=admin,superadmin`.
-3. Otherwise, the historical default applies: users with a `role` whose slug is `admin` see the dashboard; projects that don't use a `roles` field at all get the dashboard for any authenticated user.
+1. If the plugin is registered with an `access` function, it wins (see
+   [Plugin options](#plugin-options)).
+2. Otherwise, if `PAYLOAD_BACKUP_ALLOWED_ROLES` is set, it is used as a
+   comma-separated allow-list of role slugs (case-insensitive). Use `*` for "any
+   authenticated user". Example:
+   `PAYLOAD_BACKUP_ALLOWED_ROLES=admin,superadmin`.
+3. Otherwise, the historical default applies: users with a `role` whose slug is
+   `admin` see the dashboard; projects that don't use a `roles` field at all get
+   the dashboard for any authenticated user.
 
 ### Scheduled (cron) vs on-demand (manual) backups
 
-- **Scheduled / cron** backups follow shared settings: retention, media toggle, and collections to skip. Older cron archives are pruned when the keep-count is exceeded. They appear in the list as **CRON BACKUP** (or similar).
-- **Manual / on-demand** backups are configured **per run** — per-collection toggles, optional media in a `.tar.gz` archive. Manual backups are not auto-pruned; use them as checkpoints before migrations.
+- **Scheduled / cron** backups follow shared settings: retention, media toggle,
+  and collections to skip. Older cron archives are pruned when the keep-count is
+  exceeded. They appear in the list as **CRON BACKUP** (or similar).
+- **Manual / on-demand** backups are configured **per run** — per-collection
+  toggles, optional media in a `.tar.gz` archive. Manual backups are not
+  auto-pruned; use them as checkpoints before migrations.
 
 ![Manual backup dialog with per-collection selection and optional media bundling](./docs/screenshots/manual-backup.png)
 
 ### Selective restore with per-collection preview
 
-**Restore** opens a preview of the archive before any write. You can restore everything, cherry-pick collections, or skip media from `.tar.gz` when you only need database rows. Restoring from a different host or database is supported; filters help when cloning production into staging.
+**Restore** opens a preview of the archive before any write. You can restore
+everything, cherry-pick collections, or skip media from `.tar.gz` when you only
+need database rows. Restoring from a different host or database is supported;
+filters help when cloning production into staging.
 
 ![Restore dialog previewing document counts per collection](./docs/screenshots/restore.png)
 
@@ -152,10 +289,18 @@ Retention, storage token, and cron collection skip list live in one modal:
 
 ![Scheduled backup settings: cron schedule, retention, blob token, collection skip list](./docs/screenshots/settings.png)
 
-- **Schedule:** when `vercel.json` is present, the plugin can show a human-readable cron description (via [cronstrue](https://github.com/bradymholt/cronstrue)).
-- **Retention:** how many **cron** archives to keep; manual backups are not pruned by this.
-- **Dedicated backup storage (optional):** a separate Vercel Blob read/write token so backups can live in a different store than media. The UI can validate the token and optionally copy existing `backups/*` objects to the new store.
-- **Collection selection for cron:** defaults to all collections, with per-collection opt-out.
+- **Schedule:** when `vercel.json` is present, the plugin can show a
+  human-readable cron description (via
+  [cronstrue](https://github.com/bradymholt/cronstrue)).
+- **Retention:** how many **cron** archives to keep; manual backups are not
+  pruned by this.
+- **Dedicated backup storage (optional):** a separate Vercel Blob read/write
+  token (when `BACKUP_STORAGE=vercel-blob`) so backups can live in a different
+  store than media. The UI can validate the token and optionally copy existing
+  `backups/*` objects to the new store. For S3, configure the target bucket via
+  environment variables.
+- **Collection selection for cron:** defaults to all collections, with
+  per-collection opt-out.
 
 ---
 
@@ -172,12 +317,6 @@ type BackupPluginOptions = {
   /** Default cron retention when no value is stored in settings. Falls back to `BACKUPS_TO_KEEP` or `10`. */
   backupsToKeep?: number
 
-  /**
-   * If set, registers `POST /api/backup-mongodb/admin/seed` (demo dump + public seed media where applicable).
-   * Omit in production unless you need it.
-   */
-  seedDemoDumpUrl?: string
-
   /**
    * Custom access check for admin routes and the dashboard. Overrides the
    * `PAYLOAD_BACKUP_ALLOWED_ROLES` env var when provided.
@@ -191,24 +330,14 @@ type BackupPluginOptions = {
 }
 ```
 
-Example with custom access and seed URL (typical for starters):
-
-```ts
-backupMongodbPlugin({
-  access: (user) =>
-    Array.isArray((user as { roles?: { slug?: string }[] })?.roles) &&
-    (user as { roles: { slug?: string }[] }).roles.some(
-      (r) => r?.slug === 'admin' || r?.slug === 'superadmin',
-    ),
-  seedDemoDumpUrl: 'https://example.com/seed/demo-db.json',
-})
-```
-
 ---
 
 ## HTTP API (Payload REST)
 
-All routes are served by Payload’s `/api/[...slug]` handler under **`/api/backup-mongodb/…`**. The `backup-mongodb` prefix avoids clashing with a collection slug. The admin UI uses the same URLs; use the exported `backupPluginPublicApiPaths` helper in client code.
+All routes are served by Payload’s `/api/[...slug]` handler under
+**`/api/backup-mongodb/…`**. The `backup-mongodb` prefix avoids clashing with a
+collection slug. The admin UI uses the same URLs; use the exported
+`backupPluginPublicApiPaths` helper in client code.
 
 ### Cron / external (Bearer `CRON_SECRET`)
 
@@ -221,18 +350,17 @@ Authorization: Bearer <CRON_SECRET>
 
 ### Admin (session cookie, or `pollSecret` for `/task/:id` where applicable)
 
-| Method         | Path                                                           |
-| -------------- | -------------------------------------------------------------- |
-| `POST`         | `/api/backup-mongodb/admin/manual`                             |
-| `POST`         | `/api/backup-mongodb/admin/restore`                            |
-| `POST`         | `/api/backup-mongodb/admin/backup-preview`                     |
-| `POST`         | `/api/backup-mongodb/admin/restore-preview`                    |
-| `POST`         | `/api/backup-mongodb/admin/delete`                             |
-| `GET`          | `/api/backup-mongodb/admin/backup-download`                    |
-| `GET`          | `/api/backup-mongodb/admin/task/:id`                           |
-| `GET` / `POST` | `/api/backup-mongodb/admin/settings`                           |
-| `POST`         | `/api/backup-mongodb/admin/validate-blob-token`                |
-| `POST`         | `/api/backup-mongodb/admin/seed` — if `seedDemoDumpUrl` is set |
+| Method         | Path                                            |
+| -------------- | ----------------------------------------------- |
+| `POST`         | `/api/backup-mongodb/admin/manual`              |
+| `POST`         | `/api/backup-mongodb/admin/restore`             |
+| `POST`         | `/api/backup-mongodb/admin/backup-preview`      |
+| `POST`         | `/api/backup-mongodb/admin/restore-preview`     |
+| `POST`         | `/api/backup-mongodb/admin/delete`              |
+| `GET`          | `/api/backup-mongodb/admin/backup-download`     |
+| `GET`          | `/api/backup-mongodb/admin/task/:id`            |
+| `GET` / `POST` | `/api/backup-mongodb/admin/settings`            |
+| `POST`         | `/api/backup-mongodb/admin/validate-blob-token` |
 
 ---
 
@@ -241,7 +369,11 @@ Authorization: Bearer <CRON_SECRET>
 For scripts, hooks, and tests:
 
 ```ts
-import { createBackup, listBackups, restoreBackup } from '@trieb.work/payload-plugin-backup-mongodb'
+import {
+  createBackup,
+  listBackups,
+  restoreBackup,
+} from '@trieb.work/payload-plugin-backup-mongodb'
 
 // Example: manual backup from a one-off script
 await createBackup(payload, { cron: false, includeMedia: true })
@@ -266,16 +398,31 @@ backups/{type}---{dbName}---{hostname}---{collectionCount}-{timestampMs}.{json|t
 ```
 
 - `type`: `cron` or `manual` (and legacy-style labels where applicable).
-- `dbName` / `hostname`: derived from your MongoDB URL and public server URL; URL-encoded in the name.
-- `collectionCount` + `timestampMs`: sort key for listing; legacy blob names are still supported.
+- `dbName` / `hostname`: derived from your MongoDB URL and public server URL;
+  URL-encoded in the name.
+- `collectionCount` + `timestampMs`: sort key for listing; legacy blob names are
+  still supported.
 
 ### Public vs private stores
 
-A validation step probes the bucket and records whether the store behaves as public or private. New uploads use the right access mode. Restore and preview flows handle both.
+A validation step probes the bucket and records whether the store behaves as
+public or private. New uploads use the right access mode. Restore and preview
+flows handle both.
 
 ### Overriding the backup store
 
-To keep backups in a **different** Vercel Blob project than media, open **Backup settings** in the admin, paste a dedicated `BLOB_READ_WRITE_TOKEN`, validate, and optionally migrate existing `backups/*` objects to the new store before switching.
+To keep backups in a **different** Vercel Blob project than media (when
+`BACKUP_STORAGE=vercel-blob`), open **Backup settings** in the admin, paste a
+dedicated `BLOB_READ_WRITE_TOKEN`, validate, and optionally migrate existing
+`backups/*` objects to the new store before switching. For S3, the target is
+controlled entirely by environment variables.
+
+### Removed demo seed API (intentional)
+
+Earlier releases exposed an optional demo seed route (`seedDemoDumpUrl`,
+`/backup-mongodb/admin/seed`, and the `restoreSeedMedia` export). That was
+removed on purpose: a backup plugin should not ship a public “seed my database”
+API. Use your own migration/seed tooling instead.
 
 ---
 
@@ -287,29 +434,51 @@ pnpm test:int
 
 ### E2E (Playwright)
 
-End-to-end tests live in `tests/e2e/` and target the `dev/` Next + Payload app. **Locally**, start Mongo (or rely on the in-memory replica set when `DATABASE_URL` / `MONGODB_URI` are unset), then either run `pnpm dev` and `pnpm test:e2e` in another shell (Playwright reuses the server when not in `CI`), or run only `pnpm test:e2e` so Playwright starts `pnpm dev` for you.
+End-to-end tests live in `tests/e2e/` and target the `dev/` Next + Payload app.
+**Locally**, start Mongo (or rely on the in-memory replica set when
+`DATABASE_URL` / `MONGODB_URI` are unset), then either run `pnpm dev` and
+`pnpm test:e2e` in another shell (Playwright reuses the server when not in
+`CI`), or run only `pnpm test:e2e` so Playwright starts `pnpm dev` for you.
 
-**CI** (`.github/workflows/e2e.yml`, same pattern as the reference `e2e.yml` in executive-search: MongoDB 7 service, `pnpm run build` then `pnpm run build:dev`, then Playwright against `next start`). Optional secret **`BLOB_READ_WRITE_TOKEN`** for fuller blob behaviour.
+**CI** (`.github/workflows/e2e.yml`, same pattern as the reference `e2e.yml` in
+executive-search: MongoDB 7 service, `pnpm run build` then `pnpm run build:dev`,
+then Playwright against `next start`). Optional secret
+**`BLOB_READ_WRITE_TOKEN`** for fuller blob behaviour.
 
 ### Optional: deploy `dev/` to Vercel
 
-`.github/workflows/deploy-dev-vercel.yml` runs when `dev/` (or related paths) change on `main`, or via **workflow_dispatch**, **only if** `VERCEL_TOKEN`, `VERCEL_ORG_ID`, and `VERCEL_PROJECT_ID` are set. Configure the Vercel project **Root Directory** to `dev` (`dev/vercel.json` wires install/build from the repo root).
+`.github/workflows/deploy-dev-vercel.yml` runs when `dev/` (or related paths)
+change on `main`, or via **workflow_dispatch**, **only if** `VERCEL_TOKEN`,
+`VERCEL_ORG_ID`, and `VERCEL_PROJECT_ID` are set. Configure the Vercel project
+**Root Directory** to `dev` (`dev/vercel.json` wires install/build from the repo
+root).
 
-The repo includes a `dev/` Payload + Next app (MongoDB Memory Server when no URI is set): `pnpm dev` → `http://localhost:3000/admin` (login in `dev/helpers/credentials.ts`). In unit tests, external services like `@vercel/blob` and `bson` are often mocked with `vi.mock()`.
+The repo includes a `dev/` Payload + Next app (MongoDB Memory Server when no URI
+is set): `pnpm dev` → `http://localhost:3000/admin` (login in
+`dev/helpers/credentials.ts`). In unit tests, external services like
+`@vercel/blob` and `bson` are often mocked with `vi.mock()`.
 
 ---
 
 ## Publishing (npm)
 
-Versioning uses [Changesets](https://github.com/changesets/changesets): add a file with `pnpm changeset`, open a PR to `main`, and merge. The **Release** workflow opens a “version packages” PR or runs `pnpm run release` (`build` + `changeset publish`) when the set of changesets is ready. PRs need a new `.changeset/*.md` unless you add the **`no-changeset`** label (e.g. docs-only).
+Versioning uses [Changesets](https://github.com/changesets/changesets): add a
+file with `pnpm changeset`, open a PR to `main`, and merge. The **Release**
+workflow opens a “version packages” PR or runs `pnpm run release` (`build` +
+`changeset publish`) when the set of changesets is ready. PRs need a new
+`.changeset/*.md` unless you add the **`no-changeset`** label (e.g. docs-only).
 
 ---
 
 ## Roadmap / ideas
 
-- Multipart / very large backup uploads (Vercel Blob supports large objects; may need to switch past single-part limits).
-- Additional storage adapters (S3, R2, filesystem, etc.).
-- Scheduler-agnostic display when not using Vercel (`vercel.json` is currently used for the schedule summary where available).
+- Multipart / very large backup uploads (Vercel Blob supports large objects; may
+  need to switch past single-part limits). _(S3 uploads already use multipart.)_
+- Additional storage adapters (filesystem, etc.). _(AWS S3 and S3-compatible
+  stores such as R2/MinIO are supported — see
+  [Choosing a backup target](#choosing-a-backup-target-vercel-blob-or-s3).)_
+- Scheduler-agnostic display when not using Vercel (`vercel.json` is currently
+  used for the schedule summary where available).
 - Streaming restore for very large databases.
 - Configurable `backups/` prefix or bucket layout.
 - add support for tenant plugin and partial backups per tenant
@@ -322,4 +491,5 @@ MIT
 
 ---
 
-Built and maintained by [TRWK>](https://trwk.de), formerly [trieb.work](https://trieb.work).
+Built and maintained by [TRWK>](https://trwk.de), formerly
+[trieb.work](https://trieb.work).

package/dist/backup-dashboard.css

@@ -595,14 +595,31 @@
 .backup-task-status-slot {
   display: flex;
   flex-direction: row;
-  align-items: center;
+  align-items: flex-start;
   gap: 6px;
 }
+.backup-task-status-slot .backup-task-status__details {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+  min-width: 0;
+}
 .backup-task-status-slot .backup-task-status__message {
   font-size: 12px;
   line-height: 1.4;
   color: var(--theme-elevation-700);
 }
+.backup-task-status-slot .backup-task-status__warnings {
+  font-size: 12px;
+  line-height: 1.4;
+  color: var(--theme-warning-600, #b7791f);
+  white-space: pre-wrap;
+}
+.backup-task-status-slot .backup-task-status__error {
+  font-size: 12px;
+  line-height: 1.4;
+  color: var(--theme-error-500, #c0392b);
+}
 
 .restore-preview__blob-token-row {
   display: flex;

package/dist/collections/BackupTasks.js

@@ -16,7 +16,6 @@ export const BackupTasksCollection = {
             options: [
                 'backup',
                 'restore',
-                'seed',
                 'delete',
                 'blobTransfer'
             ],
@@ -29,6 +28,7 @@ export const BackupTasksCollection = {
                 'queued',
                 'running',
                 'completed',
+                'completed_with_warnings',
                 'failed'
             ],
             required: true
@@ -42,6 +42,13 @@ export const BackupTasksCollection = {
             name: 'error',
             type: 'text'
         },
+        {
+            name: 'warnings',
+            type: 'textarea',
+            admin: {
+                hidden: true
+            }
+        },
         {
             name: 'pollSecret',
             type: 'text',

package/dist/collections/BackupTasks.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/collections/BackupTasks.ts"],"sourcesContent":["import type { CollectionConfig } from 'payload'\n\nexport const BackupTasksCollection: CollectionConfig = {\n  slug: 'backup-tasks',\n  access: {\n    create: () => false,\n    delete: () => false,\n    read: () => false,\n    update: () => false,\n  },\n  admin: {\n    hidden: true,\n  },\n  fields: [\n    {\n      name: 'kind',\n      type: 'select',\n      options: ['backup', 'restore', 'seed', 'delete', 'blobTransfer'],\n      required: true,\n    },\n    {\n      name: 'status',\n      type: 'select',\n      options: ['queued', 'running', 'completed', 'failed'],\n      required: true,\n    },\n    {\n      name: 'message',\n      type: 'text',\n      required: true,\n    },\n    {\n      name: 'error',\n      type: 'text',\n    },\n    {\n      name: 'pollSecret',\n      type: 'text',\n      admin: {\n        hidden: true,\n      },\n    },\n  ],\n  timestamps: true,\n}\n"],"names":["BackupTasksCollection","slug","access","create","delete","read","update","admin","hidden","fields","name","type","options","required","timestamps"],"mappings":"AAEA,OAAO,MAAMA,wBAA0C;IACrDC,MAAM;IACNC,QAAQ;QACNC,QAAQ,IAAM;QACdC,QAAQ,IAAM;QACdC,MAAM,IAAM;QACZC,QAAQ,IAAM;IAChB;IACAC,OAAO;QACLC,QAAQ;IACV;IACAC,QAAQ;QACN;YACEC,MAAM;YACNC,MAAM;YACNC,SAAS;gBAAC;gBAAU;gBAAW;gBAAQ;gBAAU;aAAe;YAChEC,UAAU;QACZ;QACA;YACEH,MAAM;YACNC,MAAM;YACNC,SAAS;gBAAC;gBAAU;gBAAW;gBAAa;aAAS;YACrDC,UAAU;QACZ;QACA;YACEH,MAAM;YACNC,MAAM;YACNE,UAAU;QACZ;QACA;YACEH,MAAM;YACNC,MAAM;QACR;QACA;YACED,MAAM;YACNC,MAAM;YACNJ,OAAO;gBACLC,QAAQ;YACV;QACF;KACD;IACDM,YAAY;AACd,EAAC"}
+{"version":3,"sources":["../../src/collections/BackupTasks.ts"],"sourcesContent":["import type { CollectionConfig } from 'payload'\n\nexport const BackupTasksCollection: CollectionConfig = {\n  slug: 'backup-tasks',\n  access: {\n    create: () => false,\n    delete: () => false,\n    read: () => false,\n    update: () => false,\n  },\n  admin: {\n    hidden: true,\n  },\n  fields: [\n    {\n      name: 'kind',\n      type: 'select',\n      options: ['backup', 'restore', 'delete', 'blobTransfer'],\n      required: true,\n    },\n    {\n      name: 'status',\n      type: 'select',\n      options: ['queued', 'running', 'completed', 'completed_with_warnings', 'failed'],\n      required: true,\n    },\n    {\n      name: 'message',\n      type: 'text',\n      required: true,\n    },\n    {\n      name: 'error',\n      type: 'text',\n    },\n    {\n      name: 'warnings',\n      type: 'textarea',\n      admin: {\n        hidden: true,\n      },\n    },\n    {\n      name: 'pollSecret',\n      type: 'text',\n      admin: {\n        hidden: true,\n      },\n    },\n  ],\n  timestamps: true,\n}\n"],"names":["BackupTasksCollection","slug","access","create","delete","read","update","admin","hidden","fields","name","type","options","required","timestamps"],"mappings":"AAEA,OAAO,MAAMA,wBAA0C;IACrDC,MAAM;IACNC,QAAQ;QACNC,QAAQ,IAAM;QACdC,QAAQ,IAAM;QACdC,MAAM,IAAM;QACZC,QAAQ,IAAM;IAChB;IACAC,OAAO;QACLC,QAAQ;IACV;IACAC,QAAQ;QACN;YACEC,MAAM;YACNC,MAAM;YACNC,SAAS;gBAAC;gBAAU;gBAAW;gBAAU;aAAe;YACxDC,UAAU;QACZ;QACA;YACEH,MAAM;YACNC,MAAM;YACNC,SAAS;gBAAC;gBAAU;gBAAW;gBAAa;gBAA2B;aAAS;YAChFC,UAAU;QACZ;QACA;YACEH,MAAM;YACNC,MAAM;YACNE,UAAU;QACZ;QACA;YACEH,MAAM;YACNC,MAAM;QACR;QACA;YACED,MAAM;YACNC,MAAM;YACNJ,OAAO;gBACLC,QAAQ;YACV;QACF;QACA;YACEE,MAAM;YACNC,MAAM;YACNJ,OAAO;gBACLC,QAAQ;YACV;QACF;KACD;IACDM,YAAY;AACd,EAAC"}