@elytracms/forms 0.0.0-stage → 0.0.95

package/src/shared/delivery.ts

@@ -0,0 +1,263 @@
+import { z } from 'zod'
+import { INGEST_SIGNATURE_HEADER, verifyIngestSignature } from '@elytracms/core/ingest'
+import { signRevalidationBody } from '@elytracms/core/revalidation'
+import { DELIVERY_LOG_LIMIT, submissionFieldSchema } from './kind'
+import type { DeliveryEntry, DeliveryState } from './kind'
+
+/**
+ * EC-613 — DELIVERY: one scheduled action per submission (`forms:deliver`, Convex) asks the
+ * SITE to send the mail, and logs the answer per recipient on the row.
+ *
+ * Why the site sends it: the transport is the consumer's (Resend over `fetch`, SMTP over
+ * nodemailer, …) and the recipients live in the consumer's form document (`defineFormSource`).
+ * In Convex an SMTP transport would need a `"use node"` file of its own (only actions may
+ * live there) and both the vendor secrets and the form document's shape would move into the
+ * deployment; on the site they are where both consumers keep them today, and Convex stays
+ * data-only (EC-585 1e). The deployment keeps what the ruling asks of it: the scheduled
+ * action per row, the retry, and the per-recipient log — so a failed mail is a visible issue
+ * on a row that exists.
+ *
+ * The request is signed with the INGEST secret pair (`ELYTRA_INGEST_SECRET` on Convex =
+ * `INGEST_SECRET` on the site) through the one signer (`@elytracms/core/revalidation`, the
+ * same HMAC header as the ingest wire). A delivery body and an ingest body are refused by
+ * each other's strict schemas, so one cannot be replayed as the other.
+ */
+
+/** The deployment env var naming the site's delivery route (`https://example.com/api/forms`). */
+export const FORMS_DELIVERY_URL_ENV = 'ELYTRA_FORMS_DELIVERY_URL'
+
+/** Automatic attempts per run (an editor's retry starts a new run). */
+export const DELIVERY_MAX_ATTEMPTS = 5
+/** The wait after attempt N failed (N = 1…4): one minute, ten minutes, one hour, six hours. */
+export const DELIVERY_BACKOFF_MS: readonly number[] = [60_000, 10 * 60_000, 60 * 60_000, 6 * 60 * 60_000]
+
+/** One file as the site receives it (a URL it may attach or link). */
+export const deliveryFileSchema = z.strictObject({
+  field: z.string(),
+  name: z.string().optional(),
+  contentType: z.string(),
+  size: z.number(),
+  url: z.string(),
+})
+
+/** What the deployment sends the site's delivery route. */
+export const formDeliveryRequestSchema = z.strictObject({
+  kind: z.literal('formDelivery'),
+  submissionId: z.string().min(1),
+  form: z.string().min(1),
+  payload: z.array(submissionFieldSchema),
+  files: z.array(deliveryFileSchema),
+  sourceUrl: z.string().optional(),
+  submittedAt: z.string(),
+  attempt: z.number().int().positive(),
+  /** Recipients an earlier attempt of this run already reached — never sent twice. */
+  delivered: z.array(z.string()),
+})
+export type FormDeliveryRequest = z.infer<typeof formDeliveryRequestSchema>
+
+/** One recipient's outcome, as the site reports it. */
+export const deliveryResultSchema = z.union([
+  z.strictObject({ to: z.string(), ok: z.literal(true), id: z.string().optional() }),
+  z.strictObject({ to: z.string(), ok: z.literal(false), error: z.string() }),
+])
+export type DeliveryResult = z.infer<typeof deliveryResultSchema>
+
+/** The site's 200 answer: one result per recipient it tried (none for an inbox-only form). */
+export const formDeliveryResponseSchema = z.strictObject({ results: z.array(deliveryResultSchema) })
+export type FormDeliveryResponse = z.infer<typeof formDeliveryResponseSchema>
+
+/** Sign one delivery request (the deployment's half). */
+export async function signedFormDeliveryRequest(
+  request: FormDeliveryRequest,
+  secret: string,
+): Promise<{ body: string; headers: Record<string, string> }> {
+  const body = JSON.stringify(formDeliveryRequestSchema.parse(request))
+  return { body, headers: { 'content-type': 'application/json', [INGEST_SIGNATURE_HEADER]: await signRevalidationBody(body, secret) } }
+}
+
+/** Verify one delivery request (the site's half) — constant time, the one verifier. */
+export function verifyFormDeliverySignature(rawBody: string, signature: string | null | undefined, secret: string): Promise<boolean> {
+  return verifyIngestSignature(rawBody, signature, secret)
+}
+
+export { INGEST_SIGNATURE_HEADER as FORMS_DELIVERY_SIGNATURE_HEADER }
+
+// --- The state machine ---------------------------------------------------------------------
+
+/** What one attempt came to. */
+export type DeliveryOutcome =
+  /** The deployment has no delivery route configured. */
+  | { kind: 'unconfigured'; message: string }
+  /** The site could not be reached (network, timeout). Retryable. */
+  | { kind: 'unreachable'; message: string }
+  /** The site answered non-2xx. Retryable for 5xx and 429; a 4xx is a configuration or content problem. */
+  | { kind: 'refused'; status: number; message: string }
+  /** The site answered with its per-recipient results. */
+  | { kind: 'results'; results: readonly DeliveryResult[] }
+
+/** The outcome as it crosses from the delivery action into the mutation that logs it. */
+export const deliveryOutcomeSchema: z.ZodType<DeliveryOutcome> = z.discriminatedUnion('kind', [
+  z.strictObject({ kind: z.literal('unconfigured'), message: z.string() }),
+  z.strictObject({ kind: z.literal('unreachable'), message: z.string() }),
+  z.strictObject({ kind: z.literal('refused'), status: z.number().int(), message: z.string() }),
+  z.strictObject({ kind: z.literal('results'), results: z.array(deliveryResultSchema) }),
+])
+
+/** The row's delivery after one attempt, and when to try again. */
+export interface DeliveryStep {
+  deliveryState: DeliveryState
+  deliveryLog: DeliveryEntry[]
+  /** Schedule the next attempt in this many ms (absent: the run is over). */
+  retryInMs?: number
+}
+
+const ERROR_MAX = 500
+
+function clip(message: string): string {
+  return message.length > ERROR_MAX ? `${message.slice(0, ERROR_MAX - 1)}…` : message
+}
+
+/**
+ * The recipients the row's mail already reached — every successful line of the log, across
+ * runs: an attempt (and an editor's retry) re-sends only to the recipients still missing,
+ * never twice to one who has it.
+ */
+export function deliveredRecipients(log: readonly DeliveryEntry[]): string[] {
+  const delivered = new Set<string>()
+  for (const entry of log) if (entry.ok && entry.to) delivered.add(entry.to)
+  return [...delivered]
+}
+
+function retryable(outcome: DeliveryOutcome): boolean {
+  switch (outcome.kind) {
+    case 'unreachable':
+      return true
+    case 'refused':
+      return outcome.status >= 500 || outcome.status === 429
+    case 'results':
+      return outcome.results.some((result) => !result.ok)
+    case 'unconfigured':
+      return false
+  }
+}
+
+/**
+ * Apply one attempt's outcome to a row's delivery (pure — the Convex mutation and the tests
+ * run the same function). `log` is the row's log before the attempt; `delivered` the
+ * recipients this run already reached.
+ */
+export function applyDeliveryOutcome(
+  input: { log: readonly DeliveryEntry[]; attempt: number; now: string; delivered: readonly string[] },
+  outcome: DeliveryOutcome,
+): DeliveryStep {
+  const { attempt, now } = input
+  const again = retryable(outcome) && attempt < DELIVERY_MAX_ATTEMPTS
+  const retryInMs = again ? DELIVERY_BACKOFF_MS[attempt - 1] : undefined
+  const retryAt = retryInMs !== undefined ? new Date(Date.parse(now) + retryInMs).toISOString() : undefined
+  const line = (entry: Omit<DeliveryEntry, 'at' | 'attempt'>): DeliveryEntry => ({ at: now, attempt, ...entry })
+
+  const lines: DeliveryEntry[] = []
+  let reached = [...input.delivered]
+  switch (outcome.kind) {
+    case 'unconfigured':
+    case 'unreachable':
+      lines.push(line({ ok: false, error: clip(outcome.message), ...(retryAt ? { retryAt } : {}) }))
+      break
+    case 'refused':
+      lines.push(line({ ok: false, error: clip(`HTTP ${outcome.status}: ${outcome.message}`), ...(retryAt ? { retryAt } : {}) }))
+      break
+    case 'results':
+      if (outcome.results.length === 0 && reached.length === 0) {
+        lines.push(line({ ok: true, note: 'no recipients' }))
+      }
+      for (const result of outcome.results) {
+        if (result.ok) {
+          reached.push(result.to)
+          lines.push(line({ to: result.to, ok: true, ...(result.id ? { id: result.id } : {}) }))
+        } else {
+          lines.push(line({ to: result.to, ok: false, error: clip(result.error), ...(retryAt ? { retryAt } : {}) }))
+        }
+      }
+      reached = [...new Set(reached)]
+      break
+  }
+
+  const deliveryLog = [...input.log, ...lines].slice(-DELIVERY_LOG_LIMIT)
+  if (retryInMs !== undefined) return { deliveryState: 'pending', deliveryLog, retryInMs }
+  const failedNow = outcome.kind !== 'results' || outcome.results.some((result) => !result.ok)
+  let deliveryState: DeliveryState
+  if (!failedNow) deliveryState = reached.length > 0 ? 'sent' : 'skipped'
+  else deliveryState = reached.length > 0 ? 'partial' : 'failed'
+  return { deliveryState, deliveryLog }
+}
+
+/** How long the deployment waits for the site's answer. */
+export const DELIVERY_TIMEOUT_MS = 30_000
+
+/**
+ * One attempt from the deployment's side: sign the request, POST it to the site's delivery
+ * route, read the answer into an outcome. Never throws — every failure is an outcome the
+ * log records. `fetchImpl` is the transport (the action passes the runtime's `fetch`).
+ */
+export async function attemptFormDelivery(input: {
+  request: FormDeliveryRequest
+  url: string | undefined
+  secret: string | undefined
+  fetchImpl?: typeof fetch
+  timeoutMs?: number
+}): Promise<DeliveryOutcome> {
+  if (!input.url) {
+    return { kind: 'unconfigured', message: `${FORMS_DELIVERY_URL_ENV} is not set on this deployment — no delivery route to send to.` }
+  }
+  if (!input.secret) {
+    return { kind: 'unconfigured', message: 'ELYTRA_INGEST_SECRET is not set on this deployment — the delivery request cannot be signed.' }
+  }
+  const signed = await signedFormDeliveryRequest(input.request, input.secret)
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), input.timeoutMs ?? DELIVERY_TIMEOUT_MS)
+  let response: Response
+  try {
+    response = await (input.fetchImpl ?? fetch)(input.url, {
+      method: 'POST',
+      headers: signed.headers,
+      body: signed.body,
+      signal: controller.signal,
+    })
+  } catch (error) {
+    return { kind: 'unreachable', message: `The delivery route could not be reached: ${error instanceof Error ? error.message : String(error)}` }
+  } finally {
+    clearTimeout(timer)
+  }
+  const text = await response.text().catch(() => '')
+  if (response.status === 401) {
+    return {
+      kind: 'refused',
+      status: 401,
+      message: "The site refused the deployment's signature — INGEST_SECRET on the site must equal ELYTRA_INGEST_SECRET.",
+    }
+  }
+  if (!response.ok) {
+    let message = text.slice(0, ERROR_MAX)
+    try {
+      const parsed = JSON.parse(text) as { error?: unknown }
+      if (typeof parsed.error === 'string') message = parsed.error
+    } catch {
+      // not JSON — keep the text
+    }
+    return { kind: 'refused', status: response.status, message: message || `HTTP ${response.status}` }
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    return { kind: 'refused', status: 502, message: 'The delivery route answered 200 with a body that is not JSON.' }
+  }
+  const answer = formDeliveryResponseSchema.safeParse(parsed)
+  if (!answer.success) return { kind: 'refused', status: 502, message: 'The delivery route answered 200 with an invalid body.' }
+  return { kind: 'results', results: answer.data.results }
+}
+
+/** Does this delivery state need an editor's attention (the inbox's issue)? */
+export function deliveryNeedsAttention(state: DeliveryState): boolean {
+  return state === 'failed' || state === 'partial'
+}

package/src/shared/kind.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod'
+import { defineRecordKind } from '@elytracms/core/persistence'
+import type { RecordEntryOf } from '@elytracms/core/persistence'
+
+/**
+ * EC-613 — the SUBMISSION record kind: every form post a site receives, one row in the
+ * engine's record store (EC-616), declared ONCE here and read by all three planes — the
+ * Convex functions that store it (`@elytracms/forms/convex`), the studio inbox that lists
+ * and edits it (`@elytracms/forms/studio`) and the site helpers that send it
+ * (`@elytracms/forms/next`).
+ *
+ * Its functions live in the Convex module `forms` — the consumer's ONE re-export file is
+ * `convex/forms.ts`: `export * from '@elytracms/forms/convex'`.
+ *
+ * Who writes what:
+ * - the SITE (through the ingest receiver's handler, `forms:ingest`): `form`, `payload`,
+ *   `files`, `sourceUrl`, `spam`, `submittedAt` — what the visitor sent and what the checks
+ *   said. Never edited afterwards;
+ * - the EDITOR (through the inbox): `status`, `assignee`, `notes` — the inbox lifecycle (the
+ *   SMB CRM of the ruling; a sales pipeline is the developer's structure, not this kind);
+ * - the DELIVERY (the scheduled `forms:deliver` action): `deliveryState`, `deliveryLog`.
+ *
+ * The payload is a LIST of `{ name, value }` (sorted by name), not an object keyed by field
+ * name: a visitor's field names never become stored object keys. Its display order is the
+ * FORM's (`labelPayload` over the form source's `fields`). A value is a string, a number, a
+ * boolean or a list of strings, so the stored depth is bounded by construction.
+ */
+
+/** The editor's inbox lifecycle. */
+export const SUBMISSION_STATUSES = ['new', 'open', 'done', 'spam'] as const
+export type SubmissionStatus = (typeof SUBMISSION_STATUSES)[number]
+
+/** What a submission's delivery is doing — see `@elytracms/forms` `applyDeliveryOutcome`. */
+export const DELIVERY_STATES = ['pending', 'sent', 'partial', 'failed', 'skipped'] as const
+export type DeliveryState = (typeof DELIVERY_STATES)[number]
+
+/** What the spam checks said: nothing, or the form's honeypot was filled. */
+export const SPAM_VERDICTS = ['clean', 'honeypot'] as const
+export type SpamVerdict = (typeof SPAM_VERDICTS)[number]
+
+/** The longest text value one field may carry. */
+export const FORM_VALUE_MAX_LENGTH = 10_000
+
+/** One submitted value: a string, a number, a boolean, or a list of strings (a multi-select). */
+export const formValueSchema = z.union([
+  z.string().max(FORM_VALUE_MAX_LENGTH),
+  z.number(),
+  z.boolean(),
+  z.array(z.string().max(FORM_VALUE_MAX_LENGTH)).max(50),
+])
+export type FormValue = z.infer<typeof formValueSchema>
+
+/** One field of a submission's payload. */
+export const submissionFieldSchema = z.strictObject({
+  name: z.string().min(1).max(200),
+  value: formValueSchema,
+})
+export type SubmissionField = z.infer<typeof submissionFieldSchema>
+
+/** One uploaded file a submission claimed (EC-617's upload intent, checked against the stored file). */
+export const submissionFileSchema = z.strictObject({
+  /** The form field it was uploaded for. */
+  field: z.string().min(1).max(200),
+  /** The file name the visitor's browser reported (display only). */
+  name: z.string().max(300).optional(),
+  storageId: z.string().min(1),
+  contentType: z.string().min(1),
+  size: z.number().int().nonnegative(),
+  /** The storage URL (`https://<deployment>.convex.cloud/api/storage/<id>`), unguessable, valid while the file exists. */
+  url: z.string().optional(),
+})
+export type SubmissionFile = z.infer<typeof submissionFileSchema>
+
+/** One line of the delivery log: one recipient (or the whole request) in one attempt. */
+export const deliveryEntrySchema = z.strictObject({
+  at: z.string().min(1),
+  attempt: z.number().int().positive(),
+  /** The recipient — absent for an entry about the whole attempt (unreachable site, refused request). */
+  to: z.string().optional(),
+  ok: z.boolean(),
+  /** Why it failed (truncated). */
+  error: z.string().optional(),
+  /** A note on a non-failure without a recipient (`no recipients`). */
+  note: z.string().optional(),
+  /** The transport's message id, when it reported one. */
+  id: z.string().optional(),
+  /** When the next automatic attempt runs, if one is scheduled. */
+  retryAt: z.string().optional(),
+})
+export type DeliveryEntry = z.infer<typeof deliveryEntrySchema>
+
+/** The most log lines a row keeps (the oldest are dropped first). */
+export const DELIVERY_LOG_LIMIT = 100
+
+export const submissionRecordKind = defineRecordKind({
+  kind: 'submission',
+  module: 'forms',
+  keys: ['form', 'status'],
+  time: 'submittedAt',
+  fields: {
+    /** The form's key — the ingest `target` the site posted to (see `defineFormSource`'s `key`). */
+    form: z.string().min(1).max(200),
+    status: z.enum(SUBMISSION_STATUSES).default('new'),
+    assignee: z.string().max(200).optional(),
+    notes: z.string().max(20_000).optional(),
+    payload: z.array(submissionFieldSchema).max(200),
+    files: z.array(submissionFileSchema).max(20).optional(),
+    sourceUrl: z.string().max(2000).optional(),
+    spam: z.enum(SPAM_VERDICTS),
+    deliveryState: z.enum(DELIVERY_STATES),
+    deliveryLog: z.array(deliveryEntrySchema).max(DELIVERY_LOG_LIMIT).optional(),
+    submittedAt: z.string().min(1),
+  },
+})
+
+export type SubmissionRecord = RecordEntryOf<typeof submissionRecordKind>
+
+/** The columns the EDITOR owns — the only ones the inbox ever writes. */
+export const SUBMISSION_EDITOR_COLUMNS = ['status', 'assignee', 'notes'] as const
+export type SubmissionEditorColumn = (typeof SUBMISSION_EDITOR_COLUMNS)[number]

package/src/shared/mail.ts

@@ -0,0 +1,67 @@
+import type { LocalizedString } from '@elytracms/core/cms-core'
+import type { FormFieldLabel } from './source'
+import type { SubmissionField } from './kind'
+import { formatFormValue } from './submission'
+
+/**
+ * EC-613 — a submission LABELLED by its form (pure): the studio inbox shows it, the site's
+ * delivery route writes it into the mail. A payload field the form does not (or no longer)
+ * declares keeps its submitted name — what the visitor sent is never hidden.
+ */
+
+/** One payload line with the label an editor reads. */
+export interface LabelledField {
+  name: string
+  label: LocalizedString
+  value: SubmissionField['value']
+}
+
+/**
+ * The payload in the FORM's order (its declared fields first, as declared), then any field
+ * the form does not declare, in submitted order.
+ */
+export function labelPayload(payload: readonly SubmissionField[], fields: readonly FormFieldLabel[] = []): LabelledField[] {
+  const byName = new Map(payload.map((field) => [field.name, field]))
+  const out: LabelledField[] = []
+  const used = new Set<string>()
+  for (const declared of fields) {
+    const field = byName.get(declared.name)
+    if (!field || used.has(declared.name)) continue
+    used.add(declared.name)
+    out.push({ name: field.name, label: declared.label ?? field.name, value: field.value })
+  }
+  for (const field of payload) {
+    if (used.has(field.name)) continue
+    used.add(field.name)
+    out.push({ name: field.name, label: field.name, value: field.value })
+  }
+  return out
+}
+
+/** A label as plain text for a mail (a localized label in `locale`, else its first entry). */
+export function plainLabel(label: LocalizedString, locale?: string): string {
+  if (typeof label === 'string') return label
+  return (locale ? label[locale] : undefined) ?? Object.values(label)[0] ?? ''
+}
+
+/** The plain-text mail body of a submission. */
+export function submissionMailText(input: {
+  formTitle?: string
+  fields: readonly LabelledField[]
+  files: readonly { field: string; name?: string; url: string; size: number }[]
+  sourceUrl?: string
+  submittedAt: string
+  locale?: string
+}): string {
+  const lines: string[] = []
+  for (const field of input.fields) lines.push(`${plainLabel(field.label, input.locale)}: ${formatFormValue(field.value)}`)
+  if (input.files.length > 0) {
+    lines.push('', 'Files:')
+    for (const file of input.files) {
+      lines.push(`- ${file.name ?? file.field} (${Math.max(1, Math.round(file.size / 1024))} KB): ${file.url}`)
+    }
+  }
+  lines.push('', `Submitted: ${input.submittedAt}`)
+  if (input.sourceUrl) lines.push(`Page: ${input.sourceUrl}`)
+  return lines.join('\n')
+}

package/src/shared/source.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest'
+import { defaultReplyTo, defineFormSource } from './source'
+import { labelPayload, submissionMailText } from './mail'
+
+/** EC-613 — the consumer's form source (one declaration, read by the studio and the site) and the labelled payload. */
+
+interface FormValues {
+  internalId?: string
+  title?: string
+  recipient?: string
+  cc?: string[]
+  fields?: { name: string; label?: string }[]
+}
+
+const forms = defineFormSource<FormValues>({
+  collection: 'form',
+  key: 'internalId',
+  title: (form) => form.title,
+  recipients: (form) => [form.recipient, ...(form.cc ?? [])],
+  fields: (form) => form.fields ?? [],
+})
+
+describe('defineFormSource', () => {
+  const contact = { id: 'form-1', values: { internalId: 'contact', title: 'Contact', recipient: ' shop@example.test ', cc: ['shop@example.test', 'not-an-address', 'boss@example.test'] } }
+
+  it('finds a form by the key a site posts (not the document id)', () => {
+    expect(forms.find([contact], 'contact')).toBe(contact)
+    expect(forms.find([contact], 'form-1')).toBeUndefined()
+    // Control: without `key`, the document id addresses it.
+    const byId = defineFormSource({ collection: 'form', recipients: () => [] })
+    expect(byId.find([contact], 'form-1')).toBe(contact)
+  })
+
+  it('recipients are trimmed, deliverable addresses, each once — from the FORM, never the payload', () => {
+    expect(forms.recipientsOf(contact)).toEqual(['shop@example.test', 'boss@example.test'])
+  })
+
+  it('refuses a source without a collection at declaration', () => {
+    expect(() => defineFormSource({ collection: '', recipients: () => [] })).toThrow(/collection/)
+  })
+})
+
+describe('labelPayload / submissionMailText', () => {
+  const payload = [
+    { name: 'message', value: 'Hello' },
+    { name: 'email', value: 'ada@example.test' },
+    { name: 'extra', value: ['a', 'b'] },
+  ]
+
+  it('orders by the form’s fields with their labels; an undeclared field keeps its submitted name', () => {
+    expect(labelPayload(payload, [{ name: 'email', label: 'E-mail' }, { name: 'message', label: { en: 'Message', de: 'Nachricht' } }])).toEqual([
+      { name: 'email', label: 'E-mail', value: 'ada@example.test' },
+      { name: 'message', label: { en: 'Message', de: 'Nachricht' }, value: 'Hello' },
+      { name: 'extra', label: 'extra', value: ['a', 'b'] },
+    ])
+  })
+
+  it('writes the plain-text body: labelled lines, files, time and page', () => {
+    const text = submissionMailText({
+      fields: labelPayload(payload, [{ name: 'message', label: { en: 'Message', de: 'Nachricht' } }]),
+      files: [{ field: 'cv', name: 'cv.pdf', url: 'https://x.test/cv', size: 2048 }],
+      sourceUrl: 'https://site.test/contact',
+      submittedAt: '2026-10-26T12:00:00.000Z',
+      locale: 'de',
+    })
+    expect(text.split('\n')).toEqual([
+      'Nachricht: Hello',
+      'email: ada@example.test',
+      'extra: a, b',
+      '',
+      'Files:',
+      '- cv.pdf (2 KB): https://x.test/cv',
+      '',
+      'Submitted: 2026-10-26T12:00:00.000Z',
+      'Page: https://site.test/contact',
+    ])
+  })
+
+  it('the default reply-to is the first e-mail-named field holding an address', () => {
+    expect(defaultReplyTo(payload)).toBe('ada@example.test')
+    expect(defaultReplyTo([{ name: 'email', value: 'not an address' }])).toBeUndefined()
+  })
+})

package/src/shared/source.ts

@@ -0,0 +1,107 @@
+import type { LocalizedString } from '@elytracms/core/cms-core'
+import type { SubmissionField } from './kind'
+
+/**
+ * EC-613 — the FORM SOURCE: how the addon reads the consumer's own form documents, declared
+ * ONCE by the consumer and read by the two planes that know the project — the studio inbox
+ * (a submission's field labels, the form's title) and the site's delivery route (the
+ * recipients, the labels in the mail). Convex never reads it: the deployment stays
+ * data-only (EC-585 1e), and the recipients are resolved from the PUBLISHED form document on
+ * the site — never from anything a visitor sent (a recipient from the payload would make the
+ * site an open mail relay).
+ *
+ * The form collection, its field types and the renderer stay the consumer's (the ruling):
+ * this declaration only says where in a form document the addon finds what it needs.
+ *
+ * ```ts
+ * // cms/forms.ts — anywhere; the studio config and the site's delivery route import it
+ * export const contactForms = defineFormSource({
+ *   collection: 'form',
+ *   key: 'internalId', // the site posts this value as the submission's target
+ *   title: (form) => form.title,
+ *   recipients: (form) => [form.recipient],
+ *   fields: (form) => form.fields.map((field) => ({ name: field.name, label: field.label })),
+ * })
+ * ```
+ */
+
+/** One field of a form, as the addon labels a submission's payload with it. */
+export interface FormFieldLabel {
+  /** The submitted name (the input's `name`). */
+  name: string
+  /** What an editor reads instead of the name; a plain string or `{ en, de, … }`. */
+  label?: LocalizedString
+}
+
+/** A form document as the addon sees it: its id and its values (the consumer's shape). */
+export interface FormDocument<V = Record<string, unknown>> {
+  id: string
+  values: V
+}
+
+export interface FormSourceConfig<V = Record<string, unknown>> {
+  /** The collection that holds the forms. */
+  collection: string
+  /**
+   * How a site addresses a form — the submission's `target` and the row's `form` column: the
+   * name of a text field of the form document (`'internalId'`), or a function. Default: the
+   * document's id.
+   */
+  key?: string | ((form: FormDocument<V>) => string | undefined)
+  /** The form's display title (the inbox column, the mail subject). */
+  title?: (values: V) => string | undefined
+  /** Who receives a submission's mail. An empty list delivers nothing (an inbox-only form). */
+  recipients: (values: V) => readonly (string | undefined | null)[]
+  /** The form's fields, in order, for labelling a payload. Absent → the submitted names. */
+  fields?: (values: V) => readonly FormFieldLabel[]
+  /** The address a reply goes to (default: the first payload value of a field named like `email`). */
+  replyTo?: (payload: readonly SubmissionField[]) => string | undefined
+}
+
+/** A declared form source (see the module header). */
+export interface FormSource<V = Record<string, unknown>> extends FormSourceConfig<V> {
+  /** The key of one form document — `key` applied, else its id. */
+  keyOf(form: FormDocument<V>): string | undefined
+  /** The form among `forms` a submission's `form` column names. */
+  find(forms: readonly FormDocument<V>[], key: string): FormDocument<V> | undefined
+  /** The recipients of one form: trimmed, valid addresses only, each once. */
+  recipientsOf(form: FormDocument<V>): string[]
+}
+
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+/** Is this a deliverable address (the same shape both consumers' routes check)? */
+export function isEmailAddress(value: unknown): value is string {
+  return typeof value === 'string' && EMAIL.test(value.trim())
+}
+
+/** Declare how the addon reads your form documents (see the module header). */
+export function defineFormSource<V = Record<string, unknown>>(config: FormSourceConfig<V>): FormSource<V> {
+  if (!config.collection) throw new Error('defineFormSource: `collection` is required.')
+  const keyOf = (form: FormDocument<V>): string | undefined => {
+    if (config.key === undefined) return form.id
+    if (typeof config.key === 'function') return config.key(form)
+    const value = (form.values as Record<string, unknown>)[config.key]
+    return typeof value === 'string' && value.length > 0 ? value : undefined
+  }
+  return {
+    ...config,
+    keyOf,
+    find: (forms, key) => forms.find((form) => keyOf(form) === key),
+    recipientsOf: (form) => {
+      const seen = new Set<string>()
+      for (const entry of config.recipients(form.values)) {
+        if (isEmailAddress(entry)) seen.add(entry.trim())
+      }
+      return [...seen]
+    },
+  }
+}
+
+/** The default reply-to: the first payload value of a field named like `email`, if it is an address. */
+export function defaultReplyTo(payload: readonly SubmissionField[]): string | undefined {
+  for (const field of payload) {
+    if (/e-?mail/i.test(field.name) && isEmailAddress(field.value)) return (field.value as string).trim()
+  }
+  return undefined
+}