@acms-subir/core 0.3.41 → 0.3.43

package/src/lib/email/service.ts

@@ -1,9 +1,11 @@
 import type { ContentRepository } from '../repo/types';
 import { resolveConfig, decrypt, encrypt, runtimeValue } from './config';
 import { sendWithProvider } from './providers';
-import { accountMail, canonicalOrigin, eventRequestMail, guestCodeMail, EmailLinkError } from './templates';
-import { formatDate } from '../dates';
+import { accountMail, canonicalOrigin, eventRequestMail, guestCodeMail, phoneLinkedMail, EmailLinkError } from './templates';
+import { formatDate, siteLang } from '../dates';
+import { I18N } from '../i18n';
 import { bookingMail } from '../booking/service';
+import { formAlertMail, type AlertPayload } from '../forms/alert-mail';
 import type { EmailJob, Mail } from './types';
 
 async function render(repo: ContentRepository, job: EmailJob, locals?: unknown, from = ''): Promise<Mail | null> {
@@ -16,6 +18,17 @@ async function render(repo: ContentRepository, job: EmailJob, locals?: unknown,
     if (!current || current.createdAt !== payload.issuedAt || current.expiresAt <= Date.now()) return null;
     return guestCodeMail(job.recipient, settings.siteTitle, decrypt<string>(payload.code, `guest-code:${job.dedupe}`, locals));
   }
+  if (job.kind === 'phone-linked') {
+    const p = JSON.parse(job.payload) as { platform: 'ios' | 'android'; at: number; path: string };
+    const lang = (I18N.enabled && I18N.defaultLocale) || siteLang(settings);
+    let when: string;
+    try { when = new Intl.DateTimeFormat(lang, { dateStyle: 'long', timeStyle: 'short', timeZone: settings.timezone || 'UTC' }).format(p.at); }
+    catch { when = new Date(p.at).toISOString().slice(0, 16).replace('T', ' ') + ' UTC'; }
+    // a security notice still goes out without the link while Site URL is unset
+    let origin = '';
+    try { origin = canonicalOrigin(settings.siteUrl); } catch { /* text names the panel instead */ }
+    return phoneLinkedMail(job.recipient, settings.siteTitle, lang, p.platform, when, origin ? `${origin}${p.path}` : '');
+  }
   const origin = canonicalOrigin(settings.siteUrl);
   if (job.kind === 'booking') {
     const payload = JSON.parse(job.payload);
@@ -25,6 +38,7 @@ async function render(repo: ContentRepository, job: EmailJob, locals?: unknown,
     const mail = await bookingMail(repo, b, payload.kind, origin, from, payload, job.recipient);
     return { ...mail, to: job.recipient };
   }
+  if (job.kind === 'form-alert') return formAlertMail(repo, job.recipient, JSON.parse(job.payload) as AlertPayload, origin);
   if (job.kind === 'auth') {
     const payload = JSON.parse(job.payload);
     const token = await repo.email.token(payload.tokenId);
@@ -76,6 +90,9 @@ export async function dispatchEmail(repo: ContentRepository, locals?: unknown, l
           await repo.email.finish(j,{state:'cancelled',error:'Optional notification disabled.'}); continue;
         }
       }
+      if (j.kind === 'form-alert' && !current.config.staffNotifications) {
+        await repo.email.finish(j,{state:'cancelled',error:'Optional notification disabled.'}); continue;
+      }
       const mail = await render(repo,j,locals,resolved.config.from);
       if (!mail) { await repo.email.finish(j,{state:'cancelled',error:'Notification no longer applies.'}); continue; }
       // Retries must reuse exactly the same request body, including calendar

package/src/lib/email/store.ts

@@ -123,10 +123,18 @@ export class EmailStore {
     }
   }
   async rateLimit(key: string, max: number, windowMs: number): Promise<boolean> {
+    return (await this.rateHit(key, windowMs)) <= max;
+  }
+  /** counts one hit and returns how many the window holds with it */
+  async rateHit(key: string, windowMs: number): Promise<number> {
     const now = Date.now(), d = await this.getDriver();
     const rows = await d.all(`INSERT INTO email_rate_limits (key,count,expires_at) VALUES (?,1,?) ON CONFLICT(key) DO UPDATE SET
       count=CASE WHEN expires_at <= ? THEN 1 ELSE count+1 END, expires_at=CASE WHEN expires_at <= ? THEN ? ELSE expires_at END RETURNING count`, [key,now+windowMs,now,now,now+windowMs]);
-    return Number(rows[0].count) <= max;
+    return Number(rows[0].count);
+  }
+  /** gives one hit back (an attempt counted up front that turned out fine) */
+  async rateRefund(key: string): Promise<void> {
+    await (await this.getDriver()).run('UPDATE email_rate_limits SET count=count-1 WHERE key=? AND count>0 AND expires_at>?', [key, Date.now()]);
   }
   /** true when key's current window already holds max hits (checks without counting) */
   async rateLimited(key: string, max: number): Promise<boolean> {

package/src/lib/email/templates.ts

@@ -41,3 +41,23 @@ export function canonicalOrigin(value: string): string {
   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;
 }
+// "A phone was linked" (lib/push/staff.ts): a security notice to the staff
+// member, in the site's main language (usted in Spanish, like other emails)
+const PHONE_LINKED: Record<string, { subject: string; intro: (phone: string, site: string, when: string) => string; notYou: string; button: string; noLink: string; ios: string; android: string }> = {
+  en: { subject: 'A phone was linked to your account', intro: (p, s, w) => `A phone (${p}) was linked to your account at ${s} on ${w}. It gets the test notifications you send from the admin.`,
+    notYou: 'If this wasn’t you, remove it in the admin', button: 'Test phones', noLink: 'If this wasn’t you, remove it in the admin under Test phones.', ios: 'iPhone or iPad', android: 'Android' },
+  es: { subject: 'Se vinculó un teléfono a su cuenta', intro: (p, s, w) => `Se vinculó un teléfono (${p}) a su cuenta de ${s} el ${w}. Recibe las notificaciones de prueba que usted envía desde el panel.`,
+    notYou: 'Si no fue usted, quítelo en el panel', button: 'Teléfonos de prueba', noLink: 'Si no fue usted, quítelo en el panel, en Teléfonos de prueba.', ios: 'iPhone o iPad', android: 'Android' },
+  fr: { subject: 'Un téléphone a été associé à votre compte', intro: (p, s, w) => `Un téléphone (${p}) a été associé à votre compte sur ${s} le ${w}. Il reçoit les notifications de test que vous envoyez depuis l’administration.`,
+    notYou: 'Si ce n’était pas vous, retirez-le dans l’administration', button: 'Téléphones de test', noLink: 'Si ce n’était pas vous, retirez-le dans l’administration, sous Téléphones de test.', ios: 'iPhone ou iPad', android: 'Android' },
+  de: { subject: 'Ein Telefon wurde mit Ihrem Konto verknüpft', intro: (p, s, w) => `Ein Telefon (${p}) wurde am ${w} mit Ihrem Konto bei ${s} verknüpft. Es erhält die Testbenachrichtigungen, die Sie im Adminbereich senden.`,
+    notYou: 'Wenn Sie das nicht waren, entfernen Sie es im Adminbereich', button: 'Testtelefone', noLink: 'Wenn Sie das nicht waren, entfernen Sie es im Adminbereich unter Testtelefone.', ios: 'iPhone oder iPad', android: 'Android' },
+  pt: { subject: 'Um telefone foi vinculado à sua conta', intro: (p, s, w) => `Um telefone (${p}) foi vinculado à sua conta em ${s} em ${w}. Ele recebe as notificações de teste que você envia pelo painel.`,
+    notYou: 'Se não foi você, remova-o no painel', button: 'Telefones de teste', noLink: 'Se não foi você, remova-o no painel, em Telefones de teste.', ios: 'iPhone ou iPad', android: 'Android' },
+};
+export function phoneLinkedMail(to: string, site: string, lang: string, platform: 'ios' | 'android', when: string, url: string): Mail {
+  const w = PHONE_LINKED[lang.toLowerCase().split('-')[0]] ?? PHONE_LINKED.en;
+  const intro = w.intro(platform === 'ios' ? w.ios : w.android, site, when);
+  return { to, subject: `${w.subject} · ${site}`, text: [w.subject, '', intro, '', url ? `${w.notYou}: ${url}` : w.noLink].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(w.subject)}</h1><p>${escape(intro)}</p>${url ? `<p>${escape(w.notYou)}:</p><p><a style="display:inline-block;background:#ee5d20;color:#fff;padding:10px 18px;border-radius:8px;text-decoration:none" href="${escape(url)}">${escape(w.button)}</a></p>` : `<p>${escape(w.noLink)}</p>`}</div></body></html>` };
+}

package/src/lib/forms/alert-mail.ts

@@ -0,0 +1,124 @@
+// The staff alert about a new form response (queued by lib/forms/alerts.ts)
+// and its push: in the site's main language, like other staff emails. With
+// the answers, every question in order with its label; without them (forms
+// that ask for sensitive things), only that a response arrived and when, so
+// the email holds nothing about the person. Plain HTML like the staff
+// booking emails, plus a text part. Other languages fall back to English.
+import type { ContentRepository } from '../repo/types';
+import type { Settings } from '../schema';
+import type { Mail } from '../email/types';
+import { validAddress } from '../email/config';
+import { siteLang, siteLocale } from '../dates';
+import { I18N } from '../i18n';
+import { fill } from '../live/words';
+import { answerFields, type FormField, type FormResponse } from './schema';
+
+/** alerts one form sends in a day (the site's); the last one says so */
+export const ALERTS_PER_DAY = 50;
+
+/** what a queued alert job carries: ids and switches, never the answers */
+export interface AlertPayload { formId: string; submissionId: string; answers: boolean; last: boolean; via: 'web' | 'app' }
+
+// {form}, {when}, {email} and {max} slots (live/words.ts `fill`)
+interface AlertWords {
+  subject: string; received: string; open: string; reply: string; last: string;
+  via: Record<AlertPayload['via'], string>; why: string; yes: string; no: string;
+  /** the push of the day's last alert */
+  pushLast: string;
+}
+const WORDS: Record<string, AlertWords> = {
+  en: { subject: 'New response: {form}', received: 'Received {when}', open: 'Open responses in the admin', reply: 'Reply to this email to write to {email}.',
+    last: 'That’s {max} alerts for this form today, so we’ll stop emailing about it until tomorrow. See Responses in the admin for the rest.',
+    via: { web: 'Sent from the website', app: 'Sent from the app' }, why: 'You get these because you’re on this form’s alert list.', yes: 'Yes', no: 'No',
+    pushLast: 'Received {when}. That’s {max} today; the rest are in the admin.' },
+  es: { subject: 'Nueva respuesta: {form}', received: 'Recibida el {when}', open: 'Ver las respuestas en el panel', reply: 'Responda a este correo para escribir a {email}.',
+    last: 'Ya son {max} avisos de este formulario hoy, así que no le escribiremos más sobre él hasta mañana. Vea las demás respuestas en el panel.',
+    via: { web: 'Enviada desde el sitio web', app: 'Enviada desde la app' }, why: 'Recibe estos correos porque está en la lista de avisos de este formulario.', yes: 'Sí', no: 'No',
+    pushLast: 'Recibida el {when}. Ya son {max} hoy; las demás están en el panel.' },
+  fr: { subject: 'Nouvelle réponse : {form}', received: 'Reçue le {when}', open: 'Ouvrir les réponses dans l’administration', reply: 'Répondez à cet e-mail pour écrire à {email}.',
+    last: 'Cela fait {max} alertes pour ce formulaire aujourd’hui : nous n’en enverrons plus avant demain. Les autres réponses sont dans l’administration.',
+    via: { web: 'Envoyée depuis le site', app: 'Envoyée depuis l’app' }, why: 'Vous recevez ces e-mails parce que vous êtes sur la liste d’alertes de ce formulaire.', yes: 'Oui', no: 'Non',
+    pushLast: 'Reçue le {when}. Cela fait {max} aujourd’hui ; les autres sont dans l’administration.' },
+  de: { subject: 'Neue Antwort: {form}', received: 'Eingegangen am {when}', open: 'Antworten in der Verwaltung öffnen', reply: 'Antworten Sie auf diese E-Mail, um {email} zu schreiben.',
+    last: 'Das sind heute {max} Benachrichtigungen für dieses Formular, daher schreiben wir bis morgen nicht mehr. Die übrigen Antworten finden Sie in der Verwaltung.',
+    via: { web: 'Über die Website gesendet', app: 'Über die App gesendet' }, why: 'Sie erhalten diese E-Mails, weil Sie auf der Benachrichtigungsliste dieses Formulars stehen.', yes: 'Ja', no: 'Nein',
+    pushLast: 'Eingegangen am {when}. Heute sind es {max}; die übrigen finden Sie in der Verwaltung.' },
+  pt: { subject: 'Nova resposta: {form}', received: 'Recebida em {when}', open: 'Abrir as respostas no painel', reply: 'Responda a este e-mail para escrever para {email}.',
+    last: 'Já são {max} alertas deste formulário hoje, então não enviaremos mais até amanhã. Veja as demais respostas no painel.',
+    via: { web: 'Enviada pelo site', app: 'Enviada pelo app' }, why: 'Você recebe estes e-mails porque está na lista de alertas deste formulário.', yes: 'Sim', no: 'Não',
+    pushLast: 'Recebida em {when}. Já são {max} hoje; as demais estão no painel.' },
+};
+
+/** the site's main language, and the locale for dates (keeping the site's region when it's the same language) */
+function alertLanguage(settings: Settings) {
+  const lang = (I18N.enabled && I18N.defaultLocale) || siteLang(settings);
+  const base = lang.toLowerCase().split('-')[0];
+  return { lang, w: WORDS[base] ?? WORDS.en, locale: base === siteLang(settings) ? siteLocale(settings) : lang };
+}
+// the email's "Oct 20, 2026, 3:41 PM"; the push's "Oct 20, 3:41 PM", in the site's zone
+function whenText(at: number, locale: string, tz: string, year: boolean) {
+  const opts: Intl.DateTimeFormatOptions = year ? { dateStyle: 'medium', timeStyle: 'short' } : { month: 'short', day: 'numeric', hour: 'numeric', minute: '2-digit' };
+  try { return new Intl.DateTimeFormat(locale, { ...opts, timeZone: tz || 'UTC' }).format(at); }
+  catch { return new Date(at).toISOString().slice(0, 16).replace('T', ' ') + ' UTC'; }
+}
+// names can't break the subject line
+const oneLine = (s: string) => s.replace(/\s+/g, ' ').trim();
+
+function shown(f: FormField, value: string | undefined, w: AlertWords) {
+  if (f.type === 'checkbox' || f.type === 'consent') return value === 'yes' ? w.yes : w.no;
+  if (f.type === 'checkboxes') return value ? value.split('\n').join(', ') : '—';
+  return value || '—';
+}
+/** the answer to the first email question, when it's a usable address (else '') */
+export function replyAddress(response: FormResponse): string {
+  for (const f of answerFields(response.definition)) {
+    const v = (response.answers[f.id] ?? '').trim();
+    if (f.type === 'email' && v && validAddress(v)) return v;
+  }
+  return '';
+}
+
+const esc = (s: string) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+/**
+ * The alert email for one queued job, or null when it no longer applies:
+ * the response was deleted, the form's alerts were turned off or this
+ * address was taken off the list. Turning the answers off also covers
+ * alerts still waiting to go out.
+ */
+export async function formAlertMail(repo: ContentRepository, to: string, p: AlertPayload, origin: string): Promise<Mail | null> {
+  const [form, s, settings] = await Promise.all([repo.forms.get(p.formId), repo.forms.submission(p.formId, p.submissionId), repo.getSettings()]);
+  if (!form || !s || !form.alerts.enabled || !form.alerts.to.includes(to.trim().toLowerCase())) return null;
+  const answers = p.answers && form.alerts.answers;
+  const { lang, w, locale } = alertLanguage(settings);
+  const name = oneLine(form.name);
+  const heading = fill(w.subject, { form: name });
+  const intro = fill(w.received, { when: whenText(s.createdAt, locale, settings.timezone, true) });
+  const rows: [string, string][] = answers ? answerFields(s.response.definition).map((f) => [f.label, shown(f, s.response.answers[f.id], w)]) : [];
+  // replies reach the person only when the email shows their answers
+  const replyTo = answers ? replyAddress(s.response) : '';
+  const notes = [...(replyTo ? [fill(w.reply, { email: replyTo })] : []), ...(p.last ? [fill(w.last, { max: String(ALERTS_PER_DAY) })] : [])];
+  const button = { href: `${origin}/admin/forms/${encodeURIComponent(form.id)}/submissions`, label: w.open };
+  const footer = `${w.via[p.via === 'app' ? 'app' : 'web']} · ${w.why}`;
+  const html = `<!doctype html><html lang="${esc(lang)}"><body style="margin:0;background:#f6f5f2;font-family:-apple-system,Segoe UI,Inter,Arial,sans-serif;color:#1e1f24">
+<div style="max-width:520px;margin:0 auto;padding:28px 20px">
+<p style="font-size:13px;color:#6b6e78;margin:0 0 18px">${esc(settings.siteTitle)}</p>
+<h1 style="font-size:22px;margin:0 0 8px">${esc(heading)}</h1>
+<p style="font-size:15px;line-height:1.55;margin:0 0 18px;color:#3d3f47">${esc(intro)}</p>
+${rows.length ? `<table style="width:100%;border-collapse:collapse;background:#fff;border:1px solid #e5e3de;border-radius:10px">${rows
+    .map(([k, v]) => `<tr><td style="padding:10px 14px;border-bottom:1px solid #eeece8"><div style="font-size:13px;color:#6b6e78">${esc(k)}</div><div style="font-size:14px;margin-top:2px">${esc(v).replace(/\n/g, '<br>')}</div></td></tr>`)
+    .join('')}</table>` : ''}
+${notes.map((n) => `<p style="font-size:14px;line-height:1.55;margin:18px 0 0">${esc(n)}</p>`).join('')}
+<p style="margin:22px 0 0"><a href="${esc(button.href)}" style="display:inline-block;background:#1e1f24;color:#fff;text-decoration:none;font-weight:600;font-size:14px;padding:10px 16px;border-radius:8px">${esc(button.label)}</a></p>
+<p style="font-size:12px;color:#8e919a;margin:26px 0 0">${esc(footer)}</p>
+</div></body></html>`;
+  const text = [heading, '', intro, ...(rows.length ? ['', ...rows.map(([k, v]) => `${k}: ${v}`)] : []), ...notes.flatMap((n) => ['', n]), '', `${button.label}: ${button.href}`, '', footer].join('\n');
+  return { to, subject: heading, html, text, ...(replyTo ? { replyTo } : {}) };
+}
+
+/** The push to staff phones: the form's name and when, never the answers or who sent it. */
+export function alertPush(formName: string, at: number, last: boolean, settings: Settings) {
+  const { w, locale } = alertLanguage(settings);
+  const when = whenText(at, locale, settings.timezone, false);
+  return { title: fill(w.subject, { form: oneLine(formName) }), body: last ? fill(w.pushLast, { when, max: String(ALERTS_PER_DAY) }) : fill(w.received, { when }) };
+}

package/src/lib/forms/alerts.ts

@@ -0,0 +1,137 @@
+// Staff alerts for new responses to a general form (Share → Notifications,
+// SavedForm.alerts; off by default). A response accepted from the website or
+// the app queues one email per address on the form's list in the same
+// database batch as the response, so a retry, a refused or a failed
+// submission emails no one. Staff on the list who linked a phone (lib/push/
+// staff.ts) can also get a push saying only that one arrived. Needs working
+// email and Staff notifications on (Email settings); at most ALERTS_PER_DAY
+// alerts a form per site day, the last one saying so. Event RSVP forms
+// don't use this: their hosts get the RSVP email.
+import type { ContentRepository } from '../repo/types';
+import type { SqlStatement } from '../repo/sql';
+import type { Settings } from '../schema';
+import { ApiError } from '../api';
+import { resolveConfig, validAddress } from '../email/config';
+import { emailReadiness } from '../email/readiness';
+import { jobStatement } from '../email/store';
+import { kickEmail } from '../email/service';
+import { LEGAL } from '../legal/config';
+import { deniedMessage, type Permission } from '../permissions/catalog';
+import { PUSH } from '../push/config';
+import { isStaffRole } from '../roles';
+import { waitUntilFrom } from '../webhooks';
+import { ALERTS_PER_DAY, alertPush, type AlertPayload } from './alert-mail';
+import { AlertAddress, FormAlerts, MAX_ALERT_RECIPIENTS, type FormResponse, type SavedForm } from './schema';
+
+const DAY = 86_400_000;
+
+interface AlertPlan { to: string[]; answers: boolean; phones: boolean; last: boolean; key: string; configVersion: number }
+
+// the site's calendar day, so "until tomorrow" means the site's tomorrow
+function siteDay(at: number, tz: string) {
+  try { return new Intl.DateTimeFormat('en-CA', { timeZone: tz || 'UTC', year: 'numeric', month: '2-digit', day: '2-digit' }).format(at); }
+  catch { return new Date(at).toISOString().slice(0, 10); }
+}
+
+/** Whether this response alerts anyone, counted toward the form's day (null: no alert). */
+async function alertPlan(repo: ContentRepository, form: SavedForm, locals: unknown, now: number): Promise<AlertPlan | null> {
+  const a = form.alerts;
+  const to = [...new Set(a.to.map((x) => x.trim().toLowerCase()))].filter(validAddress);
+  if (!a.enabled || !to.length || form.kind !== 'form' || form.purpose !== 'general') return null;
+  const settings = await repo.getSettings();
+  const resolved = resolveConfig(await repo.email.config().catch(() => null), locals);
+  if (!resolved.config.staffNotifications || !emailReadiness(resolved, settings.siteUrl, locals).configured) return null;
+  // one counter per form and day: the key changes each day, the window only has to outlast it
+  const key = `forms:alerts:${form.id}:${siteDay(now, settings.timezone)}`;
+  const count = await repo.email.rateHit(key, 2 * DAY);
+  if (count > ALERTS_PER_DAY) return null;
+  return { to, answers: a.answers, phones: a.phones && PUSH.enabled, last: count === ALERTS_PER_DAY, key, configVersion: resolved.version };
+}
+
+// one job per address, inserted only alongside the response this batch stores
+function alertJobs(formId: string, id: string, at: number, plan: AlertPlan, via: AlertPayload['via']): SqlStatement[] {
+  const payload: AlertPayload = { formId, submissionId: id, answers: plan.answers, last: plan.last, via };
+  return plan.to.map((to) => jobStatement({ dedupe: `form-alert:${id}:${to}`, kind: 'form-alert', recipient: to, payload: JSON.stringify(payload), configVersion: plan.configVersion, expiresAt: at + 3 * DAY },
+    'EXISTS (SELECT 1 FROM form_submissions WHERE id=? AND form_id=? AND created_at=?)', [id, formId, at]));
+}
+
+// staff accounts on the list, to their linked phones; the site's main language
+async function alertPhones(repo: ContentRepository, form: SavedForm, plan: AlertPlan, locals: unknown) {
+  const users = (await repo.listUsers()).filter((u) => u.email && isStaffRole(u.role) && plan.to.includes(u.email.trim().toLowerCase()));
+  const devices = (await Promise.all(users.map((u) => repo.push.staffDevices(u.id)))).flat();
+  if (!devices.length) return;
+  const { sendNotification } = await import('../push/service');
+  // no link: the app can't open the admin, and nothing about the person goes in
+  await sendNotification(repo, { ...alertPush(form.name, Date.now(), plan.last, await repo.getSettings()), url: '', audience: [], devices: devices.map((d) => d.id),
+    locale: null, source: 'form', sourceKey: `form:${form.id}` }, { locals });
+}
+
+/**
+ * Stores a response to a published general form with its staff alerts (one
+ * request id stores it once). via: where it was sent from. True when this
+ * call stored it (false for a retry).
+ */
+export async function saveResponse(repo: ContentRepository, form: SavedForm, response: FormResponse, requestId: string, opts: { via: AlertPayload['via']; locals?: unknown; now?: number }) {
+  // a problem with alerts never loses a response
+  const plan = await alertPlan(repo, form, opts.locals, opts.now ?? Date.now()).catch((e) => { console.error('acms forms: alert check failed', e); return null; });
+  let saved = false;
+  try {
+    saved = await repo.forms.submit(form.id, response, requestId, plan ? (at) => alertJobs(form.id, requestId, at, plan, opts.via) : undefined);
+  } finally {
+    // a retry, or a response that didn't land, isn't one of the day's alerts
+    if (plan && !saved) await repo.email.rateRefund(plan.key).catch(() => {});
+  }
+  if (!plan || !saved) return saved;
+  const waitUntil = waitUntilFrom(opts.locals);
+  await kickEmail(repo, opts.locals, waitUntil);
+  if (plan.phones) {
+    const push = alertPhones(repo, form, plan, opts.locals).catch((e) => console.error('acms forms: alert push failed', e));
+    if (waitUntil) waitUntil(push); else await push;
+  }
+  return saved;
+}
+
+// ---- Share → Notifications ---------------------------------------------------
+
+/** Addresses offered when alerts were never set up: the contact email in Settings → Legal (then acms({ legal })), else the owners'. */
+export async function suggestedRecipients(repo: ContentRepository, settings: Settings): Promise<string[]> {
+  const contact = (settings.legal.contactEmail || LEGAL.contactEmail).trim().toLowerCase();
+  if (contact) return [contact];
+  return [...new Set((await repo.listUsers()).filter((u) => u.role === 'owner' && u.email).map((u) => u.email.trim().toLowerCase()))].slice(0, MAX_ALERT_RECIPIENTS);
+}
+
+/** Why alerts wouldn't go out right now, with where to fix it (null: they would). */
+export async function alertBlocker(repo: ContentRepository, settings: Settings, locals?: unknown): Promise<{ text: string; href: string; link: string } | null> {
+  const resolved = resolveConfig(await repo.email.config().catch(() => null), locals);
+  const status = emailReadiness(resolved, settings.siteUrl, locals);
+  const email = { href: '/admin/email', link: 'Email settings' };
+  if (!resolved.config.enabled || resolved.provider === 'none') return { text: 'Email is off, so no alerts go out.', ...email };
+  if (!status.configured) return { text: `Email needs attention, so no alerts go out: ${status.error || 'Choose a provider in Email settings.'}`, ...email };
+  if (!resolved.config.staffNotifications) return { text: 'Staff notifications are off in Email settings, so no alerts go out.', ...email };
+  if (status.linkError) return { text: status.linkError, href: '/admin/settings#site', link: 'Site settings' };
+  return null;
+}
+
+/**
+ * Saves the Share page's Notifications form. Managing forms is enough, except
+ * that emailing the answers also needs "View form responses", so the list
+ * can't send someone responses they couldn't read in the admin. Push isn't
+ * on: the phones switch isn't shown, and its saved value stays.
+ */
+export async function saveFormAlerts(repo: ContentRepository, access: { can(permission: Permission): boolean } | null, form: SavedForm, data: FormData): Promise<FormAlerts> {
+  if (!access?.can('forms.manage')) throw new ApiError(403, deniedMessage('forms.manage'));
+  if (form.kind !== 'form' || form.purpose !== 'general') throw new ApiError(404, 'Form not found.');
+  const enabled = data.get('enabled') === '1', answers = data.get('answers') === '1';
+  const to: string[] = [];
+  for (const raw of String(data.get('to') ?? '').split(/[\s,;]+/).filter(Boolean)) {
+    const one = AlertAddress.safeParse(raw);
+    if (!one.success) throw new ApiError(400, `“${raw.slice(0, 80)}” isn’t an email address.`);
+    if (!to.includes(one.data)) to.push(one.data);
+  }
+  if (to.length > MAX_ALERT_RECIPIENTS) throw new ApiError(400, `Add up to ${MAX_ALERT_RECIPIENTS} addresses.`);
+  if (enabled && !to.length) throw new ApiError(400, 'Add at least one email address to send alerts to.');
+  if (enabled && answers && !access.can('forms.responses')) throw new ApiError(403, 'Emailing the answers also needs View form responses. Turn off “Include the answers in the email”, or ask an owner.');
+  const alerts = FormAlerts.parse({ enabled, to, answers, phones: PUSH.enabled ? data.get('phones') === '1' : form.alerts.phones });
+  await repo.forms.saveAlerts(form.id, alerts);
+  return alerts;
+}

package/src/lib/forms/schema.ts

@@ -35,10 +35,24 @@ export const hasOther = (f: Pick<FormField, 'allowOther' | 'type'>) => Boolean(f
 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 MAX_ALERT_RECIPIENTS = 10;
+export const AlertAddress = z.string().trim().toLowerCase().email().max(200);
+// Staff alerts for new responses (Share → Notifications, lib/forms/alerts.ts).
+// Kept apart from the definition, so it's never public, never part of a
+// form's version and never copied into a response. Off for existing forms.
+export const FormAlerts = z.object({
+  enabled: z.boolean().default(false),
+  to: z.array(AlertAddress).max(MAX_ALERT_RECIPIENTS).default([]),
+  /** false: the email only says a response arrived (sensitive forms) */
+  answers: z.boolean().default(true),
+  /** also a push to the linked phones of staff on the list (never the answers) */
+  phones: z.boolean().default(false),
+});
+export type FormAlerts = z.infer<typeof FormAlerts>;
 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(),
+  revision: z.number().int(), createdAt: z.number(), updatedAt: z.number(), alerts: FormAlerts.default({}),
 });
 export type SavedForm = z.infer<typeof SavedForm>;
 export const FormSubmission = z.object({ id: z.string(), formId: z.string(), response: FormResponse, createdAt: z.number() });

package/src/lib/forms/store.ts

@@ -1,8 +1,9 @@
 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] });
+import { FormAlerts, 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, alerts: JSON.parse(String(r.alerts || '{}')) });
+const submission = (r: Record<string, unknown>) => FormSubmission.parse({ id: r.id, formId: r.form_id, response: JSON.parse(String(r.response)), createdAt: r.created_at });
+export const formInsert = (f: SavedForm): SqlStatement => ({ sql: 'INSERT INTO forms (id,name,kind,purpose,status,definition,draft,revision,created_at,updated_at,alerts) 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,JSON.stringify(f.alerts)] });
 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>) {}
@@ -22,23 +23,40 @@ export class FormStore {
       [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.');
   }
+  // Share → Notifications. Not part of the definition, so it doesn't stage a
+  // draft or bump the revision (an open Build tab keeps saving).
+  async saveAlerts(id: string, alerts: FormAlerts) {
+    const rows = await (await this.driver()).all("UPDATE forms SET alerts=?,updated_at=? WHERE id=? AND kind='form' RETURNING id", [JSON.stringify(FormAlerts.parse(alerts)), Date.now(), id]);
+    if (!rows.length) throw new ApiError(404, 'Form not found.');
+  }
   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 }));
+    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(submission);
+  }
+  async submission(formId: string, id: string) {
+    const r = (await (await this.driver()).all('SELECT * FROM form_submissions WHERE id=? AND form_id=?', [id, formId]))[0];
+    return r ? submission(r) : null;
   }
   /** the response this request id already saved to this form, if any (as stored JSON) */
   async receipt(formId: string, requestId: string) {
     const r = (await (await this.driver()).all('SELECT response FROM form_submissions WHERE id=? AND form_id=?', [requestId, formId]))[0];
     return r ? String(r.response) : null;
   }
-  async submit(formId: string, response: FormResponse, requestId: string) {
+  /**
+   * Stores a response once per request id. `also` adds statements to the
+   * same batch (the staff alerts), given the time it's stored under. True
+   * when this call stored it; false for a retry of a saved response.
+   */
+  async submit(formId: string, response: FormResponse, requestId: string, also?: (createdAt: number) => SqlStatement[]) {
     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];
+    const at = Date.now();
+    if (!old) await db.batch([{ sql: '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=?)', args: [requestId,formId,JSON.stringify(response),at,formId,JSON.stringify(response.definition)] }, ...(also?.(at) ?? [])]);
+    const saved = (await db.all('SELECT form_id,response,created_at 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.');
+    return !old && Number(saved.created_at) === at;
   }
   // 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]); }
@@ -63,7 +81,7 @@ export class FormStore {
     // 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 }));
+    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(submission);
   }
   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.

package/src/lib/legal/app-privacy.ts

@@ -32,8 +32,8 @@ export function appPrivacyAnswers(f: LegalFacts, privacyUrl: string): AppPrivacy
   });
   if (f.push.enabled) rows.push({
     data: 'Push token, platform, language, chosen topics and Android notification channels', when: 'When someone turns on notifications',
-    apple: 'Identifiers → Device ID. Purpose: App Functionality. Linked to the user. Not used for tracking.',
-    google: 'Device or other IDs. Collected, not shared (Expo, Apple and Google deliver on your behalf). Purpose: App functionality, Developer communications. Optional.',
+    apple: 'Identifiers → Device ID. Purpose: App Functionality. Linked to the user (to a staff member’s identity only when they link their own phone for test notifications). Not used for tracking.',
+    google: 'Device or other IDs. Collected, not shared (Expo, Apple and Google deliver on your behalf). Purpose: App functionality, Developer communications. Optional. Linked to a staff member’s account only when they link their own phone for test notifications.',
   });
   rows.push({
     data: 'IP address', when: 'Every request (rate limiting only)',

package/src/lib/legal/text-en.ts

@@ -46,13 +46,13 @@ export function privacyEn(f: LegalFacts, country: string): PolicySection[] {
     'Each booking has a private link to see, change or cancel it. Keep it private: anyone with the link can use it.',
   ] });
   s.push({ id: 'forms', title: 'Forms', text: [
-    'When you send a form, we store your answers as you entered them (for example your name, email address or phone number, if the form asks for them) and when you sent it. Staff with access to form responses can read and export them. We don’t store your IP address with a response.',
+    `When you send a form, we store your answers as you entered them (for example your name, email address or phone number, if the form asks for them) and when you sent it. Staff with access to form responses can read and export them. We don’t store your IP address with a response.${f.email ? ' Responses, or a notice that one arrived, may be emailed to the staff who handle that form.' : ''}`,
   ] });
   if (f.guestSignIn) s.push({ id: 'guest', title: 'Signing in to see your bookings', text: [
     'To see your bookings in our app, you can sign in with your email address. We email you a six-digit code that expires after 10 minutes. We keep your email address and that sign-in on your device until you sign out or don’t use it for 90 days.',
   ] });
   if (f.push.enabled) s.push({ id: 'push', title: 'Our app and notifications', text: [
-    'If you turn on notifications in our app, we store a push token for your device (an identifier that lets Apple or Google deliver notifications to it), whether it’s iOS or Android, your language, the topics you choose and, on Android, which notification channels the app created (such as one for urgent notices). We use them only to send the notifications you asked for, in your language. Notifications are delivered through Expo’s push service (expo.dev), Apple Push Notification service and Firebase Cloud Messaging.',
+    'If you turn on notifications in our app, we store a push token for your device (an identifier that lets Apple or Google deliver notifications to it), whether it’s iOS or Android, your language, the topics you choose and, on Android, which notification channels the app created (such as one for urgent notices). We use them only to send the notifications you asked for, in your language. Notifications are delivered through Expo’s push service (expo.dev), Apple Push Notification service and Firebase Cloud Messaging. Our staff can link their own phone to their account to receive test notifications and notices that a form response arrived; that link is removed when they remove it or turn notifications off.',
     `You choose the topics in the app and can change them at any time; we never add a topic without asking you. ${f.announcements ? 'Urgent announcements, such as cancellations, go to every device with notifications turned on, whatever topics it chose.' : 'Important notices, such as cancellations, may go to every device with notifications turned on, whatever topics it chose.'} To stop, turn notifications off in the app or in your phone’s settings. Turning them off in the app removes your device from our list right away. Devices that haven’t opened the app for ${days(f.push.retentionDays)}, and devices whose app was removed, are deleted automatically. We keep a record of each notification sent (its text, link and number of recipients, not who received it) for one year. The app works fully without notifications.`,
   ] });
   if (f.email) s.push({ id: 'email', title: 'Email', text: [

package/src/lib/legal/text-es.ts

@@ -47,13 +47,13 @@ export function privacyEs(f: LegalFacts, country: string): PolicySection[] {
     'Cada reservación tiene un enlace privado para verla, cambiarla o cancelarla. Manténgalo en privado: cualquiera que lo tenga puede usarlo.',
   ] });
   s.push({ id: 'forms', title: 'Formularios', text: [
-    'Cuando envía un formulario, guardamos sus respuestas tal como las escribió (por ejemplo su nombre, correo o teléfono, si el formulario los pide) y la fecha en que lo envió. El personal con acceso a las respuestas puede leerlas y exportarlas. No guardamos su dirección IP con la respuesta.',
+    `Cuando envía un formulario, guardamos sus respuestas tal como las escribió (por ejemplo su nombre, correo o teléfono, si el formulario los pide) y la fecha en que lo envió. El personal con acceso a las respuestas puede leerlas y exportarlas. No guardamos su dirección IP con la respuesta.${f.email ? ' Sus respuestas, o un aviso de que llegaron, pueden enviarse por correo al personal que atiende ese formulario.' : ''}`,
   ] });
   if (f.guestSignIn) s.push({ id: 'guest', title: 'Inicio de sesión para ver sus reservaciones', text: [
     'Para ver sus reservaciones en nuestra app, puede iniciar sesión con su correo electrónico. Le enviamos un código de seis dígitos que vence a los 10 minutos. Guardamos su correo y esa sesión en su dispositivo hasta que la cierre o pasen 90 días sin usarla.',
   ] });
   if (f.push.enabled) s.push({ id: 'push', title: 'Nuestra app y las notificaciones', text: [
-    'Si activa las notificaciones en nuestra app, guardamos un identificador de notificaciones de su dispositivo (que permite a Apple o Google entregárselas), si es iOS o Android, su idioma, los temas que elija y, en Android, qué canales de notificación creó la app (por ejemplo, uno para avisos urgentes). Solo los usamos para enviarle las notificaciones que pidió, en su idioma. Las notificaciones se entregan a través del servicio de Expo (expo.dev), Apple Push Notification service y Firebase Cloud Messaging.',
+    'Si activa las notificaciones en nuestra app, guardamos un identificador de notificaciones de su dispositivo (que permite a Apple o Google entregárselas), si es iOS o Android, su idioma, los temas que elija y, en Android, qué canales de notificación creó la app (por ejemplo, uno para avisos urgentes). Solo los usamos para enviarle las notificaciones que pidió, en su idioma. Las notificaciones se entregan a través del servicio de Expo (expo.dev), Apple Push Notification service y Firebase Cloud Messaging. Las personas de nuestro equipo pueden vincular su propio teléfono a su cuenta del sitio para recibir notificaciones de prueba y avisos de que llegó la respuesta a un formulario; ese vínculo se elimina cuando lo quitan o desactivan las notificaciones.',
     `Usted elige los temas en la app y puede cambiarlos cuando quiera; nunca agregamos un tema sin preguntarle. ${f.announcements ? 'Los anuncios urgentes, como una cancelación, llegan a todos los dispositivos con las notificaciones activadas, sin importar los temas que eligieron.' : 'Los avisos importantes, como una cancelación, pueden llegar a todos los dispositivos con las notificaciones activadas, sin importar los temas que eligieron.'} Para dejar de recibirlas, desactive las notificaciones en la app o en los ajustes de su teléfono. Al desactivarlas en la app, su dispositivo se elimina de nuestra lista de inmediato. Los dispositivos que no han abierto la app en ${days(f.push.retentionDays)}, y aquellos en los que se borró la app, se eliminan automáticamente. Guardamos un registro de cada notificación enviada (su texto, su enlace y el número de destinatarios, no quiénes la recibieron) durante un año. La app funciona por completo sin notificaciones.`,
   ] });
   if (f.email) s.push({ id: 'email', title: 'Correo electrónico', text: [

package/src/lib/mobile/forms.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import type { ContentRepository } from '../repo/types';
 import type { FormDefinition, SavedForm } from '../forms/schema';
 import { collectResponse, formVersion } from '../forms/service';
+import { saveResponse } from '../forms/alerts';
 import { ApiError, readJson } from '../api';
 import { sha256Hex } from '../api-keys';
 import { queryParams } from './http';
@@ -82,6 +83,6 @@ export async function submitFormResponse(c: PublicContext) {
   // only valid new responses count toward the daily ceiling
   const cap = settings.mobileAccess.responsesPerFormDay;
   if (cap && !await c.repo.email.rateLimit(`forms:day:${form.id}`, cap, 86_400_000)) throw new ApiError(429, 'This form has had a lot of responses today. Please try again tomorrow.', 86_400);
-  await c.repo.forms.submit(form.id, response, key.toLowerCase());
+  await saveResponse(c.repo, form, response, key.toLowerCase(), { via: 'app', locals: c.locals });
   return { received: true as const, confirmation: form.definition.confirmation };
 }

package/src/lib/mobile/guest.ts

@@ -44,7 +44,8 @@ async function requireGuest(c: PublicContext) {
 }
 const emailField = z.string().trim().toLowerCase().max(254).refine(validAddress, 'Enter a valid email address.');
 const hash = (email: string, code: string) => sha256Hex(`guest-code:${email}:${code}`);
-function sixDigits() {
+/** A random 6-digit code (guest sign-in, staff phone links). */
+export function sixDigits() {
   // rejection sampling keeps every code equally likely
   const buf = new Uint32Array(1);
   do crypto.getRandomValues(buf); while (buf[0] >= 4_294_000_000);

package/src/lib/mobile/openapi.ts

@@ -10,7 +10,7 @@ import { searchQuery } from './search';
 import { manageAvailabilityQuery, rescheduleInput } from './manage';
 import { formResponseInput } from './forms';
 import { codeInput, tokenInput, myBookingsQuery } from './guest';
-import { deviceInput, deviceUpdate } from '../push/api';
+import { deviceInput, deviceUpdate, staffLinkInput } from '../push/api';
 import { announcementsQuery } from '../announcements/api';
 import { localeOnlyQuery } from './locale';
 import { pageQuery, queryParams } from './http';
@@ -129,7 +129,7 @@ export async function getOpenApi(_repo: ContentRepository, url: URL) {
   paths['/api/v1/devices'] = {
     post: {
       summary: 'Register or refresh this device for push notifications; requires push',
-      description: `${pushNote} Call on every app start: it refreshes lastSeenAt (devices unseen for the retention period, default 270 days, are removed). topics replaces the device's topics; omit it to keep them. Stores the token, platform, language and topics only.`,
+      description: `${pushNote} Call on every app start: it refreshes lastSeenAt (devices unseen for the retention period, default 270 days, are removed). topics replaces the device's topics; omit it to keep them. Stores the token, platform, language and topics only (plus, for a staff member's own test phone, who linked it). device.staff names that staff member, or is null.`,
       requestBody: { required: true, content: media(jsonSchema(deviceInput)) },
       responses: { ...writeErrors, ...Object.fromEntries([200, 201].map(code => [code, { description: code === 201 ? 'Registered.' : 'Refreshed.', headers: noStore, content: media(envelope(ref('DeviceRegistration'))) }])) },
     },
@@ -142,12 +142,27 @@ export async function getOpenApi(_repo: ContentRepository, url: URL) {
       responses: { ...writeErrors, 200: { description: 'Updated.', headers: noStore, content: media(envelope(ref('Device'))) } },
     },
     delete: {
-      summary: 'Opt this device out of push notifications (idempotent); requires push', description: 'Removes the token. Unknown tokens also succeed.',
+      summary: 'Opt this device out of push notifications (idempotent); requires push', description: 'Removes the token, and a test-phone link with it. Unknown tokens also succeed.',
       parameters: [tokenParam],
       responses: { ...writeErrors, 200: { description: 'Removed.', headers: noStore, content: media(envelope(ref('DeviceRemoved'))) } },
     },
     options: { summary: 'Public CORS preflight', responses: { 204: { description: 'No body.' } } },
   };
+  const staffNote = 'Requires push; 404 when off. A staff member gets a one-time 6-digit code in the admin (Test phones; 10 minutes, single use) and types it in the app, so this registered device gets their "Send test to my phone" pushes (data.test = true). staff carries their display name only.';
+  paths['/api/v1/devices/{token}/staff-link'] = {
+    post: {
+      summary: 'Link this registered device to a staff member for test pushes; requires push',
+      description: `${staffNote} 404 for an unregistered device. A wrong, used or expired code answers 400 with the same message. Tries are capped (429 with Retry-After): 5 per device token and 5 per client address in 10 minutes, and 20 failures across the site void every waiting code.`,
+      parameters: [tokenParam], requestBody: { required: true, content: media(jsonSchema(staffLinkInput)) },
+      responses: { ...writeErrors, 429: { ...writeErrors[429], description: 'Write limit, or too many link tries (see above).' }, 200: { description: 'Linked.', headers: noStore, content: media(envelope(ref('StaffLink'))) } },
+    },
+    delete: {
+      summary: 'Unlink this device from a staff member (idempotent); requires push', description: `${staffNote} Turning notifications off (DELETE /devices/{token}) also unlinks it.`,
+      parameters: [tokenParam],
+      responses: { ...writeErrors, 200: { description: 'Unlinked.', headers: noStore, content: media(envelope(ref('StaffLink'))) } },
+    },
+    options: { summary: 'Public CORS preflight', responses: { 204: { description: 'No body.' } } },
+  };
   Object.assign(paths, editorPaths(jsonSchema));
   return {
     openapi: '3.1.0', info: { title: 'ACMS Mobile API', version: '1.0.0', description: 'Public API: no authentication, except a booking’s own routes (/bookings/manage/*: its private token in the Booking-Token header) and guest sign-in (/guest/*: a guest token from an emailed code). Owner switches in Admin → Mobile app turn app features off (404). Disabled modules are not registered. Unknown or duplicate query parameters are rejected. locale selects translated words with main-language fallback; unknown locales return 400. Editor API (tag Editor): /api/v1/auth/* and /api/v1/admin/*, registered only when acms({ mobile: { editor } }) is configured; staff sign in through the browser (OAuth 2.0 authorization code + PKCE) and send the device access token as a Bearer header. Cookies never authenticate it.' },