@nextlyhq/plugin-form-builder 0.0.2-alpha.27 → 0.0.2-alpha.29

package/dist/components/index.d.ts

@@ -1,3 +1,3 @@
-export { J as SubmissionDetail, t as SubmissionDetailProps, K as SubmissionList, u as SubmissionListProps } from '../index-C0kBvYjm.js';
+export { J as SubmissionDetail, t as SubmissionDetailProps, K as SubmissionList, u as SubmissionListProps } from '../index-BRumOEsE.js';
 import 'react';
 import 'nextly';

package/dist/{index-C0kBvYjm.d.ts → index-BRumOEsE.d.ts}

@@ -33,6 +33,27 @@ interface EmailConfig {
     cc?: string | string[];
     bcc?: string | string[];
 }
+/**
+ * @experimental A resolved outgoing form notification (template-based) as built
+ * by the submission handler, before it is sent. This is the value transformed by
+ * the `form-builder.beforeEmail` D63 filter seam.
+ */
+interface FormEmailNotification {
+    /** Resolved recipient address. */
+    to: string;
+    /** Email template slug to render. */
+    templateSlug: string;
+    /** Template variables (submitted data + form metadata). */
+    variables: Record<string, unknown>;
+    /** Email provider id; undefined = system default. */
+    providerId?: string;
+    /** CC addresses, if any. */
+    cc?: string[];
+    /** BCC addresses, if any. */
+    bcc?: string[];
+    /** Source notification id; undefined for filter-injected emails. */
+    notificationId?: string;
+}
 /**
  * A single email notification integration stored on a form.
  * Matches the shape saved by the form builder admin UI.
@@ -200,26 +221,6 @@ interface FormBuilderPluginOptions {
             defaultFields: FieldDefinition[];
         }) => FieldDefinition[]);
     };
-    /**
-     * @deprecated Use `formOverrides` and `formSubmissionOverrides` instead.
-     * This option is kept for backward compatibility.
-     */
-    collections?: {
-        forms?: Partial<CollectionConfig> & {
-            slug?: string;
-            labels?: {
-                singular?: string;
-                plural?: string;
-            };
-        };
-        submissions?: Partial<CollectionConfig> & {
-            slug?: string;
-            labels?: {
-                singular?: string;
-                plural?: string;
-            };
-        };
-    };
     /**
      * Configure which field types are available in the form builder.
      *
@@ -272,25 +273,24 @@ interface FormBuilderPluginOptions {
     /**
      * Hook called before sending email notifications.
      *
-     * Allows modifying, adding, or filtering emails before they are sent.
-     * Return the modified emails array.
+     * Runs as the `form-builder.beforeEmail` D63 filter: the resolved outgoing
+     * notifications (template + recipient + variables) are threaded through this
+     * callback before they are sent. Allows modifying, adding, or filtering the
+     * outgoing notifications. Return the modified array.
      *
      * @example
      * ```typescript
      * beforeEmail: async ({ emails, form, submission }) => {
-     *   // Add BCC to all emails
-     *   return emails.map(email => ({
-     *     ...email,
-     *     bcc: ['archive@example.com'],
-     *   }));
+     *   // Add BCC to all outgoing notifications
+     *   return emails.map((e) => ({ ...e, bcc: ['archive@example.com'] }));
      * }
      * ```
      */
     beforeEmail?: (args: {
-        emails: EmailConfig[];
+        emails: FormEmailNotification[];
         form: FormDocument;
         submission: SubmissionDocument;
-    }) => Promise<EmailConfig[]> | EmailConfig[];
+    }) => Promise<FormEmailNotification[]> | FormEmailNotification[];
     /**
      * Email notification settings.
      */

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import * as nextly from 'nextly';
-import { PluginDefinition, CollectionConfig, PluginContext } from 'nextly';
-import { R as ResolvedFormBuilderConfig, F as FormBuilderPluginOptions, a as FormConfig, b as FormSettings, c as FormNotifications, C as CheckboxFormField, D as DateFormField, E as EmailFormField, d as FileFormField, H as HiddenFormField, N as NumberFormField, P as PhoneFormField, e as RadioFormField, S as SelectFormField, T as TextFormField, f as TextareaFormField, g as TimeFormField, U as UrlFormField, h as ConditionalLogic, i as FormField, j as SubmissionDocument, k as FormDocument, W as WebhookEvent } from './index-C0kBvYjm.js';
-export { B as BaseFormField, l as ConditionalLogicCondition, m as EmailConfig, n as FieldBlockConfig, o as FormAccess, p as FormFieldType, q as FormHookContext, r as FormHooks, s as FormSubmission, t as SubmissionDetailProps, u as SubmissionListProps, V as ValidationRules, v as WebhookConfig, w as isCheckboxFormField, x as isEmailFormField, y as isFileFormField, z as isFormField, A as isFormFieldType, G as isSelectFormField, I as isTextFormField } from './index-C0kBvYjm.js';
+import { CollectionConfig, PluginContext } from 'nextly';
+import { PluginDefinition } from '@nextlyhq/plugin-sdk';
+import { R as ResolvedFormBuilderConfig, F as FormBuilderPluginOptions, a as FormConfig, b as FormSettings, c as FormNotifications, C as CheckboxFormField, D as DateFormField, E as EmailFormField, d as FileFormField, H as HiddenFormField, N as NumberFormField, P as PhoneFormField, e as RadioFormField, S as SelectFormField, T as TextFormField, f as TextareaFormField, g as TimeFormField, U as UrlFormField, h as ConditionalLogic, i as FormField, j as SubmissionDocument, k as FormDocument, W as WebhookEvent } from './index-BRumOEsE.js';
+export { B as BaseFormField, l as ConditionalLogicCondition, m as EmailConfig, n as FieldBlockConfig, o as FormAccess, p as FormFieldType, q as FormHookContext, r as FormHooks, s as FormSubmission, t as SubmissionDetailProps, u as SubmissionListProps, V as ValidationRules, v as WebhookConfig, w as isCheckboxFormField, x as isEmailFormField, y as isFileFormField, z as isFormField, A as isFormFieldType, G as isSelectFormField, I as isTextFormField } from './index-BRumOEsE.js';
 import { z } from 'zod';
 import 'react';
 
@@ -463,7 +464,7 @@ declare const text: (config: Omit<TextFormField, "type">) => TextFormField;
  *   name: 'workEmail',
  *   label: 'Work Email',
  *   required: true,
- *   placeholder: 'you@company.com',
+ *   placeholder: 'you@nextly.local',
  * })
  * ```
  */
@@ -1528,7 +1529,7 @@ declare function triggerWebhooks(options: TriggerWebhooksOptions): Promise<Trigg
  * // In submission handler - fire and forget
  * fireWebhooks(
  *   { event: 'submission.created', form, submission },
- *   pluginContext.infra.logger
+ *   pluginContext.logger
  * );
  *
  * // Continue with response immediately

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/plugin.ts
-import { getCollectionsHandler } from "nextly/runtime";
+import { definePlugin } from "@nextlyhq/plugin-sdk";
 
 // src/collections/forms.ts
 import {
@@ -425,8 +425,8 @@ function submissionsCollection(pluginConfig) {
 
 // src/plugin.ts
 function resolveConfig(options) {
-  const formOverrides = options.formOverrides || options.collections?.forms || {};
-  const submissionOverrides = options.formSubmissionOverrides || options.collections?.submissions || {};
+  const formOverrides = options.formOverrides || {};
+  const submissionOverrides = options.formSubmissionOverrides || {};
   return {
     formOverrides: {
       ...formOverrides,
@@ -495,41 +495,108 @@ function formBuilder(options = {}) {
   const resolvedConfig = resolveConfig(options);
   const formsCol = formsCollection(resolvedConfig);
   const submissionsCol = submissionsCollection(resolvedConfig);
-  const plugin = {
+  const plugin = definePlugin({
     name: "@nextlyhq/plugin-form-builder",
-    version: "0.0.8",
-    collections: [formsCol, submissionsCol],
+    // Keep in sync with package.json `version` (guarded by package-metadata.test).
+    version: "0.0.2-alpha.24",
+    nextly: ">=0.0.2-alpha.21",
+    // Declarative schema: the merged pipeline folds these into the
+    // app schema — no manual `setup()` append needed. Just register the plugin.
+    contributes: {
+      collections: [formsCol, submissionsCol],
+      // Custom permission — gates submission export beyond CRUD. The
+      // canonical example third-party plugin authors copy.
+      permissions: [
+        {
+          action: "export",
+          resource: "submissions",
+          label: "Export Submissions",
+          description: "Export form submissions as CSV/JSON",
+          group: "Form Builder"
+        }
+      ],
+      // HTTP route — exported at
+      // /api/plugins/@nextlyhq/plugin-form-builder/submissions/export. Secure by
+      // default: gated by the custom `export-submissions` permission. Reads
+      // via the secure-by-default service path as the authed user and
+      // resolves its OWN slug through `ctx.self`. The canonical
+      // contributes.routes example for third-party authors.
+      routes: [
+        {
+          method: "GET",
+          path: "/submissions/export",
+          requiredPermission: "export-submissions",
+          handler: async (_req, ctx) => {
+            const declaredSlug = resolvedConfig.formSubmissionOverrides.slug;
+            const slug = ctx.self.collections[declaredSlug] ?? declaredSlug;
+            const result = await ctx.services.collections.listEntries(
+              slug,
+              {},
+              { as: "user", user: ctx.user ?? void 0 }
+            );
+            return Response.json({ items: result.data });
+          }
+        }
+      ],
+      // Admin UI — the canonical contributes.admin example. Paths
+      // are the components form-builder's `/admin` module self-registers (kept
+      // as literals so this node entry stays React-free). menu links to
+      // the forms collection; settings renders the builder UI at
+      // /admin/plugins/<slug>; a custom page is gated by export-submissions;
+      // a submissions beforeList view injects the filter above the list.
+      admin: {
+        menu: [
+          {
+            label: "Forms",
+            to: `/admin/collections/${resolvedConfig.formOverrides.slug}`,
+            icon: "file-text",
+            order: 50,
+            requiredPermission: `read-${resolvedConfig.formOverrides.slug}`
+          }
+        ],
+        settings: {
+          component: "@nextlyhq/plugin-form-builder/admin#FormBuilderView"
+        },
+        pages: [
+          {
+            path: "submissions",
+            component: "@nextlyhq/plugin-form-builder/admin#SubmissionsFilter",
+            requiredPermission: "export-submissions"
+          }
+        ],
+        views: {
+          [resolvedConfig.formSubmissionOverrides.slug]: {
+            beforeList: "@nextlyhq/plugin-form-builder/admin#SubmissionsFilter"
+          }
+        }
+      }
+    },
     admin: {
       order: 50,
       description: "Create and manage forms with submission tracking"
     },
-    // -- Config transformer --------------------------------------------------
-    // Automatically adds plugin collections so users don't have to spread them.
-    config(config) {
-      const existing = config.collections || [];
-      const formsSlug = resolvedConfig.formOverrides.slug;
-      const submissionsSlug = resolvedConfig.formSubmissionOverrides.slug;
-      const toAdd = [];
-      if (!existing.some((c) => c.slug === formsSlug))
-        toAdd.push(formsCol);
-      if (!existing.some((c) => c.slug === submissionsSlug))
-        toAdd.push(submissionsCol);
-      return { ...config, collections: [...existing, ...toAdd] };
-    },
     // -- Init ----------------------------------------------------------------
     // Registers an afterCreate hook on submissions to send email notifications.
     init(nextly) {
-      const submissionSlug = resolvedConfig.formSubmissionOverrides.slug;
-      const guardKey = `__formBuilder_afterCreate_${submissionSlug}`;
-      const g = globalThis;
-      if (g[guardKey]) return;
-      g[guardKey] = true;
-      nextly.infra.logger.info("Form Builder plugin initialized", {
+      const declaredSubmissionsSlug = resolvedConfig.formSubmissionOverrides.slug;
+      const submissionSlug = nextly.self.collections[declaredSubmissionsSlug] ?? declaredSubmissionsSlug;
+      nextly.logger.info("Form Builder plugin initialized", {
         formsCollection: resolvedConfig.formOverrides.slug,
         submissionsCollection: submissionSlug,
         enabledFields: Object.entries(resolvedConfig.fields).filter(([, on]) => on).map(([name]) => name)
       });
       nextly.__formBuilderConfig = resolvedConfig;
+      if (resolvedConfig.beforeEmail) {
+        nextly.filters.add(
+          "form-builder.beforeEmail",
+          (emails, ctx) => resolvedConfig.beforeEmail({
+            emails,
+            // Boundary: loose runtime documents → the user's typed contract.
+            form: ctx.form,
+            submission: ctx.submission
+          })
+        );
+      }
       nextly.hooks.on(
         "afterCreate",
         submissionSlug,
@@ -538,7 +605,7 @@ function formBuilder(options = {}) {
         }
       );
     }
-  };
+  });
   return {
     plugin,
     collections: [formsCol, submissionsCol],
@@ -596,42 +663,63 @@ async function handleSubmissionCreated(context, config, nextly) {
   const formFields = Array.isArray(form.fields) ? form.fields : [];
   const fileAttachments = collectAttachmentInputs(formFields, submittedData);
   const seen = /* @__PURE__ */ new Set();
+  const emails = [];
   for (const notification of notifications) {
     if (!notification.enabled || !notification.templateSlug) continue;
     const key = notification.id || `${notification.to}::${notification.templateSlug}`;
     if (seen.has(key)) continue;
     seen.add(key);
+    const to = notification.recipientType === "field" ? resolveFieldRef(notification.to, submittedData) : notification.to;
+    if (!to) {
+      nextly.logger.warn?.(
+        "Form Builder: empty recipient, skipping notification",
+        { notificationId: notification.id, formSlug: form.slug }
+      );
+      continue;
+    }
+    const cc = Array.isArray(notification.cc) && notification.cc.length ? notification.cc : void 0;
+    const bcc = Array.isArray(notification.bcc) && notification.bcc.length ? notification.bcc : void 0;
+    emails.push({
+      to,
+      templateSlug: notification.templateSlug,
+      variables: {
+        ...submittedData,
+        formName: form.name,
+        submissionId: submission.id
+      },
+      providerId: notification.providerId,
+      cc,
+      bcc,
+      notificationId: notification.id
+    });
+  }
+  if (emails.length === 0) return;
+  const finalEmails = await nextly.filters.apply("form-builder.beforeEmail", emails, { form, submission });
+  for (const email2 of finalEmails) {
     try {
-      const to = notification.recipientType === "field" ? resolveFieldRef(notification.to, submittedData) : notification.to;
-      if (!to) {
-        nextly.infra.logger.warn?.(
-          "Form Builder: empty recipient, skipping notification",
-          { notificationId: notification.id, formSlug: form.slug }
-        );
-        continue;
-      }
-      const cc = Array.isArray(notification.cc) && notification.cc.length ? notification.cc : void 0;
-      const bcc = Array.isArray(notification.bcc) && notification.bcc.length ? notification.bcc : void 0;
       await emailService.sendWithTemplate(
-        notification.templateSlug,
-        to,
-        { ...submittedData, formName: form.name, submissionId: submission.id },
+        email2.templateSlug,
+        email2.to,
+        email2.variables,
         {
-          providerId: notification.providerId,
-          cc,
-          bcc,
+          providerId: email2.providerId,
+          cc: email2.cc,
+          bcc: email2.bcc,
           attachments: fileAttachments.length > 0 ? fileAttachments : void 0
         }
       );
-      nextly.infra.logger.info?.("Form Builder: notification sent", {
+      nextly.logger.info?.("Form Builder: notification sent", {
         formSlug: form.slug,
-        to,
-        templateSlug: notification.templateSlug,
+        to: email2.to,
+        templateSlug: email2.templateSlug,
+        notificationId: email2.notificationId,
         attachmentCount: fileAttachments.length
       });
     } catch (err) {
-      nextly.infra.logger.error?.("Form Builder: notification failed", {
-        notificationId: notification.id,
+      nextly.logger.error?.("Form Builder: notification failed", {
+        to: email2.to,
+        templateSlug: email2.templateSlug,
+        notificationId: email2.notificationId,
         error: err instanceof Error ? err.message : String(err)
       });
     }
@@ -639,27 +727,14 @@ async function handleSubmissionCreated(context, config, nextly) {
 }
 async function fetchParentForm(config, formId, nextly) {
   try {
-    const handler = getCollectionsHandler();
-    if (!handler) {
-      nextly.infra.logger.warn?.(
-        "Form Builder: CollectionsHandler unavailable, skipping notifications"
-      );
-      return null;
-    }
-    const result = await handler.getEntry({
-      collectionName: config.formOverrides.slug,
-      entryId: formId,
-      overrideAccess: true
-    });
-    const fromData = result?.data;
-    if (fromData) return fromData;
-    const fromDoc = result?.doc;
-    if (fromDoc && typeof fromDoc === "object") {
-      return fromDoc;
-    }
-    return null;
+    const form = await nextly.services.collections.findEntryById(
+      config.formOverrides.slug,
+      formId,
+      { as: "system" }
+    );
+    return form;
   } catch (err) {
-    nextly.infra.logger.error?.("Form Builder: failed to fetch form", {
+    nextly.logger.error?.("Form Builder: failed to fetch form", {
       formId,
       error: err instanceof Error ? err.message : String(err)
     });
@@ -2007,7 +2082,7 @@ async function submitForm(options, context) {
   const { formSlug, data, metadata } = options;
   const { pluginContext, pluginConfig } = context;
   const { collections } = pluginContext.services;
-  const { logger } = pluginContext.infra;
+  const { logger } = pluginContext;
   try {
     const form = await fetchFormBySlug(formSlug, pluginConfig, pluginContext);
     if (!form) {
@@ -2076,8 +2151,9 @@ async function submitForm(options, context) {
     const submission = await collections.createEntry(
       pluginConfig.formSubmissionOverrides.slug,
       submissionData,
-      {}
-      // Empty context - submission creation is public
+      // Public form submission — create as system. No ambient user; an
+      // empty context already resolves to system, but be explicit.
+      { as: "system" }
     );
     logger.info?.("Form submission created successfully", {
       formSlug,
@@ -2105,19 +2181,10 @@ async function fetchFormBySlug(slug, pluginConfig, pluginContext) {
     const { collections } = pluginContext.services;
     const result = await collections.listEntries(
       pluginConfig.formOverrides.slug,
-      {
-        pagination: { limit: 100 }
-        // Fetch enough to find the form
-      },
-      {}
-      // Empty context for public access
-    );
-    if (!result.data || result.data.length === 0) {
-      return null;
-    }
-    const form = result.data.find(
-      (entry) => entry.slug === slug
+      { where: { slug: { equals: slug } }, pagination: { limit: 1 } },
+      { as: "system" }
     );
+    const form = result.data?.[0];
     return form ? form : null;
   } catch {
     return null;
@@ -2191,33 +2258,28 @@ async function getFormSubmissionStats(formSlug, context) {
     return null;
   }
   try {
-    const result = await collections.listEntries(
-      pluginConfig.formSubmissionOverrides.slug,
-      {
-        pagination: { limit: 1e3 }
-        // Reasonable limit for stats
-      },
-      {}
-    );
-    if (!result.data) {
-      return { total: 0, new: 0, read: 0, archived: 0 };
-    }
-    const submissions = result.data.filter(
-      (entry) => entry.form === form.id
-    );
-    const stats = {
-      total: submissions.length,
-      new: 0,
-      read: 0,
-      archived: 0
-    };
-    for (const sub of submissions) {
-      const status = sub.status;
-      if (status === "new") stats.new++;
-      else if (status === "read") stats.read++;
-      else if (status === "archived") stats.archived++;
-    }
-    return stats;
+    const submissionsSlug = pluginConfig.formSubmissionOverrides.slug;
+    const sys = { as: "system" };
+    const base = { form: { equals: form.id } };
+    const [total, newCount, read, archived] = await Promise.all([
+      collections.count(submissionsSlug, { where: base }, sys),
+      collections.count(
+        submissionsSlug,
+        { where: { ...base, status: { equals: "new" } } },
+        sys
+      ),
+      collections.count(
+        submissionsSlug,
+        { where: { ...base, status: { equals: "read" } } },
+        sys
+      ),
+      collections.count(
+        submissionsSlug,
+        { where: { ...base, status: { equals: "archived" } } },
+        sys
+      )
+    ]);
+    return { total, new: newCount, read, archived };
   } catch {
     return null;
   }