@acms-subir/core 0.3.31 → 0.3.33

package/src/lib/announcements/service.ts

@@ -0,0 +1,132 @@
+// Announcements: words per language, what's up right now, publishing (with
+// its push and webhook) and the public JSON the website and apps read.
+import type { ContentRepository } from '../repo/types';
+import { I18N } from '../i18n';
+import { localizedUrl } from '../mobile/locale';
+import { emitWebhook } from '../webhooks';
+import { PUSH } from '../push/config';
+import { sendNotification, siteOriginOf, STALE_AFTER, type Composed, type PushRunOptions, type SendInput } from '../push/service';
+import type { PushNotification } from '../push/types';
+import { ANNOUNCEMENTS } from './config';
+import { announcementStrings } from './words';
+import type { Announcement, AnnouncementWords } from './types';
+
+/** The Android channel urgent announcements use, on phones whose app created it (see the native guide). */
+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 } {
+  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]];
+  if (!t) return { ...main, translated: false };
+  return {
+    title: t.title || main.title, message: t.message || main.message, details: t.details || main.details,
+    buttonLabel: t.buttonLabel || main.buttonLabel, translated: Boolean(t.title),
+  };
+}
+
+/** Up right now (published and not past its end). */
+export const isLive = (a: Announcement, now: number) => a.status === 'published' && (a.showUntil === null || a.showUntil > now);
+
+/** The built-in page for one announcement ('' when the site turned the pages off). */
+export const announcementPath = (id: string) => (ANNOUNCEMENTS.pages ? `${ANNOUNCEMENTS.base}/${encodeURIComponent(id)}` : '');
+
+/** Paragraphs of the details text (a blank line starts a new one). */
+export const paragraphs = (text: string) => text.split(/\n\s*\n/).map((p) => p.trim()).filter(Boolean);
+
+export function announcementJson(a: Announcement, locale: string | null, origin: string) {
+  const w = localizeAnnouncement(a, locale);
+  const words = announcementStrings(locale || I18N.defaultLocale);
+  const abs = (path: string) => (path ? localizedUrl(new URL(path, origin).href, origin, locale) : null);
+  return {
+    id: a.id, kind: a.kind, kindLabel: words.kinds[a.kind],
+    title: w.title, message: w.message, details: w.details,
+    button: a.link ? { label: w.buttonLabel || words.more, url: abs(a.link)! } : null,
+    url: abs(announcementPath(a.id)),
+    pinned: a.pinned, urgent: a.kind === 'urgent',
+    publishedAt: new Date(a.publishedAt ?? a.updatedAt).toISOString(),
+    showUntil: a.showUntil === null ? null : new Date(a.showUntil).toISOString(),
+    translated: w.translated,
+  };
+}
+export type AnnouncementJson = ReturnType<typeof announcementJson>;
+
+// ---- push ----------------------------------------------------------------------
+
+/**
+ * The push for an announcement: its title and short message in each phone's
+ * language. A tap opens the announcement's page (the app routes data.announcementId
+ * to its own screen); without the built-in pages, its button link. The button's
+ * link also travels as data.buttonUrl/buttonPath.
+ */
+export function announcementNotice(a: Announcement): SendInput {
+  const words = (locale: string | null): Composed => {
+    const w = localizeAnnouncement(a, locale);
+    return { title: w.title, body: w.message, url: announcementPath(a.id) || a.link };
+  };
+  return {
+    ...words(null), audience: a.kind === 'urgent' ? ['*'] : a.audience, source: 'announcement', sourceKey: `announcement:${a.id}`,
+    author: a.author, channel: a.kind === 'urgent' ? URGENT_CHANNEL : undefined, button: a.link || undefined,
+    data: { kind: 'announcement', id: a.id, announcementId: a.id, announcementKind: a.kind },
+    localize: (l) => words(l),
+  };
+}
+
+async function pushOnce(repo: ContentRepository, a: Announcement, run: PushRunOptions & { now: number }) {
+  const key = `announcement:${a.id}`;
+  if (!(await repo.push.claimKey(key, 'announcement', a.id, null, run.now))) return null;
+  // a scheduled push the scheduler reaches hours late (it was down) isn't sent late
+  if (a.publishAt !== null && run.now - a.publishAt > STALE_AFTER) {
+    await repo.push.markQueue(key, 'skipped', null, run.now);
+    return null;
+  }
+  try {
+    const n = await sendNotification(repo, announcementNotice(a), run);
+    await repo.push.markQueue(key, 'sent', n.id, run.now);
+    return n;
+  } catch (e) {
+    await repo.push.markQueue(key, 'failed', null, run.now).catch(() => {});
+    throw e;
+  }
+}
+
+export interface PublishOptions extends PushRunOptions { waitUntil?: (p: Promise<unknown>) => void }
+
+/**
+ * Puts a draft or scheduled announcement up now: status published, the
+ * `announcement.published` webhook and, when chosen, its push (once ever, through
+ * the push ledger). Null when another request published it first.
+ */
+export async function publishAnnouncement(repo: ContentRepository, a: Announcement, opts: PublishOptions = {}) {
+  const now = opts.now ?? Date.now();
+  const up = await repo.announcements.update(a.id, { status: a.showUntil !== null && a.showUntil <= now ? 'ended' : 'published', publishedAt: now, updatedAt: now }, ['draft', 'scheduled']);
+  if (!up) return null;
+  const settings = await repo.getSettings();
+  const origin = opts.origin ?? siteOriginOf(settings, opts.fallbackOrigin);
+  let notification: PushNotification | null = null;
+  let pushError = '';
+  if (up.push && PUSH.enabled && up.status === 'published') {
+    try {
+      notification = await pushOnce(repo, up, { ...opts, now, origin });
+      if (notification) await repo.announcements.update(up.id, { notificationId: notification.id });
+    } catch (e) {
+      console.error('acms announcements: push failed', e);
+      pushError = e instanceof Error ? e.message : String(e);
+    }
+  }
+  await emitWebhook(repo, 'announcement.published', { announcement: { ...announcementJson(up, I18N.defaultLocale || null, origin), status: up.status } }, { waitUntil: opts.waitUntil }).catch(() => {});
+  return { announcement: { ...up, notificationId: notification?.id ?? up.notificationId }, notification, pushError };
+}
+
+/** Scheduler entry: scheduled announcements go up (and push), ended ones come down. */
+export async function runAnnouncementJobs(repo: ContentRepository, opts: PublishOptions = {}): Promise<number> {
+  if (!ANNOUNCEMENTS.enabled) return 0;
+  const now = opts.now ?? Date.now();
+  let count = 0;
+  for (const a of await repo.announcements.due(now)) {
+    if (await publishAnnouncement(repo, a, { ...opts, now })) count++;
+  }
+  count += await repo.announcements.endExpired(now);
+  return count;
+}

package/src/lib/announcements/store.ts

@@ -0,0 +1,88 @@
+import type { SqlDriver } from '../repo/sql';
+import type { Announcement, AnnouncementKind, AnnouncementStatus, AnnouncementWords } from './types';
+
+type Row = Record<string, unknown>;
+const json = <T>(raw: unknown, fallback: T): T => { try { const v = JSON.parse(String(raw ?? '')); return v && typeof v === 'object' ? v as T : fallback; } catch { return fallback; } };
+const num = (v: unknown) => (v == null ? null : Number(v));
+function announcement(r: Row): Announcement {
+  return {
+    id: String(r.id), kind: r.kind as AnnouncementKind, title: String(r.title ?? ''), message: String(r.message ?? ''), details: String(r.details ?? ''),
+    buttonLabel: String(r.button_label ?? ''), link: String(r.link ?? ''), translations: json<Record<string, AnnouncementWords>>(r.translations, {}),
+    listed: Number(r.listed) === 1, push: Number(r.push) === 1, pinned: Number(r.pinned) === 1,
+    audience: json<string[]>(r.audience, ['*']).map(String), status: r.status as AnnouncementStatus,
+    publishAt: num(r.publish_at), showUntil: num(r.show_until), publishedAt: num(r.published_at),
+    notificationId: r.notification_id == null ? null : String(r.notification_id), author: String(r.author ?? ''),
+    createdAt: Number(r.created_at), updatedAt: Number(r.updated_at),
+  };
+}
+const COLUMNS: [keyof Announcement, string][] = [
+  ['kind', 'kind'], ['title', 'title'], ['message', 'message'], ['details', 'details'], ['buttonLabel', 'button_label'], ['link', 'link'],
+  ['translations', 'translations'], ['listed', 'listed'], ['push', 'push'], ['pinned', 'pinned'], ['audience', 'audience'], ['status', 'status'],
+  ['publishAt', 'publish_at'], ['showUntil', 'show_until'], ['publishedAt', 'published_at'], ['notificationId', 'notification_id'],
+  ['author', 'author'], ['updatedAt', 'updated_at'],
+];
+const value = (v: unknown) => (typeof v === 'boolean' ? (v ? 1 : 0) : v !== null && typeof v === 'object' ? JSON.stringify(v) : v ?? null);
+
+/** The INSERT for one announcement (create and backup restore). */
+export function announcementInsert(a: Announcement): { sql: string; args: unknown[] } {
+  const cols = ['id', 'created_at', ...COLUMNS.map(([, c]) => c)];
+  return { sql: `INSERT INTO announcements (${cols.join(',')}) VALUES (${cols.map(() => '?').join(',')})`, args: [a.id, a.createdAt, ...COLUMNS.map(([k]) => value(a[k]))] };
+}
+
+// what visitors see right now: published, in the list or pinned, not past its end
+const LIVE = `status='published' AND (show_until IS NULL OR show_until>?)`;
+
+export interface PublicQuery { kind?: AnnouncementKind; pinned?: boolean; limit: number; offset: number }
+
+// Storage for announcements. Shared by the D1 and libSQL adapters (plain SQLite).
+export class AnnouncementStore {
+  constructor(private driver: () => Promise<SqlDriver>) {}
+  private async all(sql: string, args: unknown[] = []) { return (await this.driver()).all(sql, args); }
+
+  /** Newest first; `limit` -1 = all (backups). */
+  async list(limit = 500): Promise<Announcement[]> {
+    return (await this.all(`SELECT * FROM announcements ORDER BY COALESCE(published_at, publish_at, updated_at) DESC LIMIT ?`, [limit])).map(announcement);
+  }
+  async get(id: string): Promise<Announcement | null> {
+    const r = await this.all('SELECT * FROM announcements WHERE id=?', [id]);
+    return r[0] ? announcement(r[0]) : null;
+  }
+  async create(a: Announcement): Promise<Announcement> {
+    const insert = announcementInsert(a);
+    return announcement((await this.all(`${insert.sql} RETURNING *`, insert.args))[0]);
+  }
+  /** Writes the given fields; `onlyIf` guards a status change against a concurrent one (null when it no longer matches). */
+  async update(id: string, patch: Partial<Announcement>, onlyIf?: AnnouncementStatus[]): Promise<Announcement | null> {
+    const set = COLUMNS.filter(([k]) => k in patch);
+    if (!set.length) return this.get(id);
+    const guard = onlyIf?.length ? ` AND status IN (${onlyIf.map(() => '?').join(',')})` : '';
+    const rows = await this.all(`UPDATE announcements SET ${set.map(([, c]) => `${c}=?`).join(',')} WHERE id=?${guard} RETURNING *`,
+      [...set.map(([k]) => value(patch[k])), id, ...(onlyIf ?? [])]);
+    return rows[0] ? announcement(rows[0]) : null;
+  }
+  async delete(id: string): Promise<boolean> {
+    return (await this.all('DELETE FROM announcements WHERE id=? RETURNING id', [id])).length > 0;
+  }
+
+  /** Scheduled ones whose time has come. */
+  async due(now: number, limit = 10): Promise<Announcement[]> {
+    return (await this.all(`SELECT * FROM announcements WHERE status='scheduled' AND COALESCE(publish_at,0)<=? ORDER BY publish_at LIMIT ?`, [now, limit])).map(announcement);
+  }
+  /** Published ones past their end: they come down. */
+  async endExpired(now: number): Promise<number> {
+    return (await this.all(`UPDATE announcements SET status='ended', updated_at=? WHERE status='published' AND show_until IS NOT NULL AND show_until<=? RETURNING id`, [now, now])).length;
+  }
+  /** Up right now, newest first. `pinned` = only banners; otherwise only the ones in the list. */
+  async live(now: number, q: PublicQuery): Promise<Announcement[]> {
+    const where = [LIVE, q.pinned ? 'pinned=1' : 'listed=1'];
+    const args: unknown[] = [now];
+    if (q.kind) { where.push('kind=?'); args.push(q.kind); }
+    // banners: urgent first
+    const order = q.pinned ? `kind='urgent' DESC, published_at DESC, id` : 'published_at DESC, id';
+    return (await this.all(`SELECT * FROM announcements WHERE ${where.join(' AND ')} ORDER BY ${order} LIMIT ? OFFSET ?`, [...args, q.limit, q.offset])).map(announcement);
+  }
+  /** Banners up right now: urgent first, then newest. */
+  async banners(now: number, limit = 5): Promise<Announcement[]> {
+    return (await this.all(`SELECT * FROM announcements WHERE ${LIVE} AND pinned=1 ORDER BY kind='urgent' DESC, published_at DESC LIMIT ?`, [now, limit])).map(announcement);
+  }
+}

package/src/lib/announcements/types.ts

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+
+// Announcements (Admin → Announcements): stored messages for members that
+// feed the website list and banner, the apps' list and banner, and an
+// optional push. The kind sets the icon and colour; urgent is the only one
+// that reaches every device with notifications on.
+export const ANNOUNCEMENT_KINDS = ['event', 'registration', 'help', 'info', 'urgent'] as const;
+export const AnnouncementKind = z.enum(ANNOUNCEMENT_KINDS);
+export type AnnouncementKind = z.infer<typeof AnnouncementKind>;
+export type AnnouncementStatus = 'draft' | 'scheduled' | 'published' | 'ended' | 'archived';
+
+export const LIMITS = { title: 80, message: 240, details: 5000, buttonLabel: 30 } as const;
+
+/** The words of one language. Empty fields in a translation fall back to the main language. */
+export const AnnouncementWords = z.object({
+  title: z.string().trim().max(LIMITS.title).default(''),
+  /** the push text and the line under the title */
+  message: z.string().trim().max(LIMITS.message).default(''),
+  /** shown in the app and on the website; blank lines start paragraphs */
+  details: z.string().trim().max(LIMITS.details).default(''),
+  buttonLabel: z.string().trim().max(LIMITS.buttonLabel).default(''),
+});
+export type AnnouncementWords = z.infer<typeof AnnouncementWords>;
+
+export const announcementLink = z.string().trim().max(2000)
+  .refine((v) => !v || /^\/(?!\/)/.test(v) || /^https?:\/\//i.test(v), 'Use a site path such as /events or a full https:// address.');
+const locale = z.string().regex(/^[a-z]{2,3}(-[a-z0-9]{2,8})?$/i);
+
+export interface Announcement extends AnnouncementWords {
+  id: string;
+  kind: AnnouncementKind;
+  /** site path or https URL the button opens; '' = no button */
+  link: string;
+  translations: Record<string, AnnouncementWords>;
+  /** in the announcements list (website and apps) */
+  listed: boolean;
+  /** pushed to phones when it goes up */
+  push: boolean;
+  /** shown as a banner while it's up */
+  pinned: boolean;
+  /** push audience: topic ids, or ['*'] for every device (always for urgent) */
+  audience: string[];
+  status: AnnouncementStatus;
+  /** when it goes up; null = as soon as it's scheduled */
+  publishAt: number | null;
+  /** when it comes down; null = until archived */
+  showUntil: number | null;
+  publishedAt: number | null;
+  /** the push sent when it went up */
+  notificationId: string | null;
+  author: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export const AnnouncementInput = AnnouncementWords.extend({
+  kind: AnnouncementKind.default('info'),
+  link: announcementLink.default(''),
+  translations: z.record(locale, AnnouncementWords).default({}),
+  listed: z.boolean().default(true),
+  push: z.boolean().default(false),
+  pinned: z.boolean().default(false),
+  audience: z.array(z.string().min(1).max(200)).max(50).default(['*']),
+  publishAt: z.number().int().nonnegative().nullable().default(null),
+  showUntil: z.number().int().nonnegative().nullable().default(null),
+}).strict();
+export type AnnouncementInput = z.infer<typeof AnnouncementInput>;
+
+/** An announcement as stored (backups). */
+export const AnnouncementRecord = AnnouncementInput.extend({
+  id: z.string().min(1).max(100),
+  status: z.enum(['draft', 'scheduled', 'published', 'ended', 'archived']),
+  publishedAt: z.number().int().nullable(),
+  notificationId: z.string().nullable(),
+  author: z.string().max(200).default(''),
+  createdAt: z.number().int(),
+  updatedAt: z.number().int(),
+});

package/src/lib/announcements/words.ts

@@ -0,0 +1,55 @@
+import type { AnnouncementKind } from './types';
+
+// Words the website pages, the API (kindLabel) and the default button use.
+// Other languages fall back to English.
+export interface AnnouncementStrings {
+  kinds: Record<AnnouncementKind, string>;
+  title: string;
+  intro: string;
+  all: string;
+  more: string;
+  empty: string;
+  emptyKind: string;
+  today: string;
+  thisWeek: string;
+  earlier: string;
+  until: (date: string) => string;
+  back: string;
+  dismiss: string;
+}
+
+const STRINGS: Record<string, AnnouncementStrings> = {
+  en: {
+    kinds: { event: 'Event', registration: 'Registration', help: 'Help needed', info: 'Good to know', urgent: 'Urgent' },
+    title: 'Announcements', intro: 'What’s happening and what we need this week.', all: 'All', more: 'Learn more',
+    empty: 'No announcements right now.', emptyKind: 'Nothing here right now.',
+    today: 'Today', thisWeek: 'This week', earlier: 'Earlier', until: (d) => `Until ${d}`, back: 'All announcements', dismiss: 'Dismiss announcement',
+  },
+  es: {
+    kinds: { event: 'Evento', registration: 'Inscripción', help: 'Se necesita ayuda', info: 'Para saber', urgent: 'Urgente' },
+    title: 'Anuncios', intro: 'Lo que está pasando y lo que necesitamos esta semana.', all: 'Todos', more: 'Más información',
+    empty: 'No hay anuncios por ahora.', emptyKind: 'Nada por aquí por ahora.',
+    today: 'Hoy', thisWeek: 'Esta semana', earlier: 'Antes', until: (d) => `Hasta el ${d}`, back: 'Todos los anuncios', dismiss: 'Cerrar anuncio',
+  },
+  fr: {
+    kinds: { event: 'Événement', registration: 'Inscription', help: 'Besoin d’aide', info: 'Bon à savoir', urgent: 'Urgent' },
+    title: 'Annonces', intro: 'Ce qui se passe et ce dont nous avons besoin cette semaine.', all: 'Toutes', more: 'En savoir plus',
+    empty: 'Aucune annonce pour le moment.', emptyKind: 'Rien ici pour le moment.',
+    today: 'Aujourd’hui', thisWeek: 'Cette semaine', earlier: 'Plus tôt', until: (d) => `Jusqu’au ${d}`, back: 'Toutes les annonces', dismiss: 'Fermer l’annonce',
+  },
+  de: {
+    kinds: { event: 'Veranstaltung', registration: 'Anmeldung', help: 'Hilfe gesucht', info: 'Gut zu wissen', urgent: 'Dringend' },
+    title: 'Ankündigungen', intro: 'Was los ist und was wir diese Woche brauchen.', all: 'Alle', more: 'Mehr erfahren',
+    empty: 'Gerade keine Ankündigungen.', emptyKind: 'Hier ist gerade nichts.',
+    today: 'Heute', thisWeek: 'Diese Woche', earlier: 'Früher', until: (d) => `Bis ${d}`, back: 'Alle Ankündigungen', dismiss: 'Ankündigung schließen',
+  },
+  pt: {
+    kinds: { event: 'Evento', registration: 'Inscrição', help: 'Precisamos de ajuda', info: 'Bom saber', urgent: 'Urgente' },
+    title: 'Avisos', intro: 'O que está acontecendo e do que precisamos esta semana.', all: 'Todos', more: 'Saiba mais',
+    empty: 'Nenhum aviso no momento.', emptyKind: 'Nada aqui no momento.',
+    today: 'Hoje', thisWeek: 'Esta semana', earlier: 'Antes', until: (d) => `Até ${d}`, back: 'Todos os avisos', dismiss: 'Fechar aviso',
+  },
+};
+
+export const announcementStrings = (locale: string | null | undefined): AnnouncementStrings =>
+  STRINGS[(locale || 'en').toLowerCase().split('-')[0]] ?? STRINGS.en;

package/src/lib/backup/content.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { SavedForm, FormSubmission } from '../forms/schema';
+import { AnnouncementRecord } from '../announcements/types';
 import { Page, Post, Media, Link, Tag, User, NavItem, Redirect, Settings, Calendar, CalEvent, Resource, BookingLink, Booking, Place } from '../schema';
 import type { ContentRepository } from '../repo/types';
 
@@ -18,6 +19,8 @@ export const BackupContent = z.object({
   bookingLinks: z.array(z.preprocess(legacyApproval, BookingLink)).default([]), bookings: z.array(Booking).default([]), bookingRequests: z.array(BookingRequest).optional(),
   places: z.array(Place).default([]),
   forms: z.array(SavedForm).optional(), formSubmissions: z.array(FormSubmission).optional(),
+  // optional (no version bump): older cores restore such a backup and skip them
+  announcements: z.array(AnnouncementRecord).optional(),
 }).superRefine((data, ctx) => {
   if (data.version >= 6 && (!data.forms || !data.formSubmissions)) ctx.addIssue({ code: 'custom', message: 'Version 6 requires forms and their submissions.' });
   if (data.version >= 5 && !data.bookingRequests) ctx.addIssue({ code: 'custom', message: 'Version 5 requires booking retry records.' });
@@ -36,11 +39,12 @@ export async function exportContent(repo: ContentRepository, now = Date.now()) {
     repo.listUsers(), repo.listRedirects(), repo.listCalendars(), repo.listEvents(), repo.listResources(), repo.listBookingLinks(), repo.exportBookingState(),
     repo.listPlaces(), repo.forms.list(), repo.forms.submissions(undefined, -1),
   ]);
+  const announcements = await repo.announcements.list(-1);
   return {
     format: 'acms-backup' as const, version: 6, exportedAt: new Date(now).toISOString(),
     settings: { ...settings, live: { ...settings.live, mode: 'off' as const, manual: { watchUrl: '', title: 'We’re live', until: 0 } }, ai: { ...settings.ai, enabled: false, encryptedKey: '' }, agent: { ...settings.agent, enabled: false, keyHash: '', keyPrefix: '', allowPublish: false }, monitoring: { ...settings.monitoring, pushUrl: '' } },
     pages, posts, media, links, tags, navItems, users, redirects,
     calendars: calendars.map(c => ({ ...c, feedToken: '' })), events,
-    resources: resources.map(r => ({ ...r, feedToken: '' })), bookingLinks, ...bookingState, places, forms, formSubmissions,
+    resources: resources.map(r => ({ ...r, feedToken: '' })), bookingLinks, ...bookingState, places, forms, formSubmissions, announcements,
   };
 }

package/src/lib/mobile/config.mjs

@@ -1,5 +1,17 @@
 import { z } from 'zod';
 
+// words in each site language ({ en: 'Help needed', es: 'Se necesita ayuda' }), or one string for all
+const words = (max) => z.union([z.string().trim().min(1).max(max), z.record(z.string().regex(/^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$/, 'Use language codes such as en or es-MX.'), z.string().trim().min(1).max(max))
+  .refine((o) => Object.keys(o).length > 0, 'Give at least one language.')]);
+const RESERVED_TOPICS = new Set(['news', 'events', 'live']);
+// a topic the site adds (registrations, help…): offered in the app, sent to from Admin → Mobile app
+const SiteTopic = z.object({
+  id: z.string().regex(/^[a-z0-9][a-z0-9_-]{0,39}$/, 'Use lowercase letters, numbers, - and _ (up to 40), e.g. help or registrations.')
+    .refine((id) => !RESERVED_TOPICS.has(id), 'news, events and live are built-in topics.'),
+  label: words(60),
+  description: words(200).optional(),
+}).strict();
+
 export const MobileConfig = z.object({
   ios: z.object({
     teamId: z.string().regex(/^[A-Z0-9]{10}$/, 'Use a 10-character Apple team ID.'),
@@ -15,6 +27,7 @@ export const MobileConfig = z.object({
   push: z.union([z.boolean(), z.object({
     enabled: z.boolean().default(true),
     retentionDays: z.number().int().min(30).max(730).default(270),
+    topics: z.array(SiteTopic).max(20).refine((ts) => new Set(ts.map((t) => t.id)).size === ts.length, 'Each topic id once.').default([]),
   }).strict()]).optional(),
   // Editor apps (staff sign in through the browser, OAuth 2.0 + PKCE). Off
   // unless redirect URIs are listed: only these exact URIs receive codes.
@@ -52,8 +65,11 @@ export function resolveMobile(value) {
   const result = MobileConfig.safeParse(value === undefined ? {} : value);
   if (!result.success) throw new Error(`acms: ${result.error.issues.map(i => `mobile.${i.path.join('.')}: ${i.message}`).join('; ')}`);
   const { push, editor, ...rest } = result.data;
-  const options = typeof push === 'object' ? push : { enabled: push === true, retentionDays: 270 };
-  return { ...rest, push: { enabled: options.enabled, retentionDays: options.retentionDays },
+  const options = typeof push === 'object' ? push : { enabled: push === true, retentionDays: 270, topics: [] };
+  // one string = every language ('*')
+  const all = (w) => (w === undefined ? {} : typeof w === 'string' ? { '*': w } : w);
+  const topics = options.topics.map((t) => ({ id: t.id, label: all(t.label), description: all(t.description) }));
+  return { ...rest, push: { enabled: options.enabled, retentionDays: options.retentionDays, topics },
     editor: editor ? { enabled: true, name: editor.name ?? '', redirectUris: [...new Set(editor.redirectUris)], accessTokenMinutes: editor.accessTokenMinutes, refreshTokenDays: editor.refreshTokenDays }
       : { enabled: false, name: '', redirectUris: [], accessTokenMinutes: 60, refreshTokenDays: 90 } };
 }

package/src/lib/mobile/locale.ts

@@ -3,6 +3,8 @@ import { ApiError } from '../api';
 import { I18N, localePath } from '../i18n';
 
 export const localeQuery = z.string().min(1).max(35).optional();
+/** routes whose only option is the language (/site, /push/topics) */
+export const localeOnlyQuery = z.object({ locale: localeQuery }).strict();
 export function mobileLocale(value?: string) {
   if (value && !I18N.locales.includes(value)) throw new ApiError(400, 'Unknown locale.');
   return value ?? (I18N.defaultLocale || null);

package/src/lib/mobile/openapi.ts

@@ -10,6 +10,8 @@ import { manageAvailabilityQuery, rescheduleInput } from './manage';
 import { formResponseInput } from './forms';
 import { codeInput, tokenInput, myBookingsQuery } from './guest';
 import { deviceInput, deviceUpdate } from '../push/api';
+import { announcementsQuery } from '../announcements/api';
+import { localeOnlyQuery } from './locale';
 import { pageQuery, queryParams } from './http';
 import * as schemas from './schemas';
 import { editorPaths, editorSchemas, editorSecuritySchemes } from '../editor/openapi';
@@ -37,7 +39,7 @@ export async function getOpenApi(_repo: ContentRepository, url: URL) {
   empty.parse(queryParams(url));
   const paths: Record<string, unknown> = {};
   const reads: [string, string, z.AnyZodObject, unknown, boolean?][] = [
-    ['/site', 'Site identity, navigation, languages and features', empty, ref('Site')],
+    ['/site', 'Site identity, navigation, languages, features and legal links (locale: links in that language)', localeOnlyQuery, ref('Site')],
     ['/theme', 'Active Design tokens including overrides', empty, ref('Theme')],
     ['/pages/home', 'Published home page and resolved sections', pagesQuery, ref('Page')],
     ['/pages/{slug}', 'Published page and resolved sections (slug may contain slashes)', pagesQuery, ref('Page')],
@@ -48,7 +50,9 @@ export async function getOpenApi(_repo: ContentRepository, url: URL) {
     ['/calendars', 'Public calendars; requires calendar', empty, ref('Calendars')],
     ['/resources', 'Public resources and booking links; requires bookings', z.object(pageQuery).strict(), ref('Resources')],
     ['/availability', 'Current availability; requires bookings', availabilityQuery, ref('Availability'), false],
-    ['/push/topics', 'Topics an app can offer as notification toggles; requires push', empty, ref('PushTopics')],
+    ['/push/topics', 'Topics an app can offer as notification toggles, named in the requested language; requires push', localeOnlyQuery, ref('PushTopics')],
+    ['/announcements', 'Announcements up right now, newest first, in the requested language; pinned=true lists only the banners, urgent first; requires announcements', announcementsQuery, ref('Announcements')],
+    ['/announcements/{id}', 'One announcement that is up, in the requested language; requires announcements', localeOnlyQuery, ref('AnnouncementDetail')],
     ['/links', 'The links page: profile, socials and visible blocks in order (owner switch: links)', empty, ref('Links')],
     ['/live', 'Live video status: the current broadcast (or null), server time and the owner’s display choices; never cached; 404 while live video is off', empty, ref('LiveStatus'), false],
     ['/forms/{id}', 'A published form’s questions; 410 when it stopped accepting responses (owner switch: forms)', empty, ref('Form')],

package/src/lib/mobile/schemas.ts

@@ -8,7 +8,7 @@ const Palette = z.object({ bg: str, ink: str, muted: str, line: str, accent: str
 export const Site = z.object({
   name: str, description: str, logo: str, logoDark: str, icon: str, menu: z.array(z.object({ label: str, href: str })),
   languages: z.object({ default: locale, locales: z.array(z.object({ code: str, name: str })) }),
-  features: z.object({ blog: z.array(z.object({ key: str, name: str, url: str, redirectFrom: strings })), calendar: bool, bookings: bool, search: bool, bookingChanges: bool, guestSignIn: bool, forms: bool, links: bool, live: bool }),
+  features: z.object({ blog: z.array(z.object({ key: str, name: str, url: str, redirectFrom: strings })), calendar: bool, bookings: bool, search: bool, bookingChanges: bool, guestSignIn: bool, forms: bool, links: bool, live: bool, announcements: bool }),
   legal: z.object({ privacy: str.nullable(), terms: str.nullable() }), apiVersion: z.literal(1),
 });
 export const Theme = z.object({
@@ -101,11 +101,18 @@ 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 }) });
 export const Device = z.object({
-  token: str, platform: z.enum(['ios', 'android']), locale: str.nullable(), topics: strings, registeredAt: date, lastSeenAt: date,
+  token: str, platform: z.enum(['ios', 'android']), locale: str.nullable(), topics: strings, channels: strings, registeredAt: date, lastSeenAt: date,
 });
 export const DeviceRegistration = z.object({ created: bool, device: Device });
 export const DeviceRemoved = z.object({ token: str, deleted: z.literal(true) });
-export const PushTopics = z.object({ topics: z.array(z.object({ id: str, label: str, kind: z.enum(['general', 'collection', 'calendar']) })) });
+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,
+  title: str, message: str, details: str, button: z.object({ label: str, url: str }).nullable(), url: str.nullable(),
+  pinned: bool, urgent: bool, publishedAt: date, showUntil: date.nullable(), translated: bool,
+});
+export const Announcements = z.object({ locale, announcements: z.array(Announcement), pagination: Pagination });
+export const AnnouncementDetail = Announcement.extend({ locale });
 // times are Unix milliseconds (as on the website); compare them with serverNow, not the device clock
 const ms = z.number().int();
 export const LiveSnapshot = z.object({

package/src/lib/mobile/site.ts

@@ -3,20 +3,23 @@ import type { ContentRepository } from '../repo/types';
 import { CONTENT, legacyBases } from '../content';
 import { I18N, localeName } from '../i18n';
 import { CALENDAR, bookingsEnabled } from '../calendar/config';
+import { ANNOUNCEMENTS } from '../announcements/config';
 import { SEARCH } from '../search-config';
 import { siteOrigin } from '../seo';
 import { resolveDesign } from '../theme';
 import { darkPalette, liveColor } from '../themeTokens';
 import { safeUrl } from './content';
 import { queryParams } from './http';
+import { localeOnlyQuery, localizedUrl, mobileLocale } from './locale';
 import { guestSignInReady } from './guest';
 import { LEGAL } from '../legal/config';
 
 export async function getSite(repo: ContentRepository, url: URL, _id = '', locals?: unknown) {
-  z.object({}).strict().parse(queryParams(url));
+  // locale: the legal links point at that language's pages (/es/privacy)
+  const locale = mobileLocale(localeOnlyQuery.parse(queryParams(url)).locale);
   const [settings, nav, pages] = await Promise.all([repo.getSettings(), repo.listNavItems(), repo.listPages()]);
   // the privacy notice and terms: the standard pages, or published pages at those slugs
-  const legalUrl = (slug: 'privacy' | 'terms') => (LEGAL.enabled || pages.some(p => p.status === 'published' && p.slug === slug) ? `${siteOrigin(settings, url)}/${slug}` : null);
+  const legalUrl = (slug: 'privacy' | 'terms') => (LEGAL.enabled || pages.some(p => p.status === 'published' && p.slug === slug) ? localizedUrl(`${siteOrigin(settings, url)}/${slug}`, siteOrigin(settings, url), locale) : null);
   const origin = siteOrigin(settings, url);
   const bases = new Set(Object.values(CONTENT.collections).map(c => c.base));
   const header = nav.filter(n => n.area === 'header').sort((a, b) => a.order - b.order);
@@ -40,8 +43,10 @@ export async function getSite(repo: ContentRepository, url: URL, _id = '', local
       forms: settings.mobileAccess.forms, links: settings.mobileAccess.links,
       // Integrations → Live video; GET /api/v1/live answers 404 while it's off
       live: settings.live.mode !== 'off',
+      // acms({ announcements }): GET /api/v1/announcements
+      announcements: ANNOUNCEMENTS.enabled,
     },
-    // in another site language, add /<code> after the origin, like every other page
+    // in the requested language (?locale=es → /es/privacy)
     legal: { privacy: legalUrl('privacy'), terms: legalUrl('terms') },
     apiVersion: 1,
   };

package/src/lib/push/api.ts

@@ -8,6 +8,7 @@ import { CONTENT, collectionUrl } from '../content';
 import { CALENDAR, eventUrl } from '../calendar/config';
 import { eventIsListed } from '../calendar/events';
 import { queryParams } from '../mobile/http';
+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';
@@ -16,17 +17,20 @@ import { 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[…].');
 const topicList = z.array(z.string().min(1).max(200).regex(/^[a-z0-9][a-z0-9:_-]*$/i, 'Use topic ids from GET /api/v1/push/topics.')).max(50);
 const locale = z.string().max(35).regex(/^[A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{1,8})*$/, 'Use a language tag such as en or es-MX.');
+/** Android notification channels the app created, e.g. ['urgent'] (urgent announcements use it only then) */
+const channelList = z.array(z.string().min(1).max(100).regex(/^[A-Za-z0-9._-]+$/, 'Use channel ids such as urgent.')).max(20);
 export const deviceInput = z.object({
   token: pushToken,
   platform: z.enum(['ios', 'android']),
   locale: locale.optional(),
   /** Replaces the device's topics. Omit to keep them (new devices start with none). */
   topics: topicList.optional(),
+  channels: channelList.optional(),
 }).strict();
-export const deviceUpdate = z.object({ locale: locale.optional(), topics: topicList.optional() }).strict();
+export const deviceUpdate = z.object({ locale: locale.optional(), topics: topicList.optional(), channels: channelList.optional() }).strict();
 
 export const deviceJson = (d: PushDevice) => ({
-  token: d.token, platform: d.platform, locale: d.locale || null, topics: d.topics,
+  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(),
 });
 const deviceId = (token: string) => sha256Hex(`expo-push:${token}`);
@@ -51,15 +55,15 @@ export async function registerDevice(repo: ContentRepository, request: Request)
   requirePush();
   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 }, Date.now());
+  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) };
 }
 export async function updateDevice(repo: ContentRepository, request: Request, rawToken: string) {
   requirePush();
   const token = tokenParam(rawToken);
   const body = deviceUpdate.parse(await readJson(request, 8_000));
-  if (body.locale === undefined && body.topics === undefined) throw new ApiError(400, 'Send topics, locale or both.');
-  const device = await repo.push.updateDevice(await deviceId(token), { locale: body.locale, topics: await checkTopics(repo, body.topics) }, Date.now());
+  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);
 }
@@ -72,14 +76,14 @@ export async function unregisterDevice(repo: ContentRepository, rawToken: string
 }
 export async function listPushTopics(repo: ContentRepository, url: URL) {
   requirePush();
-  z.object({}).strict().parse(queryParams(url));
-  return { topics: await pushTopics(repo) };
+  const locale = mobileLocale(localeOnlyQuery.parse(queryParams(url)).locale);
+  return { locale, topics: await pushTopics(repo, locale) };
 }
 
 // ---- admin -------------------------------------------------------------------
 
 export interface PushLinkTarget { ref: string; label: string; url: string; group: 'Pages' | 'Posts' | 'Events' }
-async function linkTargets(repo: ContentRepository): Promise<PushLinkTarget[]> {
+export async function linkTargets(repo: ContentRepository): Promise<PushLinkTarget[]> {
   const [pages, posts, events, calendars] = await Promise.all([
     repo.listPages(), repo.listPublishedPosts(),
     CALENDAR.enabled ? repo.listPublishedEvents() : Promise.resolve([]),

package/src/lib/push/config.ts

@@ -1,5 +1,5 @@
 // Push notifications config, set per project via the integration:
-//   acms({ mobile: { push: true } })  or  { push: { enabled: true, retentionDays: 270 } }
+//   acms({ mobile: { push: true } })  or  { push: { enabled: true, retentionDays: 270, topics: [...] } }
 // Off by default. When off, the device/topic endpoints and the admin Mobile
 // app page are not registered at all (like other disabled modules), and the
 // scheduler just marks any queued automatic notifications as skipped.
@@ -10,6 +10,8 @@ import { ApiError } from '../api';
 export const PUSH = {
   enabled: userConfig.mobile?.push?.enabled === true,
   retentionDays: userConfig.mobile?.push?.retentionDays ?? 270,
+  /** topics the site adds (config mobile.push.topics); labels per language, '*' = every language */
+  topics: [...(userConfig.mobile?.push?.topics ?? [])] as Array<{ id: string; label: Record<string, string>; description: Record<string, string> }>,
 };
 
 export function requirePush() {