@acms-subir/core 0.3.41 → 0.3.42

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/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

@@ -52,7 +52,7 @@ export function privacyEn(f: LegalFacts, country: string): PolicySection[] {
     '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; 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

@@ -53,7 +53,7 @@ export function privacyEs(f: LegalFacts, country: string): PolicySection[] {
     '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; 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/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.' },

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,11 @@ 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 (never counted in the weekly pace) */
+export type PushSource = 'manual' | 'post' | 'event' | 'soon' | 'live' | 'announcement' | 'change' | 'test';
 export interface PushNotification {
   id: string; title: string; body: string; url: string;
   /** ['*'] = everyone */

package/src/lib/repo/migrations.ts

@@ -695,6 +695,16 @@ 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)`,
+  ] },
 ];
 
 // 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/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); }
+};