@acms-subir/core 0.3.6 → 0.3.8

package/src/lib/email/service.ts

@@ -1,7 +1,7 @@
 import type { ContentRepository } from '../repo/types';
 import { resolveConfig, decrypt, encrypt, runtimeValue } from './config';
 import { sendWithProvider } from './providers';
-import { accountMail, canonicalOrigin } from './templates';
+import { accountMail, canonicalOrigin, EmailLinkError } from './templates';
 import { bookingMail } from '../booking/service';
 import type { EmailJob, Mail } from './types';
 
@@ -33,6 +33,7 @@ export async function dispatchEmail(repo: ContentRepository, locals?: unknown, l
   for (let i=0;i<limit;i++) {
     const j = await repo.email.claim(); if (!j) break;
     let handedToProvider = false;
+    let preparationError = 'Unable to prepare email. Check the message details and Email settings.';
     try {
       let config = await repo.email.config(j.configVersion || undefined);
       const resolved = resolveConfig(config, locals);
@@ -40,6 +41,9 @@ export async function dispatchEmail(repo: ContentRepository, locals?: unknown, l
       if (!current.config.enabled || current.config.provider === 'none') {
         await repo.email.finish(j,{state:'cancelled',error:'Email is disabled.'}); continue;
       }
+      if (resolved.error) {
+        await repo.email.finish(j,{state:'failed',error:resolved.error}); continue;
+      }
       if (j.fingerprint && j.fingerprint !== resolved.fingerprint) {
         await repo.email.finish(j,{state:'failed',error:'Provider configuration changed. Restore the original environment credentials before retrying this job.'}); continue;
       }
@@ -56,6 +60,7 @@ export async function dispatchEmail(repo: ContentRepository, locals?: unknown, l
       // Retries must reuse exactly the same request body, including calendar
       // timestamps, for Resend's idempotency key to remain valid. Encrypt the
       // snapshot because account and booking links are bearer credentials.
+      preparationError = 'Unable to protect email content. Check EMAIL_ENCRYPTION_KEY and retain any older keys needed for retries.';
       const frozen = j.rendered ? decrypt<Mail>(j.rendered,`job:${j.id}`,locals) : mail;
       if (!await repo.email.prepare(j,j.rendered || encrypt(frozen,`job:${j.id}`,locals))) continue;
       handedToProvider = true;
@@ -64,8 +69,8 @@ export async function dispatchEmail(repo: ContentRepository, locals?: unknown, l
       // Purge the recoverable raw account token once the provider accepted it.
       // The verifier hash remains so the recipient can redeem the link.
       if (result.state === 'accepted') processed++;
-    } catch {
-      await repo.email.finish(j,{state:handedToProvider?'unknown':'failed',error:handedToProvider?'Provider handoff could not be recorded. Review delivery before retrying.':'Unable to prepare email. Check canonical site URL and encryption configuration.'});
+    } catch (error) {
+      await repo.email.finish(j,{state:handedToProvider?'unknown':'failed',error:handedToProvider?'Provider handoff could not be recorded. Review delivery before retrying.':error instanceof EmailLinkError ? error.message : preparationError});
     }
   }
   await repo.email.reconcile();

package/src/lib/email/templates.ts

@@ -11,8 +11,14 @@ export function accountMail(kind: 'invite'|'reset'|'welcome'|'password-changed'|
   return { to, subject: `${copy[0]} · ${site}`, text: [copy[0], '', copy[1], ...(url ? ['',`${copy[2]}: ${url}`] : [])].join('\n'),
     html: `<!doctype html><html><body style="margin:0;background:#f6f5f2;color:#24211c;font:16px/1.6 system-ui,sans-serif"><div style="max-width:520px;margin:auto;padding:32px 24px"><p style="color:#7d776e">${escape(site)}</p><h1 style="font-size:24px">${escape(copy[0])}</h1><p>${escape(copy[1])}</p>${url ? `<p><a style="display:inline-block;background:#ee5d20;color:#fff;padding:10px 18px;border-radius:8px;text-decoration:none" href="${escape(url)}">${escape(copy[2])}</a></p>` : ''}</div></body></html>` };
 }
+export class EmailLinkError extends Error {}
 export function canonicalOrigin(value: string): string {
-  let url: URL; try { url = new URL(value); } catch { throw new Error('Set the canonical site URL in Settings before sending email links.'); }
-  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || url.pathname !== '/') throw new Error('The canonical site URL must be an HTTPS origin, without a path, credentials or query.');
+  const raw = value.trim();
+  if (!raw) throw new EmailLinkError('Set Site URL in Settings → General before sending booking or account emails. Use HTTPS for public sites, or HTTP for localhost development.');
+  // Match the site settings form's support for a bare domain, while retaining
+  // the stricter origin checks needed for links containing bearer tokens.
+  let url: URL; try { url = new URL(raw.includes('://') ? raw : `https://${raw}`); } catch { throw new EmailLinkError('Set a valid Site URL in Settings → General before sending booking or account emails.'); }
+  const loopback = url.hostname === 'localhost' || url.hostname.endsWith('.localhost') || url.hostname === '[::1]' || /^127\.(?:\d{1,3}\.){2}\d{1,3}$/.test(url.hostname);
+  if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) || url.username || url.password || url.search || url.hash || url.pathname !== '/') throw new EmailLinkError('Site URL in Settings → General must use HTTPS (HTTP is allowed for localhost), without a path, credentials or query.');
   return url.origin;
 }

package/src/lib/email/types.ts

@@ -25,6 +25,7 @@ export interface Invitation { id: string; email: string; name: string; role: Rol
 export interface PublicEmailSettings {
   version: number; config: EmailConfig; provider: Provider | 'none'; configured: boolean; error: string;
   encryptionAvailable: boolean; environmentLocked: boolean; credentialFields: string[];
+  linksReady: boolean; linkError: string;
   activity: Omit<EmailJob, 'payload' | 'lease' | 'fingerprint' | 'rendered'>[]; heartbeat: number | null;
 }
 export const DEFAULT_EMAIL_CONFIG: EmailConfig = {

package/src/lib/forms/events.ts

@@ -0,0 +1,40 @@
+import type { ContentRepository } from '../repo/types';
+import type { CalEvent } from '../schema';
+import { ApiError } from '../api';
+import { sha256Hex } from '../api-keys';
+import { createRsvp } from '../booking/service';
+import { collectResponse, formVersion } from './service';
+import { starter } from './schema';
+import { readAnswers } from './http';
+
+// Older custom EventTemplate components only post name/email/seats. Keep
+// that exact legacy case working; customized forms require versioned markup.
+export async function prepareLegacyEventForm(event: CalEvent, start: number, data: FormData) {
+  if (!event.rsvp.form && !data.has('requestId') && !data.has('formVersion') && !data.has('occurrence')) {
+    data.set('requestId', crypto.randomUUID());
+    data.set('formVersion', await formVersion(starter('simple')));
+    data.set('occurrence', String(start));
+  }
+}
+
+export async function submitEventForm(repo: ContentRepository, event: CalEvent, occurrence: { start: number; end: number }, data: FormData, requestId: string, flow: Parameters<typeof createRsvp>[2]) {
+  if (event.status !== 'published') throw new ApiError(404, 'Event not found.');
+  if (Number(data.get('occurrence')) !== occurrence.start) throw new ApiError(409, 'The event time has changed. Review the date and try again.');
+  const seats = Number(data.get('seats') || 1);
+  if (!Number.isInteger(seats) || seats < 1 || seats > event.rsvp.maxSeats) throw new ApiError(400, 'Choose a valid number of seats.');
+  const definition = event.rsvp.form ?? starter('simple');
+  const booker = { name: String(data.get('name') || ''), email: String(data.get('email') || ''), answers: readAnswers(data, definition), formVersion: String(data.get('formVersion') || '') };
+  const idempotency = { keyHash: await sha256Hex(`event-form:${requestId}`), requestHash: await sha256Hex(JSON.stringify({ event: event.id, start: occurrence.start, seats, booker })) };
+  const replay = async () => {
+    const record = await repo.getBookingRequest(idempotency.keyHash);
+    if (!record) return null;
+    if (record.requestHash !== idempotency.requestHash) throw new ApiError(409, 'This registration was already sent with different details. Reload to register again.');
+    const booking = await repo.getBooking(record.bookingId);
+    if (!booking) throw new ApiError(410, 'This registration was removed. Reload to register again.');
+    return booking;
+  };
+  const existing = await replay(); if (existing) return existing;
+  await collectResponse(definition, booker.answers, booker.formVersion);
+  try { return await createRsvp(repo, { event, ...occurrence, seats, booker }, { ...flow, idempotency }); }
+  catch (e) { const existing = await replay(); if (existing) return existing; throw e; }
+}

package/src/lib/forms/export.ts

@@ -0,0 +1,62 @@
+// Pure helpers for the admin Responses screen and its CSV export. Kept out of
+// service.ts so the public submit path stays small.
+import type { FormField, FormSubmission } from './schema';
+
+type Field = Pick<FormField, 'id' | 'type' | 'label'>;
+
+// Questions that collect an answer (section headings are layout only).
+export const answerFields = <F extends Field>(fields: F[]) => fields.filter(f => (f.type as string) !== 'heading');
+
+// One spreadsheet cell: yes/no for consent-style boxes, multi-choice answers
+// (stored newline-separated) joined with commas; paragraphs keep their lines.
+export function cellText(field: Pick<FormField, 'type'> | undefined, value: string | undefined): string {
+  if (!field) return '';
+  const type = field.type as string;
+  if (type === 'checkbox' || type === 'consent') return value === 'yes' ? 'Yes' : 'No';
+  if (type === 'textarea') return value ?? '';
+  return (value ?? '').split(/\r?\n/).map(s => s.trim()).filter(Boolean).join(', ');
+}
+
+// v1…vN in first-seen order; the live definition is the next number when no
+// response has used it yet. Unknown hashes fall back to a short hash.
+export function versionLabeler(seen: string[], current?: string) {
+  const order = [...seen];
+  if (current && !order.includes(current)) order.push(current);
+  const index = new Map(order.map((v, i) => [v, i + 1]));
+  return (v: string) => (index.has(v) ? `v${index.get(v)}` : v.slice(0, 7));
+}
+
+// Wide export: one row per response. Columns are the current questions first,
+// then questions only found in older snapshots (labelled from the newest one).
+export function wideRows(current: Field[], rows: FormSubmission[], version: (v: string) => string = v => v.slice(0, 7)): string[][] {
+  const cols: { id: string; label: string }[] = answerFields(current).map(f => ({ id: f.id, label: f.label }));
+  const known = new Set(cols.map(c => c.id));
+  for (const r of rows) for (const f of answerFields(r.response.definition.fields)) {
+    if (known.has(f.id)) continue;
+    known.add(f.id); cols.push({ id: f.id, label: f.label });
+  }
+  const used = new Set(['Reference', 'Submitted', 'Version']);
+  const header = cols.map(c => {
+    const label = used.has(c.label) ? `${c.label} (${c.id})` : c.label;
+    used.add(label); return label;
+  });
+  return [
+    ['Reference', 'Submitted', 'Version', ...header],
+    ...rows.map(r => {
+      const byId = new Map(r.response.definition.fields.map(f => [f.id, f]));
+      return [r.id, new Date(r.createdAt).toISOString(), version(r.response.version), ...cols.map(c => cellText(byId.get(c.id), r.response.answers[c.id]))];
+    }),
+  ];
+}
+
+export function relativeTime(ts: number, now = Date.now(), timeZone?: string): string {
+  const s = Math.floor((now - ts) / 1000);
+  if (s < 60) return 'Just now';
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+  if (s < 86400 * 2) return 'Yesterday';
+  if (s < 86400 * 7) return `${Math.floor(s / 86400)}d ago`;
+  const opts: Intl.DateTimeFormatOptions = { month: 'short', day: 'numeric', ...(new Date(ts).getFullYear() !== new Date(now).getFullYear() ? { year: 'numeric' } : {}) };
+  try { return new Date(ts).toLocaleDateString('en-US', { ...opts, timeZone }); }
+  catch { return new Date(ts).toLocaleDateString('en-US', opts); }
+}

package/src/lib/forms/fields.ts

@@ -0,0 +1,50 @@
+import { hasOther, isHalf, type FormDefinition, type FormField } from './schema';
+import { OTHER } from './validate';
+export const escapeForm = (s: string) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+const e = escapeForm;
+const inputType: Partial<Record<FormField['type'], string>> = { phone: 'tel', email: 'email', number: 'number', date: 'date' };
+// Websites use a text box so "example.org" can be typed; the server adds https://.
+const autocomplete: Partial<Record<FormField['type'], string>> = { email: 'email', phone: 'tel', url: 'url' };
+
+/** The answer control alone (input, select, textarea or option list). The builder canvas reuses it under editable labels. */
+export function renderControl(f: FormField, value: string, id: string): string {
+  const describe = f.help ? ` aria-describedby="${e(id)}-help"` : '';
+  const attrs = `id="${e(id)}" name="q_${e(f.id)}"${f.required ? ' required' : ''}${describe}`;
+  const ph = f.placeholder ? ` placeholder="${e(f.placeholder)}"` : '';
+  if (f.type === 'radio' || f.type === 'checkboxes') {
+    const radio = f.type === 'radio', chosen = radio ? [value] : value.split('\n');
+    const extra = chosen.find(v => v && !f.options.includes(v)) ?? '';
+    // A required checkbox group can't be enforced natively; the server checks it.
+    const req = radio && f.required ? ' required' : '';
+    const option = (o: string, i: number) => `<label class="pc-bk-option"><input type="${radio ? 'radio' : 'checkbox'}" id="${e(id)}-${i}" name="q_${e(f.id)}" value="${e(o)}"${req}${chosen.includes(o) ? ' checked' : ''}/><span>${e(o)}</span></label>`;
+    const other = hasOther(f) ? `<label class="pc-bk-option pc-bk-other"><input type="${radio ? 'radio' : 'checkbox'}" name="q_${e(f.id)}" value="${OTHER}"${req}${extra ? ' checked' : ''}/><span>Other</span><input type="text" name="o_${e(f.id)}" maxlength="200" aria-label="Other answer for ${e(f.label)}" placeholder="${e(f.placeholder || 'Type your answer')}" value="${e(extra)}"/></label>` : '';
+    return `<div class="pc-bk-options">${f.options.map(option).join('')}${other}</div>`;
+  }
+  if (f.type === 'textarea') return `<textarea ${attrs}${ph} maxlength="2000" rows="3">${e(value)}</textarea>`;
+  if (f.type === 'select') return `<select ${attrs}><option value="">${e(f.placeholder || 'Choose…')}</option>${f.options.map(o => `<option value="${e(o)}" ${o === value ? 'selected' : ''}>${e(o)}</option>`).join('')}</select>`;
+  const ac = (autocomplete[f.type] ? ` autocomplete="${autocomplete[f.type]}"` : '') + (f.type === 'url' ? ' inputmode="url" spellcheck="false"' : '');
+  return `<input ${attrs}${ph}${ac} type="${inputType[f.type] ?? 'text'}"${f.type === 'number' ? ' step="any"' : ''} maxlength="${f.type === 'phone' ? 40 : 2000}" value="${e(value)}"/>`;
+}
+
+export function renderField(f: FormField, value: string, prefix: string): string {
+  const id = `${prefix}-${f.id}`, half = isHalf(f) ? ' is-half' : '';
+  const help = f.help ? `<small id="${e(id)}-help">${e(f.help)}</small>` : '';
+  const label = `${e(f.label)}${f.required ? ' *' : ''}`;
+  if (f.type === 'heading') return `<div class="pc-form-heading" id="${e(id)}"><h3>${e(f.label)}</h3>${f.help ? `<p>${e(f.help)}</p>` : ''}</div>`;
+  if (f.type === 'checkbox' || f.type === 'consent') return `<label class="pc-bk-check${half}" for="${e(id)}"><input type="checkbox" id="${e(id)}" name="q_${e(f.id)}" ${f.required ? 'required' : ''} ${f.help ? `aria-describedby="${e(id)}-help"` : ''} value="yes" ${value === 'yes' ? 'checked' : ''}/><span>${label}${help}</span></label>`;
+  if (f.type === 'radio' || f.type === 'checkboxes') return `<fieldset class="pc-bk-field pc-bk-choices${half}"${f.help ? ` aria-describedby="${e(id)}-help"` : ''}><legend>${label}</legend>${renderControl(f, value, id)}${help}</fieldset>`;
+  return `<label class="pc-bk-field${half}" for="${e(id)}"><span>${label}</span>${renderControl(f, value, id)}${help}</label>`;
+}
+
+/** Two consecutive half-width questions share a `.pc-form-row` (side by side when there's room). */
+export function renderFields(definition: FormDefinition, values: Record<string, string> = {}, prefix = 'form'): string {
+  const out: string[] = []; let row: string[] = [];
+  const flush = () => { if (row.length) out.push(`<div class="pc-form-row">${row.join('')}</div>`); row = []; };
+  for (const f of definition.fields) {
+    const html = renderField(f, values[f.id] ?? '', prefix);
+    if (isHalf(f)) { row.push(html); if (row.length === 2) flush(); }
+    else { flush(); out.push(html); }
+  }
+  flush();
+  return out.join('');
+}

package/src/lib/forms/http.ts

@@ -0,0 +1,29 @@
+import { ApiError } from '../api';
+import { sha256Hex } from '../api-keys';
+import type { ContentRepository } from '../repo/types';
+import type { FormDefinition } from './schema';
+import { AnswerError, answersFrom } from './validate';
+export function checkOrigin(request: Request) {
+  const origin = request.headers.get('origin');
+  if ((origin && origin !== new URL(request.url).origin) || request.headers.get('sec-fetch-site') === 'cross-site') throw new ApiError(403, 'Please submit from this site.');
+}
+export async function readForm(request: Request): Promise<FormData> {
+  checkOrigin(request);
+  // Read the stream with an actual bound (Content-Length is not trustworthy).
+  const reader = request.body?.getReader(); let length = 0; const chunks: Uint8Array[] = [];
+  if (reader) for (;;) { const { value, done } = await reader.read(); if (done) break; length += value.length; if (length > 100_000) { await reader.cancel(); throw new ApiError(413, 'This form is too large.'); } chunks.push(value); }
+  const bytes = new Uint8Array(length); let at = 0; for (const c of chunks) { bytes.set(c, at); at += c.length; }
+  try { return await new Response(bytes, { headers: { 'Content-Type': request.headers.get('content-type') || 'application/x-www-form-urlencoded' } }).formData(); }
+  catch { throw new ApiError(400, 'Could not read this form.'); }
+}
+export function readAnswers(data: FormData, definition: FormDefinition) {
+  try { return answersFrom(name => data.getAll(name), definition); }
+  catch (e) { if (e instanceof AnswerError) throw new ApiError(400, e.message); throw e; }
+}
+export async function submissionGuard(repo: ContentRepository, data: FormData, address: string, scope: string) {
+  if (data.get('website')) throw new ApiError(400, 'Could not submit this form.');
+  if (!await repo.email.rateLimit(`forms:${await sha256Hex(scope + ':' + address)}`, 20, 60_000)) throw new ApiError(429, 'Too many submissions. Please try again in a minute.');
+  const key = String(data.get('requestId') ?? '');
+  if (!/^[a-f\d]{8}-[a-f\d]{4}-4[a-f\d]{3}-[89ab][a-f\d]{3}-[a-f\d]{12}$/i.test(key)) throw new ApiError(400, 'Reload the form and try again.');
+  return key;
+}

package/src/lib/forms/render.ts

@@ -0,0 +1,11 @@
+import type { FormDefinition } from './schema';
+import { formVersion } from './service';
+import { escapeForm, renderFields } from './fields';
+export { escapeForm, renderFields } from './fields';
+export function hiddenFields(version: string, requestId: string) {
+  return `<input type="hidden" name="formVersion" value="${escapeForm(version)}"><input type="hidden" name="requestId" value="${escapeForm(requestId)}"><div class="pc-form-trap" aria-hidden="true"><label>Leave empty<input name="website" tabindex="-1" autocomplete="off"></label></div>`;
+}
+export async function renderForm(id: string, definition: FormDefinition, values: Record<string, string> = {}, error = '', requestId: string = crypto.randomUUID(), embed = false) {
+  const e = escapeForm;
+  return `<section class="pc-simple-form">${definition.title ? `<h2>${e(definition.title)}</h2>` : ''}${definition.intro ? `<p>${e(definition.intro)}</p>` : ''}<form method="post" action="/forms/${e(id)}${embed ? '?embed=1' : ''}">${error ? `<p class="pc-bk-error" role="alert">${e(error)}</p>` : ''}${hiddenFields(await formVersion(definition), requestId)}${renderFields(definition, values, `f-${id}`)}<button type="submit" class="pc-bk-submit">${e(definition.submitLabel || 'Submit')}</button></form></section>`;
+}

package/src/lib/forms/schema.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+
+// `checkbox` and `consent` both mean "must tick to agree" (consent is what the
+// builder inserts; checkbox stays valid for existing data). `heading` has no
+// answer: it is a section title (label) with an optional description (help).
+export const FIELD_TYPES = ['text', 'textarea', 'email', 'phone', 'number', 'select', 'checkbox', 'date', 'radio', 'checkboxes', 'url', 'consent', 'heading'] as const;
+export const CHOICE_TYPES: readonly string[] = ['select', 'radio', 'checkboxes'];
+export const FIELD_ID = /^[a-zA-Z][a-zA-Z0-9_-]{0,79}$/;
+export const FormField = z.object({
+  id: z.string().regex(FIELD_ID),
+  type: z.enum(FIELD_TYPES), label: z.string().trim().min(1).max(200),
+  required: z.boolean().default(false), help: z.string().max(300).default(''),
+  // Checkbox answers are stored newline-joined, so a choice is one line.
+  options: z.array(z.string().trim().min(1).max(200).regex(/^[^\r\n]*$/, 'Each choice must be one line.')).max(50).default([]),
+  // Newer props are optional (not defaulted) on purpose: parsing must not add
+  // keys to stored definitions, because form versions and the submission
+  // guard compare the exact JSON. Read them through the helpers below.
+  placeholder: z.string().max(120).optional(),
+  width: z.enum(['full', 'half']).optional(),
+  allowOther: z.boolean().optional(),
+});
+export type FormField = z.infer<typeof FormField>;
+export const FormDefinition = z.object({
+  title: z.string().max(120).default(''), intro: z.string().max(1000).default(''),
+  submitLabel: z.string().max(80).default(''), confirmation: z.string().max(1000).default('Thank you. Your response has been received.'),
+  fields: z.array(FormField).max(30).default([]),
+}).superRefine((d, ctx) => {
+  if (new Set(d.fields.map(f => f.id)).size !== d.fields.length) ctx.addIssue({ code: 'custom', message: 'Field IDs must be unique.' });
+  for (const f of d.fields) if (CHOICE_TYPES.includes(f.type) && (!f.options.length || new Set(f.options).size !== f.options.length)) ctx.addIssue({ code: 'custom', message: `“${f.label}” needs unique choices.` });
+});
+export type FormDefinition = z.infer<typeof FormDefinition>;
+export const isHalf = (f: Pick<FormField, 'width' | 'type'>) => f.width === 'half' && f.type !== 'heading';
+export const hasOther = (f: Pick<FormField, 'allowOther' | 'type'>) => Boolean(f.allowOther) && (f.type === 'radio' || f.type === 'checkboxes');
+/** Fields that collect an answer (section headings don't). */
+export const answerFields = (d: Pick<FormDefinition, 'fields'>) => d.fields.filter(f => f.type !== 'heading');
+export const FormResponse = z.object({ version: z.string(), definition: FormDefinition, answers: z.record(z.string().max(2000)) });
+export type FormResponse = z.infer<typeof FormResponse>;
+export const SavedForm = z.object({
+  id: z.string(), name: z.string().trim().min(1).max(120), kind: z.enum(['form', 'template']), purpose: z.enum(['event', 'general']),
+  status: z.enum(['draft', 'published', 'archived']), definition: FormDefinition, draft: FormDefinition.nullable(),
+  revision: z.number().int(), createdAt: z.number(), updatedAt: z.number(),
+});
+export type SavedForm = z.infer<typeof SavedForm>;
+export const FormSubmission = z.object({ id: z.string(), formId: z.string(), response: FormResponse, createdAt: z.number() });
+export type FormSubmission = z.infer<typeof FormSubmission>;
+const field = (id: string, label: string, type: FormField['type'], required = false, options: string[] = []): FormField => ({ id, label, type, required, help: '', options });
+export function starter(key: string): FormDefinition {
+  const contact = key === 'contact', interest = key === 'interest';
+  return FormDefinition.parse({
+    title: contact ? 'Contact us' : interest ? 'Stay in touch' : 'Save your seat',
+    submitLabel: contact ? 'Send message' : interest ? 'Sign up' : '',
+    confirmation: contact || interest ? 'Thank you. Your response has been received.' : '',
+    fields: contact || interest ? [field('name', 'Your name', 'text', true), field('email', 'Email', 'email', true), ...(contact ? [field('message', 'Message', 'textarea', true)] : [])]
+      : key === 'event' ? [field('phone', 'Phone', 'phone'), field('dietary', 'Dietary needs', 'textarea'), field('notes', 'Notes', 'textarea')] : [],
+  });
+}

package/src/lib/forms/service.ts

@@ -0,0 +1,38 @@
+import { ApiError } from '../api';
+import { sha256Hex } from '../api-keys';
+import { FormDefinition, answerFields, type FormResponse } from './schema';
+import { AnswerError, checkAnswer } from './validate';
+
+export const formVersion = (definition: FormDefinition) => sha256Hex(JSON.stringify(FormDefinition.parse(definition)));
+export async function collectResponse(definition: FormDefinition, input: Record<string, string>, version?: string): Promise<FormResponse> {
+  definition = FormDefinition.parse(definition);
+  const current = await formVersion(definition);
+  if (version !== undefined && version !== current) throw new ApiError(409, 'This form has changed. Review the updated questions and submit again.');
+  const answers: Record<string, string> = Object.create(null);
+  if (Object.keys(input).length > 30) throw new ApiError(400, 'Too many answers.');
+  for (const f of answerFields(definition)) {
+    try { answers[f.id] = checkAnswer(f, input[f.id] ?? ''); }
+    catch (e) { if (e instanceof AnswerError) throw new ApiError(400, e.message); throw e; }
+  }
+  return { version: current, definition, answers };
+}
+// Labels are a compatibility view only; snapshots are the authoritative record.
+export function displayAnswers(response: FormResponse): Record<string, string> {
+  const out: Record<string, string> = Object.create(null);
+  for (const f of answerFields(response.definition)) {
+    const v = response.answers[f.id];
+    let label = f.label;
+    let n = 0;
+    while (Object.hasOwn(out, label)) label = `${f.label} (${f.id}${n++ ? `-${n}` : ''})`;
+    out[label] = f.type === 'checkbox' || f.type === 'consent' ? v === 'yes' ? 'Yes' : 'No'
+      : f.type === 'checkboxes' ? (v ? v.split('\n').join(', ') : '—') : v || '—';
+  }
+  return out;
+}
+export function csv(rows: unknown[][]): string {
+  return '\uFEFF' + rows.map(row => row.map(cell => {
+    let s = String(cell ?? '');
+    if (/^[\s]*[=+\-@]|^[\t\r\n]/.test(s)) s = "'" + s;
+    return '"' + s.replace(/"/g, '""') + '"';
+  }).join(',')).join('\r\n');
+}

package/src/lib/forms/store.ts

@@ -0,0 +1,78 @@
+import type { SqlDriver, SqlStatement } from '../repo/sql';
+import { ApiError } from '../api';
+import { FormDefinition, FormResponse, FormSubmission, SavedForm } from './schema';
+const row = (r: Record<string, unknown>) => SavedForm.parse({ ...r, definition: JSON.parse(String(r.definition)), draft: r.draft ? JSON.parse(String(r.draft)) : null, createdAt: r.created_at, updatedAt: r.updated_at });
+export const formInsert = (f: SavedForm): SqlStatement => ({ sql: 'INSERT INTO forms (id,name,kind,purpose,status,definition,draft,revision,created_at,updated_at) VALUES (?,?,?,?,?,?,?,?,?,?)', args: [f.id,f.name,f.kind,f.purpose,f.status,JSON.stringify(f.definition),f.draft ? JSON.stringify(f.draft) : null,f.revision,f.createdAt,f.updatedAt] });
+export const submissionInsert = (s: FormSubmission): SqlStatement => ({ sql: 'INSERT INTO form_submissions (id,form_id,response,created_at) VALUES (?,?,?,?)', args: [s.id,s.formId,JSON.stringify(s.response),s.createdAt] });
+export class FormStore {
+  constructor(private driver: () => Promise<SqlDriver>) {}
+  async list() { return (await (await this.driver()).all('SELECT * FROM forms ORDER BY updated_at DESC')).map(row); }
+  async get(id: string) { const r = (await (await this.driver()).all('SELECT * FROM forms WHERE id=?', [id]))[0]; return r ? row(r) : null; }
+  async create(name: string, definition: FormDefinition, kind: SavedForm['kind'] = 'form', purpose: SavedForm['purpose'] = 'general') {
+    const now = Date.now();
+    const f = SavedForm.parse({ id: crypto.randomUUID(), name, definition, kind, purpose, status: 'draft', draft: null, revision: 1, createdAt: now, updatedAt: now });
+    await (await this.driver()).batch([formInsert(f)]); return f;
+  }
+  async save(id: string, revision: number, name: string, definition: FormDefinition, op: 'save' | 'publish' | 'archive') {
+    const current = await this.get(id); if (!current) throw new ApiError(404, 'Form not found.');
+    const f = SavedForm.parse({ ...current, name, definition });
+    // Published definitions remain immutable until an explicit publish.
+    const live = op === 'save' && current.status === 'published';
+    const rows = await (await this.driver()).all('UPDATE forms SET name=?,definition=?,draft=?,status=?,revision=revision+1,updated_at=? WHERE id=? AND revision=? RETURNING id',
+      [f.name, JSON.stringify(live ? current.definition : f.definition), live ? JSON.stringify(f.definition) : null, op === 'publish' ? 'published' : op === 'archive' ? 'archived' : current.status, Date.now(), id, revision]);
+    if (!rows.length) throw new ApiError(409, 'This form changed in another window. Reload before saving.');
+  }
+  async submissions(formId?: string, limit = 100, offset = 0) {
+    return (await (await this.driver()).all(`SELECT * FROM form_submissions ${formId ? 'WHERE form_id=?' : ''} ORDER BY created_at DESC LIMIT ? OFFSET ?`, [...(formId ? [formId] : []), limit, offset])).map(r => FormSubmission.parse({ id: r.id, formId: r.form_id, response: JSON.parse(String(r.response)), createdAt: r.created_at }));
+  }
+  async submit(formId: string, response: FormResponse, requestId: string) {
+    response = FormResponse.parse(response);
+    const db = await this.driver();
+    // The receipt is also the unique request identity, so retries don't duplicate responses.
+    const old = (await db.all('SELECT form_id,response FROM form_submissions WHERE id=?', [requestId]))[0];
+    if (old && (old.form_id !== formId || String(old.response) !== JSON.stringify(response))) throw new ApiError(409, 'This request was already submitted with different answers. Reload to send a new response.');
+    if (!old) await db.run('INSERT OR IGNORE INTO form_submissions (id,form_id,response,created_at) SELECT ?,?,?,? WHERE EXISTS (SELECT 1 FROM forms WHERE id=? AND status=\'published\' AND kind=\'form\' AND purpose=\'general\' AND definition=?)', [requestId,formId,JSON.stringify(response),Date.now(),formId,JSON.stringify(response.definition)]);
+    const saved = (await db.all('SELECT form_id,response FROM form_submissions WHERE id=?', [requestId]))[0];
+    if (!saved || saved.form_id !== formId || String(saved.response) !== JSON.stringify(response)) throw new ApiError(409, 'This form changed. Reload and try again.');
+  }
+  // Archived → draft (the definition is kept; publishing reopens it).
+  async restore(id: string) { await (await this.driver()).run("UPDATE forms SET status='draft',revision=revision+1,updated_at=? WHERE id=? AND status='archived'", [Date.now(), id]); }
+  // One grouped query for the list page: response count + latest per form.
+  async stats() {
+    const rows = await (await this.driver()).all('SELECT form_id, COUNT(*) AS n, MAX(created_at) AS last FROM form_submissions GROUP BY form_id');
+    return new Map(rows.map(r => [String(r.form_id), { count: Number(r.n), last: r.last == null ? null : Number(r.last) }]));
+  }
+  async submissionStats(formId: string, since: number) {
+    const r = (await (await this.driver()).all('SELECT COUNT(*) AS n, MAX(created_at) AS last, SUM(CASE WHEN created_at >= ? THEN 1 ELSE 0 END) AS recent FROM form_submissions WHERE form_id=?', [since, formId]))[0] ?? {};
+    return { total: Number(r.n ?? 0), recent: Number(r.recent ?? 0), last: r.last == null ? null : Number(r.last) };
+  }
+  // Distinct definition versions in first-seen order, so v1…vN read as history.
+  async versions(formId: string) {
+    return (await (await this.driver()).all("SELECT json_extract(response,'$.version') AS v, MIN(created_at) AS first FROM form_submissions WHERE form_id=? GROUP BY v ORDER BY first ASC LIMIT 500", [formId])).map(r => String(r.v));
+  }
+  // Filtered page of responses. `q` matches answers only (not question labels).
+  async searchSubmissions(formId: string, opts: { limit?: number; offset?: number; since?: number; q?: string; ids?: string[] } = {}) {
+    const where = ['form_id=?'], args: unknown[] = [formId];
+    if (opts.since) { where.push('created_at >= ?'); args.push(opts.since); }
+    const q = opts.q?.trim().slice(0, 100);
+    // instr, not LIKE: D1 rejects LIKE patterns over 50 bytes
+    if (q) { where.push("EXISTS (SELECT 1 FROM json_each(form_submissions.response,'$.answers') WHERE instr(lower(CAST(value AS TEXT)), lower(?)) > 0)"); args.push(q); }
+    if (opts.ids) { const ids = opts.ids.slice(0, 500); if (!ids.length) return []; where.push(`id IN (${ids.map(() => '?').join(',')})`); args.push(...ids); }
+    return (await (await this.driver()).all(`SELECT * FROM form_submissions WHERE ${where.join(' AND ')} ORDER BY created_at DESC LIMIT ? OFFSET ?`, [...args, opts.limit ?? 100, opts.offset ?? 0])).map(r => FormSubmission.parse({ id: r.id, formId: r.form_id, response: JSON.parse(String(r.response)), createdAt: r.created_at }));
+  }
+  async deleteSubmissions(formId: string, ids: string[]) { for (const id of ids.slice(0, 500)) await this.deleteSubmission(formId, id); }
+  // Posts, pages and events whose body (live or staged draft) embeds this form.
+  async usedOn(formId: string) {
+    const db = await this.driver();
+    // instr, not LIKE: a uuid pattern is over D1's 50-byte LIKE limit
+    const html = `data-form="${formId}"`, json = `data-form=\\"${formId}\\"`;
+    const q = (table: string, extra = '') => db.all(`SELECT id, title, status${extra} FROM ${table} WHERE instr(body_html, ?) > 0 OR instr(draft, ?) > 0 ORDER BY updated_at DESC LIMIT 50`, [html, json]);
+    const [posts, pages, events] = await Promise.all([q('posts', ', collection'), q('pages'), q('events')]);
+    return [
+      ...posts.map(r => ({ kind: 'post' as const, id: String(r.id), title: String(r.title || ''), status: String(r.status), collection: String(r.collection || 'posts') })),
+      ...pages.map(r => ({ kind: 'page' as const, id: String(r.id), title: String(r.title || ''), status: String(r.status), collection: '' })),
+      ...events.map(r => ({ kind: 'event' as const, id: String(r.id), title: String(r.title || ''), status: String(r.status), collection: '' })),
+    ];
+  }
+  async deleteSubmission(formId: string, id: string) { await (await this.driver()).run('DELETE FROM form_submissions WHERE form_id=? AND id=?', [formId,id]); }
+}

package/src/lib/forms/validate.ts

@@ -0,0 +1,71 @@
+// Pure answer reading + validation, shared by the server (collectResponse,
+// readAnswers) and the builder's preview. No server imports here.
+import { answerFields, hasOther, type FormDefinition, type FormField } from './schema';
+
+/** Value of the "Other" radio/checkbox; its text arrives as `o_<field id>`. */
+export const OTHER = '__other__';
+export class AnswerError extends Error {}
+const invalid = (f: FormField) => new AnswerError(`Please enter a valid answer for “${f.label}”.`);
+
+/** Reads posted answers (`q_<id>`, plus `o_<id>` for "Other" text). Checkbox groups may post several values; they are stored newline-joined. */
+export function answersFrom(getAll: (name: string) => unknown[], definition: Pick<FormDefinition, 'fields'>): Record<string, string> {
+  const answers: Record<string, string> = Object.create(null);
+  for (const f of answerFields(definition)) {
+    const values = getAll(`q_${f.id}`);
+    if (values.some(v => typeof v !== 'string')) throw new AnswerError('Invalid form answer.');
+    const other = () => { const o = getAll(`o_${f.id}`); if (o.length > 1 || o.some(v => typeof v !== 'string')) throw new AnswerError('Invalid form answer.'); return String(o[0] ?? '').trim(); };
+    if (f.type === 'checkboxes') {
+      if (values.length > f.options.length + 1) throw new AnswerError('Invalid form answer.');
+      let list = values as string[];
+      if (hasOther(f) && list.includes(OTHER)) { const text = other(); list = list.filter(v => v !== OTHER); if (text) list.push(text); }
+      answers[f.id] = list.join('\n');
+    } else {
+      if (values.length > 1) throw new AnswerError('Invalid form answer.');
+      const value = String(values[0] ?? '');
+      answers[f.id] = f.type === 'radio' && hasOther(f) && value === OTHER ? other() : value;
+    }
+  }
+  return answers;
+}
+
+/** Validates one answer and returns its stored form. Throws AnswerError with a visitor-facing message. */
+export function checkAnswer(f: FormField, raw: unknown): string {
+  if (typeof raw !== 'string' || raw.length > 2000) throw new AnswerError(`“${f.label}” is too long.`);
+  if (f.type === 'heading') return '';
+  if (f.type === 'checkboxes') {
+    const items = raw.split('\n').map(s => s.trim()).filter(Boolean);
+    const extra = items.filter(i => !f.options.includes(i));
+    if (f.required && !items.length) throw new AnswerError(`Please answer “${f.label}”.`);
+    if (new Set(items).size !== items.length || extra.length > (hasOther(f) ? 1 : 0) || extra.some(e => e.length > 200)) throw invalid(f);
+    // Store in the form's choice order, with "Other" text last.
+    return [...f.options.filter(o => items.includes(o)), ...extra].join('\n');
+  }
+  let value = raw.trim();
+  const agree = f.type === 'checkbox' || f.type === 'consent';
+  if (f.required && (!value || (agree && value !== 'yes'))) throw new AnswerError(`Please answer “${f.label}”.`);
+  if (!value) return value;
+  let valid = true;
+  if (f.type === 'email') valid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+  if (f.type === 'number') valid = /^[-+]?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?$/i.test(value) && Number.isFinite(Number(value));
+  if (f.type === 'date') valid = /^\d{4}-\d{2}-\d{2}$/.test(value) && Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0, 10) === value;
+  if (f.type === 'select') valid = f.options.includes(value);
+  if (f.type === 'radio') valid = f.options.includes(value) || (hasOther(f) && value.length <= 200 && !value.includes('\n'));
+  if (agree) valid = value === 'yes';
+  if (f.type === 'phone') valid = value.length <= 40 && /^[+\d().\s-]+$/.test(value);
+  if (f.type === 'url') {
+    // Accept "example.org" too; store it with a scheme.
+    if (!/^[a-z][a-z\d+.-]*:/i.test(value)) value = `https://${value}`;
+    try { const u = new URL(value); valid = (u.protocol === 'https:' || u.protocol === 'http:') && /\./.test(u.hostname) && !/\s/.test(value); }
+    catch { valid = false; }
+  }
+  if (!valid) throw invalid(f);
+  return value;
+}
+
+/** All answers at once (used by the builder preview); returns the first error message, or ''. */
+export function firstError(definition: Pick<FormDefinition, 'fields'>, answers: Record<string, string>): string {
+  for (const f of answerFields(definition)) {
+    try { checkAnswer(f, answers[f.id] ?? ''); } catch (e) { return e instanceof Error ? e.message : 'Invalid answer.'; }
+  }
+  return '';
+}

package/src/lib/maps/config.ts

@@ -0,0 +1,64 @@
+// Maps setup: acms({ maps: { provider } }) picks the provider; secrets come
+// from the environment (Worker vars/secrets or process.env):
+//   MAPS_API_KEY — the provider's API key / access token
+//   MAPS_URL     — base URL of a self-hosted Photon, Nominatim or Pelias
+// With no provider configured: MAPS_URL set → photon; else MAPS_API_KEY set
+// → geoapify; else maps are off (link parsing and saved places still work).
+// Keys stay on the server — only MapsStatus ever reaches the browser.
+import { userConfig } from 'virtual:acms-config';
+import { env } from '../env';
+import type { MapsProviderId, MapsStatus } from './types';
+import { PROVIDERS, type MapsProvider } from './providers';
+
+function runtimeValue(key: string, locals?: unknown): string {
+  const value = (locals as { runtime?: { env?: Record<string, unknown> } } | undefined)?.runtime?.env?.[key];
+  return typeof value === 'string' ? value.trim() : env(key).trim();
+}
+
+function configuredProvider(): MapsProviderId | '' {
+  const p = userConfig.maps?.provider ?? '';
+  return p in PROVIDERS ? (p as MapsProviderId) : '';
+}
+
+interface Resolved {
+  id: MapsProviderId | '';
+  key: string;
+  url: string;
+  ready: boolean;
+}
+
+function resolve(locals?: unknown): Resolved {
+  const key = runtimeValue('MAPS_API_KEY', locals);
+  const url = runtimeValue('MAPS_URL', locals).replace(/\/+$/, '');
+  const id = configuredProvider() || (url ? 'photon' : key ? 'geoapify' : '');
+  if (!id) return { id: '', key, url, ready: false };
+  const def = PROVIDERS[id];
+  const okUrl = /^https?:\/\//i.test(url);
+  return { id, key, url, ready: def.selfHosted ? okUrl : Boolean(key) };
+}
+
+export function mapsStatus(locals?: unknown): MapsStatus {
+  const r = resolve(locals);
+  if (!r.id) return { enabled: false, provider: '', label: '', search: false, staticMaps: false };
+  const def = PROVIDERS[r.id];
+  return { enabled: r.ready, provider: r.id, label: def.label, search: r.ready, staticMaps: r.ready && def.staticMaps };
+}
+
+/** the active provider adapter, or null when maps aren't set up */
+export function activeProvider(locals?: unknown, origin = ''): MapsProvider | null {
+  const r = resolve(locals);
+  if (!r.id || !r.ready) return null;
+  return PROVIDERS[r.id].create({ key: r.key, url: r.url, userAgent: `acms${origin ? ` (+${origin})` : ''}` });
+}
+
+// what the setup instructions show for each provider
+export const MAPS_SETUP: { id: MapsProviderId; env: string }[] = [
+  { id: 'geoapify', env: 'MAPS_API_KEY' },
+  { id: 'google', env: 'MAPS_API_KEY' },
+  { id: 'mapbox', env: 'MAPS_API_KEY' },
+  { id: 'locationiq', env: 'MAPS_API_KEY' },
+  { id: 'stadia', env: 'MAPS_API_KEY' },
+  { id: 'photon', env: 'MAPS_URL' },
+  { id: 'nominatim', env: 'MAPS_URL' },
+  { id: 'pelias', env: 'MAPS_URL' },
+];

package/src/lib/maps/migration.ts

@@ -0,0 +1,12 @@
+// Saved places (HQ, the park pavilion…) and the place a room is in. Event
+// locations live in the events.location JSON column, so the new pin fields
+// (lat/lng, placeId, map images) need no event migration.
+export const PLACES_MIGRATION = { version: 43, statements: [
+  `CREATE TABLE IF NOT EXISTS places (
+    id TEXT PRIMARY KEY, name TEXT NOT NULL, address TEXT NOT NULL DEFAULT '', url TEXT NOT NULL DEFAULT '',
+    lat REAL, lng REAL, notes TEXT NOT NULL DEFAULT '', is_default INTEGER NOT NULL DEFAULT 0,
+    map_image TEXT NOT NULL DEFAULT '', map_image_dark TEXT NOT NULL DEFAULT '',
+    ord INTEGER NOT NULL DEFAULT 0, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+  )`,
+  `ALTER TABLE resources ADD COLUMN place_id TEXT NOT NULL DEFAULT ''`,
+] };