@acms-subir/core 0.3.31 → 0.3.33

package/src/lib/push/service.ts

@@ -22,30 +22,51 @@ export const RECEIPT_DELAY = 15 * MINUTE;
 
 // ---- topics ------------------------------------------------------------------
 
+// names of the built-in topics; other languages show English
+const TOPIC_WORDS: Record<string, { news: string; events: string; live: string }> = {
+  en: { news: 'News', events: 'Events', live: 'Live video' },
+  es: { news: 'Noticias', events: 'Eventos', live: 'Video en vivo' },
+  fr: { news: 'Actualités', events: 'Événements', live: 'Vidéo en direct' },
+  de: { news: 'Neuigkeiten', events: 'Veranstaltungen', live: 'Live-Video' },
+  pt: { news: 'Notícias', events: 'Eventos', live: 'Vídeo ao vivo' },
+};
+/** A site topic's words in a language: exact code, its base ("es-MX" → "es"), every language ('*'), the site's main language, then any. */
+export function topicWords(words: Record<string, string>, locale: string): string {
+  const base = locale.toLowerCase().split('-')[0];
+  return words[locale] ?? words[base] ?? words['*'] ?? (I18N.defaultLocale ? words[I18N.defaultLocale] : undefined) ?? Object.values(words)[0] ?? '';
+}
+
 /**
- * Topics an app can offer as toggles. `news` = every new post, `events` = every
- * new event, `live` = "we're live" (while live video isn't off). Per-collection
- * and per-calendar topics appear once there is more than one of them (a single
- * one would just repeat news/events). Devices only get the topics they (or the
- * app, at their first registration) choose: a new topic never reaches existing
- * devices on its own.
+ * Topics an app can offer as toggles, named in `locale` (default: the site's
+ * main language). `news` = every new post, `events` = every new event, `live` =
+ * "we're live" (while live video isn't off), then the site's own topics
+ * (acms({ mobile: { push: { topics } } })). Per-collection and per-calendar
+ * topics appear once there is more than one of them (a single one would just
+ * repeat news/events). Devices only get the topics they (or the app, at their
+ * first registration) choose: a new topic never reaches existing devices on its own.
  */
-export async function pushTopics(repo: ContentRepository): Promise<PushTopic[]> {
+export async function pushTopics(repo: ContentRepository, locale?: string | null): Promise<PushTopic[]> {
+  const lang = locale || I18N.defaultLocale || (await repo.getSettings()).locale || 'en';
+  const w = TOPIC_WORDS[lang.toLowerCase().split('-')[0]] ?? TOPIC_WORDS.en;
   const collections = Object.entries(CONTENT.collections);
-  const out: PushTopic[] = [{ id: 'news', label: 'News', kind: 'general' }];
+  const out: PushTopic[] = [{ id: 'news', label: w.news, kind: 'general' }];
   if (collections.length > 1) out.push(...collections.map(([key, c]): PushTopic => ({ id: `collection:${key}`, label: c.plural, kind: 'collection' })));
   if (CALENDAR.enabled) {
-    out.push({ id: 'events', label: 'Events', kind: 'general' });
+    out.push({ id: 'events', label: w.events, kind: 'general' });
     const calendars = (await repo.listCalendars()).filter((c) => c.visibility === 'public');
     if (calendars.length > 1) out.push(...calendars.map((c): PushTopic => ({ id: `calendar:${c.slug}`, label: c.name, kind: 'calendar' })));
   }
-  if ((await repo.getSettings()).live.mode !== 'off') out.push({ id: 'live', label: 'Live video', kind: 'general' });
+  if ((await repo.getSettings()).live.mode !== 'off') out.push({ id: 'live', label: w.live, kind: 'general' });
+  for (const t of PUSH.topics) {
+    const description = topicWords(t.description, lang);
+    out.push({ id: t.id, label: topicWords(t.label, lang), kind: 'site', ...(description ? { description } : {}) });
+  }
   return out;
 }
 
 /** Every topic a device may subscribe to (listed or not). `live` stays valid while live video is off, so a saved choice survives. */
 export async function knownTopics(repo: ContentRepository): Promise<Set<string>> {
-  const set = new Set(['news', 'live', ...Object.keys(CONTENT.collections).map((k) => `collection:${k}`)]);
+  const set = new Set(['news', 'live', ...Object.keys(CONTENT.collections).map((k) => `collection:${k}`), ...PUSH.topics.map((t) => t.id)]);
   if (CALENDAR.enabled) {
     set.add('events');
     for (const c of await repo.listCalendars()) if (c.visibility === 'public') set.add(`calendar:${c.slug}`);
@@ -94,6 +115,10 @@ export interface SendInput extends Composed {
   author?: string;
   /** words for a device in an extra site language; null = use the main words */
   localize?: (locale: string) => Composed | null;
+  /** Android channel, used only on devices whose app reported creating it */
+  channel?: string;
+  /** a second link (an announcement's button), sent as data.buttonUrl/buttonPath in each phone's language */
+  button?: string;
   data?: Record<string, unknown>;
 }
 export interface PushRunOptions {
@@ -144,9 +169,12 @@ export async function sendNotification(repo: ContentRepository, input: SendInput
       c = words.get(locale)!;
     }
     const link = notificationLink(c.url, origin, locale);
+    const button = input.button ? notificationLink(input.button, origin, locale) : null;
     return {
       to: d.token, title: clip(c.title, 120), body: clip(c.body, 240), sound: 'default', priority: 'high',
-      data: { ...input.data, notificationId: n.id, source: input.source, url: link.url, path: link.path, locale: locale ?? (I18N.defaultLocale || null) },
+      ...(input.channel && d.platform === 'android' && d.channels.includes(input.channel) ? { channelId: input.channel } : {}),
+      data: { ...input.data, notificationId: n.id, source: input.source, url: link.url, path: link.path, locale: locale ?? (I18N.defaultLocale || null),
+        ...(button?.url ? { buttonUrl: button.url, buttonPath: button.path } : {}) },
     };
   });
   const tickets = messages.length ? await sendMessages(messages, expoOptions(opts.locals, opts.expo)) : [];

package/src/lib/push/store.ts

@@ -5,7 +5,7 @@ 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),
-    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) };
 }
 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),
@@ -29,19 +29,21 @@ export class PushStore {
 
   // ---- devices ----
   /** Register or refresh. `topics` undefined keeps a known device's topics (new devices start with none). */
-  async upsertDevice(d: { id: string; token: string; platform: PushPlatform; locale: string; topics?: string[] }, now: number): Promise<{ device: PushDevice; created: boolean }> {
+  async upsertDevice(d: { id: string; token: string; platform: PushPlatform; locale: string; topics?: string[]; channels?: string[] }, now: number): Promise<{ device: PushDevice; created: boolean }> {
     const topics = d.topics === undefined ? null : JSON.stringify(d.topics);
+    const channels = d.channels === undefined ? null : JSON.stringify(d.channels);
     // RETURNING also yields the previous row's created_at on the update branch,
     // so "created" is exact: only the insert branch writes created_at = now.
-    const rows = await this.all(`INSERT INTO push_devices (id,token,platform,locale,topics,created_at,updated_at,last_seen_at) VALUES (?,?,?,?,COALESCE(?,'[]'),?,?,?)
+    const rows = await this.all(`INSERT INTO push_devices (id,token,platform,locale,topics,channels,created_at,updated_at,last_seen_at) VALUES (?,?,?,?,COALESCE(?,'[]'),COALESCE(?,'[]'),?,?,?)
       ON CONFLICT(id) DO UPDATE SET platform=excluded.platform, locale=excluded.locale, topics=COALESCE(?,push_devices.topics),
-      updated_at=excluded.updated_at, last_seen_at=excluded.last_seen_at RETURNING *`, [d.id, d.token, d.platform, d.locale, topics, now, now, now, topics]);
+      channels=COALESCE(?,push_devices.channels), updated_at=excluded.updated_at, last_seen_at=excluded.last_seen_at RETURNING *`,
+      [d.id, d.token, d.platform, d.locale, topics, channels, now, now, now, topics, channels]);
     const row = device(rows[0]);
     return { device: row, created: row.createdAt === now };
   }
-  async updateDevice(id: string, data: { locale?: string; topics?: string[] }, now: number): Promise<PushDevice | null> {
-    const rows = await this.all(`UPDATE push_devices SET locale=COALESCE(?,locale), topics=COALESCE(?,topics), updated_at=?, last_seen_at=? WHERE id=? RETURNING *`,
-      [data.locale ?? null, data.topics ? JSON.stringify(data.topics) : null, now, now, id]);
+  async updateDevice(id: string, data: { locale?: string; topics?: string[]; channels?: string[] }, now: number): Promise<PushDevice | null> {
+    const rows = await this.all(`UPDATE push_devices SET locale=COALESCE(?,locale), topics=COALESCE(?,topics), channels=COALESCE(?,channels), updated_at=?, last_seen_at=? WHERE id=? RETURNING *`,
+      [data.locale ?? null, data.topics ? JSON.stringify(data.topics) : null, data.channels ? JSON.stringify(data.channels) : null, now, now, id]);
     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; }
@@ -69,6 +71,17 @@ export class PushStore {
       topics: Object.fromEntries(topics.map((r) => [String(r.topic), Number(r.n)])) };
   }
 
+  /** Devices in an audience per raw device language ('' = none sent). */
+  async audienceLocales(topics: string[]): Promise<Record<string, number>> {
+    const w = audienceWhere(topics);
+    const rows = await this.all(`SELECT locale, COUNT(*) AS n FROM push_devices WHERE ${w.sql} GROUP BY locale`, w.args);
+    return Object.fromEntries(rows.map((r) => [String(r.locale ?? ''), Number(r.n)]));
+  }
+  /** Notifications from these sources created since `since` (pacing: "sent this week"). */
+  async countSent(sources: PushNotification['source'][], since: number): Promise<number> {
+    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);
+  }
+
   // ---- 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)

package/src/lib/push/types.ts

@@ -19,9 +19,11 @@ export type PushSettings = z.infer<typeof PushSettings>;
 export type PushPlatform = 'ios' | 'android';
 export interface PushDevice {
   id: string; token: string; platform: PushPlatform; locale: string; topics: string[];
+  /** Android notification channels the app created (beyond its default one) */
+  channels: string[];
   createdAt: number; updatedAt: number; lastSeenAt: number;
 }
-export type PushSource = 'manual' | 'post' | 'event' | 'soon' | 'live';
+export type PushSource = 'manual' | 'post' | 'event' | 'soon' | 'live' | 'announcement';
 export interface PushNotification {
   id: string; title: string; body: string; url: string;
   /** ['*'] = everyone */
@@ -33,8 +35,8 @@ export interface PushNotification {
   removed: number;
   error: string; author: string; createdAt: number; finishedAt: number | null;
 }
-export interface PushQueueRow { key: string; kind: 'post' | 'event' | 'soon' | 'live'; docId: string; occurrence: number | null; status: string; createdAt: number }
-export interface PushTopic { id: string; label: string; kind: 'general' | 'collection' | 'calendar' }
+export interface PushQueueRow { key: string; kind: 'post' | 'event' | 'soon' | 'live' | 'announcement'; docId: string; occurrence: number | null; status: string; createdAt: number }
+export interface PushTopic { id: string; label: string; kind: 'general' | 'collection' | 'calendar' | 'site'; description?: string }
 export interface PushStats {
   devices: number;
   platforms: Record<PushPlatform, number>;

package/src/lib/repo/migrations.ts

@@ -8,6 +8,7 @@ import { CALENDAR_SETTINGS_MIGRATION, ROOM_HOLD_MIGRATION } from '../calendar/mi
 import { PLACES_MIGRATION } from '../maps/migration';
 import { ROLES_MIGRATION } from '../permissions/migration';
 import { SYNC_MIGRATION } from '../sync/migration';
+import { ANNOUNCEMENT_TABLE, ANNOUNCEMENT_VISIBLE_COLUMNS } from '../announcements/migration';
 // Versioned schema migrations shared by the two SQLite-dialect adapters
 // (D1 and libSQL). Applied versions are recorded in the `migrations` table;
 // each adapter's runner applies whatever is newer, in order, at startup.
@@ -676,6 +677,8 @@ export const MIGRATIONS: Migration[] = [
     `DROP TRIGGER content_version_settings_update`,
     ...contentVersionTriggers('settings', [...CONTENT_VERSION_COLUMNS.settings, 'links_verified', 'links_avatar_shape', 'links_avatar_fit', 'links_avatar_scale', 'legal']),
   ] },
+  // announcements show on public pages, the banner and the app API
+  { version: 58, statements: [...ANNOUNCEMENT_TABLE, ...contentVersionTriggers('announcements', ANNOUNCEMENT_VISIBLE_COLUMNS)] },
 ];
 
 // Current cache coverage; keep earlier migration inputs frozen for upgrade compatibility.
@@ -683,6 +686,7 @@ export const CURRENT_CONTENT_VERSION_COLUMNS = {
   ...CONTENT_VERSION_COLUMNS,
   settings: [...CONTENT_VERSION_COLUMNS.settings, 'links_verified', 'links_avatar_shape', 'links_avatar_fit', 'links_avatar_scale', 'legal'],
   events: [...CONTENT_VERSION_COLUMNS.events, 'cancelled_dates'],
+  announcements: ANNOUNCEMENT_VISIBLE_COLUMNS,
 };
 
 export const LATEST_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;

package/src/lib/repo/sql.ts

@@ -5,6 +5,7 @@ import { FormStore, formInsert, submissionInsert } from '../forms/store';
 import { GuestStore } from '../mobile/guest-store';
 import { LiveStore } from '../live/store';
 import { PushStore } from '../push/store';
+import { AnnouncementStore, announcementInsert } from '../announcements/store';
 import { EditorStore } from '../editor/store';
 import { PermissionStore } from '../permissions/store';
 import { BackupStore } from '../backup/store';
@@ -276,6 +277,7 @@ export class SqlRepository implements ContentRepository {
   readonly guests: GuestStore;
   readonly live: LiveStore;
   readonly push: PushStore;
+  readonly announcements: AnnouncementStore;
   readonly editor: EditorStore;
   readonly backups: BackupStore;
   readonly permissions: PermissionStore;
@@ -287,6 +289,7 @@ export class SqlRepository implements ContentRepository {
     this.guests = new GuestStore(async () => { await this.ready; return this.driver; });
     this.live = new LiveStore(async () => { await this.ready; return this.driver; });
     this.push = new PushStore(async () => { await this.ready; return this.driver; });
+    this.announcements = new AnnouncementStore(async () => { await this.ready; return this.driver; });
     this.editor = new EditorStore(async () => { await this.ready; return this.driver; });
     this.backups = new BackupStore(async () => { await this.ready; return this.driver; });
     this.auth = new AuthStore(async () => { await this.ready; return this.driver; });
@@ -1823,6 +1826,9 @@ export class SqlRepository implements ContentRepository {
           JSON.stringify(e.hostIds ?? []), e.request ? JSON.stringify(e.request) : null,
         ],
       })),
+      // announcements (a backup made before them leaves the current ones). Restored
+      // rows never push again here: the push ledger keeps announcement:<id>
+      ...(content.announcements ? [{ sql: 'DELETE FROM announcements' }, ...content.announcements.map(announcementInsert)] : []),
       ...(content.forms ?? []).map(formInsert),
       ...(content.formSubmissions ?? []).map(submissionInsert),
       ...(content.resources ?? []).map((r) => this.resourceInsert(r)),

package/src/lib/repo/types.ts

@@ -8,6 +8,8 @@ import type { LiveStore } from '../live/store';
 import type { BookingRequest } from '../backup/content';
 import type { EmailStore } from '../email/store';
 import type { PushStore } from '../push/store';
+import type { AnnouncementStore } from '../announcements/store';
+import type { Announcement } from '../announcements/types';
 import type { EditorStore } from '../editor/store';
 import type { PermissionStore } from '../permissions/store';
 export interface ImportRun { id: string; source: string; label: string; status: 'running' | 'done' | 'undone'; report: Record<string, unknown>; createdAt: number; updatedAt: number }
@@ -62,6 +64,7 @@ export interface ContentRepository {
   readonly guests: GuestStore;
   readonly live: LiveStore;
   readonly push: PushStore;
+  readonly announcements: AnnouncementStore;
   readonly editor: EditorStore;
   readonly permissions: PermissionStore;
   // Bounded public catalog; fetch limit + 1 IDs without loading every body.
@@ -319,6 +322,8 @@ export interface ContentRepository {
     places?: Place[];
     forms?: SavedForm[];
     formSubmissions?: FormSubmission[];
+    // added with announcements; a backup without them leaves the current ones
+    announcements?: Announcement[];
   }, authRecovery?: { issuer: string; subject: string; userId: string }): Promise<void>;
 
   // imports (lib/import/apply.ts drives these). writeImported is the

package/src/lib/scheduler.ts

@@ -4,6 +4,7 @@ import { processDueDeliveries } from './webhooks';
 import { dispatchEmail } from './email/service';
 import { decideOverdue, sendDueReminders } from './booking/service';
 import { runPushJobs } from './push/service';
+import { runAnnouncementJobs } from './announcements/service';
 import { GUEST_IDLE_MS } from './mobile/guest-store';
 import { pushHeartbeat, pushUrlFor } from './monitoring';
 import { syncCachePurge } from './cache/purge';
@@ -22,6 +23,8 @@ export async function runScheduledTasks(repo: ContentRepository, locals?: unknow
     approvals: () => decideOverdue(repo, { origin: settings.siteUrl, locals, now: startedAt }),
     email: () => dispatchEmail(repo, locals, 10),
     live: () => syncDueLive(repo, locals),
+    // scheduled announcements go up (with their push) and ended ones come down
+    announcements: () => runAnnouncementJobs(repo, { locals, now: startedAt }),
     // queued first-publish notices, starting-soon reminders, receipts, retention
     push: () => runPushJobs(repo, { locals, now: startedAt }),
     // expired guest sign-in codes and app sessions unused for 90 days

package/src/lib/schema.ts

@@ -710,6 +710,7 @@ export const WEBHOOK_EVENTS = [
   'design.published', 'media.created', 'media.updated', 'media.deleted', 'site.restored',
   'event.published', 'event.updated', 'event.unpublished', 'event.deleted',
   'booking.created', 'booking.confirmed', 'booking.declined', 'booking.cancelled', 'booking.rescheduled',
+  'announcement.published',
 ] as const;
 export type WebhookEventType = (typeof WEBHOOK_EVENTS)[number];
 

package/src/pages/admin/announcements.astro

@@ -0,0 +1,18 @@
+---
+import Admin from '../../layouts/Admin.astro';
+import Announcements from '../../components/Announcements';
+import { getRepo } from '../../lib/repo';
+import { forbiddenUnless } from '../../lib/permissions/access';
+const repo = await getRepo(Astro.locals);
+const denied = await forbiddenUnless(Astro.request, Astro.cookies, repo, 'services.manage');
+if (denied) return denied;
+---
+<Admin title="Announcements" section="announcements">
+  <div class="page-head">
+    <div>
+      <h1>Announcements</h1>
+      <p class="sub">Write it once: it goes on the announcements list, as a banner and, if you choose, as a push to the app.</p>
+    </div>
+  </div>
+  <Announcements client:only="react" />
+</Admin>

package/src/pages/admin/integrations.astro

@@ -5,6 +5,7 @@ import { getRepo } from '../../lib/repo';
 import { API_SCOPES, WEBHOOK_EVENTS, type ApiScope } from '../../lib/schema';
 import { accessFor } from '../../lib/permissions/access';
 import { CALENDAR, bookingsEnabled } from '../../lib/calendar/config';
+import { ANNOUNCEMENTS } from '../../lib/announcements/config';
 import { issueApiKey } from '../../lib/api-keys';
 import { sessionRole } from '../../lib/api';
 import { attemptDelivery, generateWebhookSecret, validateWebhookUrl } from '../../lib/webhooks';
@@ -243,7 +244,7 @@ MAPS_API_KEY=…`}</pre>
       <input type="hidden" name="op" value="hook" />
       <label class="field"><span>Endpoint URL</span><input type="url" class="mono" name="url" placeholder="https://hooks.zapier.com/…" required /></label>
       <div class="field"><span>Send these events</span>
-        {WEBHOOK_EVENTS.filter((e) => (CALENDAR.enabled || !e.startsWith('event.')) && (bookingsEnabled() || !e.startsWith('booking.'))).map((e) => <label class="check-row"><input type="checkbox" name="events" value={e} checked={e === 'post.published' || e === 'page.published'} /> <code>{e}</code></label>)}
+        {WEBHOOK_EVENTS.filter((e) => (CALENDAR.enabled || !e.startsWith('event.')) && (bookingsEnabled() || !e.startsWith('booking.')) && (ANNOUNCEMENTS.enabled || !e.startsWith('announcement.'))).map((e) => <label class="check-row"><input type="checkbox" name="events" value={e} checked={e === 'post.published' || e === 'page.published'} /> <code>{e}</code></label>)}
       </div>
       <div class="modal-foot"><button class="btn ghost" type="button" data-close>Cancel</button><button class="btn primary" type="submit">Add endpoint</button></div>
       <p class="hint modal-note">Deliveries are signed and retried 3 times over about an hour.</p>

package/src/pages/admin/settings.astro

@@ -4,6 +4,7 @@ import AiSettings from '../../components/AiSettings';
 import MonitoringSettings from '../../components/MonitoringSettings';
 import LegalSettings from '../../components/LegalSettings';
 import { LEGAL } from '../../lib/legal/config';
+import { ANNOUNCEMENTS } from '../../lib/announcements/config';
 import { getRepo } from '../../lib/repo';
 import { accessFor } from '../../lib/permissions/access';
 import type { Permission } from '../../lib/permissions/catalog';
@@ -381,6 +382,7 @@ const groups = [
             <label class="field"><span>Link (optional)</span><input type="text" name="annLink" value={settings.announcement.link} placeholder={`${CONTENT.posts.base}/announcement`} /></label>
           </div>
           <label class="check-row"><input type="checkbox" name="annDismissible" checked={settings.announcement.dismissible} /><span>Visitors can dismiss it <span class="hint">(remembered per browser until the text changes)</span></span></label>
+          {ANNOUNCEMENTS.enabled && <p class="hint">A pinned announcement (<a href="/admin/announcements">Announcements</a>) shows here instead while it’s up, in each language and on a schedule.</p>}
         </form>
       </section>
 

package/src/pages/announcements/[id].astro

@@ -0,0 +1,35 @@
+---
+import Site from '../../layouts/Site.astro';
+import { getRepo } from '../../lib/repo';
+import { requestLocale, localePath } from '../../lib/i18n';
+import { siteLang } from '../../lib/dates';
+import { ANNOUNCEMENTS } from '../../lib/announcements/config';
+import { isLive } from '../../lib/announcements/service';
+import { announcementStrings } from '../../lib/announcements/words';
+import { announcementView } from '../../lib/announcements/pages';
+import '../../styles/announcements-site.css';
+
+// One announcement while it's up (404 before it goes up and after it comes
+// down). Pushes without a button open this page.
+if (!ANNOUNCEMENTS.enabled || !ANNOUNCEMENTS.pages) return new Response(null, { status: 404, statusText: 'Not found' });
+const repo = await getRepo(Astro.locals);
+const id = Astro.params.id ?? '';
+const now = Date.now();
+const a = id.length <= 100 ? await repo.announcements.get(id) : null;
+if (!a || !isLive(a, now) || !(a.listed || a.pinned)) return new Response(null, { status: 404, statusText: 'Not found' });
+const settings = await repo.getSettings();
+const locale = requestLocale(Astro.url, Astro.locals);
+const lang = locale || siteLang(settings);
+const t = announcementStrings(lang);
+const v = announcementView(a, locale, lang, settings.timezone || 'UTC', now);
+---
+<Site title={v.title} description={v.message}>
+  <article class="ann-page ann-detail" data-kind={v.kind}>
+    <p class="ann-back"><a href={localePath(ANNOUNCEMENTS.base, locale)}>← {t.back}</a></p>
+    <p class="ann-meta"><span class="ann-kind">{v.kindLabel}</span> · <time datetime={v.iso}>{v.date}</time>{v.until && <> · {v.until}</>}</p>
+    <h1>{v.title}</h1>
+    {v.message && <p class="ann-lead">{v.message}</p>}
+    {v.details.map((p) => <p>{p}</p>)}
+    {v.button && <p><a class="ann-button" href={v.button.href} rel={v.button.external ? 'noopener' : undefined}>{v.button.label}</a></p>}
+  </article>
+</Site>

package/src/pages/announcements/index.astro

@@ -0,0 +1,61 @@
+---
+import Site from '../../layouts/Site.astro';
+import { getRepo } from '../../lib/repo';
+import { requestLocale, localePath } from '../../lib/i18n';
+import { siteLang } from '../../lib/dates';
+import { ANNOUNCEMENTS } from '../../lib/announcements/config';
+import { ANNOUNCEMENT_KINDS, type AnnouncementKind } from '../../lib/announcements/types';
+import { announcementStrings } from '../../lib/announcements/words';
+import { announcementView, groupByWhen } from '../../lib/announcements/pages';
+import '../../styles/announcements-site.css';
+
+// The website's announcements list (acms({ announcements })): what's up
+// right now, newest first, with a tab per kind. A site file at this path
+// replaces it; GET /api/v1/announcements has the same data.
+if (!ANNOUNCEMENTS.enabled || !ANNOUNCEMENTS.pages) return new Response(null, { status: 404, statusText: 'Not found' });
+const repo = await getRepo(Astro.locals);
+const settings = await repo.getSettings();
+const locale = requestLocale(Astro.url, Astro.locals);
+const lang = locale || siteLang(settings);
+const t = announcementStrings(lang);
+const tz = settings.timezone || 'UTC';
+const now = Date.now();
+const asked = Astro.url.searchParams.get('kind') ?? '';
+const kind = (ANNOUNCEMENT_KINDS as readonly string[]).includes(asked) ? asked as AnnouncementKind : undefined;
+const live = await repo.announcements.live(now, { limit: 200, offset: 0 });
+// tabs only for kinds that have something up (urgent shows under All)
+const kinds = ANNOUNCEMENT_KINDS.filter((k) => k !== 'urgent' && live.some((a) => a.kind === k));
+const shown = live.filter((a) => !kind || a.kind === kind).map((a) => announcementView(a, locale, lang, tz, now));
+const groups = groupByWhen(shown, lang, tz, now);
+const base = localePath(ANNOUNCEMENTS.base, locale);
+const tabs = kinds.length ? [{ href: base, label: t.all, current: !kind }, ...kinds.map((k) => ({ href: base + '?kind=' + k, label: t.kinds[k], current: kind === k }))] : [];
+---
+<Site title={t.title} description={t.intro}>
+  <section class="ann-page">
+    <header class="ann-head">
+      <h1>{t.title}</h1>
+      <p>{t.intro}</p>
+    </header>
+    {tabs.length > 0 && (
+      <nav class="ann-tabs" aria-label={t.title}>
+        {tabs.map((tab) => <a href={tab.href} aria-current={tab.current ? 'page' : undefined}>{tab.label}</a>)}
+      </nav>
+    )}
+    {groups.length === 0 && <p class="ann-empty">{kind ? t.emptyKind : t.empty}</p>}
+    {groups.map((g) => (
+      <section class="ann-group" aria-labelledby={'ann-' + g.key}>
+        <h2 id={'ann-' + g.key}>{g.label}</h2>
+        <ul class="ann-list">
+          {g.items.map((a) => (
+            <li class="ann-item" data-kind={a.kind}>
+              <p class="ann-meta"><span class="ann-kind">{a.kindLabel}</span> · <time datetime={a.iso}>{a.date}</time></p>
+              <h3><a href={a.href}>{a.title}</a></h3>
+              {a.message && <p class="ann-message">{a.message}</p>}
+              {a.button && <a class="ann-action" href={a.button.href} rel={a.button.external ? 'noopener' : undefined}>{a.button.label} →</a>}
+            </li>
+          ))}
+        </ul>
+      </section>
+    ))}
+  </section>
+</Site>

package/src/pages/api/announcements.ts

@@ -0,0 +1,32 @@
+import type { APIRoute } from 'astro';
+import { getRepo } from '../../lib/repo';
+import { ApiError, apiError, json, readJson } from '../../lib/api';
+import { OWNER_ENV } from '../../lib/auth';
+import { validateRequestSession } from '../../lib/auth/request';
+import { requirePermission } from '../../lib/permissions/access';
+import { waitUntilFrom } from '../../lib/webhooks';
+import { AdminAnnouncementAction, adminAnnouncementAction, adminAnnouncementsState, requireAnnouncements } from '../../lib/announcements/api';
+
+// Admin → Announcements: the people who can send pushes (Connected services).
+export const GET: APIRoute = async ({ request, cookies, locals, url }) => {
+  try {
+    requireAnnouncements();
+    const repo = await getRepo(locals);
+    await requirePermission(request, cookies, repo, 'services.manage');
+    return json(await adminAnnouncementsState(repo, url));
+  } catch (e) { return apiError(e); }
+};
+export const POST: APIRoute = async ({ request, cookies, locals, url }) => {
+  try {
+    requireAnnouncements();
+    const repo = await getRepo(locals);
+    await requirePermission(request, cookies, repo, 'services.manage');
+    // publishing can reach every installed app: only from this site's admin
+    if (request.headers.get('origin') !== url.origin) throw new ApiError(403, 'Change this from this site’s admin.');
+    const input = AdminAnnouncementAction.parse(await readJson(request, 100_000));
+    const id = await validateRequestSession(request, cookies, repo);
+    const author = id === OWNER_ENV ? 'Owner' : (await repo.getUser(id ?? ''))?.name ?? '';
+    const result = await adminAnnouncementAction(repo, input, { url, author, locals, waitUntil: waitUntilFrom(locals), fallbackOrigin: url.origin });
+    return json({ ...result, state: input.action === 'count' ? undefined : await adminAnnouncementsState(repo, url) });
+  } catch (e) { return apiError(e); }
+};

package/src/pages/api/v1/announcements/[id].ts

@@ -0,0 +1,7 @@
+import { getAnnouncement } from '../../../../lib/announcements/api';
+import { readRoute } from '../../../../lib/mobile/route';
+import { methodNotAllowed } from '../../../../lib/mobile/http';
+export { preflight as OPTIONS } from '../../../../lib/mobile/http';
+export const GET = readRoute(getAnnouncement);
+export const HEAD = GET;
+export const ALL = () => methodNotAllowed();

package/src/pages/api/v1/announcements/index.ts

@@ -0,0 +1,8 @@
+import { listAnnouncements } from '../../../../lib/announcements/api';
+import { readRoute } from '../../../../lib/mobile/route';
+import { methodNotAllowed } from '../../../../lib/mobile/http';
+export { preflight as OPTIONS } from '../../../../lib/mobile/http';
+// announcements go up and come down with the clock: not timeless
+export const GET = readRoute(listAnnouncements);
+export const HEAD = GET;
+export const ALL = () => methodNotAllowed();

package/src/pages/api/webhooks/docs.ts

@@ -23,6 +23,7 @@ design.published: a design draft is published, including its navigation and sect
 Restoring design history only stages a draft; publishing it emits this event.
 media.created/updated/deleted: a media record is added, its alt text changes, or it is removed.
 site.restored: a content backup is restored; resync instead of expecting individual record events.
+announcement.published: an announcement goes up (acms({ announcements }); scheduled ones when their time comes).
 Existing event.* and booking.* payloads are described at /api/calendar/docs.
 
 ## Payloads
@@ -34,6 +35,7 @@ page.* data: { "page": { "id", "slug", "title", "status", "locale", "isHome" },
 design.published data: { "design": { "revision", "activeTheme", "navigationChanged", "sectionPageIds" } }
 media.* data: { "media": { "id", "key", "filename", "mime", "width", "height", "size", "alt" } }
 site.restored data: { "counts": { "posts", "pages", "media" } }
+announcement.published data: { "announcement": { the GET /api/v1/announcements/<id> item in the main language, plus "status" } }
 
 Content notifications carry metadata, not document bodies or pending drafts.
 On publication/update, fetch current public content from /api/v1/content/<id>?kind=post (or kind=page).

package/src/styles/announcements-site.css

@@ -0,0 +1,32 @@
+/* Built-in /announcements pages: on the page background (no card), the
+   kind in words first, urgent marked by its label rather than colour alone. */
+.ann-page { max-width: 720px; margin: 0 auto; padding: 40px 20px 72px; }
+.ann-head h1, .ann-detail h1 { font-size: clamp(28px, 4vw, 36px); letter-spacing: -0.03em; margin: 0 0 6px; }
+.ann-head p { color: var(--muted); margin: 0 0 24px; }
+.ann-tabs { display: flex; flex-wrap: wrap; gap: 4px 18px; border-bottom: 1px solid var(--line); margin-bottom: 8px; }
+.ann-tabs a { color: var(--muted); text-decoration: none; padding: 10px 0; min-height: 44px; display: inline-flex; align-items: center; border-bottom: 2px solid transparent; margin-bottom: -1px; }
+.ann-tabs a:hover { color: var(--ink); }
+.ann-tabs a[aria-current='page'] { color: var(--ink); border-bottom-color: var(--ink); font-weight: 600; }
+.ann-group h2 { font-size: 13px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.06em; color: var(--muted); margin: 28px 0 4px; }
+.ann-list { list-style: none; margin: 0; padding: 0; }
+.ann-item { padding: 16px 0; border-bottom: 1px solid var(--line); }
+.ann-item:last-child { border-bottom: 0; }
+.ann-meta { font-size: 13px; color: var(--muted); margin: 0 0 4px; }
+.ann-kind { font-weight: 600; color: var(--ink); }
+[data-kind='urgent'] .ann-kind { text-transform: uppercase; letter-spacing: 0.04em; }
+.ann-item h3 { font-size: 18px; margin: 0 0 4px; letter-spacing: -0.01em; }
+.ann-item h3 a { color: inherit; text-decoration: none; }
+.ann-item h3 a:hover { text-decoration: underline; text-underline-offset: 3px; }
+.ann-message { margin: 0 0 6px; }
+.ann-action { font-weight: 600; color: var(--accent-text, var(--accent)); text-decoration: none; display: inline-block; padding: 4px 0; }
+.ann-action:hover { text-decoration: underline; text-underline-offset: 3px; }
+.ann-empty { color: var(--muted); padding: 32px 0; }
+.ann-back { margin: 0 0 20px; }
+.ann-back a { color: var(--muted); text-decoration: none; }
+.ann-back a:hover { color: var(--ink); }
+.ann-lead { font-size: 18px; }
+.ann-button {
+  display: inline-flex; align-items: center; min-height: 44px; padding: 0 20px; border-radius: var(--r-sm);
+  background: var(--btn); color: var(--btn-ink); text-decoration: none; font-weight: 600;
+}
+.ann-button:hover { opacity: 0.92; }