@nextlyhq/plugin-form-builder 0.0.2-alpha.7 → 0.0.2-alpha.71

package/README.md

@@ -1,6 +1,6 @@
 # @nextlyhq/plugin-form-builder
 
-Drag-and-drop form builder plugin for Nextly. Build forms visually, collect submissions, and filter them by form. _Coming soon in beta._
+Drag-and-drop form builder plugin for Nextly. Build forms visually, collect submissions, and filter them by form.
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@nextlyhq/plugin-form-builder"><img alt="npm" src="https://img.shields.io/npm/v/@nextlyhq/plugin-form-builder?style=flat-square&label=npm&color=cb3837" /></a>
@@ -8,11 +8,10 @@ Drag-and-drop form builder plugin for Nextly. Build forms visually, collect subm
   <a href="https://nextlyhq.com/docs"><img alt="Status" src="https://img.shields.io/badge/status-alpha-orange?style=flat-square" /></a>
 </p>
 
-> [!WARNING]
-> **Coming soon in beta. Plugins are not ready for use yet.** Public plugin support, including stable APIs, the official plugin gallery, and documentation guarantees, lands at the Nextly **beta** release. This package is published for early exploration only. Surfaces, names, and behaviour will change without notice. Do not rely on plugins for production or serious development work. Wait for the beta release announcement before integrating plugins into your project.
-
 > [!IMPORTANT]
-> Nextly is in alpha. APIs may change before 1.0. Pin exact versions in production.
+> Nextly is in alpha. APIs may change before 1.0 — pin exact versions in production.
+> See the [plugin stability ladder](https://nextlyhq.com/docs/plugins/stability) for
+> which plugin surfaces are stable and which are experimental.
 
 ## What it is
 
@@ -40,21 +39,26 @@ const fb = formBuilder({
 
 export default defineConfig({
   plugins: [fb.plugin],
-  collections: [...fb.collections],
+  collections: [
+    /* your own collections only */
+  ],
 });
 ```
 
+The plugin registers its `forms` and `form-submissions` collections itself. Don't
+also add `fb.collections` to `collections`: the same slug twice stops the app
+from booting with a duplicate `forms` collection.
+
 > A `formBuilderPlugin` default-instance shortcut is also exported for cases where no customization is needed. See [the plugin docs](https://nextlyhq.com/docs/plugins/form-builder) for the full options reference.
 
-## Admin styling
+## Admin components
 
-The plugin's admin UI requires three imports in your admin route page so the builder and submissions filter render correctly:
+The plugin's admin UI needs one import in your admin route page (a side effect
+that registers the builder and submissions views):
 
 ```tsx
 // app/admin/[[...params]]/page.tsx
 import "@nextlyhq/plugin-form-builder/admin";
-import "@nextlyhq/plugin-form-builder/styles/builder.css";
-import "@nextlyhq/plugin-form-builder/styles/submissions-filter.css";
 ```
 
 ## What this plugin adds
@@ -62,7 +66,15 @@ import "@nextlyhq/plugin-form-builder/styles/submissions-filter.css";
 - **Admin routes:** `/admin/collections/forms` and `/admin/collections/form-submissions`
 - **Collections:** `forms`, `form-submissions`
 - **Form lifecycle states:** Draft, Published, Closed
-- **Optional integrations:** email notifications, webhook delivery on submission, spam protection (honeypot, rate limit, reCAPTCHA v3)
+- **Optional integrations:** email notifications, a `form.submission.created` webhook through Nextly's own webhooks, spam protection (honeypot, rate limit, reCAPTCHA v3)
+
+### Submission privacy
+
+Submissions carry visitor-entered answers plus `ipAddress` and `userAgent`, so the `form-submissions` collection suppresses the default `entry.*` events (which would otherwise deliver that content to any endpoint subscribed to `entry.created` or `*`). In their place it emits a curated **`form.submission.created`** event carrying only safe metadata — which form, when, and the submission status — never the answers, IP, or user agent. Subscribe an endpoint to `form.submission.created` to be notified of new submissions without receiving their content.
+
+Do **not** override the submissions collection with `webhooks: true`: that would re-enable the raw `entry.*` events and deliver the PII-bearing submission content. Any collection can adopt the same pattern via the `webhooks` option: `{ record: false }` suppresses the default events, and `{ record: false, emit: { event, fields } }` additionally emits a curated event carrying only the allowlisted `fields`. Recording is on by default for everything else.
+
+A collection or single created in the **Schema Builder** can be opted out the same way, without touching code: **Settings → Advanced → Webhook recording**. The choice is stored on the entity's registry row, so it holds across restarts. For code-first entities the `webhooks` option in config remains the source of truth and is republished on every boot.
 
 ## Field types
 
@@ -94,15 +106,15 @@ See the [Field types reference](https://nextlyhq.com/docs/plugins/form-builder#f
 - Server helpers: `submitForm`, `validateSubmission`, `getFormSubmissionStats`, `createFormConfig`, `validateFormConfig`, `assertValidFormConfig`
 - Export utilities: `exportToCSV`, `exportToJSON`, `exportAndDownload`, `downloadFile`, `generateExportFilename`
 - Collections: `formsCollection`, `submissionsCollection`
-- Type exports: `FormDocument`, `SubmissionDocument`, `FormSubmission`, `EmailConfig`, `WebhookConfig`, `WebhookEvent`, `FormFieldOption`, `SubmissionListProps`, `SubmissionDetailProps`
+- Type exports: `FormDocument`, `SubmissionDocument`, `FormSubmission`, `FormNotification`, `EmailConfig`, `FormFieldOption`
 
 ## Compatibility
 
-| Tool              | Version |
-| ----------------- | ------- |
-| Node.js           | 20+     |
-| `nextly`          | 0.0.x   |
-| `@nextlyhq/admin` | 0.0.x   |
+| Tool              | Version       |
+| ----------------- | ------------- |
+| Node.js           | 22.12+ or 24+ |
+| `nextly`          | 0.0.x         |
+| `@nextlyhq/admin` | 0.0.x         |
 
 Plugins can break across minor versions during alpha. Pin exact versions of `nextly`, `@nextlyhq/admin`, and this plugin together.