@acms-subir/core 0.3.41 → 0.3.43

package/src/lib/mobile/schemas.ts

@@ -120,11 +120,15 @@ export const Availability = z.object({ timezone: str, mode: z.enum(['slots', 'da
 export const BookingResult = z.object({ manageToken: str, booking: Booking.pick({
   id: true, kind: true, status: true, name: true, email: true, phone: true, seats: true, answers: true, formResponse: true, source: true,
 }).extend({ start: date, end: date, resourceId: str.nullable(), linkId: str.nullable(), eventId: str.nullable(), createdAt: date }) });
+// a staff member's test phone: their display name only (never an email)
+const LinkedStaff = z.object({ name: str }).nullable();
 export const Device = z.object({
   token: str, platform: z.enum(['ios', 'android']), locale: str.nullable(), topics: strings, channels: strings, registeredAt: date, lastSeenAt: date,
+  staff: LinkedStaff,
 });
 export const DeviceRegistration = z.object({ created: bool, device: Device });
 export const DeviceRemoved = z.object({ token: str, deleted: z.literal(true) });
+export const StaffLink = z.object({ linked: bool, staff: LinkedStaff });
 export const PushTopics = z.object({ locale, topics: z.array(z.object({ id: str, label: str, kind: z.enum(['general', 'collection', 'calendar', 'site']), description: str.optional() })) });
 export const Announcement = z.object({
   id: str, kind: z.enum(['event', 'registration', 'help', 'info', 'urgent']), kindLabel: str,

package/src/lib/push/api.ts

@@ -1,5 +1,5 @@
-// Public device endpoints (/api/v1/devices, /api/v1/push/topics) and the
-// owner-only admin state/actions behind Admin → Mobile app.
+// Public device endpoints (/api/v1/devices, /api/v1/push/topics, a staff
+// member's test-phone link) and the admin state/actions behind Admin → Mobile app.
 import { z } from 'zod';
 import type { ContentRepository } from '../repo/types';
 import { ApiError, readJson } from '../api';
@@ -12,6 +12,7 @@ import { localeOnlyQuery, mobileLocale } from '../mobile/locale';
 import { EXPO_PUSH_BASE, PUSH, requirePush } from './config';
 import { expoOptions } from './expo';
 import { knownTopics, pushTopics, sendNotification, siteOriginOf, type PushRunOptions } from './service';
+import { linkPhone, sendTest } from './staff';
 import { MAX_CHANGE_RULES, PushAuto, type PushDevice } from './types';
 
 export const pushToken = z.string().max(250).regex(/^Expo(?:nent)?PushToken\[[A-Za-z0-9_-]{8,200}\]$/, 'Use an Expo push token such as ExponentPushToken[…].');
@@ -29,11 +30,16 @@ export const deviceInput = z.object({
 }).strict();
 export const deviceUpdate = z.object({ locale: locale.optional(), topics: topicList.optional(), channels: channelList.optional() }).strict();
 
-export const deviceJson = (d: PushDevice) => ({
+/** `staff`: who linked it as a test phone (their name only), or null */
+export const deviceJson = (d: PushDevice, staff: { name: string } | null = null) => ({
   token: d.token, platform: d.platform, locale: d.locale || null, topics: d.topics, channels: d.channels,
-  registeredAt: new Date(d.createdAt).toISOString(), lastSeenAt: new Date(d.lastSeenAt).toISOString(),
+  registeredAt: new Date(d.createdAt).toISOString(), lastSeenAt: new Date(d.lastSeenAt).toISOString(), staff,
 });
 const deviceId = (token: string) => sha256Hex(`expo-push:${token}`);
+async function staffOf(repo: ContentRepository, d: PushDevice) {
+  const user = d.staffUserId ? await repo.getUser(d.staffUserId) : null;
+  return user ? { name: user.name } : null;
+}
 
 async function checkTopics(repo: ContentRepository, topics: string[] | undefined) {
   if (!topics) return undefined;
@@ -56,7 +62,7 @@ export async function registerDevice(repo: ContentRepository, request: Request)
   const body = deviceInput.parse(await readJson(request, 8_000));
   const topics = await checkTopics(repo, body.topics);
   const { device, created } = await repo.push.upsertDevice({ id: await deviceId(body.token), token: body.token, platform: body.platform, locale: body.locale ?? '', topics, channels: body.channels && [...new Set(body.channels)] }, Date.now());
-  return { created, device: deviceJson(device) };
+  return { created, device: deviceJson(device, await staffOf(repo, device)) };
 }
 export async function updateDevice(repo: ContentRepository, request: Request, rawToken: string) {
   requirePush();
@@ -65,15 +71,30 @@ export async function updateDevice(repo: ContentRepository, request: Request, ra
   if (body.locale === undefined && body.topics === undefined && body.channels === undefined) throw new ApiError(400, 'Send topics, locale, channels or a mix.');
   const device = await repo.push.updateDevice(await deviceId(token), { locale: body.locale, topics: await checkTopics(repo, body.topics), channels: body.channels && [...new Set(body.channels)] }, Date.now());
   if (!device) throw new ApiError(404, 'This device is not registered. Register it with POST /api/v1/devices.');
-  return deviceJson(device);
+  return deviceJson(device, await staffOf(repo, device));
 }
 export async function unregisterDevice(repo: ContentRepository, rawToken: string) {
   requirePush();
   const token = tokenParam(rawToken);
-  // idempotent: an unknown token is already opted out
+  // idempotent: an unknown token is already opted out (a test-phone link goes with the row)
   await repo.push.deleteDevices([await deviceId(token)]);
   return { token, deleted: true };
 }
+
+export const staffLinkInput = z.object({ code: z.string().trim().regex(/^\d{6}$/, 'Enter the 6-digit code from the admin.') }).strict();
+/** POST /devices/{token}/staff-link: this phone gets the code's staff member's test pushes. */
+export async function linkDevice(repo: ContentRepository, request: Request, rawToken: string, address: string, locals?: unknown) {
+  requirePush();
+  const token = tokenParam(rawToken);
+  const { code } = staffLinkInput.parse(await readJson(request, 1_000));
+  return linkPhone({ repo, deviceId: await deviceId(token), address, locals }, code);
+}
+/** DELETE /devices/{token}/staff-link (idempotent). */
+export async function unlinkDevice(repo: ContentRepository, rawToken: string) {
+  requirePush();
+  await repo.push.unlinkStaff(await deviceId(tokenParam(rawToken)));
+  return { linked: false as const, staff: null };
+}
 export async function listPushTopics(repo: ContentRepository, url: URL) {
   requirePush();
   const locale = mobileLocale(localeOnlyQuery.parse(queryParams(url)).locale);
@@ -128,6 +149,8 @@ const link = z.string().trim().max(2000).refine((v) => !v || (/^\/(?!\/)/.test(v
 export const AdminPushInput = z.discriminatedUnion('action', [
   z.object({ action: z.literal('count'), audience }).strict(),
   z.object({ action: z.literal('send'), title: z.string().trim().min(1, 'Add a title.').max(80), body: z.string().trim().max(240).default(''), url: link.default(''), audience }).strict(),
+  // "Send test to my phone": the sender's linked phones only
+  z.object({ action: z.literal('test'), title: z.string().trim().min(1, 'Add a title.').max(80), body: z.string().trim().max(240).default(''), url: link.default('') }).strict(),
   z.object({ action: z.literal('saveAuto'), auto: PushAuto }).strict(),
 ]);
 
@@ -139,7 +162,7 @@ async function checkAudience(repo: ContentRepository, list: string[]) {
   return [...new Set(list)];
 }
 
-export async function adminPushAction(repo: ContentRepository, input: z.infer<typeof AdminPushInput>, ctx: { url: URL; locals?: unknown; author: string; run?: PushRunOptions }) {
+export async function adminPushAction(repo: ContentRepository, input: z.infer<typeof AdminPushInput>, ctx: { url: URL; locals?: unknown; author: string; userId?: string; run?: PushRunOptions }) {
   switch (input.action) {
     case 'count':
       return { recipients: await repo.push.countAudience(await checkAudience(repo, input.audience)) };
@@ -151,6 +174,12 @@ export async function adminPushAction(repo: ContentRepository, input: z.infer<ty
       }, { locals: ctx.locals, origin: siteOriginOf(settings, ctx.url.origin), ...ctx.run });
       return { notification };
     }
+    case 'test': {
+      const settings = await repo.getSettings();
+      const notification = await sendTest(repo, { userId: ctx.userId ?? '', author: ctx.author, title: input.title, body: input.body, url: input.url },
+        { locals: ctx.locals, origin: siteOriginOf(settings, ctx.url.origin), ...ctx.run });
+      return { notification };
+    }
     case 'saveAuto': {
       const collections = new Set(Object.keys(CONTENT.collections));
       const calendars = new Set((CALENDAR.enabled ? await repo.listCalendars() : []).filter((c) => c.visibility === 'public').map((c) => c.id));

package/src/lib/push/service.ts

@@ -133,6 +133,10 @@ export interface Composed { title: string; body: string; url: string }
 export interface SendInput extends Composed {
   /** topic ids, or ['*'] for every device */
   audience: string[];
+  /** these devices (ids) instead of the audience: a staff member's test phones */
+  devices?: string[];
+  /** every device gets this site language (null = the main one) instead of its own: a test in the language being previewed */
+  locale?: string | null;
   source: PushSource;
   sourceKey?: string;
   author?: string;
@@ -176,7 +180,7 @@ export function notificationLink(raw: string, origin: string, locale: string | n
 export async function sendNotification(repo: ContentRepository, input: SendInput, opts: PushRunOptions = {}): Promise<PushNotification> {
   const now = opts.now ?? Date.now();
   const origin = opts.origin ?? siteOriginOf(await repo.getSettings(), opts.fallbackOrigin);
-  const devices = await repo.push.audience(input.audience);
+  const devices = input.devices ? await repo.push.devicesByIds(input.devices) : await repo.push.audience(input.audience);
   const n: PushNotification = {
     id: crypto.randomUUID(), title: input.title, body: input.body, url: input.url, topics: input.audience,
     source: input.source, sourceKey: input.sourceKey ?? '', status: 'sending', recipients: devices.length,
@@ -185,7 +189,7 @@ export async function sendNotification(repo: ContentRepository, input: SendInput
   await repo.push.createNotification(n);
   const words = new Map<string, Composed>();
   const messages: ExpoMessage[] = devices.map((d) => {
-    const locale = deviceLocale(d.locale);
+    const locale = input.locale !== undefined ? input.locale : deviceLocale(d.locale);
     let c: Composed = input;
     if (locale) {
       if (!words.has(locale)) words.set(locale, input.localize?.(locale) ?? input);

package/src/lib/push/staff.ts

@@ -0,0 +1,162 @@
+// Staff test phones: a staff member links their own phone once (a one-time
+// code from the admin's Test phones panel, typed into the app), then "Send
+// test to my phone" in the announcement and notification composers pushes the
+// draft to their linked phones only. Codes are 6 digits, last 10 minutes and
+// work once; only their SHA-256 is stored. Guessing is capped per device
+// token, per client address and across the site.
+import { z } from 'zod';
+import type { ContentRepository } from '../repo/types';
+import { ApiError } from '../api';
+import { sha256Hex } from '../api-keys';
+import { OWNER_ENV } from '../auth';
+import { I18N } from '../i18n';
+import { resolveConfig } from '../email/config';
+import { emailReadiness } from '../email/readiness';
+import { kickEmail } from '../email/service';
+import { sixDigits } from '../mobile/guest';
+import { waitUntilFrom } from '../webhooks';
+import { ANNOUNCEMENTS } from '../announcements/config';
+import { requirePush } from './config';
+import { sendNotification, type PushRunOptions } from './service';
+import type { PushDevice } from './types';
+
+const MINUTE = 60_000, HOUR = 60 * MINUTE;
+export const LINK_CODE_MS = 10 * MINUTE;
+const WINDOW = 10 * MINUTE;
+/** link attempts per device token and per client address in 10 minutes */
+export const LINK_TRIES = 5;
+/** wrong codes across the site in 10 minutes before every waiting code stops working */
+export const SITE_LINK_TRIES = 20;
+export const TESTS_PER_HOUR = 10;
+const SITE_KEY = 'push:link:site';
+// one answer for a wrong, used and expired code: nothing tells them apart
+const BAD_CODE = 'That code didn’t work. Get a new one in the admin.';
+const TOO_MANY = 'Too many tries. Try again in a few minutes.';
+const NO_ACCOUNT = 'Test phones need a Team account with an email. You’re signed in with the owner password.';
+
+const codeHash = (code: string) => sha256Hex(`staff-link:${code}`);
+/** Where staff manage their test phones (linked from the "A phone was linked" email). */
+export const testPhonesPath = () => `${ANNOUNCEMENTS.enabled ? '/admin/announcements' : '/admin/mobile'}#test-phones`;
+
+// ---- admin: Test phones ----------------------------------------------------
+
+export async function testPhonesState(repo: ContentRepository, userId: string, now = Date.now()) {
+  requirePush();
+  // the owner password has no user row (and no email) to link a phone to
+  if (userId === OWNER_ENV) return { canLink: false, phones: [], codeExpiresAt: null };
+  const [phones, codeExpiresAt] = await Promise.all([repo.push.staffDevices(userId), repo.push.linkCodeExpiry(userId, now)]);
+  return {
+    canLink: true, codeExpiresAt,
+    phones: phones.map((d) => ({ id: d.id, platform: d.platform, lastSeenAt: d.lastSeenAt, linkedAt: d.staffLinkedAt ?? d.createdAt })),
+  };
+}
+export type TestPhonesState = Awaited<ReturnType<typeof testPhonesState>>;
+
+export const TestPhonesInput = z.discriminatedUnion('action', [
+  z.object({ action: z.literal('code') }).strict(),
+  z.object({ action: z.literal('remove'), id: z.string().min(1).max(100) }).strict(),
+]);
+
+/** A new one-time code for this staff member (their earlier one stops working). */
+export async function createLinkCode(repo: ContentRepository, userId: string, now = Date.now()) {
+  requirePush();
+  if (userId === OWNER_ENV) throw new ApiError(409, NO_ACCOUNT);
+  // a clash with someone else's waiting code just draws again
+  for (let i = 0; i < 5; i++) {
+    const code = sixDigits();
+    if (await repo.push.saveLinkCode(await codeHash(code), userId, now + LINK_CODE_MS, now)) return { code, expiresAt: now + LINK_CODE_MS };
+  }
+  throw new ApiError(503, 'Couldn’t make a code right now. Try again.');
+}
+
+export async function testPhonesAction(repo: ContentRepository, input: z.infer<typeof TestPhonesInput>, userId: string) {
+  if (input.action === 'code') {
+    const code = await createLinkCode(repo, userId);
+    return { ...(await testPhonesState(repo, userId)), code: code.code, codeExpiresAt: code.expiresAt };
+  }
+  if (!(await repo.push.unlinkStaff(input.id, userId))) throw new ApiError(404, 'That phone isn’t linked to you.');
+  return testPhonesState(repo, userId);
+}
+
+// ---- app: link this phone ------------------------------------------------------
+
+export interface LinkContext { repo: ContentRepository; deviceId: string; address: string; locals?: unknown; now?: number }
+
+/**
+ * Links a registered device to the staff member whose code it sends. Every
+ * try counts before the lookup (so parallel guesses can't slip past the caps)
+ * and a success gives its tries back: 5 per device token and per client
+ * address, and 20 across the site, in 10 minutes. Past the site-wide cap
+ * every waiting code stops working and tries are refused until the window ends.
+ */
+export async function linkPhone(c: LinkContext, code: string) {
+  requirePush();
+  const now = c.now ?? Date.now();
+  const device = await c.repo.push.getDevice(c.deviceId);
+  if (!device) throw new ApiError(404, 'This device is not registered. Register it with POST /api/v1/devices.');
+  // the device id is already a hash of its token; without a real client address the per-token and site caps still apply
+  const keys = [`push:link:token:${device.id}`, ...(c.address && c.address !== 'unknown' ? [`push:link:ip:${await sha256Hex(c.address)}`] : [])];
+  for (const key of keys) if (!(await c.repo.email.rateLimit(key, LINK_TRIES, WINDOW))) throw new ApiError(429, TOO_MANY, WINDOW / 1000);
+  if (!(await c.repo.email.rateLimit(SITE_KEY, SITE_LINK_TRIES, WINDOW))) {
+    // someone is guessing across many phones or addresses: staff make a new code
+    await c.repo.push.revokeLinkCodes();
+    throw new ApiError(429, TOO_MANY, WINDOW / 1000);
+  }
+  const userId = await c.repo.push.consumeLinkCode(await codeHash(code), now);
+  const user = userId ? await c.repo.getUser(userId) : null;
+  if (!user) throw new ApiError(400, BAD_CODE);
+  const linked = await c.repo.push.linkStaff(device.id, user.id, now);
+  if (!linked) throw new ApiError(404, 'This device is not registered. Register it with POST /api/v1/devices.');
+  for (const key of [...keys, SITE_KEY]) await c.repo.email.rateRefund(key);
+  await noticeLinked(c.repo, user.email, linked, now, c.locals).catch((e) => console.error('acms push: linked-phone email failed', e));
+  return { linked: true as const, staff: { name: user.name } };
+}
+
+// A security notice, so it ignores the "Staff notifications" switch; it needs
+// working email (and the key that protects queued mail), else it's skipped.
+async function noticeLinked(repo: ContentRepository, email: string, device: PushDevice, now: number, locals?: unknown) {
+  if (!email) return;
+  const resolved = resolveConfig(await repo.email.config().catch(() => null), locals);
+  if (!emailReadiness(resolved, (await repo.getSettings()).siteUrl, locals).configured) return;
+  await repo.email.enqueue({ dedupe: `phone-linked:${device.id}:${now}`, kind: 'phone-linked', recipient: email, configVersion: resolved.version,
+    payload: JSON.stringify({ platform: device.platform, at: now, path: testPhonesPath() }), expiresAt: now + 24 * HOUR });
+  await kickEmail(repo, locals, waitUntilFrom(locals));
+}
+
+// ---- send a test -----------------------------------------------------------------
+
+// the title's prefix, in the language the test is in
+const TEST_WORD: Record<string, string> = { en: '[Test]', es: '[Prueba]', fr: '[Test]', de: '[Test]', pt: '[Teste]' };
+export const testWord = (locale: string) => TEST_WORD[locale.toLowerCase().split('-')[0]] ?? TEST_WORD.en;
+
+export interface TestInput {
+  userId: string; author: string; title: string; body: string;
+  /** what a tap opens ('' = the app's home) */
+  url: string;
+  /** a site language to send it in (the composer's preview); the main one otherwise */
+  locale?: string | null;
+  /** Android channel (urgent announcements) */
+  channel?: string;
+  data?: Record<string, unknown>;
+}
+
+/**
+ * The draft as a push to the sender's own linked phones, titled "[Test] …" in
+ * its language. Logged as source `test` (never counted in the weekly pace);
+ * 10 an hour per person.
+ */
+export async function sendTest(repo: ContentRepository, input: TestInput, opts: PushRunOptions = {}) {
+  requirePush();
+  if (input.userId === OWNER_ENV) throw new ApiError(409, NO_ACCOUNT);
+  const phones = await repo.push.staffDevices(input.userId);
+  if (!phones.length) throw new ApiError(409, 'No phone linked yet. Link one first.');
+  if (!(await repo.email.rateLimit(`push:test:${input.userId}`, TESTS_PER_HOUR, HOUR))) throw new ApiError(429, `That’s ${TESTS_PER_HOUR} tests in an hour. Try again later.`, 3600);
+  const settings = await repo.getSettings();
+  const main = (I18N.enabled && I18N.defaultLocale) || settings.locale || 'en';
+  const locale = input.locale && I18N.enabled && input.locale !== I18N.defaultLocale && I18N.locales.includes(input.locale) ? input.locale : null;
+  return sendNotification(repo, {
+    title: `${testWord(locale ?? main)} ${input.title}`, body: input.body, url: input.url,
+    audience: [], devices: phones.map((d) => d.id), locale, source: 'test', author: input.author, channel: input.channel,
+    data: { ...input.data, test: true },
+  }, opts);
+}

package/src/lib/push/store.ts

@@ -5,7 +5,8 @@ type Row = Record<string, unknown>;
 const list = (raw: unknown): string[] => { try { const v = JSON.parse(String(raw ?? '[]')); return Array.isArray(v) ? v.map(String) : []; } catch { return []; } };
 function device(r: Row): PushDevice {
   return { id: String(r.id), token: String(r.token), platform: r.platform as PushPlatform, locale: String(r.locale ?? ''), topics: list(r.topics),
-    channels: list(r.channels), createdAt: Number(r.created_at), updatedAt: Number(r.updated_at), lastSeenAt: Number(r.last_seen_at) };
+    channels: list(r.channels), createdAt: Number(r.created_at), updatedAt: Number(r.updated_at), lastSeenAt: Number(r.last_seen_at),
+    staffUserId: r.staff_user_id == null ? null : String(r.staff_user_id), staffLinkedAt: r.staff_linked_at == null ? null : Number(r.staff_linked_at) };
 }
 function notification(r: Row): PushNotification {
   return { id: String(r.id), title: String(r.title), body: String(r.body ?? ''), url: String(r.url ?? ''), topics: list(r.topics),
@@ -47,6 +48,14 @@ export class PushStore {
     return rows[0] ? device(rows[0]) : null;
   }
   async getDevice(id: string) { const r = await this.all('SELECT * FROM push_devices WHERE id=?', [id]); return r[0] ? device(r[0]) : null; }
+  async devicesByIds(ids: string[]): Promise<PushDevice[]> {
+    const out: PushDevice[] = [];
+    for (let i = 0; i < ids.length; i += 90) {
+      const chunk = ids.slice(i, i + 90);
+      out.push(...(await this.all(`SELECT * FROM push_devices WHERE id IN (${chunk.map(() => '?').join(',')}) ORDER BY created_at`, chunk)).map(device));
+    }
+    return out;
+  }
   async deleteDevices(ids: string[]) {
     for (let i = 0; i < ids.length; i += 90) {
       const chunk = ids.slice(i, i + 90);
@@ -82,6 +91,43 @@ export class PushStore {
     return Number((await this.all(`SELECT COUNT(*) AS n FROM push_notifications WHERE created_at>=? AND status!='failed' AND source IN (${sources.map(() => '?').join(',')})`, [since, ...sources]))[0]?.n ?? 0);
   }
 
+  // ---- staff test phones ----
+  /** Phones a staff member linked, most recently linked first. */
+  async staffDevices(userId: string): Promise<PushDevice[]> {
+    return (await this.all('SELECT * FROM push_devices WHERE staff_user_id=? ORDER BY staff_linked_at DESC LIMIT 50', [userId])).map(device);
+  }
+  async linkStaff(id: string, userId: string, now: number): Promise<PushDevice | null> {
+    const rows = await this.all('UPDATE push_devices SET staff_user_id=?, staff_linked_at=? WHERE id=? RETURNING *', [userId, now, id]);
+    return rows[0] ? device(rows[0]) : null;
+  }
+  /** `userId`: only while it's linked to them (the admin's Remove). */
+  async unlinkStaff(id: string, userId?: string): Promise<boolean> {
+    const rows = await this.all(`UPDATE push_devices SET staff_user_id=NULL, staff_linked_at=NULL WHERE id=?${userId ? ' AND staff_user_id=?' : ''} RETURNING id`, userId ? [id, userId] : [id]);
+    return rows.length > 0;
+  }
+  /**
+   * A staff member's one link code (an earlier one is voided). False when an
+   * unexpired code of someone else's has the same hash: draw another.
+   */
+  async saveLinkCode(codeHash: string, userId: string, expiresAt: number, now: number): Promise<boolean> {
+    await this.run('DELETE FROM push_link_codes WHERE user_id=? OR expires_at<=?', [userId, now]);
+    const rows = await this.all('INSERT INTO push_link_codes (code_hash,user_id,expires_at,created_at) VALUES (?,?,?,?) ON CONFLICT(code_hash) DO NOTHING RETURNING code_hash',
+      [codeHash, userId, expiresAt, now]);
+    return rows.length > 0;
+  }
+  /** Deletes the code (single use, expired or not) and returns whose it was while it was still valid. */
+  async consumeLinkCode(codeHash: string, now: number): Promise<string | null> {
+    const r = (await this.all('DELETE FROM push_link_codes WHERE code_hash=? RETURNING user_id, expires_at', [codeHash]))[0];
+    return r && Number(r.expires_at) > now ? String(r.user_id) : null;
+  }
+  /** When this staff member's code stops working (null: none waiting). */
+  async linkCodeExpiry(userId: string, now: number): Promise<number | null> {
+    const r = (await this.all('SELECT expires_at FROM push_link_codes WHERE user_id=? AND expires_at>?', [userId, now]))[0];
+    return r ? Number(r.expires_at) : null;
+  }
+  /** Every waiting code stops working (too many wrong ones across the site). */
+  async revokeLinkCodes() { await this.run('DELETE FROM push_link_codes'); }
+
   // ---- delivery log ----
   async createNotification(n: PushNotification) {
     await this.run(`INSERT INTO push_notifications (id,title,body,url,topics,source,source_key,status,recipients,sent,ok,failed,removed,error,author,created_at,finished_at)
@@ -175,12 +221,13 @@ export class PushStore {
   async queueStatus(key: string) { return (await this.all('SELECT status FROM push_queue WHERE key=?', [key]))[0]?.status as string | undefined; }
 
   // ---- retention ----
-  /** Devices not seen since `devicesBefore`, log rows older than a year, expired tickets, and old occurrence, broadcast and change keys. */
+  /** Devices not seen since `devicesBefore`, log rows older than a year, expired tickets and link codes, and old occurrence, broadcast and change keys. */
   async purge(now: number, devicesBefore: number): Promise<number> {
     const gone = await this.all('DELETE FROM push_devices WHERE last_seen_at<? RETURNING id', [devicesBefore]);
     await (await this.driver()).batch([
       { sql: 'DELETE FROM push_notifications WHERE created_at<?', args: [now - 365 * 86400000] },
       { sql: 'DELETE FROM push_tickets WHERE created_at<?', args: [now - 86400000] },
+      { sql: 'DELETE FROM push_link_codes WHERE expires_at<=?', args: [now] },
       { sql: `DELETE FROM push_queue WHERE kind IN ('soon','live','change') AND updated_at<?`, args: [now - 30 * 86400000] },
     ]);
     return gone.length;

package/src/lib/push/types.ts

@@ -47,8 +47,15 @@ export interface PushDevice {
   /** Android notification channels the app created (beyond its default one) */
   channels: string[];
   createdAt: number; updatedAt: number; lastSeenAt: number;
+  /** the staff member who linked this phone for test sends (null = not linked) */
+  staffUserId: string | null; staffLinkedAt: number | null;
 }
-export type PushSource = 'manual' | 'post' | 'event' | 'soon' | 'live' | 'announcement' | 'change';
+/**
+ * test: "Send test to my phone", to the sender's linked phones only; form: a
+ * new form response, to the linked phones of staff on its alert list. Neither
+ * counts in the weekly pace.
+ */
+export type PushSource = 'manual' | 'post' | 'event' | 'soon' | 'live' | 'announcement' | 'change' | 'test' | 'form';
 export interface PushNotification {
   id: string; title: string; body: string; url: string;
   /** ['*'] = everyone */

package/src/lib/repo/migrations.ts

@@ -695,6 +695,21 @@ export const MIGRATIONS: Migration[] = [
   { version: 61, statements: [
     `ALTER TABLE bookings ADD COLUMN hold_until INTEGER`,
   ] },
+  // staff test phones: a device a staff member linked with a one-time code
+  // (only its SHA-256 is stored, keyed by it: the app sends the code alone)
+  // gets their "Send test to my phone" pushes. Not public, so no cache trigger.
+  { version: 62, statements: [
+    `ALTER TABLE push_devices ADD COLUMN staff_user_id TEXT`,
+    `ALTER TABLE push_devices ADD COLUMN staff_linked_at INTEGER`,
+    `CREATE INDEX push_devices_staff ON push_devices (staff_user_id)`,
+    `CREATE TABLE push_link_codes (code_hash TEXT PRIMARY KEY, user_id TEXT NOT NULL, expires_at INTEGER NOT NULL, created_at INTEGER NOT NULL)`,
+    `CREATE INDEX push_link_codes_user ON push_link_codes (user_id)`,
+  ] },
+  // staff alerts for a form's new responses (SavedForm.alerts: who gets them,
+  // with or without the answers); '{}' = off. Not public, so no cache trigger.
+  { version: 63, statements: [
+    `ALTER TABLE forms ADD COLUMN alerts TEXT NOT NULL DEFAULT '{}'`,
+  ] },
 ];
 
 // Current cache coverage; keep earlier migration inputs frozen for upgrade compatibility.

package/src/lib/repo/sql.ts

@@ -1708,7 +1708,10 @@ export class SqlRepository implements ContentRepository {
   }
   async deleteUser(id: string) {
     await this.ready;
-    await this.guardedUserWrite([...this.ownerGuard(id), { sql: 'DELETE FROM users WHERE id = ?', args: [id] }]);
+    await this.guardedUserWrite([...this.ownerGuard(id), { sql: 'DELETE FROM users WHERE id = ?', args: [id] },
+      // their test phones stop getting tests, and a waiting link code stops working
+      { sql: 'UPDATE push_devices SET staff_user_id = NULL, staff_linked_at = NULL WHERE staff_user_id = ?', args: [id] },
+      { sql: 'DELETE FROM push_link_codes WHERE user_id = ?', args: [id] }]);
   }
   async getUserAuth(email: string) {
     await this.ready;

package/src/lib/sync/catalog.ts

@@ -50,7 +50,8 @@ export const schemas = {
   }).strict(),
   booking: BookingLink.omit(common).strict(),
   place: Place.omit(common).strict(),
-  form: SavedForm.omit({ ...common, draft: true, revision: true }).strict(),
+  // who gets a form's alerts belongs to one environment, like notifyEmails
+  form: SavedForm.omit({ ...common, draft: true, revision: true, alerts: true }).strict(),
   media: Media.omit({ id: true, createdAt: true })
     .extend({
       objects: z

package/src/pages/admin/forms/[id]/share.astro

@@ -6,8 +6,10 @@ import { readForm } from '../../../../lib/forms/http';
 import { escapeForm } from '../../../../lib/forms/fields';
 import { siteOrigin } from '../../../../lib/seo';
 import { CONTENT } from '../../../../lib/content';
+import { alertBlocker, saveFormAlerts, suggestedRecipients } from '../../../../lib/forms/alerts';
+import { PUSH } from '../../../../lib/push/config';
 import '../../../../styles/forms-admin.css';
-import { forbiddenUnless } from '../../../../lib/permissions/access';
+import { accessFor, forbiddenUnless } from '../../../../lib/permissions/access';
 
 const repo = await getRepo(Astro.locals);
 if (Astro.request.method === 'POST') { const denied = await forbiddenUnless(Astro.request, Astro.cookies, repo, 'forms.manage'); if (denied) return denied; }
@@ -15,20 +17,40 @@ let form = await repo.forms.get(Astro.params.id || '');
 if (!form || form.kind !== 'form') return new Response(null, { status: 404 });
 Astro.response.headers.set('Cache-Control', 'private, no-store');
 
-let error = '', notice = '';
+let error = '', notice = '', alertError = '', alertNotice = '';
+// what the Notifications form shows: saved settings, or what was just posted when it didn't save
+let posted: FormData | null = null;
 if (Astro.request.method === 'POST') {
+  let op = '';
   try {
     const data = await readForm(Astro.request);
-    const op = String(data.get('op') || '');
-    if (op !== 'publish' && op !== 'archive') throw new Error('Unknown action.');
-    // Same store operation as the Build tab: publish promotes pending edits.
-    await repo.forms.save(form.id, Number(data.get('revision')), form.name, form.draft ?? form.definition, op);
-    form = (await repo.forms.get(form.id))!;
-    notice = op === 'publish' ? 'Published. The form is accepting responses.' : 'Archived. The form no longer accepts responses; existing responses are kept.';
-  } catch (e) { error = e instanceof Error ? e.message : 'Could not update the form.'; }
+    op = String(data.get('op') || '');
+    if (op === 'alerts') {
+      posted = data;
+      await saveFormAlerts(repo, await accessFor(Astro.request, Astro.cookies, repo), form, data);
+      form = (await repo.forms.get(form.id))!;
+      posted = null;
+      alertNotice = form.alerts.enabled ? 'Saved. New responses are emailed to this list.' : 'Saved. New responses aren’t emailed.';
+    } else {
+      if (op !== 'publish' && op !== 'archive') throw new Error('Unknown action.');
+      // Same store operation as the Build tab: publish promotes pending edits.
+      await repo.forms.save(form.id, Number(data.get('revision')), form.name, form.draft ?? form.definition, op);
+      form = (await repo.forms.get(form.id))!;
+      notice = op === 'publish' ? 'Published. The form is accepting responses.' : 'Archived. The form no longer accepts responses; existing responses are kept.';
+    }
+  } catch (e) {
+    const message = e instanceof Error ? e.message : 'Could not update the form.';
+    if (op === 'alerts') alertError = message; else error = message;
+  }
 }
 
 const [settings, stats, used] = await Promise.all([repo.getSettings(), repo.forms.submissionStats(form.id, 0), repo.forms.usedOn(form.id)]);
+// never set up: offer the contact email (Settings → Legal), else the owners'
+const fresh = !form.alerts.enabled && !form.alerts.to.length;
+const alerts = posted
+  ? { enabled: posted.get('enabled') === '1', to: String(posted.get('to') ?? ''), answers: posted.get('answers') === '1', phones: posted.get('phones') === '1' }
+  : { ...form.alerts, to: (fresh ? await suggestedRecipients(repo, settings) : form.alerts.to).join('\n') };
+const blocker = alerts.enabled ? await alertBlocker(repo, settings, Astro.locals) : null;
 const origin = siteOrigin(settings, Astro.url);
 const link = `${origin}/forms/${form.id}`;
 const title = escapeForm(form.definition.title || form.name);
@@ -101,9 +123,24 @@ const copyIcon = 'M9 9h10v10H9zM5 15V5h10';
       </div>
     </section>
 
-    <section class="fs-sec">
-      <div class="fs-label"><b>Notifications</b></div>
-      <div class="fs-body"><p class="hint">Email alerts and webhooks for new responses are coming later. For now, check Responses or export a CSV.</p></div>
+    <section class="fs-sec" id="notifications">
+      <div class="fs-label"><b>Notifications</b><small>Email staff when someone sends this form, from the website or the app.</small></div>
+      <div class="fs-body">
+        {alertError && <p class="notice warn" role="alert">{alertError}</p>}
+        {alertNotice && <p class="notice" role="status">{alertNotice}</p>}
+        <form method="post" action="#notifications" class="fs-alerts">
+          <input type="hidden" name="op" value="alerts" />
+          <label class="check-row"><input type="checkbox" name="enabled" value="1" checked={alerts.enabled} /><span>Email new responses</span></label>
+          <div class="fs-alerts-more">
+            <label class="field"><span>Send to</span><textarea name="to" rows="3" spellcheck="false" placeholder="office@example.org">{alerts.to}</textarea><small class="hint">Up to 10 email addresses, one per line.</small></label>
+            <label class="check-row"><input type="checkbox" name="answers" value="1" checked={alerts.answers} /><span>Include the answers in the email<small class="hint">Turn this off for forms that ask for sensitive information, such as prayer requests, health details or children’s names. The email then only says a response arrived.</small></span></label>
+            {PUSH.enabled && <label class="check-row"><input type="checkbox" name="phones" value="1" checked={alerts.phones} /><span>Also notify their linked phones<small class="hint">People on this list with a Team account who linked a phone under Test phones get a notification with the form’s name and the time, never the answers.</small></span></label>}
+            <p class="hint">Up to 50 alerts a day for this form; the 50th says so, and later responses wait in Responses.</p>
+          </div>
+          {blocker && <p class="notice warn"><span>{blocker.text} <a href={blocker.href}>{blocker.link}</a></span></p>}
+          <div class="fs-row"><button class="btn primary">Save notifications</button></div>
+        </form>
+      </div>
     </section>
   </div>
 </Admin>

package/src/pages/api/announcements.ts

@@ -26,7 +26,7 @@ export const POST: APIRoute = async ({ request, cookies, locals, url }) => {
     const input = AdminAnnouncementAction.parse(await readJson(request, 100_000));
     const id = await validateRequestSession(request, cookies, repo);
     const author = id === OWNER_ENV ? 'Owner' : (await repo.getUser(id ?? ''))?.name ?? '';
-    const result = await adminAnnouncementAction(repo, input, { url, author, locals, waitUntil: waitUntilFrom(locals), fallbackOrigin: url.origin });
-    return json({ ...result, state: input.action === 'count' ? undefined : await adminAnnouncementsState(repo, url) });
+    const result = await adminAnnouncementAction(repo, input, { url, author, userId: id ?? '', locals, waitUntil: waitUntilFrom(locals), fallbackOrigin: url.origin });
+    return json({ ...result, state: input.action === 'count' || input.action === 'test' ? undefined : await adminAnnouncementsState(repo, url) });
   } catch (e) { return apiError(e); }
 };

package/src/pages/api/push/admin.ts

@@ -23,7 +23,7 @@ export const POST: APIRoute = async ({ request, cookies, locals, url }) => {
     const input = AdminPushInput.parse(await readJson(request, 20_000));
     const id = await validateRequestSession(request, cookies, repo);
     const author = id === OWNER_ENV ? 'Owner' : (await repo.getUser(id ?? ''))?.name ?? '';
-    const result = await adminPushAction(repo, input, { url, locals, author });
+    const result = await adminPushAction(repo, input, { url, locals, author, userId: id ?? '' });
     return json({ ...result, state: input.action === 'count' ? undefined : await adminPushState(repo, url, locals) });
   } catch (e) { return apiError(e); }
 };

package/src/pages/api/push/phones.ts

@@ -0,0 +1,25 @@
+import type { APIRoute } from 'astro';
+import { getRepo } from '../../../lib/repo';
+import { ApiError, apiError, json, readJson } from '../../../lib/api';
+import { requirePermission } from '../../../lib/permissions/access';
+import { TestPhonesInput, testPhonesAction, testPhonesState } from '../../../lib/push/staff';
+
+// Test phones (Admin → Announcements and Admin → Mobile app; registered only
+// when push is enabled): each person links and removes their own phones.
+export const GET: APIRoute = async ({ request, cookies, locals }) => {
+  try {
+    const repo = await getRepo(locals);
+    const access = await requirePermission(request, cookies, repo, 'services.manage');
+    return json(await testPhonesState(repo, access.userId));
+  } catch (e) { return apiError(e); }
+};
+export const POST: APIRoute = async ({ request, cookies, locals, url }) => {
+  try {
+    const repo = await getRepo(locals);
+    const access = await requirePermission(request, cookies, repo, 'services.manage');
+    // a link code gets this person's test pushes: only from this site's admin
+    if (request.headers.get('origin') !== url.origin) throw new ApiError(403, 'Change this from this site’s admin.');
+    const input = TestPhonesInput.parse(await readJson(request, 2_000));
+    return json(await testPhonesAction(repo, input, access.userId));
+  } catch (e) { return apiError(e); }
+};

package/src/pages/api/v1/devices/[token]/staff-link.ts

@@ -0,0 +1,20 @@
+import type { APIRoute } from 'astro';
+import { getRepo } from '../../../../../lib/repo';
+import { linkDevice, unlinkDevice } from '../../../../../lib/push/api';
+import { failure, limitRequest, methodNotAllowed, response } from '../../../../../lib/mobile/http';
+export { preflight as OPTIONS } from '../../../../../lib/mobile/http';
+// POST: link this phone to a staff member (a code from the admin's Test phones) for test pushes. DELETE: unlink (idempotent).
+function handler(run: (repo: Awaited<ReturnType<typeof getRepo>>, request: Request, token: string, address: string, locals: unknown) => Promise<unknown>): APIRoute {
+  return async context => {
+    try {
+      const repo = await getRepo(context.locals);
+      let address = 'unknown';
+      try { address = context.clientAddress || address; } catch { /* shared fallback bucket */ }
+      await limitRequest(repo, address, true);
+      return response(await run(repo, context.request, context.params.token ?? '', address, context.locals));
+    } catch (error) { return failure(error); }
+  };
+}
+export const POST = handler((repo, request, token, address, locals) => linkDevice(repo, request, token, address, locals));
+export const DELETE = handler((repo, _request, token) => unlinkDevice(repo, token));
+export const ALL = () => methodNotAllowed('POST, DELETE, OPTIONS');