@acms-subir/core 0.3.41 → 0.3.43

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @acms-subir/core
 
+## 0.3.43
+
+### Patch Changes
+
+- 8e9263a: Forms can email staff about new responses. On a form's **Share** tab, **Notifications** (off for every form, including existing ones) has **Email new responses** with a list of up to 10 addresses; the first time, it offers the contact email in Settings → Legal, or the owners' addresses. Each response sent from the website or the app emails everyone on the list, in the site's main language: "New response: Prayer requests", when it arrived, every question with its answer in order, an **Open responses in the admin** button, and where it came from and why they get it. When the form asks for an email address, replying writes to the person. A spam-trap, rate-limited or refused response, or a retry of one already saved, emails no one.
+
+  **Include the answers in the email** is on by default. Turn it 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 and when, with nothing about the person and no reply address. Turning it off also covers alerts still waiting to go out, and a deleted response or an address taken off the list drops its alert. With push notifications on, **Also notify their linked phones** sends staff on the list who linked a phone under Test phones a push, "New response: Prayer requests" / "Received Mar 14, 3:41 PM", that never carries answers and opens nothing; the delivery log shows it as "New form response". A form sends at most 50 alerts a day; the 50th says so, and later responses that day wait in Responses.
+
+  Alerts need email set up and **Staff notifications** on in Email settings, which now also turns these off (including ones already queued); the Share tab says when alerts can't go out. Saving them needs **Manage forms**, and emailing the answers also needs **View form responses**, so the list can't send anyone responses they couldn't read in the admin. Event registration forms are unchanged: their hosts get the RSVP email. Environment sync leaves the alert settings out; backups keep them. Push data `source` can now be `form`. Migration 63 adds `forms.alerts`.
+
+  The privacy notice now says that, on sites with email, responses or a notice that one arrived may be emailed to the staff who handle that form, and that staff phones linked for tests also get notices that a form response arrived, so its "Last updated" date moves.
+
+## 0.3.42
+
+### Patch Changes
+
+- b5964fd: Staff can send a test notification to their own phone before anything goes out. Admin → Announcements and Admin → Mobile app have a **Test phones** panel: **Link my phone** shows a 6-digit code that works once for 10 minutes; in the app, open Notifications, choose **Staff? Link this phone** and enter it. The panel lists your linked phones (when linked, when the app was last opened) with **Remove**; each person sees only their own. Signed in with the owner password, there's no account to link a phone to, so the panel says to use a Team account with an email. When a phone is linked, its owner gets an email, "A phone was linked to your account", in the site's main language with a link back to the panel; it goes out whenever email is set up, even with staff notifications off, because it's a security notice.
+
+  **Send test to my phone**, under the preview in the announcement composer and the Mobile app composer, sends the draft as it stands (title, message, and the button's link or the app's home as the tap) to your linked phones only, titled "[Test] …" in the language chosen in the preview ("[Prueba]" in Spanish, "[Teste]" in Portuguese). An urgent draft uses the urgent channel, so you see how it looks. Tests show in the delivery log as "Test by …", never count toward the weekly pace, and are limited to 10 an hour per person. With no phone linked, the button opens the Test phones panel.
+
+  Codes are stored only as a hash. Guessing is capped: 5 tries per phone and 5 per address in 10 minutes, and after 20 wrong codes across the site every waiting code stops working (make a new one). The app API adds `POST /api/v1/devices/{token}/staff-link` (body `{ code }`, answers `{ linked, staff: { name } }`) and `DELETE` to unlink; device responses carry `staff` (the name only, never an email), test pushes carry `data.test: true` and `source: 'test'`, and turning notifications off unlinks the phone. Migration 62 adds `push_devices.staff_user_id` and `staff_linked_at` and the `push_link_codes` table.
+
+  The privacy notice now says staff can link their own phone to their account to receive test notifications and that the link is removed when they remove it or turn notifications off, so its "Last updated" date moves on sites with push; the app store answers say the device ID is linked to a staff member only then. The push recipe's Notifications screen gets the row (only while notifications are on) and a new `/link-phone` screen; update it with `npx acms mobile recipe add push --force`, which overwrites the recipe's files, including any changes you made to them, and needs this release's `@acms-subir/native`. Describe the screen in App Review Notes: "Notifications has a staff-only screen to receive test notifications; it needs a code from the website admin."
+
 ## 0.3.41
 
 ### Patch Changes

package/cli/migrations.generated.mjs

@@ -1121,6 +1121,21 @@ var MIGRATIONS = [
   // everything else, so older rows need no backfill
   { 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 '{}'`
   ] }
 ];
 var CURRENT_CONTENT_VERSION_COLUMNS = {

package/docs/mobile.md

@@ -289,6 +289,14 @@ plus automatic ones: new post, new event, "starting soon", event changes,
    `<AcmsProvider>` in `app/_layout.tsx`. Link to `/notifications`.
 3. Taps carry `data.url` / `data.path` and go through the provider's
    `onNavigate`, so route `/events/<slug>` and post paths to your screens there.
+4. Staff test phones: the recipe's Notifications screen ends with a visible
+   "Staff? Link this phone" row (only while notifications are on) that opens
+   `/link-phone`, where staff type the code from Admin → Announcements or
+   Mobile app → Test phones (`useLinkStaffPhone()`); then "Send test to my
+   phone" in the admin reaches their phone. Never hide it behind a long press
+   or gesture (App Review 2.3.1(a), 2.5.19). In App Store Connect's **App
+   Review Notes**, say: "Notifications has a staff-only screen to receive test
+   notifications; it needs a code from the website admin."
 
 Rules: ask for permission from a button after saying why (the recipe does),
 never on first launch. Topic ids and names come from the site
@@ -322,7 +330,8 @@ a pre-ticked choice doesn't count. So:
   completes it in **Settings → Legal**, which also lists the App Privacy and
   Data safety answers. Link to it inside the app: `useSite().data.legal.privacy`
   (and `.terms`). The site stores only the Expo token, platform, language and
-  topics, with no name or email.
+  topics, with no name or email, except a staff member's own test phone, which
+  records who linked it (the notice and the store answers say so).
 
 ## Editor apps (staff sign-in)
 

package/integration.mjs

@@ -765,8 +765,10 @@ export default function acms(options = {}) {
     routes.push(
       ['/api/v1/devices', 'api/v1/devices/index.ts'],
       ['/api/v1/devices/[token]', 'api/v1/devices/[token].ts'],
+      ['/api/v1/devices/[token]/staff-link', 'api/v1/devices/[token]/staff-link.ts'],
       ['/api/v1/push/topics', 'api/v1/push/topics.ts'],
       ['/api/push/admin', 'api/push/admin.ts'],
+      ['/api/push/phones', 'api/push/phones.ts'],
     );
   }
   // Admin → Mobile app: app access switches always; notifications when push is on

package/mobile-template/recipes/push/files/app/link-phone.tsx

@@ -0,0 +1,43 @@
+import { useState } from 'react';
+import { ScrollView, Text, TextInput, View } from 'react-native';
+import { Stack } from 'expo-router';
+import { Button, fill, linkCodeInput, staffLinkProblemText, useLayout, useLinkStaffPhone, useStrings, useTheme } from '@acms-subir/native';
+
+// Staff only: link this phone with the 6-digit code from the website admin
+// (Announcements or Mobile app → Test phones), so "Send test to my phone"
+// reaches it. Opened from the last row of /notifications while notifications
+// are on; turning them off unlinks it. Words: useStrings() in the app's language.
+export default function LinkPhoneScreen() {
+  const t = useTheme();
+  const { gutter } = useLayout();
+  const words = useStrings();
+  const staff = useLinkStaffPhone();
+  const [code, setCode] = useState('');
+  const input = { borderWidth: 1, borderColor: t.colors.line, borderRadius: Math.min(t.radius, 10), padding: 12, fontSize: 22, letterSpacing: 4, color: t.colors.ink, backgroundColor: t.colors.panel } as const;
+  const link = async () => { if (await staff.link(code)) setCode(''); };
+  return (
+    <ScrollView style={{ backgroundColor: t.colors.bg }} contentContainerStyle={{ padding: gutter, gap: 16, width: '100%', maxWidth: 640, alignSelf: 'center' }} keyboardShouldPersistTaps="handled">
+      <Stack.Screen options={{ title: words.linkPhoneTitle }} />
+      <Text style={t.styles.text.muted}>{words.linkPhoneIntro}</Text>
+
+      {staff.status === 'off' ? (
+        <Text style={t.styles.text.body}>{words.linkNeedsNotifications}</Text>
+      ) : staff.linked ? (
+        <View style={[t.styles.card, { flexDirection: 'row', alignItems: 'center', gap: 12 }]}>
+          <Text style={[t.styles.text.body, { flex: 1 }]}>{fill(words.linkedTo, staff.linked)}</Text>
+          <Button variant="outline" label={words.unlinkPhone} disabled={staff.status !== 'ready'} onPress={() => { staff.unlink(); }} />
+        </View>
+      ) : (
+        <View style={{ gap: 6 }}>
+          <Text style={t.styles.text.label}>{words.linkCode}</Text>
+          <TextInput value={code} onChangeText={(v) => setCode(linkCodeInput(v))} onSubmitEditing={link} keyboardType="number-pad" textContentType="oneTimeCode"
+            autoComplete="one-time-code" maxLength={6} accessibilityLabel={words.linkCode} placeholder="000000" placeholderTextColor={t.colors.muted} style={input} />
+        </View>
+      )}
+      {!!staff.problem && <Text accessibilityRole="alert" style={[t.styles.text.small, { color: t.colors.ink, fontWeight: '600' }]}>{staffLinkProblemText(staff.problem, words)}</Text>}
+      {staff.status !== 'off' && !staff.linked && (
+        <Button label={staff.status === 'linking' ? words.linkingPhone : words.linkPhone} disabled={code.length !== 6 || staff.status !== 'ready'} onPress={link} />
+      )}
+    </ScrollView>
+  );
+}

package/mobile-template/recipes/push/files/app/notifications.tsx

@@ -1,15 +1,19 @@
-import { Linking, ScrollView, Switch, Text, View } from 'react-native';
-import { Stack } from 'expo-router';
-import { Button, useLayout, usePushRegistration, usePushTopics, useTheme } from '@acms-subir/native';
+import { Linking, Pressable, ScrollView, Switch, Text, View } from 'react-native';
+import { Link, Stack } from 'expo-router';
+import { Button, fill, useLayout, useLinkStaffPhone, usePushRegistration, usePushTopics, useStrings, useTheme } from '@acms-subir/native';
 import { STARTING_TOPICS } from '../lib/push';
 
 // Turn notifications on, choose topics, or turn them off. Topics and their
 // names come from the site, so new calendars or collections appear here
-// without an app update.
+// without an app update. While notifications are on, the last row opens
+// /link-phone, where staff link their own phone for test notifications (a
+// visible row, so App Review can find it: describe it in the Review Notes).
 export default function NotificationsScreen() {
   const t = useTheme();
   const { gutter } = useLayout();
+  const words = useStrings();
   const push = usePushRegistration({ topics: STARTING_TOPICS });
+  const staff = useLinkStaffPhone();
   const offered = usePushTopics();
   const toggle = (id: string, on: boolean) => {
     const next = on ? [...push.topics, id] : push.topics.filter((x) => x !== id);
@@ -57,6 +61,12 @@ export default function NotificationsScreen() {
           </View>
           <Text style={t.styles.text.small}>Announcements from the site reach everyone with notifications on.</Text>
           <Button variant="outline" label="Turn off notifications" onPress={() => { push.unregister().catch(() => {}); }} />
+          <Link href="/link-phone" asChild>
+            <Pressable accessibilityRole="button" style={[t.styles.card, { gap: 2, minHeight: 52, justifyContent: 'center' }]}>
+              <Text style={t.styles.text.body}>{words.staffRow}</Text>
+              <Text style={t.styles.text.small}>{staff.linked ? fill(words.linkedTo, staff.linked) : words.staffRowNote}</Text>
+            </Pressable>
+          </Link>
         </>
       )}
     </ScrollView>

package/mobile-template/recipes/push/recipe.json

@@ -7,7 +7,8 @@
     "expo-device"
   ],
   "routes": [
-    "/notifications"
+    "/notifications",
+    "/link-phone"
   ],
   "next": [
     "Turn push on for the site: acms({ mobile: { push: true } }) in astro.config.mjs, then restart or deploy",
@@ -15,6 +16,7 @@
     "Push tokens need an EAS project id: npx eas-cli init (saves extra.eas.projectId in app.json)",
     "Mount <PushSetup /> inside <AcmsProvider> in app/_layout.tsx (re-registers on start, opens tapped notifications)",
     "Link to the screen: <Link href=\"/notifications\">Notifications</Link> (expo-router)",
-    "Send from the site: Admin → Mobile app"
+    "Send from the site: Admin → Mobile app",
+    "Staff test their notifications on their own phone: Notifications → \"Staff? Link this phone\" (/link-phone, shown while notifications are on) takes the code from Admin → Announcements or Mobile app → Test phones. Describe it in App Store Connect's App Review Notes: \"Notifications has a staff-only screen to receive test notifications; it needs a code from the website admin.\""
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acms-subir/core",
-  "version": "0.3.41",
+  "version": "0.3.43",
   "publishConfig": {
     "access": "public"
   },

package/src/components/Announcements.tsx

@@ -3,6 +3,7 @@ import type { AdminAnnouncementAction, AdminAnnouncementsState } from '../lib/an
 import type { Announcement, AnnouncementInput, AnnouncementKind, AnnouncementWords } from '../lib/announcements/types';
 import type { PushNotification } from '../lib/push/types';
 import { announcementStrings } from '../lib/announcements/words';
+import TestPhones, { SendTest } from './TestPhones';
 import '../styles/announcements.css';
 
 // Admin → Announcements: write a message once, choose where it shows (the
@@ -274,6 +275,7 @@ function List({ state, setState, tab, setTab, flash, setFlash, focusTabs, onEdit
           {state.base && <a href={`${state.site.origin}${state.base}`} target="_blank" rel="noopener">View on the site ↗</a>}
         </p>
       )}
+      {state.push.enabled && <TestPhones />}
       <dialog className="modal" ref={dialog} aria-labelledby="an-del-h" onClose={() => setDoomed(null)}>
         <div className="modal-head"><span id="an-del-h">Delete this announcement?</span>
           <button type="button" className="modal-x" onClick={() => dialog.current?.close()} aria-label="Close">✕</button></div>
@@ -681,7 +683,12 @@ function Composer({ state, setState, startId, onClose }: {
             {tz && state.site.timezone && tz !== state.site.timezone && <p className="hint an-after">Times are in this device’s time zone ({tz}); the site uses {state.site.timezone}.</p>}
           </div>
         </div>
-        <Preview state={state} form={form} lang={previewLang} setLang={setPreviewLang} />
+        <Preview state={state} form={form} lang={previewLang} setLang={setPreviewLang}>
+          {state.push.enabled && (
+            <SendTest problem={!localize(form, previewLang, main.code).title.trim() ? 'Add a title first.' : badLink || (form.linkRef === CUSTOM && !link) ? 'Fix the button’s address first.' : undefined}
+              send={() => api<{ notification: PushNotification }>({ action: 'test', announcement: input, locale: previewLang }).then((r) => r.notification)} />
+          )}
+        </Preview>
       </div>
 
       <dialog className="modal an-review" ref={review} aria-labelledby={`${uid}-review-h`}>
@@ -764,7 +771,8 @@ function Toggle({ label, note, checked, disabled, onChange }: { label: string; n
 
 // A phone lock screen with the push, and the website banner when pinned.
 // Device and site previews: fixed neutral colours, not admin tokens.
-function Preview({ state, form, lang, setLang }: { state: State; form: Form; lang: string; setLang: (l: string) => void }) {
+// children: "Send test to my phone", under the phone
+function Preview({ state, form, lang, setLang, children }: { state: State; form: Form; lang: string; setLang: (l: string) => void; children?: ReactNode }) {
   const [open, setOpen] = useState(false);
   const [time, setTime] = useState(() => new Date());
   useEffect(() => { const t = setInterval(() => setTime(new Date()), 30_000); return () => clearInterval(t); }, []);
@@ -803,6 +811,7 @@ function Preview({ state, form, lang, setLang }: { state: State; form: Form; lan
         </div>
       </div>
       <p className="hint an-cap">{push ? 'Phones shorten long text; keep the key words first.' : 'Not pushed. Tick Push to phones to send it.'}</p>
+      {children}
       {form.pinned && (
         <div className="an-site">
           <small className="an-site-label">Website banner</small>

package/src/components/EmailSettings.tsx

@@ -477,7 +477,7 @@ export default function EmailSettings() {
           </label>
           <label className="ems-toggle">
             <input type="checkbox" checked={notify.staff} onChange={(e) => setNotify((n) => ({ ...n, staff: e.target.checked }))} />
-            <span>Staff notifications<small>Tell site staff about new booking and event requests</small></span>
+            <span>Staff notifications<small>Tell site staff about new bookings, RSVPs, event requests and form responses</small></span>
           </label>
           {pwField(notify.pw, (v) => setNotify((n) => ({ ...n, pw: v })), 'pw-notify')}
           <div className="ems-actions">

package/src/components/MobileApp.tsx

@@ -1,6 +1,7 @@
-import { useEffect, useId, useMemo, useRef, useState } from 'react';
+import { useEffect, useId, useMemo, useRef, useState, type ReactNode } from 'react';
 import type { AdminPushState } from '../lib/push/api';
 import type { ChangeRule, PushAuto, PushNotification } from '../lib/push/types';
+import TestPhones, { SendTest } from './TestPhones';
 import '../styles/mobile-app.css';
 
 // Admin → Mobile app: send a notification to the site's own app, choose the
@@ -37,7 +38,7 @@ function ago(ms: number, now: number) {
     : d.toLocaleDateString([], { month: 'short', day: 'numeric', ...(d.getFullYear() !== new Date(now).getFullYear() ? { year: 'numeric' } : {}) });
 }
 
-const SOURCE: Record<PushNotification['source'], string> = { manual: 'Sent by', post: 'New post', event: 'New event', soon: 'Starting soon', live: 'We’re live', announcement: 'Announcement by', change: 'Event changed' };
+const SOURCE: Record<PushNotification['source'], string> = { manual: 'Sent by', post: 'New post', event: 'New event', soon: 'Starting soon', live: 'We’re live', announcement: 'Announcement by', change: 'Event changed', test: 'Test by', form: 'New form response' };
 
 export default function MobileApp() {
   const [state, setState] = useState<AdminPushState | null>(null);
@@ -74,6 +75,7 @@ function MobileAppView({ state, setState }: { state: AdminPushState; setState: (
         </div>
       )}
       <Composer state={state} setState={setState} topicLabel={topicLabel} />
+      <TestPhones />
       <div className="ma-grid ma-grid-2">
         <Automatic state={state} setState={setState} />
         <Audience state={state} topicLabel={topicLabel} />
@@ -116,8 +118,14 @@ function Composer({ state, setState, topicLabel }: { state: AdminPushState; setS
   }, [mode, topics.join('|'), state.stats.devices]);
 
   const toggle = (id: string) => setTopics((t) => (t.includes(id) ? t.filter((x) => x !== id) : [...t, id]));
-  const problem = !title.trim() ? 'Add a title.' : mode === 'topics' && !topics.length ? 'Choose at least one topic.'
-    : linkRef === CUSTOM && url && !/^(\/(?!\/)|https?:\/\/)/i.test(url) ? 'Links start with / or https://.' : '';
+  const badLink = linkRef === CUSTOM && url && !/^(\/(?!\/)|https?:\/\/)/i.test(url) ? 'Links start with / or https://.' : '';
+  const problem = !title.trim() ? 'Add a title.' : mode === 'topics' && !topics.length ? 'Choose at least one topic.' : badLink;
+  // a test goes to the sender's own phones: the audience doesn't matter
+  const sendTest = async () => {
+    const r = await api<{ notification: PushNotification; state: AdminPushState }>({ action: 'test', title: title.trim(), body: body.trim(), url });
+    setState(r.state);
+    return r.notification;
+  };
 
   const send = async () => {
     setBusy(true); setMsg({});
@@ -194,7 +202,9 @@ function Composer({ state, setState, topicLabel }: { state: AdminPushState; setS
           <button type="button" className="btn primary" disabled={!!problem || busy} title={problem || undefined} onClick={() => dialog.current?.showModal()}>Send…</button>
         </div>
       </div>
-      <LockScreen state={state} title={title} body={body} />
+      <LockScreen state={state} title={title} body={body}>
+        <SendTest send={sendTest} problem={!title.trim() ? 'Add a title.' : badLink || undefined} />
+      </LockScreen>
       <dialog className="modal" ref={dialog} aria-labelledby="ma-confirm-h">
         <div className="modal-head"><span id="ma-confirm-h">Send to {count === null ? 'these devices' : plural(count, 'device')}?</span>
           <button type="button" className="modal-x" onClick={() => dialog.current?.close()} aria-label="Close">✕</button></div>
@@ -217,7 +227,8 @@ function Composer({ state, setState, topicLabel }: { state: AdminPushState; setS
 
 // A phone lock screen with the notification as it will show. Device preview:
 // fixed neutral colors (like the site previews), not admin tokens.
-function LockScreen({ state, title, body }: { state: AdminPushState; title: string; body: string }) {
+// children: "Send test to my phone", under the phone
+function LockScreen({ state, title, body, children }: { state: AdminPushState; title: string; body: string; children?: ReactNode }) {
   const [now, setNow] = useState(() => new Date());
   useEffect(() => { const t = setInterval(() => setNow(new Date()), 30_000); return () => clearInterval(t); }, []);
   return (
@@ -244,6 +255,7 @@ function LockScreen({ state, title, body }: { state: AdminPushState; title: stri
         </div>
       </div>
       <figcaption className="hint">Phones shorten long text; keep the key words first.</figcaption>
+      {children}
     </figure>
   );
 }
@@ -450,8 +462,8 @@ function DeliveryLog({ log, topicLabel }: { log: PushNotification[]; topicLabel:
                     {n.body && <div className="ma-body">{n.body}</div>}
                     {n.url && <div className="t-sub ma-url">{n.url}</div>}
                   </td>
-                  <td data-l="Audience" className="ma-aud">{n.topics.map(topicLabel).join(', ')}</td>
-                  <td data-l="From">{SOURCE[n.source]}{n.source === 'manual' && n.author ? ` ${n.author}` : n.source === 'manual' ? ' an owner' : ''}</td>
+                  <td data-l="Audience" className="ma-aud">{n.source === 'test' ? 'Their test phones' : n.source === 'form' ? 'Staff on the form’s alert list' : n.topics.map(topicLabel).join(', ')}</td>
+                  <td data-l="From">{SOURCE[n.source]}{(n.source === 'manual' || n.source === 'test') && n.author ? ` ${n.author}` : n.source === 'manual' || n.source === 'test' ? ' an owner' : ''}</td>
                   <td data-l="Delivered" className="num ma-result">
                     {n.status === 'sending' ? <span className="ma-st" data-tone="info">Sending…</span>
                       : !n.recipients ? <span className="ma-st">No devices</span>

package/src/components/TestPhones.tsx

@@ -0,0 +1,177 @@
+import { useEffect, useId, useRef, useState } from 'react';
+import type { TestPhonesState } from '../lib/push/staff';
+import type { PushNotification } from '../lib/push/types';
+import '../styles/test-phones.css';
+
+// Test phones (Admin → Announcements and Admin → Mobile app): each staff
+// member links their own phone once with a one-time code typed into the app,
+// then "Send test to my phone" in a composer reaches only their phones. The
+// owner password has no account (or email) to link a phone to.
+
+const ENDPOINT = '/api/push/phones';
+// LINK_CODE_MS (lib/push/staff, which brings the server)
+const CODE_MS = 10 * 60_000;
+type State = TestPhonesState & { code?: string };
+
+async function api<T>(body?: Record<string, unknown>): Promise<T> {
+  const res = await fetch(ENDPOINT, {
+    method: body ? 'POST' : 'GET', credentials: 'same-origin',
+    headers: body ? { 'content-type': 'application/json', accept: 'application/json' } : { accept: 'application/json' },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const data = await res.json().catch(() => null);
+  if (!res.ok) throw new Error(data?.issues?.[0]?.message || data?.error || `${res.status} ${res.statusText || 'Request failed'}`);
+  return data as T;
+}
+const errText = (e: unknown) => (e instanceof Error ? e.message : String(e));
+const PLATFORM = { ios: 'iPhone or iPad', android: 'Android phone' } as const;
+const clock = (ms: number) => new Date(ms).toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' });
+function when(ms: number, now: number) {
+  const s = Math.round((now - ms) / 1000);
+  if (s < 60) return 'just now';
+  if (s < 3600) return `${Math.floor(s / 60)} min ago`;
+  const d = new Date(ms);
+  return new Date(now).toDateString() === d.toDateString() ? `today, ${clock(ms)}`
+    : d.toLocaleDateString([], { month: 'short', day: 'numeric', ...(d.getFullYear() !== new Date(now).getFullYear() ? { year: 'numeric' } : {}) });
+}
+
+/**
+ * The panel: this person's linked phones (Remove) and "Link my phone", which
+ * shows a code and waits for the app to use it. `embedded`: inside a dialog
+ * (no card, no anchor). `onPhones` hears how many are linked.
+ */
+export default function TestPhones({ embedded = false, onPhones }: { embedded?: boolean; onPhones?: (n: number) => void }) {
+  const uid = useId();
+  const [state, setState] = useState<State | null>(null);
+  const [loadError, setLoadError] = useState('');
+  const [code, setCode] = useState<{ code: string; expiresAt: number } | null>(null);
+  const [busy, setBusy] = useState('');
+  const [msg, setMsg] = useState<{ ok?: string; err?: string }>({});
+  const root = useRef<HTMLElement>(null);
+  const show = (s: State) => { setState(s); onPhones?.(s.phones.length); };
+
+  useEffect(() => { api<State>().then(show, (e) => setLoadError(errText(e))); }, []);
+  // the link in the "A phone was linked" email lands here
+  useEffect(() => { if (state && !embedded && location.hash === '#test-phones') root.current?.scrollIntoView({ block: 'start' }); }, [state === null]);
+  // while a code waits, look for the phone that uses it
+  useEffect(() => {
+    if (!code) return;
+    const t = setInterval(async () => {
+      if (Date.now() >= code.expiresAt) { setCode(null); setMsg({ err: 'That code expired. Make a new one when your phone is ready.' }); return; }
+      const next = await api<State>().catch(() => null);
+      if (!next || next.codeExpiresAt !== null) return;
+      setCode(null);
+      show(next);
+      // used (a phone linked since it was made), or voided after too many wrong codes on the site
+      setMsg(next.phones.some((p) => p.linkedAt >= code.expiresAt - CODE_MS) ? { ok: 'Phone linked. Tests you send now reach it.' } : { err: 'That code stopped working. Make a new one.' });
+    }, 4000);
+    return () => clearInterval(t);
+  }, [code]);
+
+  const run = async (body: Record<string, unknown>, label: string) => {
+    setBusy(label); setMsg({});
+    try {
+      const next = await api<State>(body);
+      show(next);
+      if (next.code && next.codeExpiresAt) setCode({ code: next.code, expiresAt: next.codeExpiresAt });
+      else if (body.action === 'remove') setMsg({ ok: 'Removed. It won’t get your tests.' });
+    } catch (e) { setMsg({ err: errText(e) }); } finally { setBusy(''); }
+  };
+
+  const now = Date.now();
+  return (
+    <section ref={root} className={embedded ? 'tp' : 'card card-pad tp'} id={embedded ? undefined : 'test-phones'} aria-labelledby={embedded ? undefined : `${uid}-h`}>
+      {!embedded && (
+        <header className="tp-head">
+          <h2 id={`${uid}-h`}>Test phones</h2>
+          <p>Link your own phone to see a notification on it before it goes out. Only you get your tests. Forms that email you about new responses can notify it too.</p>
+        </header>
+      )}
+      {loadError ? <p className="flash error" role="alert">{loadError}</p> : !state ? <p className="hint">Loading…</p> : !state.canLink ? (
+        <p className="hint tp-note">You’re signed in with the owner password, which has no account to link a phone to. Sign in with a Team account that has an email to link one. Owners create accounts in Team → Users.</p>
+      ) : (
+        <>
+          {state.phones.length > 0 ? (
+            <ul className="tp-list">
+              {state.phones.map((p) => (
+                <li key={p.id}>
+                  <span className="tp-phone">
+                    <b>{PLATFORM[p.platform] ?? p.platform}</b>
+                    <small>Linked {when(p.linkedAt, now)} · App last opened {when(p.lastSeenAt, now)}</small>
+                  </span>
+                  <button type="button" className="btn sm" disabled={busy !== ''} onClick={() => run({ action: 'remove', id: p.id }, p.id)}>
+                    {busy === p.id ? 'Removing…' : 'Remove'}</button>
+                </li>
+              ))}
+            </ul>
+          ) : <p className="tp-empty">No phone linked yet.</p>}
+          {code ? (
+            <div className="tp-code" role="group" aria-label="Link code">
+              {/* read out digit by digit */}
+              <b className="tp-digits" aria-hidden="true">{code.code}</b>
+              <span className="sr-only">Code: {code.code.split('').join(' ')}.</span>
+              <p>In the app, open Notifications and choose Link this phone, then enter this code. It works once, until {clock(code.expiresAt)}.</p>
+              <button type="button" className="btn sm" disabled={busy !== ''} onClick={() => run({ action: 'code' }, 'code')}>New code</button>
+            </div>
+          ) : (
+            <button type="button" className="btn" disabled={busy !== ''} onClick={() => run({ action: 'code' }, 'code')}>
+              {busy === 'code' ? 'Making a code…' : state.phones.length ? 'Link another phone' : 'Link my phone'}</button>
+          )}
+        </>
+      )}
+      <div className="tp-flash" aria-live="polite">
+        {msg.ok && <p className="flash">{msg.ok}</p>}
+        {msg.err && <p className="flash error">{msg.err}</p>}
+      </div>
+    </section>
+  );
+}
+
+/** what a test send says: how many of the sender's phones it went to */
+export function testResult(n: PushNotification): { ok?: string; err?: string } {
+  if (n.status === 'failed') return { err: `Not delivered: ${n.error || 'the push service refused it.'}` };
+  if (n.ok === n.sent) return { ok: n.sent === 1 ? 'Test sent to your phone.' : `Test sent to your ${n.sent} phones.` };
+  return { ok: `Test sent to ${n.ok} of your ${n.sent} phones.${n.error ? ` ${n.error}` : ''}` };
+}
+
+/**
+ * "Send test to my phone" for a composer. `send` posts the draft as it
+ * stands; `problem` disables it. With no phone linked yet it opens the Test
+ * phones panel in a dialog instead.
+ */
+export function SendTest({ send, problem }: { send: () => Promise<PushNotification>; problem?: string }) {
+  const uid = useId();
+  const [phones, setPhones] = useState<number | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [msg, setMsg] = useState<{ ok?: string; err?: string }>({});
+  const dialog = useRef<HTMLDialogElement>(null);
+  const run = async () => {
+    setBusy(true); setMsg({});
+    try { setMsg(testResult(await send())); } catch (e) { setMsg({ err: errText(e) }); } finally { setBusy(false); }
+  };
+  return (
+    <div className="tp-send">
+      {phones === 0 ? (
+        <button type="button" className="btn" onClick={() => { setMsg({}); dialog.current?.showModal(); }}>Link a phone to send tests…</button>
+      ) : (
+        <button type="button" className="btn" disabled={busy || !!problem} title={problem || undefined} onClick={run}>{busy ? 'Sending test…' : 'Send test to my phone'}</button>
+      )}
+      <div className="tp-flash" aria-live="polite">
+        {msg.ok && <p className="flash">{msg.ok}</p>}
+        {msg.err && <p className="flash error">{msg.err}</p>}
+      </div>
+      <dialog className="modal" ref={dialog} aria-labelledby={`${uid}-h`}>
+        <div className="modal-head"><span id={`${uid}-h`}>Test phones</span>
+          <button type="button" className="modal-x" onClick={() => dialog.current?.close()} aria-label="Close">✕</button></div>
+        <div className="modal-body">
+          <p className="hint tp-intro">Link your own phone to see a notification on it before it goes out. Only you get your tests. Forms that email you about new responses can notify it too.</p>
+          {/* loads on mount (the dialog's content is always there) and says how many are linked */}
+          <TestPhones embedded onPhones={setPhones} />
+          <div className="modal-foot">
+            <button type="button" className="btn" onClick={() => dialog.current?.close()}>Done</button>
+          </div>
+        </div>
+      </dialog>
+    </div>
+  );
+}

package/src/lib/announcements/api.ts

@@ -10,8 +10,9 @@ import { localeOnlyQuery, localeQuery, mobileLocale } from '../mobile/locale';
 import { PUSH } from '../push/config';
 import { deviceLocale, knownTopics, pushTopics, siteOriginOf, sitePath } from '../push/service';
 import { linkTargets } from '../push/api';
+import { sendTest } from '../push/staff';
 import { ANNOUNCEMENTS } from './config';
-import { announcementJson, isLive, publishAnnouncement, type PublishOptions } from './service';
+import { URGENT_CHANNEL, announcementJson, isLive, localizeAnnouncement, publishAnnouncement, type PublishOptions } from './service';
 import { announcementStrings } from './words';
 import { ANNOUNCEMENT_KINDS, AnnouncementInput, AnnouncementKind, LIMITS, type Announcement, type AnnouncementWords } from './types';
 
@@ -115,6 +116,8 @@ export const AdminAnnouncementAction = z.discriminatedUnion('action', [
   z.object({ action: z.literal('archive'), id }).strict(),
   z.object({ action: z.literal('restore'), id }).strict(),
   z.object({ action: z.literal('delete'), id }).strict(),
+  // "Send test to my phone": the draft as it stands, in the preview's language, to the sender's linked phones
+  z.object({ action: z.literal('test'), announcement: AnnouncementInput, locale: z.string().max(35).optional() }).strict(),
 ]);
 export type AdminAnnouncementAction = z.infer<typeof AdminAnnouncementAction>;
 
@@ -156,7 +159,7 @@ export function scheduleProblem(a: Pick<Announcement, 'title' | 'message' | 'lis
   return null;
 }
 
-export interface AdminContext extends PublishOptions { url: URL; author: string }
+export interface AdminContext extends PublishOptions { url: URL; author: string; userId?: string }
 
 export async function adminAnnouncementAction(repo: ContentRepository, input: AdminAnnouncementAction, ctx: AdminContext) {
   requireAnnouncements();
@@ -166,6 +169,7 @@ export async function adminAnnouncementAction(repo: ContentRepository, input: Ad
     return { recipients: await countRecipients(repo, input.kind === 'urgent' ? ['*'] : await checkAudience(repo, input.audience)) };
   }
   if (input.action === 'save') return save(repo, input, ctx, now);
+  if (input.action === 'test') return test(repo, input, ctx);
   const a = await repo.announcements.get(input.id);
   if (!a) throw new ApiError(404, 'Announcement not found.');
   if (input.action === 'archive') {
@@ -184,6 +188,19 @@ export async function adminAnnouncementAction(repo: ContentRepository, input: Ad
   return { deleted: a.id };
 }
 
+// a tap opens the button's link, else the app (a draft has no page yet); urgent uses its channel so it looks the part
+async function test(repo: ContentRepository, input: Extract<AdminAnnouncementAction, { action: 'test' }>, ctx: AdminContext) {
+  if (!PUSH.enabled) throw new ApiError(400, 'Push notifications are off on this site (acms({ mobile: { push } })).');
+  const a = input.announcement;
+  const w = localizeAnnouncement({ ...a, translations: cleanTranslations(a.translations) }, input.locale ?? null);
+  if (!w.title) throw new ApiError(400, 'Add a title.');
+  const notification = await sendTest(repo, {
+    userId: ctx.userId ?? '', author: ctx.author, title: w.title, body: w.message, url: a.link, locale: input.locale ?? null,
+    channel: a.kind === 'urgent' ? URGENT_CHANNEL : undefined, data: { announcementKind: a.kind },
+  }, { ...ctx, origin: ctx.origin ?? siteOriginOf(await repo.getSettings(), ctx.url.origin) });
+  return { notification };
+}
+
 async function save(repo: ContentRepository, input: Extract<AdminAnnouncementAction, { action: 'save' }>, ctx: AdminContext, now: number) {
   const body = input.announcement;
   const existing = input.id ? await repo.announcements.get(input.id) : null;

package/src/lib/announcements/service.ts

@@ -15,7 +15,7 @@ import type { Announcement, AnnouncementWords } from './types';
 export const URGENT_CHANNEL = 'urgent';
 
 /** Each field in `locale`, falling back to the main words; `translated` = the language has its own title. */
-export function localizeAnnouncement(a: Announcement, locale: string | null | undefined): AnnouncementWords & { translated: boolean } {
+export function localizeAnnouncement(a: AnnouncementWords & Pick<Announcement, 'translations'>, locale: string | null | undefined): AnnouncementWords & { translated: boolean } {
   const main = { title: a.title, message: a.message, details: a.details, buttonLabel: a.buttonLabel };
   if (!locale || locale === I18N.defaultLocale) return { ...main, translated: true };
   const t = a.translations[locale] ?? a.translations[locale.toLowerCase().split('-')[0]];