@elytracms/forms 0.0.0-stage → 0.0.95

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 finaldream
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@elytracms/forms` — forms, the first Elytra addon (EC-613, on the addon contract of
+ * EC-616 and the public ingest seam of EC-617).
+ *
+ * A site's form post becomes a SUBMISSION — a row in the project's record store that the
+ * studio lists in an inbox — and its mail is a scheduled delivery with a per-recipient log
+ * on that row, so a failed mail is a visible issue on a submission that exists, never a lost
+ * message. Uploads go into the deployment's storage, claimed by the submission.
+ *
+ * This entry holds what every plane shares — the record kind, the form source, the forms
+ * wire and the pure rules. The planes:
+ *
+ * | Entry | What it holds | How the project wires it |
+ * | --- | --- | --- |
+ * | `@elytracms/forms/convex` | the kind's functions, the receiver's handler, the delivery | `studio/convex/forms.ts`: `export * from '@elytracms/forms/convex'`, and `ingest: { submission: formsIngest }` in `studio/convex/http.ts` |
+ * | `@elytracms/forms/studio` | the inbox | `formsInbox({ source })` in `defineStudio({ sidebar })` |
+ * | `@elytracms/forms/next` | the browser submit, the no-JS form post, the delivery route | `frontend/app/api/forms/route.ts` (+ the ingest route) |
+ */
+export { DELIVERY_LOG_LIMIT, DELIVERY_STATES, FORM_VALUE_MAX_LENGTH, SPAM_VERDICTS, SUBMISSION_EDITOR_COLUMNS, SUBMISSION_STATUSES, deliveryEntrySchema, formValueSchema, submissionFieldSchema, submissionFileSchema, submissionRecordKind, } from './shared/kind.js';
+export type { DeliveryEntry, DeliveryState, FormValue, SpamVerdict, SubmissionEditorColumn, SubmissionField, SubmissionFile, SubmissionRecord, SubmissionStatus, } from './shared/kind.js';
+export { defaultReplyTo, defineFormSource, isEmailAddress } from './shared/source.js';
+export type { FormDocument, FormFieldLabel, FormSource, FormSourceConfig } from './shared/source.js';
+export { DEFAULT_HONEYPOT_FIELD, FORMS_HONEYPOT_KEY, FORMS_RESERVED_PREFIX, FORMS_SOURCE_KEY, FORMS_TARGET_FIELD, FORMS_UPLOAD_CONTENT_TYPES, formatFormValue, readSubmissionPayload, FORM_FIELD_NAME_MAX, formFieldNameMessage, formFieldNameProblem, } from './shared/submission.js';
+export type { SubmissionColumns, SubmissionRead } from './shared/submission.js';
+export { DELIVERY_BACKOFF_MS, DELIVERY_MAX_ATTEMPTS, DELIVERY_TIMEOUT_MS, FORMS_DELIVERY_SIGNATURE_HEADER, FORMS_DELIVERY_URL_ENV, applyDeliveryOutcome, attemptFormDelivery, deliveredRecipients, deliveryNeedsAttention, deliveryOutcomeSchema, deliveryResultSchema, formDeliveryRequestSchema, formDeliveryResponseSchema, signedFormDeliveryRequest, verifyFormDeliverySignature, } from './shared/delivery.js';
+export type { DeliveryOutcome, DeliveryResult, DeliveryStep, FormDeliveryRequest, FormDeliveryResponse, } from './shared/delivery.js';
+export { labelPayload, plainLabel, submissionMailText } from './shared/mail.js';
+export type { LabelledField } from './shared/mail.js';

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * `@elytracms/forms` — forms, the first Elytra addon (EC-613, on the addon contract of
+ * EC-616 and the public ingest seam of EC-617).
+ *
+ * A site's form post becomes a SUBMISSION — a row in the project's record store that the
+ * studio lists in an inbox — and its mail is a scheduled delivery with a per-recipient log
+ * on that row, so a failed mail is a visible issue on a submission that exists, never a lost
+ * message. Uploads go into the deployment's storage, claimed by the submission.
+ *
+ * This entry holds what every plane shares — the record kind, the form source, the forms
+ * wire and the pure rules. The planes:
+ *
+ * | Entry | What it holds | How the project wires it |
+ * | --- | --- | --- |
+ * | `@elytracms/forms/convex` | the kind's functions, the receiver's handler, the delivery | `studio/convex/forms.ts`: `export * from '@elytracms/forms/convex'`, and `ingest: { submission: formsIngest }` in `studio/convex/http.ts` |
+ * | `@elytracms/forms/studio` | the inbox | `formsInbox({ source })` in `defineStudio({ sidebar })` |
+ * | `@elytracms/forms/next` | the browser submit, the no-JS form post, the delivery route | `frontend/app/api/forms/route.ts` (+ the ingest route) |
+ */
+export { DELIVERY_LOG_LIMIT, DELIVERY_STATES, FORM_VALUE_MAX_LENGTH, SPAM_VERDICTS, SUBMISSION_EDITOR_COLUMNS, SUBMISSION_STATUSES, deliveryEntrySchema, formValueSchema, submissionFieldSchema, submissionFileSchema, submissionRecordKind, } from './shared/kind.js';
+export { defaultReplyTo, defineFormSource, isEmailAddress } from './shared/source.js';
+export { DEFAULT_HONEYPOT_FIELD, FORMS_HONEYPOT_KEY, FORMS_RESERVED_PREFIX, FORMS_SOURCE_KEY, FORMS_TARGET_FIELD, FORMS_UPLOAD_CONTENT_TYPES, formatFormValue, readSubmissionPayload, FORM_FIELD_NAME_MAX, formFieldNameMessage, formFieldNameProblem, } from './shared/submission.js';
+export { DELIVERY_BACKOFF_MS, DELIVERY_MAX_ATTEMPTS, DELIVERY_TIMEOUT_MS, FORMS_DELIVERY_SIGNATURE_HEADER, FORMS_DELIVERY_URL_ENV, applyDeliveryOutcome, attemptFormDelivery, deliveredRecipients, deliveryNeedsAttention, deliveryOutcomeSchema, deliveryResultSchema, formDeliveryRequestSchema, formDeliveryResponseSchema, signedFormDeliveryRequest, verifyFormDeliverySignature, } from './shared/delivery.js';
+export { labelPayload, plainLabel, submissionMailText } from './shared/mail.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,aAAa,EACb,yBAAyB,EACzB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,eAAe,CAAA;AAYtB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAElF,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,0BAA0B,EAC1B,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,+BAA+B,EAC/B,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,yBAAyB,EACzB,0BAA0B,EAC1B,yBAAyB,EACzB,2BAA2B,GAC5B,MAAM,mBAAmB,CAAA;AAQ1B,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA","sourcesContent":["/**\n * `@elytracms/forms` — forms, the first Elytra addon (EC-613, on the addon contract of\n * EC-616 and the public ingest seam of EC-617).\n *\n * A site's form post becomes a SUBMISSION — a row in the project's record store that the\n * studio lists in an inbox — and its mail is a scheduled delivery with a per-recipient log\n * on that row, so a failed mail is a visible issue on a submission that exists, never a lost\n * message. Uploads go into the deployment's storage, claimed by the submission.\n *\n * This entry holds what every plane shares — the record kind, the form source, the forms\n * wire and the pure rules. The planes:\n *\n * | Entry | What it holds | How the project wires it |\n * | --- | --- | --- |\n * | `@elytracms/forms/convex` | the kind's functions, the receiver's handler, the delivery | `studio/convex/forms.ts`: `export * from '@elytracms/forms/convex'`, and `ingest: { submission: formsIngest }` in `studio/convex/http.ts` |\n * | `@elytracms/forms/studio` | the inbox | `formsInbox({ source })` in `defineStudio({ sidebar })` |\n * | `@elytracms/forms/next` | the browser submit, the no-JS form post, the delivery route | `frontend/app/api/forms/route.ts` (+ the ingest route) |\n */\nexport {\n  DELIVERY_LOG_LIMIT,\n  DELIVERY_STATES,\n  FORM_VALUE_MAX_LENGTH,\n  SPAM_VERDICTS,\n  SUBMISSION_EDITOR_COLUMNS,\n  SUBMISSION_STATUSES,\n  deliveryEntrySchema,\n  formValueSchema,\n  submissionFieldSchema,\n  submissionFileSchema,\n  submissionRecordKind,\n} from './shared/kind'\nexport type {\n  DeliveryEntry,\n  DeliveryState,\n  FormValue,\n  SpamVerdict,\n  SubmissionEditorColumn,\n  SubmissionField,\n  SubmissionFile,\n  SubmissionRecord,\n  SubmissionStatus,\n} from './shared/kind'\nexport { defaultReplyTo, defineFormSource, isEmailAddress } from './shared/source'\nexport type { FormDocument, FormFieldLabel, FormSource, FormSourceConfig } from './shared/source'\nexport {\n  DEFAULT_HONEYPOT_FIELD,\n  FORMS_HONEYPOT_KEY,\n  FORMS_RESERVED_PREFIX,\n  FORMS_SOURCE_KEY,\n  FORMS_TARGET_FIELD,\n  FORMS_UPLOAD_CONTENT_TYPES,\n  formatFormValue,\n  readSubmissionPayload,\n  FORM_FIELD_NAME_MAX,\n  formFieldNameMessage,\n  formFieldNameProblem,\n} from './shared/submission'\nexport type { SubmissionColumns, SubmissionRead } from './shared/submission'\nexport {\n  DELIVERY_BACKOFF_MS,\n  DELIVERY_MAX_ATTEMPTS,\n  DELIVERY_TIMEOUT_MS,\n  FORMS_DELIVERY_SIGNATURE_HEADER,\n  FORMS_DELIVERY_URL_ENV,\n  applyDeliveryOutcome,\n  attemptFormDelivery,\n  deliveredRecipients,\n  deliveryNeedsAttention,\n  deliveryOutcomeSchema,\n  deliveryResultSchema,\n  formDeliveryRequestSchema,\n  formDeliveryResponseSchema,\n  signedFormDeliveryRequest,\n  verifyFormDeliverySignature,\n} from './shared/delivery'\nexport type {\n  DeliveryOutcome,\n  DeliveryResult,\n  DeliveryStep,\n  FormDeliveryRequest,\n  FormDeliveryResponse,\n} from './shared/delivery'\nexport { labelPayload, plainLabel, submissionMailText } from './shared/mail'\nexport type { LabelledField } from './shared/mail'\n"]}

package/dist/next/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@elytracms/forms/next` — the forms addon's SITE half (EC-613): how a form post reaches the
+ * project, and how its mail leaves the site.
+ *
+ * - {@link submitForm} — the browser submit (a client component): files go straight to the
+ *   deployment's storage through the ingest seam's upload URLs, then the submission;
+ * - {@link createFormPostRoute} — the same calls for a form posted without JavaScript, with a
+ *   303 back to the page and an outcome flag;
+ * - {@link formsDeliveryRoute} / {@link createFormsDeliveryRoute} — the route the deployment's
+ *   scheduled delivery calls: the recipients from the published form document, one mail per
+ *   recipient through YOUR transport, answered per recipient.
+ *
+ * The ingest route itself is the engine's (`elytra.ingestRoute()`, EC-617) — its gate,
+ * limiter and signature cover every call these helpers make.
+ */
+export { formPayload, sendFormSubmission, submitForm } from './submit.js';
+export type { FormPayload, FormPayloadOptions, SubmitResult, SubmitTransport } from './submit.js';
+export { createFormPostRoute, createFormsDeliveryRoute, formPostOutcome, formsDeliveryRoute, plainLabel } from './routes.js';
+export type { FormMail, FormMailTransport, FormPostOutcome, FormPostRouteOptions, FormsDeliveryHost, FormsDeliveryRouteOptions, IngestRouteLike, } from './routes.js';
+export { DEFAULT_HONEYPOT_FIELD, FORMS_TARGET_FIELD } from '../shared/submission.js';

package/dist/next/index.js

@@ -0,0 +1,19 @@
+/**
+ * `@elytracms/forms/next` — the forms addon's SITE half (EC-613): how a form post reaches the
+ * project, and how its mail leaves the site.
+ *
+ * - {@link submitForm} — the browser submit (a client component): files go straight to the
+ *   deployment's storage through the ingest seam's upload URLs, then the submission;
+ * - {@link createFormPostRoute} — the same calls for a form posted without JavaScript, with a
+ *   303 back to the page and an outcome flag;
+ * - {@link formsDeliveryRoute} / {@link createFormsDeliveryRoute} — the route the deployment's
+ *   scheduled delivery calls: the recipients from the published form document, one mail per
+ *   recipient through YOUR transport, answered per recipient.
+ *
+ * The ingest route itself is the engine's (`elytra.ingestRoute()`, EC-617) — its gate,
+ * limiter and signature cover every call these helpers make.
+ */
+export { formPayload, sendFormSubmission, submitForm } from './submit.js';
+export { createFormPostRoute, createFormsDeliveryRoute, formPostOutcome, formsDeliveryRoute, plainLabel } from './routes.js';
+export { DEFAULT_HONEYPOT_FIELD, FORMS_TARGET_FIELD } from '../shared/submission.js';
+//# sourceMappingURL=index.js.map

package/dist/next/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/next/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAEtE,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,eAAe,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAUzH,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA","sourcesContent":["/**\n * `@elytracms/forms/next` — the forms addon's SITE half (EC-613): how a form post reaches the\n * project, and how its mail leaves the site.\n *\n * - {@link submitForm} — the browser submit (a client component): files go straight to the\n *   deployment's storage through the ingest seam's upload URLs, then the submission;\n * - {@link createFormPostRoute} — the same calls for a form posted without JavaScript, with a\n *   303 back to the page and an outcome flag;\n * - {@link formsDeliveryRoute} / {@link createFormsDeliveryRoute} — the route the deployment's\n *   scheduled delivery calls: the recipients from the published form document, one mail per\n *   recipient through YOUR transport, answered per recipient.\n *\n * The ingest route itself is the engine's (`elytra.ingestRoute()`, EC-617) — its gate,\n * limiter and signature cover every call these helpers make.\n */\nexport { formPayload, sendFormSubmission, submitForm } from './submit'\nexport type { FormPayload, FormPayloadOptions, SubmitResult, SubmitTransport } from './submit'\nexport { createFormPostRoute, createFormsDeliveryRoute, formPostOutcome, formsDeliveryRoute, plainLabel } from './routes'\nexport type {\n  FormMail,\n  FormMailTransport,\n  FormPostOutcome,\n  FormPostRouteOptions,\n  FormsDeliveryHost,\n  FormsDeliveryRouteOptions,\n  IngestRouteLike,\n} from './routes'\nexport { DEFAULT_HONEYPOT_FIELD, FORMS_TARGET_FIELD } from '../shared/submission'\n"]}

package/dist/next/routes.d.ts

@@ -0,0 +1,145 @@
+import type { SubmissionField } from '../shared/kind.js';
+import type { FormDocument, FormSource } from '../shared/source.js';
+import { plainLabel } from '../shared/mail.js';
+import type { LabelledField } from '../shared/mail.js';
+import type { SubmitResult } from './submit.js';
+/**
+ * EC-613 — the forms addon's two SITE routes:
+ *
+ * - {@link createFormPostRoute} — a form posted WITHOUT JavaScript (`<form method="post">`,
+ *   both consumers' forms) turned into the same ingest calls the browser helper sends, then a
+ *   303 back to the page with the outcome (`?form=ok|invalid|upload|busy|refused|failed`). Its
+ *   files pass through the site's function, so they are bound by the host's request body
+ *   limit; `submitForm` (JavaScript) sends the bytes straight to storage instead;
+ * - {@link createFormsDeliveryRoute} — the route the deployment's scheduled delivery calls:
+ *   it verifies the deployment's signature, resolves the form and its RECIPIENTS from the
+ *   published form document (never from the payload), and hands one mail per recipient to
+ *   the project's TRANSPORT (any vendor — the addon supplies the slot, never the vendor). It
+ *   answers per recipient; the deployment logs the answer on the row.
+ */
+/** The ingest route a form-post route sends through (`elytra.ingestRoute()`). */
+export interface IngestRouteLike {
+    POST(request: Request): Promise<Response>;
+}
+/** The `?form=` outcome of a no-JS post. */
+export type FormPostOutcome = 'ok' | 'invalid' | 'upload' | 'busy' | 'refused' | 'failed';
+/** Map a submit result onto the outcome flag a page shows. */
+export declare function formPostOutcome(result: SubmitResult): FormPostOutcome;
+export interface FormPostRouteOptions {
+    /** The site's ingest route — `elytra.ingestRoute()` (its gate, limiter and signature apply). */
+    ingest: IngestRouteLike;
+    /** The honeypot field the forms render (default `website`). */
+    honeypot?: string;
+    /** The query parameter the outcome is reported in (default `form`). */
+    param?: string;
+    /** Transport for the file bytes (tests). */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * The no-JS form post: the form names its target in a hidden `elytra:form` input
+ * (`<input type="hidden" name="elytra:form" value="contact">`).
+ *
+ * ```ts
+ * // frontend/app/api/form/route.ts
+ * export const { POST } = createFormPostRoute({ ingest: elytra.ingestRoute() })
+ * ```
+ */
+export declare function createFormPostRoute(options: FormPostRouteOptions): {
+    POST(request: Request): Promise<Response>;
+};
+/** One mail the transport sends — to ONE recipient. */
+export interface FormMail {
+    to: string;
+    subject: string;
+    /** A plain-text body (labelled fields, file links, time, page). Write your own from `submission` if you prefer. */
+    text: string;
+    replyTo?: string;
+    /** The submission's files, by URL — attach them (nodemailer and Resend both take a URL) or link them. */
+    attachments: {
+        filename: string;
+        contentType: string;
+        size: number;
+        url: string;
+    }[];
+    form: {
+        key: string;
+        title?: string;
+    };
+    submission: {
+        id: string;
+        payload: SubmissionField[];
+        /** The payload labelled by the form, in the form's order. */
+        fields: LabelledField[];
+        sourceUrl?: string;
+        submittedAt: string;
+    };
+}
+/**
+ * The project's mail transport: send one mail, resolve (optionally with the vendor's message
+ * id) when it was accepted, THROW when it was not — the error message is logged on the row.
+ */
+export type FormMailTransport = (mail: FormMail) => Promise<{
+    id?: string;
+} | void>;
+export interface FormsDeliveryRouteOptions<V> {
+    /** The ingest secret (`INGEST_SECRET` — equal to the deployment's `ELYTRA_INGEST_SECRET`). Unset → 503. */
+    secret: string | undefined;
+    /** How the addon reads your form documents. */
+    source: FormSource<V>;
+    /** The PUBLISHED form documents (the site's content read). A throw is answered 503 (the deployment retries). */
+    forms: () => Promise<readonly FormDocument<V>[]>;
+    transport: FormMailTransport;
+    /** The locale a localized field label is written in (default: its first entry). */
+    locale?: string;
+    /** The subject line (default `New submission: <form title>`). */
+    subject?: (form: {
+        key: string;
+        title?: string;
+    }) => string;
+}
+/** The route the deployment's delivery calls (see the module header). */
+export declare function createFormsDeliveryRoute<V>(options: FormsDeliveryRouteOptions<V>): {
+    POST(request: Request): Promise<Response>;
+};
+/** The slice of the delivery kit (`createElytraHost`'s handle) the delivery route reads. */
+export interface FormsDeliveryHost {
+    env: {
+        ingestSecret?: string | undefined;
+    };
+    loadContent(request: {
+        perspective: 'published';
+    }): Promise<{
+        client(init: {
+            perspective: 'published';
+        }): {
+            listDocuments(collection: string, query?: {
+                cursor?: string;
+            }): {
+                ok: true;
+                documents: readonly {
+                    id: string;
+                }[];
+                nextCursor: string | null;
+            } | {
+                ok: false;
+                errors: readonly {
+                    message: string;
+                }[];
+            };
+        };
+    }>;
+}
+/**
+ * The delivery route over the site's own kit — the published forms through its content read,
+ * the secret from its env:
+ *
+ * ```ts
+ * // frontend/app/api/forms/route.ts
+ * export const { POST } = formsDeliveryRoute(elytra, { source: contactForms, transport: sendWithResend })
+ * ```
+ */
+export declare function formsDeliveryRoute<V>(host: FormsDeliveryHost, options: Omit<FormsDeliveryRouteOptions<V>, 'secret' | 'forms'>): {
+    POST(request: Request): Promise<Response>;
+};
+/** A label as the mail writes it (re-exported for transports that compose their own body). */
+export { plainLabel };

package/dist/next/routes.js

@@ -0,0 +1,214 @@
+import { FORMS_TARGET_FIELD } from '../shared/submission.js';
+import { defaultReplyTo } from '../shared/source.js';
+import { labelPayload, plainLabel, submissionMailText } from '../shared/mail.js';
+import { formDeliveryRequestSchema, verifyFormDeliverySignature, FORMS_DELIVERY_SIGNATURE_HEADER } from '../shared/delivery.js';
+import { formPayload, sendFormSubmission } from './submit.js';
+/** Map a submit result onto the outcome flag a page shows. */
+export function formPostOutcome(result) {
+    if (result.ok)
+        return 'ok';
+    if (result.status === 413 || result.status === 415 || result.stage === 'storage')
+        return 'upload';
+    if (result.status === 400 || result.status === 404 || result.status === 422)
+        return 'invalid';
+    if (result.status === 429)
+        return 'busy';
+    if (result.status === 403)
+        return 'refused';
+    return 'failed';
+}
+/** 303 back to the page the form was posted from (same-origin `Referer` only, else `/`). */
+function redirectBack(request, param, outcome) {
+    let path = '/';
+    const referer = request.headers.get('referer');
+    if (referer) {
+        try {
+            const url = new URL(referer);
+            if (url.origin === new URL(request.url).origin)
+                path = url.pathname;
+        }
+        catch {
+            // a malformed referer → '/'
+        }
+    }
+    const target = new URL(path, request.url);
+    target.searchParams.set(param, outcome);
+    return Response.redirect(target, 303);
+}
+/** The same-origin page a post came from, as the submission's `$source`. */
+function sourceOf(request) {
+    const referer = request.headers.get('referer');
+    if (!referer)
+        return undefined;
+    try {
+        const url = new URL(referer);
+        return url.origin === new URL(request.url).origin ? url.href : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The no-JS form post: the form names its target in a hidden `elytra:form` input
+ * (`<input type="hidden" name="elytra:form" value="contact">`).
+ *
+ * ```ts
+ * // frontend/app/api/form/route.ts
+ * export const { POST } = createFormPostRoute({ ingest: elytra.ingestRoute() })
+ * ```
+ */
+export function createFormPostRoute(options) {
+    const param = options.param ?? 'form';
+    const fetchImpl = options.fetchImpl ?? fetch;
+    return {
+        async POST(request) {
+            let formData;
+            try {
+                formData = await request.formData();
+            }
+            catch {
+                return redirectBack(request, param, 'invalid');
+            }
+            const target = formData.get(FORMS_TARGET_FIELD);
+            if (typeof target !== 'string' || target.length === 0)
+                return redirectBack(request, param, 'invalid');
+            const sourceUrl = sourceOf(request);
+            const payload = formPayload(formData.entries(), {
+                ...(options.honeypot ? { honeypot: options.honeypot } : {}),
+                ...(sourceUrl ? { sourceUrl } : {}),
+            });
+            // Every ingest call carries the visitor's own request headers (origin, client address
+            // for the limiter, whatever the bot gate reads) — only the body is the payload.
+            const headers = new Headers(request.headers);
+            headers.delete('content-length');
+            headers.set('content-type', 'application/json');
+            const result = await sendFormSubmission({
+                target,
+                payload,
+                transport: {
+                    ingest: (body) => options.ingest.POST(new Request(request.url, { method: 'POST', headers, body: JSON.stringify(body) })),
+                    store: (uploadUrl, file, contentType) => fetchImpl(uploadUrl, { method: 'POST', headers: { 'content-type': contentType }, body: file }),
+                },
+            });
+            return redirectBack(request, param, formPostOutcome(result));
+        },
+    };
+}
+const MAX_DELIVERY_BODY = 512 * 1024;
+function json(status, body) {
+    return Response.json(body, { status, headers: { 'cache-control': 'no-store' } });
+}
+/** The route the deployment's delivery calls (see the module header). */
+export function createFormsDeliveryRoute(options) {
+    return {
+        async POST(request) {
+            if (!options.secret)
+                return json(503, { error: 'Form delivery is not configured on this site (INGEST_SECRET is unset).' });
+            const raw = await request.text();
+            if (raw.length > MAX_DELIVERY_BODY)
+                return json(413, { error: 'The delivery request is too large.' });
+            if (!(await verifyFormDeliverySignature(raw, request.headers.get(FORMS_DELIVERY_SIGNATURE_HEADER), options.secret))) {
+                return json(401, { error: 'Invalid or missing signature.' });
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                return json(400, { error: 'The delivery request is not JSON.' });
+            }
+            const read = formDeliveryRequestSchema.safeParse(parsed);
+            if (!read.success)
+                return json(400, { error: 'The delivery request has an invalid shape.' });
+            const delivery = read.data;
+            let forms;
+            try {
+                forms = await options.forms();
+            }
+            catch (error) {
+                return json(503, { error: `The site could not read its forms: ${error instanceof Error ? error.message : String(error)}` });
+            }
+            const form = options.source.find(forms, delivery.form);
+            if (!form)
+                return json(404, { error: `No published form “${delivery.form}” in “${options.source.collection}”.` });
+            const title = options.source.title?.(form.values);
+            const formInfo = { key: delivery.form, ...(title ? { title } : {}) };
+            const fields = labelPayload(delivery.payload, options.source.fields?.(form.values) ?? []);
+            const replyTo = (options.source.replyTo ?? defaultReplyTo)(delivery.payload);
+            const mail = {
+                subject: options.subject?.(formInfo) ?? `New submission: ${title ?? delivery.form}`,
+                text: submissionMailText({
+                    ...(title ? { formTitle: title } : {}),
+                    fields,
+                    files: delivery.files,
+                    ...(delivery.sourceUrl ? { sourceUrl: delivery.sourceUrl } : {}),
+                    submittedAt: delivery.submittedAt,
+                    ...(options.locale ? { locale: options.locale } : {}),
+                }),
+                ...(replyTo ? { replyTo } : {}),
+                attachments: delivery.files.map((file) => ({
+                    filename: file.name ?? file.field,
+                    contentType: file.contentType,
+                    size: file.size,
+                    url: file.url,
+                })),
+                form: formInfo,
+                submission: {
+                    id: delivery.submissionId,
+                    payload: delivery.payload,
+                    fields,
+                    ...(delivery.sourceUrl ? { sourceUrl: delivery.sourceUrl } : {}),
+                    submittedAt: delivery.submittedAt,
+                },
+            };
+            const already = new Set(delivery.delivered);
+            const results = [];
+            for (const to of options.source.recipientsOf(form)) {
+                if (already.has(to))
+                    continue;
+                try {
+                    const sent = await options.transport({ to, ...mail });
+                    results.push({ to, ok: true, ...(sent && sent.id ? { id: sent.id } : {}) });
+                }
+                catch (error) {
+                    results.push({ to, ok: false, error: error instanceof Error ? error.message : String(error) });
+                }
+            }
+            return json(200, { results });
+        },
+    };
+}
+/**
+ * The delivery route over the site's own kit — the published forms through its content read,
+ * the secret from its env:
+ *
+ * ```ts
+ * // frontend/app/api/forms/route.ts
+ * export const { POST } = formsDeliveryRoute(elytra, { source: contactForms, transport: sendWithResend })
+ * ```
+ */
+export function formsDeliveryRoute(host, options) {
+    return createFormsDeliveryRoute({
+        ...options,
+        secret: host.env.ingestSecret,
+        forms: async () => {
+            const content = await host.loadContent({ perspective: 'published' });
+            const client = content.client({ perspective: 'published' });
+            const out = [];
+            let cursor;
+            do {
+                const listed = client.listDocuments(options.source.collection, cursor ? { cursor } : undefined);
+                if (!listed.ok)
+                    throw new Error(listed.errors.map((error) => error.message).join(' ') || 'the forms could not be listed');
+                // A delivered document is flat (`{ id, collection, …fields }`) — its fields are the values.
+                for (const document of listed.documents)
+                    out.push({ id: document.id, values: document });
+                cursor = listed.nextCursor ?? undefined;
+            } while (cursor);
+            return out;
+        },
+    });
+}
+/** A label as the mail writes it (re-exported for transports that compose their own body). */
+export { plainLabel };
+//# sourceMappingURL=routes.js.map

package/dist/next/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../../src/next/routes.ts"],"names":[],"mappings":"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","sourcesContent":["import { FORMS_TARGET_FIELD } from '../shared/submission'\nimport type { SubmissionField } from '../shared/kind'\nimport type { FormDocument, FormSource } from '../shared/source'\nimport { defaultReplyTo } from '../shared/source'\nimport { labelPayload, plainLabel, submissionMailText } from '../shared/mail'\nimport type { LabelledField } from '../shared/mail'\nimport { formDeliveryRequestSchema, verifyFormDeliverySignature, FORMS_DELIVERY_SIGNATURE_HEADER } from '../shared/delivery'\nimport type { DeliveryResult } from '../shared/delivery'\nimport { formPayload, sendFormSubmission } from './submit'\nimport type { SubmitResult } from './submit'\n\n/**\n * EC-613 — the forms addon's two SITE routes:\n *\n * - {@link createFormPostRoute} — a form posted WITHOUT JavaScript (`<form method=\"post\">`,\n *   both consumers' forms) turned into the same ingest calls the browser helper sends, then a\n *   303 back to the page with the outcome (`?form=ok|invalid|upload|busy|refused|failed`). Its\n *   files pass through the site's function, so they are bound by the host's request body\n *   limit; `submitForm` (JavaScript) sends the bytes straight to storage instead;\n * - {@link createFormsDeliveryRoute} — the route the deployment's scheduled delivery calls:\n *   it verifies the deployment's signature, resolves the form and its RECIPIENTS from the\n *   published form document (never from the payload), and hands one mail per recipient to\n *   the project's TRANSPORT (any vendor — the addon supplies the slot, never the vendor). It\n *   answers per recipient; the deployment logs the answer on the row.\n */\n\n/** The ingest route a form-post route sends through (`elytra.ingestRoute()`). */\nexport interface IngestRouteLike {\n  POST(request: Request): Promise<Response>\n}\n\n/** The `?form=` outcome of a no-JS post. */\nexport type FormPostOutcome = 'ok' | 'invalid' | 'upload' | 'busy' | 'refused' | 'failed'\n\n/** Map a submit result onto the outcome flag a page shows. */\nexport function formPostOutcome(result: SubmitResult): FormPostOutcome {\n  if (result.ok) return 'ok'\n  if (result.status === 413 || result.status === 415 || result.stage === 'storage') return 'upload'\n  if (result.status === 400 || result.status === 404 || result.status === 422) return 'invalid'\n  if (result.status === 429) return 'busy'\n  if (result.status === 403) return 'refused'\n  return 'failed'\n}\n\n/** 303 back to the page the form was posted from (same-origin `Referer` only, else `/`). */\nfunction redirectBack(request: Request, param: string, outcome: FormPostOutcome): Response {\n  let path = '/'\n  const referer = request.headers.get('referer')\n  if (referer) {\n    try {\n      const url = new URL(referer)\n      if (url.origin === new URL(request.url).origin) path = url.pathname\n    } catch {\n      // a malformed referer → '/'\n    }\n  }\n  const target = new URL(path, request.url)\n  target.searchParams.set(param, outcome)\n  return Response.redirect(target, 303)\n}\n\n/** The same-origin page a post came from, as the submission's `$source`. */\nfunction sourceOf(request: Request): string | undefined {\n  const referer = request.headers.get('referer')\n  if (!referer) return undefined\n  try {\n    const url = new URL(referer)\n    return url.origin === new URL(request.url).origin ? url.href : undefined\n  } catch {\n    return undefined\n  }\n}\n\nexport interface FormPostRouteOptions {\n  /** The site's ingest route — `elytra.ingestRoute()` (its gate, limiter and signature apply). */\n  ingest: IngestRouteLike\n  /** The honeypot field the forms render (default `website`). */\n  honeypot?: string\n  /** The query parameter the outcome is reported in (default `form`). */\n  param?: string\n  /** Transport for the file bytes (tests). */\n  fetchImpl?: typeof fetch\n}\n\n/**\n * The no-JS form post: the form names its target in a hidden `elytra:form` input\n * (`<input type=\"hidden\" name=\"elytra:form\" value=\"contact\">`).\n *\n * ```ts\n * // frontend/app/api/form/route.ts\n * export const { POST } = createFormPostRoute({ ingest: elytra.ingestRoute() })\n * ```\n */\nexport function createFormPostRoute(options: FormPostRouteOptions): { POST(request: Request): Promise<Response> } {\n  const param = options.param ?? 'form'\n  const fetchImpl = options.fetchImpl ?? fetch\n  return {\n    async POST(request: Request): Promise<Response> {\n      let formData: FormData\n      try {\n        formData = await request.formData()\n      } catch {\n        return redirectBack(request, param, 'invalid')\n      }\n      const target = formData.get(FORMS_TARGET_FIELD)\n      if (typeof target !== 'string' || target.length === 0) return redirectBack(request, param, 'invalid')\n      const sourceUrl = sourceOf(request)\n      const payload = formPayload(formData.entries() as Iterable<[string, string | Blob]>, {\n        ...(options.honeypot ? { honeypot: options.honeypot } : {}),\n        ...(sourceUrl ? { sourceUrl } : {}),\n      })\n      // Every ingest call carries the visitor's own request headers (origin, client address\n      // for the limiter, whatever the bot gate reads) — only the body is the payload.\n      const headers = new Headers(request.headers)\n      headers.delete('content-length')\n      headers.set('content-type', 'application/json')\n      const result = await sendFormSubmission({\n        target,\n        payload,\n        transport: {\n          ingest: (body) => options.ingest.POST(new Request(request.url, { method: 'POST', headers, body: JSON.stringify(body) })),\n          store: (uploadUrl, file, contentType) =>\n            fetchImpl(uploadUrl, { method: 'POST', headers: { 'content-type': contentType }, body: file }),\n        },\n      })\n      return redirectBack(request, param, formPostOutcome(result))\n    },\n  }\n}\n\n// --- Delivery --------------------------------------------------------------------------------\n\n/** One mail the transport sends — to ONE recipient. */\nexport interface FormMail {\n  to: string\n  subject: string\n  /** A plain-text body (labelled fields, file links, time, page). Write your own from `submission` if you prefer. */\n  text: string\n  replyTo?: string\n  /** The submission's files, by URL — attach them (nodemailer and Resend both take a URL) or link them. */\n  attachments: { filename: string; contentType: string; size: number; url: string }[]\n  form: { key: string; title?: string }\n  submission: {\n    id: string\n    payload: SubmissionField[]\n    /** The payload labelled by the form, in the form's order. */\n    fields: LabelledField[]\n    sourceUrl?: string\n    submittedAt: string\n  }\n}\n\n/**\n * The project's mail transport: send one mail, resolve (optionally with the vendor's message\n * id) when it was accepted, THROW when it was not — the error message is logged on the row.\n */\nexport type FormMailTransport = (mail: FormMail) => Promise<{ id?: string } | void>\n\nexport interface FormsDeliveryRouteOptions<V> {\n  /** The ingest secret (`INGEST_SECRET` — equal to the deployment's `ELYTRA_INGEST_SECRET`). Unset → 503. */\n  secret: string | undefined\n  /** How the addon reads your form documents. */\n  source: FormSource<V>\n  /** The PUBLISHED form documents (the site's content read). A throw is answered 503 (the deployment retries). */\n  forms: () => Promise<readonly FormDocument<V>[]>\n  transport: FormMailTransport\n  /** The locale a localized field label is written in (default: its first entry). */\n  locale?: string\n  /** The subject line (default `New submission: <form title>`). */\n  subject?: (form: { key: string; title?: string }) => string\n}\n\nconst MAX_DELIVERY_BODY = 512 * 1024\n\nfunction json(status: number, body: Record<string, unknown>): Response {\n  return Response.json(body, { status, headers: { 'cache-control': 'no-store' } })\n}\n\n/** The route the deployment's delivery calls (see the module header). */\nexport function createFormsDeliveryRoute<V>(options: FormsDeliveryRouteOptions<V>): { POST(request: Request): Promise<Response> } {\n  return {\n    async POST(request: Request): Promise<Response> {\n      if (!options.secret) return json(503, { error: 'Form delivery is not configured on this site (INGEST_SECRET is unset).' })\n      const raw = await request.text()\n      if (raw.length > MAX_DELIVERY_BODY) return json(413, { error: 'The delivery request is too large.' })\n      if (!(await verifyFormDeliverySignature(raw, request.headers.get(FORMS_DELIVERY_SIGNATURE_HEADER), options.secret))) {\n        return json(401, { error: 'Invalid or missing signature.' })\n      }\n      let parsed: unknown\n      try {\n        parsed = JSON.parse(raw)\n      } catch {\n        return json(400, { error: 'The delivery request is not JSON.' })\n      }\n      const read = formDeliveryRequestSchema.safeParse(parsed)\n      if (!read.success) return json(400, { error: 'The delivery request has an invalid shape.' })\n      const delivery = read.data\n\n      let forms: readonly FormDocument<V>[]\n      try {\n        forms = await options.forms()\n      } catch (error) {\n        return json(503, { error: `The site could not read its forms: ${error instanceof Error ? error.message : String(error)}` })\n      }\n      const form = options.source.find(forms, delivery.form)\n      if (!form) return json(404, { error: `No published form “${delivery.form}” in “${options.source.collection}”.` })\n\n      const title = options.source.title?.(form.values)\n      const formInfo = { key: delivery.form, ...(title ? { title } : {}) }\n      const fields = labelPayload(delivery.payload, options.source.fields?.(form.values) ?? [])\n      const replyTo = (options.source.replyTo ?? defaultReplyTo)(delivery.payload)\n      const mail = {\n        subject: options.subject?.(formInfo) ?? `New submission: ${title ?? delivery.form}`,\n        text: submissionMailText({\n          ...(title ? { formTitle: title } : {}),\n          fields,\n          files: delivery.files,\n          ...(delivery.sourceUrl ? { sourceUrl: delivery.sourceUrl } : {}),\n          submittedAt: delivery.submittedAt,\n          ...(options.locale ? { locale: options.locale } : {}),\n        }),\n        ...(replyTo ? { replyTo } : {}),\n        attachments: delivery.files.map((file) => ({\n          filename: file.name ?? file.field,\n          contentType: file.contentType,\n          size: file.size,\n          url: file.url,\n        })),\n        form: formInfo,\n        submission: {\n          id: delivery.submissionId,\n          payload: delivery.payload,\n          fields,\n          ...(delivery.sourceUrl ? { sourceUrl: delivery.sourceUrl } : {}),\n          submittedAt: delivery.submittedAt,\n        },\n      }\n\n      const already = new Set(delivery.delivered)\n      const results: DeliveryResult[] = []\n      for (const to of options.source.recipientsOf(form)) {\n        if (already.has(to)) continue\n        try {\n          const sent = await options.transport({ to, ...mail })\n          results.push({ to, ok: true, ...(sent && sent.id ? { id: sent.id } : {}) })\n        } catch (error) {\n          results.push({ to, ok: false, error: error instanceof Error ? error.message : String(error) })\n        }\n      }\n      return json(200, { results })\n    },\n  }\n}\n\n/** The slice of the delivery kit (`createElytraHost`'s handle) the delivery route reads. */\nexport interface FormsDeliveryHost {\n  env: { ingestSecret?: string | undefined }\n  loadContent(request: { perspective: 'published' }): Promise<{\n    client(init: { perspective: 'published' }): {\n      listDocuments(\n        collection: string,\n        query?: { cursor?: string },\n      ):\n        | { ok: true; documents: readonly { id: string }[]; nextCursor: string | null }\n        | { ok: false; errors: readonly { message: string }[] }\n    }\n  }>\n}\n\n/**\n * The delivery route over the site's own kit — the published forms through its content read,\n * the secret from its env:\n *\n * ```ts\n * // frontend/app/api/forms/route.ts\n * export const { POST } = formsDeliveryRoute(elytra, { source: contactForms, transport: sendWithResend })\n * ```\n */\nexport function formsDeliveryRoute<V>(\n  host: FormsDeliveryHost,\n  options: Omit<FormsDeliveryRouteOptions<V>, 'secret' | 'forms'>,\n): { POST(request: Request): Promise<Response> } {\n  return createFormsDeliveryRoute<V>({\n    ...options,\n    secret: host.env.ingestSecret,\n    forms: async () => {\n      const content = await host.loadContent({ perspective: 'published' })\n      const client = content.client({ perspective: 'published' })\n      const out: FormDocument<V>[] = []\n      let cursor: string | undefined\n      do {\n        const listed = client.listDocuments(options.source.collection, cursor ? { cursor } : undefined)\n        if (!listed.ok) throw new Error(listed.errors.map((error) => error.message).join(' ') || 'the forms could not be listed')\n        // A delivered document is flat (`{ id, collection, …fields }`) — its fields are the values.\n        for (const document of listed.documents) out.push({ id: document.id, values: document as unknown as V })\n        cursor = listed.nextCursor ?? undefined\n      } while (cursor)\n      return out\n    },\n  })\n}\n\n/** A label as the mail writes it (re-exported for transports that compose their own body). */\nexport { plainLabel }\n"]}

package/dist/next/submit.d.ts

@@ -0,0 +1,83 @@
+/**
+ * EC-613 — a form post as the ingest seam's calls (EC-617): one `upload` per file (the route
+ * asks the receiver for ONE short-lived storage URL, the bytes go straight to it), then one
+ * `submission` that claims the stored files. The ONE flow, with injected transports, so the
+ * browser (`submitForm`) and the site's no-JS form-post route (`createFormPostRoute`) send
+ * exactly the same calls.
+ */
+/** A posted value: text, or a file (a `File` / `Blob` with a name). */
+type PostedValue = string | Blob;
+/** The form's fields as the ingest payload carries them, and the files to upload. */
+export interface FormPayload {
+    data: Record<string, string | string[]>;
+    files: {
+        field: string;
+        file: Blob;
+        name: string;
+    }[];
+}
+export interface FormPayloadOptions {
+    /** The honeypot field the form renders (default `website`); its value goes to `elytra:honeypot`. */
+    honeypot?: string;
+    /** The page the form was submitted from (`$source`). */
+    sourceUrl?: string;
+}
+/**
+ * Read a form's entries (pure): repeated names become a list, the honeypot moves to
+ * `elytra:honeypot`, `elytra:form` (the no-JS target input) is not a field, and every non-empty file is
+ * an upload whose NAME is the field's value (what the inbox and the mail list). A file input
+ * left empty posts a nameless zero-byte part — it is skipped.
+ */
+export declare function formPayload(entries: Iterable<[string, PostedValue]>, options?: FormPayloadOptions): FormPayload;
+/** What a submit came to. */
+export type SubmitResult = {
+    ok: true;
+    id: string;
+} | {
+    ok: false;
+    /** Which call failed: an upload URL, the bytes, or the submission. */
+    stage: 'upload' | 'storage' | 'submission';
+    status: number;
+    error: string;
+    issues?: {
+        path: (string | number)[];
+        message: string;
+    }[];
+};
+/** The two transports the flow runs over. */
+export interface SubmitTransport {
+    /** Send one ingest payload through the site's ingest route; resolve with its answer. */
+    ingest(payload: Record<string, unknown>): Promise<Response>;
+    /** Send one file's bytes to an issued storage URL; resolve with the storage's answer (`{ storageId }`). */
+    store(uploadUrl: string, file: Blob, contentType: string): Promise<Response>;
+}
+/**
+ * Send one form post to form `target` (its key — see `defineFormSource`'s `key`): each file
+ * uploaded first, then the submission claiming them. The first failure ends it and is
+ * returned with its stage and status; nothing is retried here.
+ */
+export declare function sendFormSubmission(input: {
+    target: string;
+    payload: FormPayload;
+    transport: SubmitTransport;
+}): Promise<SubmitResult>;
+/**
+ * Submit a form from the BROWSER (a client component's submit handler): its fields and files
+ * through the site's ingest route (default `/api/ingest`), the files' bytes straight to the
+ * deployment's storage — so an upload is not bound by the site's function body limit.
+ *
+ * ```tsx
+ * const result = await submitForm({ form: event.currentTarget, target: 'contact' })
+ * ```
+ */
+export declare function submitForm(input: {
+    form: HTMLFormElement | FormData;
+    target: string;
+    /** The site's ingest route (default `/api/ingest`). */
+    endpoint?: string;
+    honeypot?: string;
+    /** Default: the current page. */
+    sourceUrl?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<SubmitResult>;
+export {};