@acms-subir/core 0.3.3-next.20260929113209 → 0.3.3

package/src/lib/push/api.ts

@@ -0,0 +1,158 @@
+// Public device endpoints (/api/v1/devices, /api/v1/push/topics) and the
+// owner-only admin state/actions behind Admin → Mobile app.
+import { z } from 'zod';
+import type { ContentRepository } from '../repo/types';
+import { ApiError, readJson } from '../api';
+import { sha256Hex } from '../api-keys';
+import { CONTENT, collectionUrl } from '../content';
+import { CALENDAR, eventUrl } from '../calendar/config';
+import { eventIsListed } from '../calendar/events';
+import { queryParams } from '../mobile/http';
+import { EXPO_PUSH_BASE, PUSH, requirePush } from './config';
+import { expoOptions } from './expo';
+import { knownTopics, pushTopics, sendNotification, siteOriginOf, type PushRunOptions } from './service';
+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.');
+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(),
+}).strict();
+export const deviceUpdate = z.object({ locale: locale.optional(), topics: topicList.optional() }).strict();
+
+export const deviceJson = (d: PushDevice) => ({
+  token: d.token, platform: d.platform, locale: d.locale || null, topics: d.topics,
+  registeredAt: new Date(d.createdAt).toISOString(), lastSeenAt: new Date(d.lastSeenAt).toISOString(),
+});
+const deviceId = (token: string) => sha256Hex(`expo-push:${token}`);
+
+async function checkTopics(repo: ContentRepository, topics: string[] | undefined) {
+  if (!topics) return undefined;
+  const known = await knownTopics(repo);
+  const unique = [...new Set(topics)];
+  const unknown = unique.find((t) => !known.has(t));
+  if (unknown) throw new ApiError(400, `Unknown topic: ${unknown}. See GET /api/v1/push/topics.`);
+  return unique;
+}
+function tokenParam(raw: string) {
+  let value = raw;
+  try { if (/%[0-9a-f]{2}/i.test(raw)) value = decodeURIComponent(raw); } catch { /* keep raw */ }
+  const parsed = pushToken.safeParse(value);
+  if (!parsed.success) throw new ApiError(400, 'Use an Expo push token such as ExponentPushToken[…] in the path.');
+  return parsed.data;
+}
+
+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());
+  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 (!device) throw new ApiError(404, 'This device is not registered. Register it with POST /api/v1/devices.');
+  return deviceJson(device);
+}
+export async function unregisterDevice(repo: ContentRepository, rawToken: string) {
+  requirePush();
+  const token = tokenParam(rawToken);
+  // idempotent: an unknown token is already opted out
+  await repo.push.deleteDevices([await deviceId(token)]);
+  return { token, deleted: true };
+}
+export async function listPushTopics(repo: ContentRepository, url: URL) {
+  requirePush();
+  z.object({}).strict().parse(queryParams(url));
+  return { topics: await pushTopics(repo) };
+}
+
+// ---- admin -------------------------------------------------------------------
+
+export interface PushLinkTarget { ref: string; label: string; url: string; group: 'Pages' | 'Posts' | 'Events' }
+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([]),
+    CALENDAR.enabled ? repo.listCalendars() : Promise.resolve([]),
+  ]);
+  const cals = new Map(calendars.map((c) => [c.id, c]));
+  return [
+    ...pages.filter((p) => p.status === 'published').map((p): PushLinkTarget => ({ ref: `page:${p.id}`, label: p.title || p.slug, url: p.isHome ? '/' : `/${p.slug}`, group: 'Pages' })),
+    ...posts.filter((p) => CONTENT.collections[p.collection]).slice(0, 200).map((p): PushLinkTarget => ({ ref: `post:${p.id}`, label: p.title, url: collectionUrl(p.collection, p.slug), group: 'Posts' })),
+    ...events.filter((e) => eventIsListed(e, cals)).slice(0, 200).map((e): PushLinkTarget => ({ ref: `event:${e.id}`, label: e.title, url: eventUrl(e.slug), group: 'Events' })),
+  ];
+}
+
+export async function adminPushState(repo: ContentRepository, url: URL, locals?: unknown) {
+  const now = Date.now();
+  const settings = await repo.getSettings();
+  const expo = expoOptions(locals);
+  const [stats, topics, calendars, links, log] = await Promise.all([
+    repo.push.stats(now), pushTopics(repo),
+    CALENDAR.enabled ? repo.listCalendars() : Promise.resolve([]),
+    linkTargets(repo), repo.push.listNotifications(50),
+  ]);
+  return {
+    enabled: PUSH.enabled, retentionDays: PUSH.retentionDays,
+    site: { name: settings.siteTitle, icon: settings.siteFavicon, origin: siteOriginOf(settings, url.origin) },
+    stats, topics, auto: settings.push.auto, links, log,
+    collections: Object.entries(CONTENT.collections).map(([key, c]) => ({ key, label: c.plural })),
+    calendarEnabled: CALENDAR.enabled,
+    calendars: calendars.filter((c) => c.visibility === 'public').map((c) => ({ id: c.id, slug: c.slug, name: c.name, color: c.color })),
+    expo: { accessToken: Boolean(expo.accessToken), customEndpoint: expo.base !== EXPO_PUSH_BASE },
+  };
+}
+export type AdminPushState = Awaited<ReturnType<typeof adminPushState>>;
+
+const audience = z.array(z.string().min(1).max(200)).min(1, 'Choose who gets it.').max(50);
+const link = 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.');
+export const AdminPushInput = z.discriminatedUnion('action', [
+  z.object({ action: z.literal('count'), audience }).strict(),
+  z.object({ action: z.literal('send'), title: z.string().trim().min(1, 'Add a title.').max(80), body: z.string().trim().max(240).default(''), url: link.default(''), audience }).strict(),
+  z.object({ action: z.literal('saveAuto'), auto: PushAuto }).strict(),
+]);
+
+async function checkAudience(repo: ContentRepository, list: string[]) {
+  if (list.includes('*')) return ['*'];
+  const known = await knownTopics(repo);
+  const bad = list.find((t) => !known.has(t));
+  if (bad) throw new ApiError(400, `Unknown topic: ${bad}.`);
+  return [...new Set(list)];
+}
+
+export async function adminPushAction(repo: ContentRepository, input: z.infer<typeof AdminPushInput>, ctx: { url: URL; locals?: unknown; author: string; run?: PushRunOptions }) {
+  switch (input.action) {
+    case 'count':
+      return { recipients: await repo.push.countAudience(await checkAudience(repo, input.audience)) };
+    case 'send': {
+      const settings = await repo.getSettings();
+      const notification = await sendNotification(repo, {
+        title: input.title, body: input.body, url: input.url, audience: await checkAudience(repo, input.audience),
+        source: 'manual', author: ctx.author,
+      }, { locals: ctx.locals, origin: siteOriginOf(settings, ctx.url.origin), ...ctx.run });
+      return { notification };
+    }
+    case 'saveAuto': {
+      const collections = new Set(Object.keys(CONTENT.collections));
+      const calendars = new Set((CALENDAR.enabled ? await repo.listCalendars() : []).filter((c) => c.visibility === 'public').map((c) => c.id));
+      const cals = (ids: string[]) => [...new Set(ids)].filter((id) => id === '*' || calendars.has(id));
+      const auto = {
+        newPost: { collections: [...new Set(input.auto.newPost.collections)].filter((k) => collections.has(k)) },
+        newEvent: { calendars: CALENDAR.enabled ? cals(input.auto.newEvent.calendars) : [] },
+        startingSoon: { calendars: CALENDAR.enabled ? cals(input.auto.startingSoon.calendars) : [], minutes: input.auto.startingSoon.minutes },
+      };
+      await repo.updateSettings({ push: { auto } });
+      return { auto };
+    }
+  }
+}

package/src/lib/push/config.ts

@@ -0,0 +1,20 @@
+// Push notifications config, set per project via the integration:
+//   acms({ mobile: { push: true } })  or  { push: { enabled: true, retentionDays: 270 } }
+// 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.
+import { userConfig } from 'virtual:acms-config';
+import { ApiError } from '../api';
+
+// mutable so tests can exercise the disabled paths
+export const PUSH = {
+  enabled: userConfig.mobile?.push?.enabled === true,
+  retentionDays: userConfig.mobile?.push?.retentionDays ?? 270,
+};
+
+export function requirePush() {
+  if (!PUSH.enabled) throw new ApiError(404, 'This feature is disabled.');
+}
+
+/** Expo's push service. ACMS_EXPO_PUSH_URL overrides it (a local stub in tests/QA). */
+export const EXPO_PUSH_BASE = 'https://exp.host/--/api/v2/push';

package/src/lib/push/expo.ts

@@ -0,0 +1,76 @@
+// Expo push service client: https://docs.expo.dev/push-notifications/sending-notifications/
+// send: POST <base>/send with up to 100 messages → one ticket per message, in order.
+// receipts: POST <base>/getReceipts with up to 1000 ticket ids, some minutes later.
+// An Expo access token (EXPO_ACCESS_TOKEN) is only needed when "enhanced push
+// security" is on for the Expo project. ACMS_EXPO_PUSH_URL points the sender at
+// a stub for tests and local QA.
+import { runtimeValue } from '../email/config';
+import { EXPO_PUSH_BASE } from './config';
+
+export interface ExpoMessage {
+  to: string; title: string; body: string; data: Record<string, unknown>;
+  sound?: 'default' | null; priority?: 'default' | 'normal' | 'high'; channelId?: string;
+}
+export type ExpoTicket = { status: 'ok'; id: string } | { status: 'error'; message: string; details?: { error?: string } };
+export type ExpoReceipt = { status: 'ok' } | { status: 'error'; message: string; details?: { error?: string } };
+export type Fetcher = (url: string, init: RequestInit) => Promise<Response>;
+export interface ExpoOptions { base: string; accessToken: string; fetcher?: Fetcher; retryDelayMs?: number }
+
+export const SEND_BATCH = 100;
+export const RECEIPT_BATCH = 1000;
+
+export function expoOptions(locals?: unknown, extra: Partial<ExpoOptions> = {}): ExpoOptions {
+  const base = (runtimeValue('ACMS_EXPO_PUSH_URL', locals) || EXPO_PUSH_BASE).replace(/\/+$/, '');
+  return { base, accessToken: runtimeValue('EXPO_ACCESS_TOKEN', locals), ...extra };
+}
+
+async function post(opts: ExpoOptions, path: string, body: unknown): Promise<{ ok: true; json: any } | { ok: false; message: string }> {
+  const fetcher: Fetcher = opts.fetcher ?? ((url, init) => fetch(url, init));
+  const headers: Record<string, string> = { 'content-type': 'application/json', accept: 'application/json', 'user-agent': 'acms-push/1.0' };
+  if (opts.accessToken) headers.authorization = `Bearer ${opts.accessToken}`;
+  let last = 'Push service unreachable.';
+  // one retry for rate limits, server errors and network failures
+  for (let attempt = 0; attempt < 2; attempt++) {
+    if (attempt) await new Promise((r) => setTimeout(r, opts.retryDelayMs ?? 1500));
+    try {
+      const res = await fetcher(`${opts.base}${path}`, { method: 'POST', headers, body: JSON.stringify(body), signal: AbortSignal.timeout(15_000) });
+      const json = await res.json().catch(() => null);
+      if (res.ok && json && typeof json === 'object') return { ok: true, json };
+      last = json?.errors?.[0]?.message ?? `Push service answered ${res.status}.`;
+      if (res.status !== 429 && res.status < 500) break;
+    } catch (e) {
+      last = e instanceof Error && e.name === 'TimeoutError' ? 'Push service timed out.' : 'Push service unreachable.';
+    }
+  }
+  return { ok: false, message: last };
+}
+
+/** One ticket per message, aligned by index. A failed batch yields error tickets for each of its messages. */
+export async function sendMessages(messages: ExpoMessage[], opts: ExpoOptions): Promise<ExpoTicket[]> {
+  const tickets: ExpoTicket[] = [];
+  for (let i = 0; i < messages.length; i += SEND_BATCH) {
+    const batch = messages.slice(i, i + SEND_BATCH);
+    const res = await post(opts, '/send', batch);
+    const data = res.ok && Array.isArray(res.json.data) ? res.json.data : null;
+    for (let j = 0; j < batch.length; j++) {
+      const t = data?.[j];
+      if (t?.status === 'ok' && typeof t.id === 'string') tickets.push({ status: 'ok', id: t.id });
+      else if (t?.status === 'error') tickets.push({ status: 'error', message: String(t.message ?? 'Rejected.'), details: t.details });
+      else tickets.push({ status: 'error', message: res.ok ? 'No ticket returned.' : res.message, details: { error: 'RequestFailed' } });
+    }
+  }
+  return tickets;
+}
+
+/** Receipts by ticket id. Ids Expo doesn't know yet (or anymore) are simply missing. */
+export async function fetchReceipts(ids: string[], opts: ExpoOptions): Promise<Record<string, ExpoReceipt>> {
+  const out: Record<string, ExpoReceipt> = {};
+  for (let i = 0; i < ids.length; i += RECEIPT_BATCH) {
+    const res = await post(opts, '/getReceipts', { ids: ids.slice(i, i + RECEIPT_BATCH) });
+    if (!res.ok) throw new Error(res.message);
+    Object.assign(out, res.json.data ?? {});
+  }
+  return out;
+}
+
+export const isGone = (x: { status: string; details?: { error?: string } }) => x.status === 'error' && x.details?.error === 'DeviceNotRegistered';

package/src/lib/push/migration.ts

@@ -0,0 +1,60 @@
+// v37: push notifications. Devices hold the Expo push token (needed to send)
+// and nothing personal. push_queue doubles as the "already announced" ledger:
+// one row per post/event ever published (key post:<id> / event:<id>) and per
+// "starting soon" occurrence (soon:<id>:<start ms>), so automatic notices go
+// out on the FIRST publish only, never for edits or re-publishing.
+//
+// Rows are written by triggers, so every publish path (editor, scheduled
+// publishing, API, agent) is covered without touching each caller. Imports and
+// restores run with webhook_control.suppressed=1 and are recorded as skipped:
+// migrating old posts is not news. The scheduler decides whether a pending row
+// is actually sent (push enabled, matching automatic rule, still published).
+const now = "CAST((julianday('now') - 2440587.5) * 86400000 AS INTEGER)";
+const status = "CASE WHEN (SELECT suppressed FROM webhook_control WHERE id=1)=1 THEN 'skipped' ELSE 'pending' END";
+function enqueue(kind: 'post' | 'event') {
+  // Plain INSERT … SELECT … WHERE NOT EXISTS: no conflict clause, so an outer
+  // INSERT OR REPLACE (restore) can't turn it into a replace of a sent row.
+  return `INSERT INTO push_queue (key,kind,doc_id,occurrence,status,notification_id,created_at,updated_at)
+    SELECT '${kind}:'||NEW.id,'${kind}',NEW.id,NULL,${status},NULL,${now},${now}
+    WHERE NOT EXISTS (SELECT 1 FROM push_queue WHERE key='${kind}:'||NEW.id);`;
+}
+function triggers(kind: 'post' | 'event') {
+  const table = `${kind}s`;
+  return [
+    `CREATE TRIGGER push_${kind}_insert AFTER INSERT ON ${table} WHEN NEW.status='published' BEGIN ${enqueue(kind)} END`,
+    `CREATE TRIGGER push_${kind}_publish AFTER UPDATE OF status ON ${table}
+      WHEN NEW.status='published' AND OLD.status IS NOT 'published' BEGIN ${enqueue(kind)} END`,
+  ];
+}
+
+export const PUSH_MIGRATION = { version: 37, statements: [
+  `ALTER TABLE settings ADD COLUMN push TEXT NOT NULL DEFAULT '{}'`,
+  `CREATE TABLE push_devices (
+    id TEXT PRIMARY KEY, token TEXT NOT NULL UNIQUE, platform TEXT NOT NULL,
+    locale TEXT NOT NULL DEFAULT '', topics TEXT NOT NULL DEFAULT '[]',
+    created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, last_seen_at INTEGER NOT NULL
+  )`,
+  `CREATE INDEX push_devices_seen ON push_devices (last_seen_at)`,
+  `CREATE TABLE push_notifications (
+    id TEXT PRIMARY KEY, title TEXT NOT NULL, body TEXT NOT NULL DEFAULT '', url TEXT NOT NULL DEFAULT '',
+    topics TEXT NOT NULL DEFAULT '[]', source TEXT NOT NULL DEFAULT 'manual', source_key TEXT NOT NULL DEFAULT '',
+    status TEXT NOT NULL DEFAULT 'sending', recipients INTEGER NOT NULL DEFAULT 0, sent INTEGER NOT NULL DEFAULT 0,
+    ok INTEGER NOT NULL DEFAULT 0, failed INTEGER NOT NULL DEFAULT 0, removed INTEGER NOT NULL DEFAULT 0,
+    error TEXT NOT NULL DEFAULT '', author TEXT NOT NULL DEFAULT '', created_at INTEGER NOT NULL, finished_at INTEGER
+  )`,
+  `CREATE INDEX push_notifications_created ON push_notifications (created_at)`,
+  // Expo push tickets awaiting a receipt check (receipts expire after 24h)
+  `CREATE TABLE push_tickets (id TEXT PRIMARY KEY, notification_id TEXT NOT NULL, device_id TEXT NOT NULL, created_at INTEGER NOT NULL)`,
+  `CREATE INDEX push_tickets_created ON push_tickets (created_at)`,
+  `CREATE TABLE push_queue (
+    key TEXT PRIMARY KEY, kind TEXT NOT NULL, doc_id TEXT NOT NULL, occurrence INTEGER,
+    status TEXT NOT NULL, notification_id TEXT, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+  )`,
+  `CREATE INDEX push_queue_status ON push_queue (status, created_at)`,
+  // everything already live counts as announced
+  `INSERT INTO push_queue (key,kind,doc_id,occurrence,status,notification_id,created_at,updated_at)
+    SELECT 'post:'||id,'post',id,NULL,'seen',NULL,${now},${now} FROM posts WHERE status='published'`,
+  `INSERT INTO push_queue (key,kind,doc_id,occurrence,status,notification_id,created_at,updated_at)
+    SELECT 'event:'||id,'event',id,NULL,'seen',NULL,${now},${now} FROM events WHERE status='published'`,
+  ...triggers('post'), ...triggers('event'),
+] };

package/src/lib/push/service.ts

@@ -0,0 +1,302 @@
+// Push notifications: topics, audiences, the Expo sender pipeline, automatic
+// notices (first publish of a post/event, "starting soon") and receipts.
+import type { ContentRepository } from '../repo/types';
+import type { CalEvent, Calendar, Post, Settings } from '../schema';
+import { CONTENT, collectionUrl } from '../content';
+import { CALENDAR, eventUrl } from '../calendar/config';
+import { eventIsListed, eventTimeZone, expandEvents } from '../calendar/events';
+import { I18N } from '../i18n';
+import { localizeDoc } from '../translations';
+import { localizedUrl } from '../mobile/locale';
+import { PUSH } from './config';
+import { expoOptions, fetchReceipts, isGone, sendMessages, type ExpoMessage, type ExpoOptions } from './expo';
+import type { PushNotification, PushSource, PushTopic } from './types';
+
+const MINUTE = 60_000, HOUR = 60 * MINUTE, DAY = 24 * HOUR;
+/** automatic notices queued longer ago than this are skipped, never sent late */
+export const STALE_AFTER = 6 * HOUR;
+/** Expo recommends waiting before reading receipts */
+export const RECEIPT_DELAY = 15 * MINUTE;
+
+// ---- topics ------------------------------------------------------------------
+
+/**
+ * Topics an app can offer as toggles. `news` = every new post, `events` = every
+ * new event. Per-collection and per-calendar topics appear once there is more
+ * than one of them (a single one would just repeat news/events).
+ */
+export async function pushTopics(repo: ContentRepository): Promise<PushTopic[]> {
+  const collections = Object.entries(CONTENT.collections);
+  const out: PushTopic[] = [{ id: 'news', label: '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' });
+    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' })));
+  }
+  return out;
+}
+
+/** Every topic a device may subscribe to (listed or not). */
+export async function knownTopics(repo: ContentRepository): Promise<Set<string>> {
+  const set = new Set(['news', ...Object.keys(CONTENT.collections).map((k) => `collection:${k}`)]);
+  if (CALENDAR.enabled) {
+    set.add('events');
+    for (const c of await repo.listCalendars()) if (c.visibility === 'public') set.add(`calendar:${c.slug}`);
+  }
+  return set;
+}
+
+// ---- language ----------------------------------------------------------------
+
+/** The site's extra locale for a device language ("es-MX" → "es"), or null for the main language. */
+export function deviceLocale(raw: string): string | null {
+  if (!I18N.enabled || !raw) return null;
+  const want = raw.toLowerCase().replace('_', '-');
+  const match = I18N.locales.find((l) => l.toLowerCase() === want) ?? I18N.locales.find((l) => l.toLowerCase() === want.split('-')[0]);
+  return match && match !== I18N.defaultLocale ? match : null;
+}
+
+const STRINGS: Record<string, { startsIn: (m: number) => string; now: string }> = {
+  en: { startsIn: (m) => `Starts in ${m} min`, now: 'Starting now' },
+  es: { startsIn: (m) => `Empieza en ${m} min`, now: 'Empieza ahora' },
+  fr: { startsIn: (m) => `Commence dans ${m} min`, now: 'Commence maintenant' },
+  de: { startsIn: (m) => `Beginnt in ${m} Min.`, now: 'Beginnt jetzt' },
+  pt: { startsIn: (m) => `Começa em ${m} min`, now: 'Começa agora' },
+};
+export const pushStrings = (locale: string) => STRINGS[locale.split('-')[0]] ?? STRINGS.en;
+
+const clip = (s: string, n: number) => {
+  const t = s.replace(/\s+/g, ' ').trim();
+  return t.length > n ? `${t.slice(0, n - 1).trimEnd()}…` : t;
+};
+function when(start: number, allDay: boolean, tz: string, locale: string, timeOnly = false) {
+  const opts: Intl.DateTimeFormatOptions = timeOnly ? { hour: 'numeric', minute: '2-digit' }
+    : allDay ? { weekday: 'short', month: 'short', day: 'numeric' } : { weekday: 'short', month: 'short', day: 'numeric', hour: 'numeric', minute: '2-digit' };
+  try { return new Intl.DateTimeFormat(locale, { ...opts, timeZone: tz }).format(start); }
+  catch { return new Date(start).toISOString().slice(0, 16).replace('T', ' '); }
+}
+
+// ---- sending -----------------------------------------------------------------
+
+export interface Composed { title: string; body: string; url: string }
+export interface SendInput extends Composed {
+  /** topic ids, or ['*'] for every device */
+  audience: string[];
+  source: PushSource;
+  sourceKey?: string;
+  author?: string;
+  /** words for a device in an extra site language; null = use the main words */
+  localize?: (locale: string) => Composed | null;
+  data?: Record<string, unknown>;
+}
+export interface PushRunOptions {
+  /** site origin for absolute links; defaults to the Site URL setting */
+  origin?: string;
+  /** used when the Site URL setting is empty (e.g. the current request's origin) */
+  fallbackOrigin?: string;
+  now?: number;
+  locals?: unknown;
+  expo?: Partial<ExpoOptions>;
+}
+
+export function siteOriginOf(settings: Pick<Settings, 'siteUrl'>, fallback = ''): string {
+  const configured = settings.siteUrl.trim().replace(/\/+$/, '');
+  if (!configured) return fallback;
+  try { return new URL(configured.includes('://') ? configured : `https://${configured}`).origin; } catch { return fallback; }
+}
+
+/** Absolute URL (when the origin is known) and site path for a notification link. */
+export function notificationLink(raw: string, origin: string, locale: string | null): { url: string; path: string } {
+  if (!raw) return { url: '', path: '' };
+  const base = origin || 'https://site.invalid';
+  let u: URL;
+  try { u = new URL(raw, base); } catch { return { url: '', path: '' }; }
+  if (u.protocol !== 'https:' && u.protocol !== 'http:') return { url: '', path: '' };
+  if (u.origin !== new URL(base).origin) return { url: u.href, path: '' };
+  if (locale) u = new URL(localizedUrl(u.href, base, locale));
+  const path = `${u.pathname}${u.search}${u.hash}`;
+  return { url: origin ? u.href : path, path };
+}
+
+export async function sendNotification(repo: ContentRepository, input: SendInput, opts: PushRunOptions = {}): Promise<PushNotification> {
+  const now = opts.now ?? Date.now();
+  const origin = opts.origin ?? siteOriginOf(await repo.getSettings(), opts.fallbackOrigin);
+  const devices = await repo.push.audience(input.audience);
+  const n: PushNotification = {
+    id: crypto.randomUUID(), title: input.title, body: input.body, url: input.url, topics: input.audience,
+    source: input.source, sourceKey: input.sourceKey ?? '', status: 'sending', recipients: devices.length,
+    sent: 0, ok: 0, failed: 0, removed: 0, error: '', author: input.author ?? '', createdAt: now, finishedAt: null,
+  };
+  await repo.push.createNotification(n);
+  const words = new Map<string, Composed>();
+  const messages: ExpoMessage[] = devices.map((d) => {
+    const locale = deviceLocale(d.locale);
+    let c: Composed = input;
+    if (locale) {
+      if (!words.has(locale)) words.set(locale, input.localize?.(locale) ?? input);
+      c = words.get(locale)!;
+    }
+    const link = notificationLink(c.url, origin, locale);
+    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) },
+    };
+  });
+  const tickets = messages.length ? await sendMessages(messages, expoOptions(opts.locals, opts.expo)) : [];
+  const accepted: { id: string; notificationId: string; deviceId: string }[] = [];
+  const gone: string[] = [];
+  let error = '';
+  tickets.forEach((t, i) => {
+    if (t.status === 'ok') accepted.push({ id: t.id, notificationId: n.id, deviceId: devices[i].id });
+    else {
+      // an uninstalled app is routine (counted as removed); never echo tokens into the log
+      if (isGone(t)) gone.push(devices[i].id);
+      else error ||= t.message.replace(/Expo(?:nent)?PushToken\[[^\]]*\]/g, 'a device');
+    }
+  });
+  await repo.push.addTickets(accepted, now);
+  if (gone.length) await repo.push.deleteDevices(gone);
+  const done: PushNotification = { ...n, status: messages.length && !accepted.length ? 'failed' : 'sent', sent: messages.length,
+    ok: accepted.length, failed: messages.length - accepted.length, removed: gone.length, error: clip(error, 300), finishedAt: Date.now() };
+  await repo.push.finishNotification(n.id, done);
+  return done;
+}
+
+// ---- automatic notices ---------------------------------------------------------
+
+const listedCalendars = (calendars: Calendar[]) => new Map(calendars.map((c) => [c.id, c]));
+const inRule = (rule: string[], e: CalEvent) => rule.includes('*') || e.calendarIds.some((id) => rule.includes(id));
+function eventTopics(e: CalEvent, calendars: Map<string, Calendar>) {
+  return ['events', ...e.calendarIds.map((id) => calendars.get(id)).filter((c): c is Calendar => c?.visibility === 'public').map((c) => `calendar:${c.slug}`)];
+}
+const displayLocale = (settings: Settings) => settings.locale || I18N.defaultLocale || 'en';
+
+export function postNotice(post: Post, settings: Settings): SendInput {
+  const words = (p: Post): Composed => ({ title: clip(p.title, 120), body: clip(p.excerpt || p.seoDesc || settings.siteTitle, 240), url: collectionUrl(p.collection, p.slug) });
+  return { ...words(post), audience: ['news', `collection:${post.collection}`], source: 'post', sourceKey: `post:${post.id}`,
+    data: { kind: 'post', id: post.id, slug: post.slug, collection: post.collection }, localize: (l) => words(localizeDoc(post, l)) };
+}
+
+export function eventNotice(e: CalEvent, settings: Settings, calendars: Map<string, Calendar>, now: number, soon?: { start: number; allDay: boolean }): SendInput {
+  const tz = eventTimeZone(e, settings);
+  const next = soon ?? (() => {
+    const o = expandEvents([e], settings, { displayTz: tz, now, windowStartMs: now, windowEndMs: now + 400 * DAY })[0];
+    return o ? { start: o.start, allDay: o.allDay } : { start: e.startAt, allDay: e.allDay };
+  })();
+  const words = (ev: CalEvent, locale: string): Composed => {
+    const place = ev.location.name ? ` · ${ev.location.name}` : '';
+    let body: string;
+    if (soon) {
+      const s = pushStrings(locale);
+      const mins = Math.max(0, Math.round((soon.start - now) / MINUTE));
+      body = `${mins <= 1 ? s.now : s.startsIn(mins)} · ${when(soon.start, false, tz, locale, true)}${place}`;
+    } else body = `${when(next.start, next.allDay, tz, locale)}${place}`;
+    return { title: clip(ev.title, 120), body: clip(body, 240), url: eventUrl(ev.slug) };
+  };
+  return { ...words(e, displayLocale(settings)), audience: eventTopics(e, calendars), source: soon ? 'soon' : 'event',
+    sourceKey: soon ? `soon:${e.id}:${soon.start}` : `event:${e.id}`,
+    data: { kind: 'event', id: e.id, slug: e.slug, ...(soon ? { start: new Date(soon.start).toISOString() } : {}) },
+    localize: (l) => words(localizeDoc(e, l), l) };
+}
+
+/** Sends (or skips) queued first-publish notices. Returns how many were sent. */
+export async function processPushQueue(repo: ContentRepository, opts: PushRunOptions = {}): Promise<number> {
+  const now = opts.now ?? Date.now();
+  if (!PUSH.enabled) { await repo.push.skipPending(now); return 0; }
+  const rows = await repo.push.claimPending(now, now - STALE_AFTER, 10);
+  if (!rows.length) return 0;
+  const settings = await repo.getSettings();
+  const auto = settings.push.auto;
+  const calendars = CALENDAR.enabled ? listedCalendars(await repo.listCalendars()) : new Map<string, Calendar>();
+  const run = { ...opts, now, origin: opts.origin ?? siteOriginOf(settings, opts.fallbackOrigin) };
+  let sent = 0;
+  for (const row of rows) {
+    try {
+      let notice: SendInput | null = null;
+      if (row.kind === 'post') {
+        const post = await repo.getPost(row.docId);
+        if (post && post.status === 'published' && CONTENT.collections[post.collection] && auto.newPost.collections.includes(post.collection)) notice = postNotice(post, settings);
+      } else if (row.kind === 'event' && CALENDAR.enabled) {
+        const e = await repo.getEvent(row.docId);
+        if (e && !e.cancelled && eventIsListed(e, calendars) && inRule(auto.newEvent.calendars, e)) notice = eventNotice(e, settings, calendars, now);
+      }
+      if (!notice) { await repo.push.markQueue(row.key, 'skipped', null, now); continue; }
+      const n = await sendNotification(repo, notice, run);
+      await repo.push.markQueue(row.key, 'sent', n.id, now);
+      sent++;
+    } catch (e) {
+      console.error('acms push: automatic notification failed', e);
+      await repo.push.markQueue(row.key, 'failed', null, now).catch(() => {});
+    }
+  }
+  return sent;
+}
+
+/** "Starting soon": one notice per occurrence, `minutes` before it starts. */
+export async function sendStartingSoon(repo: ContentRepository, opts: PushRunOptions = {}): Promise<number> {
+  if (!PUSH.enabled || !CALENDAR.enabled) return 0;
+  const now = opts.now ?? Date.now();
+  const settings = await repo.getSettings();
+  const rule = settings.push.auto.startingSoon;
+  if (!rule.calendars.length) return 0;
+  const [all, events] = await Promise.all([repo.listCalendars(), repo.listPublishedEvents()]);
+  const calendars = listedCalendars(all);
+  const chosen = events.filter((e) => !e.cancelled && eventIsListed(e, calendars) && inRule(rule.calendars, e));
+  if (!chosen.length) return 0;
+  const lead = rule.minutes * MINUTE;
+  const occurrences = expandEvents(chosen, settings, { displayTz: settings.timezone || 'UTC', now, windowStartMs: now, windowEndMs: now + lead + 1 })
+    .filter((o) => !o.allDay && o.start > now && o.start - lead <= now);
+  const run = { ...opts, now, origin: opts.origin ?? siteOriginOf(settings, opts.fallbackOrigin) };
+  let sent = 0;
+  for (const o of occurrences) {
+    const key = `soon:${o.event.id}:${o.start}`;
+    if (!(await repo.push.claimKey(key, 'soon', o.event.id, o.start, now))) continue;
+    try {
+      const n = await sendNotification(repo, eventNotice(o.event, settings, calendars, now, { start: o.start, allDay: false }), run);
+      await repo.push.markQueue(key, 'sent', n.id, now);
+      sent++;
+    } catch (e) {
+      console.error('acms push: starting-soon notification failed', e);
+      await repo.push.markQueue(key, 'failed', null, now).catch(() => {});
+    }
+  }
+  return sent;
+}
+
+/** Reads Expo receipts for tickets older than RECEIPT_DELAY; prunes devices Expo says are gone. */
+export async function checkPushReceipts(repo: ContentRepository, opts: PushRunOptions = {}): Promise<number> {
+  const now = opts.now ?? Date.now();
+  const due = await repo.push.dueTickets(now - RECEIPT_DELAY, 1000);
+  if (!due.length) return 0;
+  const receipts = await fetchReceipts(due.map((t) => t.id), expoOptions(opts.locals, opts.expo));
+  const done: string[] = [];
+  const gone = new Set<string>();
+  const counts = new Map<string, { failed: number; removed: number }>();
+  for (const t of due) {
+    const r = receipts[t.id];
+    if (!r) { if (t.createdAt < now - DAY) done.push(t.id); continue; }
+    done.push(t.id);
+    if (r.status !== 'error') continue;
+    const c = counts.get(t.notificationId) ?? { failed: 0, removed: 0 };
+    c.failed++;
+    if (isGone(r)) { gone.add(t.deviceId); c.removed++; }
+    counts.set(t.notificationId, c);
+  }
+  if (gone.size) await repo.push.deleteDevices([...gone]);
+  if (counts.size) await repo.push.receiptFailed(counts);
+  await repo.push.deleteTickets(done);
+  return done.length;
+}
+
+/** Scheduler entry: queue, starting soon, receipts and retention. Disabled → queued notices are skipped. */
+export async function runPushJobs(repo: ContentRepository, opts: PushRunOptions = {}): Promise<number> {
+  const now = opts.now ?? Date.now();
+  if (!PUSH.enabled) { await repo.push.skipPending(now); return 0; }
+  const run = { ...opts, now };
+  let count = await processPushQueue(repo, run);
+  count += await sendStartingSoon(repo, run);
+  count += await checkPushReceipts(repo, run);
+  await repo.push.purge(now, now - PUSH.retentionDays * DAY);
+  return count;
+}