@elytracms/forms 0.0.0-stage → 0.0.94

package/src/shared/submission.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest'
+import { CONVEX_MAX_NESTING_DEPTH } from '@elytracms/core/cms-core'
+import { recordRowDepth, resolveRecordSave } from '@elytracms/core/persistence'
+import { submissionRecordKind } from './kind'
+import { FORMS_HONEYPOT_KEY, FORMS_SOURCE_KEY, readSubmissionPayload } from './submission'
+
+/** EC-613 — the one reader of a site's submission payload (the receiver's handler runs it). */
+
+const submission = (data: Record<string, unknown>, target = 'contact') => ({ kind: 'submission' as const, target, data })
+
+describe('readSubmissionPayload', () => {
+  it('keeps the fields sorted by name (the one order every runtime agrees on), drops empty answers, reads the reserved keys', () => {
+    const read = readSubmissionPayload(
+      submission({
+        name: 'Ada',
+        topics: ['cakes', 'tarts'],
+        empty: '   ',
+        none: [],
+        newsletter: true,
+        guests: 4,
+        [FORMS_SOURCE_KEY]: 'https://example.test/contact',
+        [FORMS_HONEYPOT_KEY]: '',
+      }),
+    )
+    expect(read).toEqual({
+      ok: true,
+      columns: {
+        form: 'contact',
+        payload: [
+          { name: 'guests', value: 4 },
+          { name: 'name', value: 'Ada' },
+          { name: 'newsletter', value: true },
+          { name: 'topics', value: ['cakes', 'tarts'] },
+        ],
+        sourceUrl: 'https://example.test/contact',
+        spam: 'clean',
+      },
+    })
+  })
+
+  it('a filled honeypot is the verdict, not a refusal (the row is kept and marked)', () => {
+    const read = readSubmissionPayload(submission({ name: 'Bot', [FORMS_HONEYPOT_KEY]: 'http://spam.test' }))
+    expect(read.ok && read.columns.spam).toBe('honeypot')
+    // Control: an empty honeypot is clean.
+    const clean = readSubmissionPayload(submission({ name: 'Ada', [FORMS_HONEYPOT_KEY]: '' }))
+    expect(clean.ok && clean.columns.spam).toBe('clean')
+  })
+
+  it('refuses, visibly, a value that is not a form value and an unknown reserved key', () => {
+    const read = readSubmissionPayload(submission({ name: 'Ada', nested: { deep: { deeper: 1 } }, 'elytra:admin': 'yes' }))
+    expect(read.ok).toBe(false)
+    if (read.ok) return
+    expect(read.status).toBe(422)
+    expect(read.issues.map((issue) => issue.path.join('.'))).toEqual(['data.elytra:admin', 'data.nested'])
+  })
+
+  it('refuses a submission with no answer — unless it carries files', () => {
+    expect(readSubmissionPayload(submission({ name: '' })).ok).toBe(false)
+    expect(readSubmissionPayload(submission({ name: '' }), { hasFiles: true }).ok).toBe(true)
+  })
+})
+
+describe('the submission kind', () => {
+  it('a maximal row stays far below Convex’s nesting ceiling (the values are flat by construction)', () => {
+    const columns = resolveRecordSave(submissionRecordKind, 'submission_max', undefined, {
+      form: 'contact',
+      payload: [{ name: 'topics', value: ['a', 'b'] }],
+      files: [{ field: 'cv', name: 'cv.pdf', storageId: 's1', contentType: 'application/pdf', size: 1, url: 'https://x.test/s1' }],
+      spam: 'clean',
+      deliveryState: 'failed',
+      deliveryLog: [{ at: 't', attempt: 1, to: 'a@example.test', ok: false, error: 'x', retryAt: 't2' }],
+      submittedAt: 't',
+      meta: { tag: 'x' },
+    })
+    expect(recordRowDepth(columns)).toBeLessThanOrEqual(6)
+    expect(recordRowDepth(columns)).toBeLessThan(CONVEX_MAX_NESTING_DEPTH)
+  })
+
+  it('a create defaults the inbox status to new; an edit never re-applies it', () => {
+    const created = resolveRecordSave(submissionRecordKind, 's', undefined, {
+      form: 'contact',
+      payload: [],
+      spam: 'clean',
+      deliveryState: 'pending',
+      submittedAt: 't',
+    })
+    expect(created.status).toBe('new')
+    const edited = resolveRecordSave(submissionRecordKind, 's', { ...created, status: 'done' }, { notes: 'called back' })
+    expect(edited).toMatchObject({ status: 'done', notes: 'called back' })
+  })
+
+  it('keys the inbox by form and by status, ordered by the submission time (EC-616 slots)', () => {
+    expect(submissionRecordKind.keys).toEqual(['form', 'status'])
+    expect(submissionRecordKind.time).toBe('submittedAt')
+    expect(submissionRecordKind.module).toBe('forms')
+  })
+})

package/src/shared/submission.ts

@@ -0,0 +1,163 @@
+import { convexFieldNameProblem } from '@elytracms/core/ingest'
+import type { IngestPayload } from '@elytracms/core/ingest'
+import { formValueSchema } from './kind'
+import type { FormValue, SpamVerdict, SubmissionField } from './kind'
+
+/**
+ * EC-613 — the FORMS WIRE inside the ingest envelope (EC-617): what a site's `submission`
+ * payload carries for this addon, and the ONE reader the receiver's handler turns it into a
+ * row with. Pure (no Convex), so the rules are unit-tested on their own.
+ *
+ * `data` holds the form's fields by name, plus RESERVED keys the addon's site helpers fill,
+ * in the `elytra:` namespace:
+ *
+ * - `elytra:source` — the page the form was submitted from (the row's `sourceUrl`);
+ * - `elytra:honeypot` — the value of the form's honeypot field (a real visitor leaves it empty).
+ *
+ * Any other `elytra:` key is refused — never silently dropped. Empty values (`''`, `[]`) are
+ * not answers and are not stored; a submission with no answer and no file is refused.
+ *
+ * A field NAME follows ONE rule ({@link formFieldNameProblem}): the ingest envelope's — a name
+ * Convex can store (`convexFieldNameProblem`, `@elytracms/core/ingest`: printable ASCII, no
+ * leading `$`, at most 1024 characters; the route and the receiver refuse anything else with
+ * 400) — plus the forms addon's own cap of 200 characters (the stored payload's `name`). The
+ * site helpers refuse a name before sending, with the same reason the envelope would give.
+ */
+
+/** The reserved namespace of the forms wire. */
+export const FORMS_RESERVED_PREFIX = 'elytra:'
+/** The page a submission came from. */
+export const FORMS_SOURCE_KEY = 'elytra:source'
+/** The honeypot's value. */
+export const FORMS_HONEYPOT_KEY = 'elytra:honeypot'
+/**
+ * The hidden input a native (no-JS) form post names its form with — read by the `./next`
+ * form-post route, never sent on: it becomes the ingest payload's `target`.
+ */
+export const FORMS_TARGET_FIELD = 'elytra:form'
+
+/** The forms addon's own cap on a field name (the stored payload's `name`) — below Convex's 1024. */
+export const FORM_FIELD_NAME_MAX = 200
+
+/**
+ * Why a form field may not be named `name`, or `undefined` when it may: the ingest envelope's
+ * rule first (`convexFieldNameProblem` — the ONE rule, read, never restated), then the forms
+ * addon's own limits (not empty, at most {@link FORM_FIELD_NAME_MAX} characters). Phrased to
+ * follow `The field name “<name>” …`, exactly as the envelope's 400 issue reads.
+ */
+export function formFieldNameProblem(name: string): string | undefined {
+  const core = convexFieldNameProblem(name)
+  if (core) return core
+  if (name.length === 0) return 'is empty'
+  if (name.length > FORM_FIELD_NAME_MAX) return `is longer than ${FORM_FIELD_NAME_MAX} characters (the forms addon's own limit)`
+  return undefined
+}
+
+/** The issue message for a refused field name — the envelope's wording (`@elytracms/core/ingest`). */
+export function formFieldNameMessage(name: string, problem: string): string {
+  return `The field name “${name}” ${problem}.`
+}
+/** The honeypot field both consumers' forms already render (overridable in the site helpers). */
+export const DEFAULT_HONEYPOT_FIELD = 'website'
+
+/**
+ * The file types a form upload may have — documents and raster images. Anything that a
+ * browser would run when opened from the deployment's storage URL (HTML, SVG, scripts) is
+ * refused by the receiver's handler (415), and so is every type not listed.
+ */
+export const FORMS_UPLOAD_CONTENT_TYPES: readonly string[] = [
+  'application/pdf',
+  'application/msword',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  'application/vnd.oasis.opendocument.text',
+  'application/rtf',
+  'text/plain',
+  'text/csv',
+  'image/jpeg',
+  'image/png',
+  'image/webp',
+  'image/gif',
+  'image/heic',
+  'image/heif',
+]
+
+/** The longest source URL a row keeps. */
+const SOURCE_URL_MAX = 2000
+
+/** What a site's submission becomes in the row (the visitor's part — see the kind's header). */
+export interface SubmissionColumns {
+  form: string
+  payload: SubmissionField[]
+  sourceUrl?: string
+  spam: SpamVerdict
+}
+
+export type SubmissionRead =
+  | { ok: true; columns: SubmissionColumns }
+  | { ok: false; status: 422; message: string; issues: { path: (string | number)[]; message: string }[] }
+
+function isEmptyValue(value: FormValue): boolean {
+  return (typeof value === 'string' && value.trim() === '') || (Array.isArray(value) && value.length === 0)
+}
+
+/**
+ * Read a `submission` payload into the row's visitor columns (fields sorted by name). Refuses (422, with the issues)
+ * a value that is not a form value, an unknown reserved key, an over-long source URL, and a
+ * submission with no answer — unless it carries files (`hasFiles`).
+ */
+export function readSubmissionPayload(
+  payload: Extract<IngestPayload, { kind: 'submission' }>,
+  options: { hasFiles?: boolean } = {},
+): SubmissionRead {
+  const issues: { path: (string | number)[]; message: string }[] = []
+  const fields: SubmissionField[] = []
+  let sourceUrl: string | undefined
+  let spam: SpamVerdict = 'clean'
+  // Sorted by name: an object's key order does not survive a Convex function boundary
+  // (measured — the receiver's handler receives the keys sorted), so the stored order is the
+  // one order every runtime agrees on. The FORM's order is its declaration's (`labelPayload`).
+  for (const [name, raw] of Object.entries(payload.data).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+    if (name === FORMS_SOURCE_KEY) {
+      if (typeof raw !== 'string' || raw.length > SOURCE_URL_MAX) {
+        issues.push({ path: ['data', name], message: `“${name}” must be a URL of at most ${SOURCE_URL_MAX} characters.` })
+      } else if (raw.length > 0) sourceUrl = raw
+      continue
+    }
+    if (name === FORMS_HONEYPOT_KEY) {
+      if (typeof raw === 'string' && raw.trim().length > 0) spam = 'honeypot'
+      continue
+    }
+    if (name.startsWith(FORMS_RESERVED_PREFIX)) {
+      issues.push({ path: ['data', name], message: `“${name}” is not a reserved forms key (${FORMS_SOURCE_KEY}, ${FORMS_HONEYPOT_KEY}).` })
+      continue
+    }
+    const value = formValueSchema.safeParse(raw)
+    if (!value.success) {
+      issues.push({ path: ['data', name], message: `“${name}” is not a form value (text, a number, yes/no, or a list of texts).` })
+      continue
+    }
+    const nameProblem = formFieldNameProblem(name)
+    if (nameProblem) {
+      issues.push({ path: ['data', name], message: formFieldNameMessage(name, nameProblem) })
+      continue
+    }
+    if (!isEmptyValue(value.data)) fields.push({ name, value: value.data })
+  }
+  if (issues.length === 0 && fields.length === 0 && !options.hasFiles) {
+    issues.push({ path: ['data'], message: 'The submission carries no answer.' })
+  }
+  if (issues.length > 0) {
+    return { ok: false, status: 422, message: 'The submission is not valid.', issues }
+  }
+  return {
+    ok: true,
+    columns: { form: payload.target, payload: fields, ...(sourceUrl ? { sourceUrl } : {}), spam },
+  }
+}
+
+/** The display text of one value (a list joined by commas, a boolean as yes/no). */
+export function formatFormValue(value: FormValue): string {
+  if (Array.isArray(value)) return value.join(', ')
+  if (typeof value === 'boolean') return value ? 'yes' : 'no'
+  return String(value)
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.