@aphexcms/plugin-forms 0.1.0

package/README.md

@@ -0,0 +1,52 @@
+# @aphexcms/plugin-forms
+
+Editor-composed forms for [AphexCMS](https://github.com/IcelandicIcecream/aphex) — contact forms, signups, surveys — built in the admin rather than in code, with submissions stored as documents.
+
+📚 **Documentation: [docs.getaphex.com/forms](https://docs.getaphex.com/forms)**
+
+## Install
+
+```bash
+pnpm add @aphexcms/plugin-forms
+```
+
+```ts title="src/lib/plugins.ts"
+import { formsPlugin } from '@aphexcms/plugin-forms';
+
+export const plugins = [
+	formsPlugin({
+		// Address notification emails come from. Falls back to APHEX_EMAIL_FROM.
+		from: 'Acme <forms@example.com>'
+	})
+];
+```
+
+The plugin is self-contained: it registers its own schemas, its submission endpoint, its admin tool, and its notification consumer. Nothing else in `aphex.config.ts` needs to know it exists.
+
+After adding it, regenerate types with the plugins path as the third argument, or the `form` and `formSubmission` collections stay untyped:
+
+```bash
+aphex generate:types ./src/lib/schemaTypes/index.ts ./src/lib/generated-types.ts ./src/lib/plugins.ts
+```
+
+## What you get
+
+- A **form builder** in the admin — fields, labels, options, required flags, and confirmation behaviour, all editable by a non-developer.
+- **Stored submissions** as ordinary documents, so they're searchable, exportable, and subject to the same access control as everything else.
+- **Validation** derived from the form definition and enforced server-side, not just in the browser.
+- **Spam handling** — a honeypot field plus rate limiting on the submission endpoint.
+- **Email notifications** via an event consumer, so a failed send retries with backoff instead of vanishing.
+
+## Submissions carry personal data
+
+They usually contain names and email addresses, so the default access rule on `formSubmission` is deliberately stricter than on ordinary content. Widen it knowingly, and check it before exposing submissions through the HTTP or GraphQL APIs.
+
+## Multi-tenancy
+
+The endpoint derives the organization from the globally unique published form ID and never accepts
+an organization ID from the visitor. The submission and its notification event then commit in one
+transaction within that exact tenant.
+
+## License
+
+MIT

package/dist/compile.d.ts

@@ -0,0 +1,75 @@
+import type { FormDefinition } from '@aphexcms/cms-core';
+/**
+ * Turn a `form` document — what an editor composed in the studio — into a
+ * `FormDefinition`, the developer-authored form shape cms-core already knows how
+ * to validate.
+ *
+ * This is the whole reason the plugin is small. `validateFormData` runs a form's
+ * fields through the same engine the admin uses for documents, so "required",
+ * "is an email", "within this range" and "one of these options" are already
+ * implemented, already consistent with the rest of the CMS, and already returning
+ * errors in the shape every other surface uses. Hand-rolling a second validator
+ * for submissions would be a second set of rules to keep in step — and the one
+ * that runs against untrusted input is the worst place to have a divergent copy.
+ *
+ * The two layers meet here: `defineForm` is a form a developer writes in code;
+ * a `form` document is a form an editor drew in the studio. Compiling the second
+ * into the first means only the authoring differs.
+ */
+/** One field as stored on a `form` document. */
+export interface FormFieldValue {
+    _type: string;
+    _key?: string;
+    name?: string;
+    label?: string;
+    required?: boolean;
+    width?: 'full' | 'half';
+    placeholder?: string;
+    defaultValue?: string | boolean;
+    rows?: number;
+    min?: number;
+    max?: number;
+    options?: Array<{
+        label?: string;
+        value?: string;
+    }>;
+    message?: unknown;
+}
+/** A `form` document, as far as this plugin cares. */
+export interface FormDocument {
+    id: string;
+    _meta?: {
+        publishedHash?: string | null;
+        status?: string | null;
+    };
+    title?: string;
+    fields?: FormFieldValue[];
+    submitButtonLabel?: string;
+    confirmationType?: 'message' | 'redirect';
+    confirmationMessage?: unknown;
+    redirectUrl?: string;
+    emails?: NotificationEmailValue[];
+}
+export interface NotificationEmailValue {
+    _type?: string;
+    _key?: string;
+    to?: string;
+    replyTo?: string;
+    subject?: string;
+    message?: string;
+}
+/** Field kinds that collect an answer. `formMessage` is display-only. */
+export declare function isInputField(field: FormFieldValue): boolean;
+/** The stored value for a select option — its `value`, or the label when blank. */
+export declare function optionValue(option: {
+    label?: string;
+    value?: string;
+}): string;
+/**
+ * Compile a `form` document into a `FormDefinition` that `validateFormData` can
+ * run. `store` and `notifyEmail` are deliberately left off — this plugin stores
+ * submissions as documents and sends notifications from its own consumer, so the
+ * definition is used purely as a validation contract.
+ */
+export declare function compileForm(doc: FormDocument): FormDefinition;
+//# sourceMappingURL=compile.d.ts.map

package/dist/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../src/lib/compile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEhE;;;;;;;;;;;;;;;;GAgBG;AAEH,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;IAC1C,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,sBAAsB,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,sBAAsB;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAE3D;AAED,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAE9E;AA+FD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,cAAc,CAkB7D"}

package/dist/compile.js

@@ -0,0 +1,119 @@
+/** Field kinds that collect an answer. `formMessage` is display-only. */
+export function isInputField(field) {
+    return field._type !== 'formMessage' && typeof field.name === 'string' && field.name.length > 0;
+}
+/** The stored value for a select option — its `value`, or the label when blank. */
+export function optionValue(option) {
+    return (option.value ?? '').trim() || (option.label ?? '').trim();
+}
+/**
+ * Compile one authored field into a CMS `Field`.
+ *
+ * Returns `null` for anything that collects nothing, so the caller can filter
+ * rather than branch. An unrecognised `_type` also returns `null`: a form saved
+ * by a newer version of this plugin must not have an unknown field silently
+ * treated as free text.
+ */
+function toField(field) {
+    if (!isInputField(field))
+        return null;
+    const name = field.name;
+    const title = field.label ?? name;
+    const required = field.required === true;
+    switch (field._type) {
+        case 'formText':
+            return {
+                name,
+                type: 'string',
+                title,
+                validation: (Rule) => (required ? Rule.required() : Rule.optional())
+            };
+        case 'formEmail':
+            return {
+                name,
+                type: 'string',
+                title,
+                // `.email()` on an optional field only judges values that are present,
+                // so a blank optional email stays valid.
+                validation: (Rule) => (required ? Rule.required().email() : Rule.optional().email())
+            };
+        case 'formTextarea':
+            return {
+                name,
+                type: 'text',
+                title,
+                validation: (Rule) => (required ? Rule.required() : Rule.optional())
+            };
+        case 'formNumber':
+            return {
+                name,
+                type: 'number',
+                title,
+                validation: (Rule) => {
+                    let rule = required ? Rule.required() : Rule.optional();
+                    if (typeof field.min === 'number')
+                        rule = rule.min(field.min);
+                    if (typeof field.max === 'number')
+                        rule = rule.max(field.max);
+                    return rule;
+                }
+            };
+        case 'formCheckbox':
+            return {
+                name,
+                type: 'boolean',
+                title,
+                /*
+                 * "Required" on a checkbox means ticked, not present — it's the consent
+                 * box. `Rule.required()` would accept `false`, which is exactly the case
+                 * the editor is trying to prevent, so this is a custom rule instead.
+                 */
+                validation: (Rule) => required
+                    ? Rule.custom((value) => value === true || 'This must be ticked')
+                    : Rule.optional()
+            };
+        case 'formSelect': {
+            const values = (field.options ?? []).map(optionValue).filter(Boolean);
+            return {
+                name,
+                type: 'string',
+                title,
+                list: values,
+                validation: (Rule) => (required ? Rule.required() : Rule.optional()).custom((value) => {
+                    if (value === undefined || value === null || value === '')
+                        return true;
+                    // Never trust the posted value to be one the form offered: a select
+                    // is a client-side constraint, and the request isn't.
+                    return values.includes(String(value)) || 'Not one of the available options';
+                })
+            };
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Compile a `form` document into a `FormDefinition` that `validateFormData` can
+ * run. `store` and `notifyEmail` are deliberately left off — this plugin stores
+ * submissions as documents and sends notifications from its own consumer, so the
+ * definition is used purely as a validation contract.
+ */
+export function compileForm(doc) {
+    const fields = (doc.fields ?? []).map(toField).filter((f) => f !== null);
+    return {
+        id: doc.id,
+        title: doc.title ?? 'Form',
+        fields,
+        // Trim every string before validation. This is the transform half — the one
+        // thing validation can't do — so " " fails a required check instead of
+        // passing it.
+        transform: (data) => {
+            const out = {};
+            for (const [key, value] of Object.entries(data)) {
+                out[key] = typeof value === 'string' ? value.trim() : value;
+            }
+            return out;
+        }
+    };
+}
+//# sourceMappingURL=compile.js.map

package/dist/compile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.js","sourceRoot":"","sources":["../src/lib/compile.ts"],"names":[],"mappings":"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"}

package/dist/events.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+/**
+ * Emitted once a submission has been stored.
+ *
+ * Carries identifiers only, in line with the rest of the event catalog: the log
+ * is not a content mirror, and a submission is the one payload most likely to
+ * hold a person's name, email and message. Keeping those out of the immutable
+ * log means a deletion request can be honoured by deleting the submission
+ * document — an append-only log that quietly held a second copy would make that
+ * impossible.
+ *
+ * The notification consumer reads the submission back to build the email.
+ */
+export declare const formSubmissionCreated: import("@aphexcms/cms-core").EventDefinition<"forms.submission.created", z.ZodObject<{
+    submissionId: z.ZodString;
+    formId: z.ZodString;
+}, z.core.$strip>>;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/lib/events.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB;;;kBAMjC,CAAC"}

package/dist/events.js

@@ -0,0 +1,19 @@
+import { defineEvent } from '@aphexcms/cms-core';
+import { z } from 'zod';
+/**
+ * Emitted once a submission has been stored.
+ *
+ * Carries identifiers only, in line with the rest of the event catalog: the log
+ * is not a content mirror, and a submission is the one payload most likely to
+ * hold a person's name, email and message. Keeping those out of the immutable
+ * log means a deletion request can be honoured by deleting the submission
+ * document — an append-only log that quietly held a second copy would make that
+ * impossible.
+ *
+ * The notification consumer reads the submission back to build the email.
+ */
+export const formSubmissionCreated = defineEvent('forms.submission.created', z.object({
+    submissionId: z.string(),
+    formId: z.string()
+}));
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/lib/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,WAAW,CAC/C,0BAA0B,EAC1B,CAAC,CAAC,MAAM,CAAC;IACR,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IACxB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;CAClB,CAAC,CACF,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import type { SchemaAccess } from '@aphexcms/cms-core';
+export interface FormsPluginOptions {
+    /**
+     * The address notification emails are sent from. The app owns its sending
+     * identity, so this is passed in rather than guessed; falls back to
+     * `APHEX_EMAIL_FROM`. With neither set, submissions are still stored and a
+     * configured notification retries, then dead-letters visibly in Activity.
+     */
+    from?: string;
+    /**
+     * Override submission collection access. Defaults to owner/admin read and
+     * delete access, with direct create/update/publish operations blocked. Partial
+     * overrides are merged with those defaults, so adding a custom reviewer role
+     * does not accidentally reopen writes.
+     */
+    submissionAccess?: SchemaAccess;
+}
+export declare function formsPlugin(options?: FormsPluginOptions): import("@aphexcms/cms-core").CMSPlugin;
+export { defaultSubmissionAccess, formSchema, formSubmissionSchema, formFieldTypes } from './schema.js';
+export { compileForm, isInputField, optionValue } from './compile.js';
+export type { FormDocument, FormFieldValue, NotificationEmailValue } from './compile.js';
+export { formSubmissionCreated } from './events.js';
+export { renderTemplate, fieldLabels, toStoredValue } from './template.js';
+export type { Answer } from './template.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/lib/index.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAA0B,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAQ/E,MAAM,WAAW,kBAAkB;IAClC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,YAAY,CAAC;CAChC;AAOD,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,0CAyC3D;AAED,OAAO,EACN,uBAAuB,EACvB,UAAU,EACV,oBAAoB,EACpB,cAAc,EACd,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACnE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACtF,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACxE,YAAY,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,83 @@
+/**
+ * First-party form-builder plugin — comparable to `@payloadcms/plugin-form-builder`.
+ *
+ * `formsPlugin()` contributes everything a form needs and nothing an app has to
+ * wire:
+ *
+ *  - two collections, `form` and `formSubmission` (`aphex/schema`)
+ *  - `POST /api/form-submissions`, public, with a honeypot and rate limiting
+ *    (`aphex/server/route`)
+ *  - a consumer that emails the form's notification list out of band
+ *    (`aphex/event/consumer`)
+ *
+ * Add it to the plugins array and an editor can build a form; nothing goes in
+ * `aphex.config.ts` beyond that.
+ *
+ * ## What the app still owns
+ *
+ * Rendering. The plugin defines what a form *is* and what happens when one is
+ * submitted; how it looks belongs to the site, so the template ships a `FormBlock`
+ * component that reads a form document and posts to the endpoint. That split is
+ * deliberate — a plugin that shipped markup would have to ship a design with it.
+ *
+ * ## Layering
+ *
+ * cms-core already has `defineForm` — a form a *developer* writes in code. This
+ * plugin is the same idea with the authoring moved into the studio: a `form`
+ * document is compiled into a `FormDefinition` and validated by the identical
+ * engine (see `compile.ts`). One validator, two ways to author.
+ */
+import { definePlugin, effectiveOrganizationRole } from '@aphexcms/cms-core';
+import { formSchema, formSubmissionSchema } from './schema.js';
+import { handleSubmit } from './submit.js';
+import { notifyOnSubmission } from './notify.js';
+import { formSubmissionCreated } from './events.js';
+const PLUGIN_ID = '@aphexcms/plugin-forms';
+function strictSubmissionRule(rule) {
+    if (!Array.isArray(rule))
+        return rule;
+    return ({ auth }) => rule.includes(effectiveOrganizationRole(auth) ?? '');
+}
+export function formsPlugin(options = {}) {
+    const mergedAccess = { ...formSubmissionSchema.access, ...options.submissionAccess };
+    const submissionSchema = {
+        ...formSubmissionSchema,
+        access: Object.fromEntries(Object.entries(mergedAccess).map(([operation, rule]) => [
+            operation,
+            strictSubmissionRule(rule)
+        ]))
+    };
+    const parts = [
+        {
+            implements: 'aphex/schema',
+            schemas: [formSchema, submissionSchema]
+        },
+        {
+            implements: 'aphex/server/route',
+            id: 'forms.submit',
+            method: 'POST',
+            path: '/form-submissions',
+            handler: handleSubmit,
+            /*
+             * The one endpoint here that must be open: a form is for people who
+             * don't have accounts. Opting out of the capability gate is deliberate
+             * and the handler does its own verification — it validates against the
+             * form's declared fields, drops undeclared keys, rate-limits per IP and
+             * carries a honeypot. See `submit.ts`.
+             */
+            requiredCapabilities: 'public'
+        },
+        {
+            implements: 'aphex/event/consumer',
+            id: 'forms.notify',
+            events: [formSubmissionCreated.type],
+            handler: notifyOnSubmission(options.from)
+        }
+    ];
+    return definePlugin({ name: PLUGIN_ID, version: '0.1.0', parts });
+}
+export { defaultSubmissionAccess, formSchema, formSubmissionSchema, formFieldTypes } from './schema.js';
+export { compileForm, isInputField, optionValue } from './compile.js';
+export { formSubmissionCreated } from './events.js';
+export { renderTemplate, fieldLabels, toStoredValue } from './template.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAE,YAAY,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAE7E,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEjD,MAAM,SAAS,GAAG,wBAAwB,CAAC;AAoB3C,SAAS,oBAAoB,CAAC,IAA4B;IACzD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,yBAAyB,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,UAA8B,EAAE;IAC3D,MAAM,YAAY,GAAG,EAAE,GAAG,oBAAoB,CAAC,MAAM,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IACrF,MAAM,gBAAgB,GAAgC;QACrD,GAAG,oBAAoB;QACvB,MAAM,EAAE,MAAM,CAAC,WAAW,CACzB,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;YACvD,SAAS;YACT,oBAAoB,CAAC,IAAI,CAAC;SAC1B,CAAC,CACc;KACjB,CAAC;IAEF,MAAM,KAAK,GAAiB;QAC3B;YACC,UAAU,EAAE,cAAc;YAC1B,OAAO,EAAE,CAAC,UAAU,EAAE,gBAAgB,CAAC;SACvC;QACD;YACC,UAAU,EAAE,oBAAoB;YAChC,EAAE,EAAE,cAAc;YAClB,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,mBAAmB;YACzB,OAAO,EAAE,YAAY;YACrB;;;;;;eAMG;YACH,oBAAoB,EAAE,QAAQ;SAC9B;QACD;YACC,UAAU,EAAE,sBAAsB;YAClC,EAAE,EAAE,cAAc;YAClB,MAAM,EAAE,CAAC,qBAAqB,CAAC,IAAI,CAAC;YACpC,OAAO,EAAE,kBAAkB,CAAC,OAAO,CAAC,IAAI,CAAC;SACzC;KACD,CAAC;IAEF,OAAO,YAAY,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;AACnE,CAAC;AAED,OAAO,EACN,uBAAuB,EACvB,UAAU,EACV,oBAAoB,EACpB,cAAc,EACd,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAEnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/notify.d.ts

@@ -0,0 +1,17 @@
+import type { EventConsumerHandler } from '@aphexcms/cms-core';
+/**
+ * Sends a form's notification emails, out of band.
+ *
+ * This runs as a delivery job, which is the entire reason a mail outage can't
+ * fail a visitor's submit: the submission is already stored, and a throw here
+ * retries with backoff and eventually dead-letters, visible in Activity. Sending
+ * inline in the request would have coupled "did my message go through" to
+ * whether an SMTP host answered.
+ *
+ * At-least-once delivery means this can run twice for one submission. A duplicate
+ * notification email is the acceptable failure — the alternative, tracking sent
+ * state to make it exactly-once, would have to be written somewhere that itself
+ * can fail between the send and the write.
+ */
+export declare function notifyOnSubmission(from?: string): EventConsumerHandler;
+//# sourceMappingURL=notify.d.ts.map

package/dist/notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../src/lib/notify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAK/D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,oBAAoB,CAoEtE"}

package/dist/notify.js

@@ -0,0 +1,76 @@
+import { formSubmissionCreated } from './events.js';
+import { renderTemplate } from './template.js';
+/**
+ * Sends a form's notification emails, out of band.
+ *
+ * This runs as a delivery job, which is the entire reason a mail outage can't
+ * fail a visitor's submit: the submission is already stored, and a throw here
+ * retries with backoff and eventually dead-letters, visible in Activity. Sending
+ * inline in the request would have coupled "did my message go through" to
+ * whether an SMTP host answered.
+ *
+ * At-least-once delivery means this can run twice for one submission. A duplicate
+ * notification email is the acceptable failure — the alternative, tracking sent
+ * state to make it exactly-once, would have to be written somewhere that itself
+ * can fail between the send and the write.
+ */
+export function notifyOnSubmission(from) {
+    return async ({ event, databaseAdapter, emailAdapter, logger }) => {
+        /*
+         * The sending identity belongs to the app, not to this plugin — it's the same
+         * address the CMS's own password-reset and invitation mail goes out as. Passed
+         * in via `formsPlugin({ from })`, falling back to the variable the templates
+         * already use. Missing configuration throws when this submission has recipients,
+         * making the delivery retry and eventually surface in Activity instead of being
+         * acknowledged without sending.
+         */
+        const { submissionId } = formSubmissionCreated.parse(event.payload);
+        const submissionRow = await databaseAdapter.findByDocIdAdvanced(event.organizationId, submissionId);
+        if (!submissionRow) {
+            // The document was deleted between the submit and this delivery. Nothing to
+            // send, and nothing that retrying would fix.
+            logger.warn(`[forms] submission ${submissionId} is gone; skipping notification`);
+            return;
+        }
+        // A submission is written as a draft and never published, so `draftData` is
+        // where both its answers and immutable notification snapshot live.
+        const submission = (submissionRow.draftData ?? {});
+        const emails = submission.notificationEmails ?? [];
+        if (emails.length === 0)
+            return;
+        if (!emailAdapter)
+            throw new Error('[forms] notification email adapter is not configured');
+        const sender = from ?? process.env.APHEX_EMAIL_FROM;
+        if (!sender)
+            throw new Error('[forms] notification from-address is not configured');
+        const answers = (submission.submissionData ?? []).map((a) => ({
+            field: String(a.field ?? ''),
+            value: String(a.value ?? '')
+        }));
+        const labels = new Map((submission.notificationFieldLabels ?? []).map((entry) => [
+            String(entry.field ?? ''),
+            String(entry.label ?? entry.field ?? '')
+        ]));
+        for (const email of emails) {
+            const to = (email.to ?? '')
+                .split(',')
+                .map((address) => address.trim())
+                .filter(Boolean);
+            if (to.length === 0)
+                continue;
+            const result = await emailAdapter.send({
+                from: sender,
+                to,
+                replyTo: email.replyTo,
+                subject: renderTemplate(email.subject ?? 'New form submission', answers, labels)
+                    .replace(/[\r\n]+/g, ' ')
+                    .slice(0, 998),
+                text: renderTemplate(email.message ?? '{{allFields}}', answers, labels)
+            });
+            if (result.error)
+                throw new Error(`[forms] notification email failed: ${result.error}`);
+        }
+        logger.info(`[forms] sent ${emails.length} notification(s) for submission ${submissionId}`);
+    };
+}
+//# sourceMappingURL=notify.js.map

package/dist/notify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.js","sourceRoot":"","sources":["../src/lib/notify.ts"],"names":[],"mappings":"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"}

package/dist/schema.d.ts

@@ -0,0 +1,14 @@
+import type { SchemaAccess, SchemaType, TypeReference } from '@aphexcms/cms-core';
+/** Every field kind an editor can add, in the order they appear in the "add" menu. */
+export declare const formFieldTypes: TypeReference[];
+/** Field kinds that actually collect an answer — everything except `formMessage`. */
+export declare const INPUT_FIELD_TYPES: string[];
+export declare const formSchema: SchemaType;
+/**
+ * Submissions can contain personal data, so the general document capabilities
+ * are too broad. The submit route writes with system access; humans may only
+ * read or erase submissions when their organization role explicitly allows it.
+ */
+export declare const defaultSubmissionAccess: SchemaAccess;
+export declare const formSubmissionSchema: SchemaType;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/lib/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AA0PzF,sFAAsF;AACtF,eAAO,MAAM,cAAc,EAAE,aAAa,EAQzC,CAAC;AAEF,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,UAEY,CAAC;AAE3C,eAAO,MAAM,UAAU,EAAE,UAwIxB,CAAC;AAsBF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,YAOrC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,UAqFlC,CAAC"}