@acms-subir/core 0.3.40 → 0.3.42

package/src/lib/mobile/rsvp.ts

@@ -4,7 +4,7 @@ import type { CalEvent, Settings } from '../schema';
 import { ApiError } from '../api';
 import { answerFields } from '../forms/schema';
 import { eventIsPublic, expandEvents, rsvpDeadline, type Occurrence } from '../calendar/events';
-import { seatsTaken } from '../booking/service';
+import { seatsTaken, waitlistLine, waitlistOn } from '../booking/service';
 import { localizeDoc } from '../translations';
 import { siteLang } from '../dates';
 import { rsvpStrings } from '../calendar/rsvp-words';
@@ -14,9 +14,11 @@ import { formJson } from './forms';
 import { localeQuery, mobileLocale } from './locale';
 
 // RSVP status of one date of an event, for apps: whether it takes RSVPs now,
-// live seats and the questions with their version. The same rules as the
-// event's web page: open until the event's deadline or the date ends, no
-// waitlist. Never cached; seats change with every RSVP. POST /bookings saves one.
+// live seats, its waitlist and the questions with their version. The same
+// rules as the event's web page: open until the event's deadline or the date
+// ends; a full date with a waitlist takes places in line (POST /bookings with
+// waitlist: true). Never cached; seats change with every RSVP. POST /bookings
+// saves one.
 
 /** a public event (slug or id) and its occurrence starting exactly at `start` */
 export async function rsvpOccurrence(repo: ContentRepository, ref: string, start: string): Promise<Occurrence> {
@@ -52,8 +54,9 @@ export async function getRsvpStatus(repo: ContentRepository, url: URL, slug: str
   const o = await rsvpOccurrence(repo, slug, q.start);
   const settings = await repo.getSettings();
   const { rsvp } = o.event;
-  // pending and confirmed RSVPs hold seats, as in the capacity check
+  // pending, confirmed and held (waitlist) RSVPs take seats, as in the capacity check
   const going = rsvp.enabled ? await seatsTaken(repo, o.event.id, o.start) : 0;
+  const line = waitlistOn(o.event) ? await waitlistLine(repo, o.event.id, o.start) : [];
   const left = rsvp.capacity ? Math.max(0, rsvp.capacity - going) : null;
   const closed = rsvpClosed(o, settings);
   const deadline = rsvp.enabled ? rsvpDeadline(o, settings) : null;
@@ -74,6 +77,8 @@ export async function getRsvpStatus(repo: ContentRepository, url: URL, slug: str
     closesAt: deadline === null ? null : new Date(deadline).toISOString(),
     // seats one RSVP may take right now
     maxSeats: Math.min(rsvp.maxSeats || 1, left ?? Infinity), autoConfirm: rsvp.autoConfirm,
+    // a full date takes places in line: how many people wait, for how many seats, and the most one may ask for
+    waitlist: { enabled: waitlistOn(o.event), waiting: line.length, seats: line.reduce((n, b) => n + b.seats, 0), maxSeats: rsvp.maxSeats || 1 },
     form: form ? { ...await formJson(form), submitLabel } : null,
   };
 }

package/src/lib/mobile/schemas.ts

@@ -77,13 +77,20 @@ export const RsvpStatus = z.object({
   going: z.number().int(), left: z.number().int().nullable(), capacity: z.number().int(), maxSeats: z.number().int(), autoConfirm: bool,
   // the event's RSVP deadline for this date (null: open until it ends)
   closesAt: date.nullable(),
+  // enabled: a full date (reason full) takes places in line; waiting: people in line, seats: theirs; maxSeats: the most one may ask for
+  waitlist: z.object({ enabled: bool, waiting: z.number().int(), seats: z.number().int(), maxSeats: z.number().int() }),
   form: Form.omit({ id: true }).nullable(),
 });
-const GuestChanges = z.object({ cancel: bool, reschedule: bool, cutoffHours: z.number().int(), closed: bool });
+// confirm: a spot offered from the waitlist is still held for them
+const GuestChanges = z.object({ cancel: bool, reschedule: bool, confirm: bool, cutoffHours: z.number().int(), closed: bool });
+// waitlisted: in line for a full date; offered: a freed spot held until holdUntil; expired: not confirmed in time
+const BookingStatus = z.enum(['pending', 'confirmed', 'declined', 'cancelled', 'waitlisted', 'offered', 'expired']);
 export const ManagedBooking = z.object({
   booking: z.object({
-    id: str, reference: str, kind: z.enum(['booking', 'rsvp']), status: z.enum(['pending', 'confirmed', 'declined', 'cancelled']),
+    id: str, reference: str, kind: z.enum(['booking', 'rsvp']), status: BookingStatus,
     start: date, end: date, allDay: bool, timezone: str, seats: z.number().int(), name: str, email: str, phone: str, answers: z.record(str), createdAt: date,
+    // waitlisted: the place in line (1 = next); offered: until when the spot is held
+    position: z.number().int().nullable(), holdUntil: date.nullable(),
   }),
   title: str, location: str,
   resource: z.object({ slug: str, name: str }).nullable(),
@@ -96,7 +103,7 @@ export const ManagedBooking = z.object({
 export const GuestCodeSent = z.object({ sent: z.literal(true), expiresInMinutes: z.number().int() });
 export const GuestToken = z.object({ accessToken: str, tokenType: z.literal('Bearer'), email: str, idleDays: z.number().int() });
 export const GuestBookings = z.object({ email: str, pagination: Pagination, items: z.array(z.object({
-  id: str, reference: str, kind: z.enum(['booking', 'rsvp']), status: z.enum(['pending', 'confirmed', 'declined', 'cancelled']),
+  id: str, reference: str, kind: z.enum(['booking', 'rsvp']), status: BookingStatus,
   start: date, end: date, seats: z.number().int(), title: str, manageToken: str, manageUrl: str, can: GuestChanges,
 })) });
 export const GuestSignedOut = z.object({ signedOut: z.literal(true) });
@@ -113,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

@@ -690,6 +690,21 @@ export const MIGRATIONS: Migration[] = [
   { version: 60, statements: [
     `ALTER TABLE bookings ADD COLUMN locale TEXT NOT NULL DEFAULT ''`,
   ] },
+  // RSVP waitlists: an offered spot is held until hold_until (ms); null for
+  // 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)`,
+  ] },
 ];
 
 // Current cache coverage; keep earlier migration inputs frozen for upgrade compatibility.