@acms-subir/core 0.3.32 → 0.3.34

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/cache/policy.ts

@@ -8,6 +8,12 @@ import { I18N } from '../i18n';
 
 export const PRIVATE_CACHE_CONTROL = 'private, no-store';
 export const publicCacheControl = () => `public, s-maxage=${CACHE.maxAge}, stale-while-revalidate=${CACHE.staleWhileRevalidate}`;
+// The public app API: browsers (Expo web, web apps) revalidate by ETag every
+// time, since stale-while-revalidate would hand them an old /site without a
+// feature the app just got. CDNs that read CDN-Cache-Control (RFC 9213, e.g.
+// Cloudflare) still serve it stale while they refresh, like pages; others fall
+// back to s-maxage.
+export const apiCacheControl = () => `public, max-age=0, s-maxage=${CACHE.maxAge}`;
 // publicResponse's own header: browsers/apps always revalidate by ETag. The
 // policy upgrades it with s-maxage so a CDN can share it.
 export const API_REVALIDATE = 'public, max-age=0, must-revalidate';
@@ -64,12 +70,13 @@ export function applyCachePolicy(request: Request, response: Response, pathname
   if (!CACHE.enabled) return response;
   if (OWN_HEADERS.test(pathname)) return response;
   const current = response.headers.get('cache-control');
-  const set = (value: string) => {
-    try { response.headers.set('Cache-Control', value); return response; }
+  const set = (value: string, cdn?: string) => {
+    const write = (h: Headers) => { h.set('Cache-Control', value); if (cdn) h.set('CDN-Cache-Control', cdn); };
+    try { write(response.headers); return response; }
     catch {
       // immutable headers (a proxied/fetched response): copy it
       const copy = new Response(response.body, response);
-      copy.headers.set('Cache-Control', value);
+      write(copy.headers);
       return copy;
     }
   };
@@ -85,5 +92,6 @@ export function applyCachePolicy(request: Request, response: Response, pathname
     warnCookie(pathname);
     return set(PRIVATE_CACHE_CONTROL);
   }
+  if (pathname.startsWith('/api/v1/')) return set(apiCacheControl(), publicCacheControl());
   return set(publicCacheControl());
 }

package/src/lib/legal/app-privacy.ts

@@ -29,7 +29,7 @@ export function appPrivacyAnswers(f: LegalFacts, privacyUrl: string): AppPrivacy
     google: 'Personal info → Email address. Collected, not shared. Purpose: App functionality, Account management. Optional.',
   });
   if (f.push.enabled) rows.push({
-    data: 'Push token, platform, language and chosen topics', when: 'When someone turns on notifications',
+    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.',
   });

package/src/lib/legal/facts.ts

@@ -3,6 +3,7 @@ import type { ContentRepository } from '../repo/types';
 import type { Settings } from '../schema';
 import { CALENDAR, bookingsEnabled } from '../calendar/config';
 import { PUSH } from '../push/config';
+import { ANNOUNCEMENTS } from '../announcements/config';
 import { AUTH } from '../auth/config';
 import { EDITOR } from '../editor/config';
 import { SITE_ROLES } from '../roles';
@@ -39,6 +40,8 @@ export interface LegalFacts {
   /** maps provider name, or '' */
   maps: string;
   live: boolean;
+  /** acms({ announcements }): urgent ones reach every device; read and closed state stays in the app */
+  announcements: boolean;
   analytics: { umami: boolean; replay: boolean; meta: boolean; tiktok: boolean };
   ai: boolean;
   offsiteBackups: boolean;
@@ -79,6 +82,7 @@ export async function legalFacts(repo: ContentRepository, settings: Settings, lo
     email: email && !email.error && email.provider !== 'none' && email.config.enabled ? EMAIL_NAMES[email.provider] ?? email.provider : '',
     maps: (() => { const m = mapsStatus(locals); return m.enabled ? m.label.replace(/ \(self-hosted\)$/, '') : ''; })(),
     live: settings.live.mode !== 'off',
+    announcements: ANNOUNCEMENTS.enabled,
     analytics: {
       umami: a.umami.enabled && !!a.umami.websiteId,
       replay: a.umami.enabled && !!a.umami.websiteId && a.umami.replay.enabled,

package/src/lib/legal/text-en.ts

@@ -52,8 +52,8 @@ 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 and the topics you choose. 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.',
-    `You choose the topics in the app and can change them at any time; we never add a topic without asking you. 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 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.',
+    `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: [
     `We send email through ${f.email}, which processes your email address and the message. We keep a delivery record (recipient and status) for 30 days, and keep addresses that bounce or report our email as spam on a list so we stop writing to them.`,
@@ -79,7 +79,9 @@ export function privacyEn(f: LegalFacts, country: string): PolicySection[] {
   ] });
   s.push({ id: 'cookies', title: 'Cookies and storage on your device', text: [
     `${f.auth === 'clerk' ? 'Clerk’s sign-in cookies' : 'A sign-in cookie (up to seven days)'} for people who sign in; a preview cookie only for staff previews and design share links (up to 30 days); and, in your browser, your light or dark mode choice, the announcements you close and, for one visit, the live video notices you close.${pixels ? ` ${pixelNames} ${f.analytics.meta && f.analytics.tiktok ? 'set their' : 'sets its'} own advertising cookies.` : ' We don’t use cookies for advertising.'}`,
-    ...(app ? ['Our app may keep the content it last loaded on your phone so it works offline, and remembers your notification choice there.'] : []),
+    ...(app ? [f.announcements
+      ? 'Our app may keep the content it last loaded on your phone so it works offline, and remembers there your notification choice and which announcements you’ve read or closed. That stays on your phone and is never sent to us.'
+      : 'Our app may keep the content it last loaded on your phone so it works offline, and remembers your notification choice there.'] : []),
   ] });
   s.push({ id: 'sharing', title: 'Who receives your information', text: [
     `We don’t sell your personal information${pixels ? '' : ' or share it for advertising'}. These service providers process it on our behalf and only for the purposes above: ${list(processors(f))}. They must protect it at least as this notice describes. Some of them may store it outside your country, including in the United States.`,

package/src/lib/legal/text-es.ts

@@ -53,8 +53,8 @@ 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 y los temas que elija. 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.',
-    `Usted elige los temas en la app y puede cambiarlos cuando quiera; nunca agregamos un tema sin preguntarle. 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.`,
+    '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.',
+    `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: [
     `Enviamos correos a través de ${f.email}, que trata su dirección de correo y el mensaje. Guardamos un registro de entrega (destinatario y estado) durante 30 días, y mantenemos en una lista las direcciones que rebotan o marcan nuestros correos como spam para dejar de escribirles.`,
@@ -80,7 +80,9 @@ export function privacyEs(f: LegalFacts, country: string): PolicySection[] {
   ] });
   s.push({ id: 'cookies', title: 'Cookies y almacenamiento en su dispositivo', text: [
     `${f.auth === 'clerk' ? 'Las cookies de inicio de sesión de Clerk' : 'Una cookie de inicio de sesión (hasta siete días)'} para quienes inician sesión; una cookie de vista previa solo para las vistas previas del personal y los enlaces para compartir diseños (hasta 30 días); y, en su navegador, su preferencia de modo claro u oscuro, los anuncios que cierra y, durante una visita, los avisos de video en vivo que cierra.${pixels ? ` ${pixelNames} ${both ? 'guardan sus propias' : 'guarda sus propias'} cookies de publicidad.` : ' No usamos cookies con fines publicitarios.'}`,
-    ...(app ? ['Nuestra app puede guardar en su teléfono el contenido que cargó por última vez para funcionar sin conexión, y recuerda ahí su preferencia de notificaciones.'] : []),
+    ...(app ? [f.announcements
+      ? 'Nuestra app puede guardar en su teléfono el contenido que cargó por última vez para funcionar sin conexión, y recuerda ahí su preferencia de notificaciones y qué anuncios leyó o cerró. Eso se queda en su teléfono y nunca se nos envía.'
+      : 'Nuestra app puede guardar en su teléfono el contenido que cargó por última vez para funcionar sin conexión, y recuerda ahí su preferencia de notificaciones.'] : []),
   ] });
   s.push({ id: 'sharing', title: 'Quién recibe sus datos', text: [
     `No vendemos sus datos personales${pixels ? '' : ' ni los compartimos con fines publicitarios'}. Estos proveedores los tratan por cuenta nuestra y solo para los fines descritos: ${list(processors(f))}. Deben protegerlos al menos como lo describe este aviso. Algunos pueden guardarlos fuera de su país, incluido Estados Unidos.`,

package/src/lib/mobile/openapi.ts

@@ -10,6 +10,7 @@ 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';
@@ -50,6 +51,8 @@ export async function getOpenApi(_repo: ContentRepository, url: URL) {
     ['/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, 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({ 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,6 +3,7 @@ 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';
@@ -42,6 +43,8 @@ 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 the requested language (?locale=es → /es/privacy)
     legal: { privacy: legalUrl('privacy'), terms: legalUrl('terms') },