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

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;
+}

package/src/lib/push/store.ts

@@ -0,0 +1,144 @@
+import type { SqlDriver } from '../repo/sql';
+import type { PushDevice, PushNotification, PushQueueRow, PushStats, PushPlatform } from './types';
+
+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) };
+}
+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),
+    source: r.source as PushNotification['source'], sourceKey: String(r.source_key ?? ''), status: r.status as PushNotification['status'],
+    recipients: Number(r.recipients), sent: Number(r.sent), ok: Number(r.ok), failed: Number(r.failed), removed: Number(r.removed ?? 0),
+    error: String(r.error ?? ''), author: String(r.author ?? ''), createdAt: Number(r.created_at), finishedAt: r.finished_at == null ? null : Number(r.finished_at) };
+}
+// audience filter: ['*'] = every device, otherwise any shared topic
+function audienceWhere(topics: string[]): { sql: string; args: unknown[] } {
+  if (topics.includes('*')) return { sql: '1', args: [] };
+  if (!topics.length) return { sql: '0', args: [] };
+  return { sql: `EXISTS (SELECT 1 FROM json_each(push_devices.topics) t WHERE t.value IN (${topics.map(() => '?').join(',')}))`, args: topics };
+}
+
+// Storage for devices, the delivery log, Expo tickets and the automatic
+// notification queue. Shared by the D1 and libSQL adapters (plain SQLite).
+export class PushStore {
+  constructor(private driver: () => Promise<SqlDriver>) {}
+  private async all(sql: string, args: unknown[] = []) { return (await this.driver()).all(sql, args); }
+  private async run(sql: string, args: unknown[] = []) { return (await this.driver()).run(sql, args); }
+
+  // ---- 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 }> {
+    const topics = d.topics === undefined ? null : JSON.stringify(d.topics);
+    // 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(?,'[]'),?,?,?)
+      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]);
+    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]);
+    return rows[0] ? device(rows[0]) : null;
+  }
+  async getDevice(id: string) { const r = await this.all('SELECT * FROM push_devices WHERE id=?', [id]); return r[0] ? device(r[0]) : null; }
+  async deleteDevices(ids: string[]) {
+    for (let i = 0; i < ids.length; i += 90) {
+      const chunk = ids.slice(i, i + 90);
+      await this.run(`DELETE FROM push_devices WHERE id IN (${chunk.map(() => '?').join(',')})`, chunk);
+    }
+  }
+  async audience(topics: string[]): Promise<PushDevice[]> {
+    const w = audienceWhere(topics);
+    return (await this.all(`SELECT * FROM push_devices WHERE ${w.sql} ORDER BY created_at`, w.args)).map(device);
+  }
+  async countAudience(topics: string[]): Promise<number> {
+    const w = audienceWhere(topics);
+    return Number((await this.all(`SELECT COUNT(*) AS n FROM push_devices WHERE ${w.sql}`, w.args))[0]?.n ?? 0);
+  }
+  async stats(now: number): Promise<PushStats> {
+    const [totals, topics] = await Promise.all([
+      this.all(`SELECT COUNT(*) AS n, SUM(platform='ios') AS ios, SUM(platform='android') AS android, SUM(last_seen_at>=?) AS active FROM push_devices`, [now - 30 * 86400000]),
+      this.all(`SELECT t.value AS topic, COUNT(*) AS n FROM push_devices, json_each(push_devices.topics) t GROUP BY t.value`),
+    ]);
+    const t = totals[0] ?? {};
+    return { devices: Number(t.n ?? 0), platforms: { ios: Number(t.ios ?? 0), android: Number(t.android ?? 0) }, active30: Number(t.active ?? 0),
+      topics: Object.fromEntries(topics.map((r) => [String(r.topic), Number(r.n)])) };
+  }
+
+  // ---- 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)
+      VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`, [n.id, n.title, n.body, n.url, JSON.stringify(n.topics), n.source, n.sourceKey, n.status,
+      n.recipients, n.sent, n.ok, n.failed, n.removed, n.error, n.author, n.createdAt, n.finishedAt]);
+  }
+  async finishNotification(id: string, d: Pick<PushNotification, 'status' | 'sent' | 'ok' | 'failed' | 'removed' | 'error' | 'finishedAt'>) {
+    await this.run('UPDATE push_notifications SET status=?,sent=?,ok=?,failed=?,removed=?,error=?,finished_at=? WHERE id=?',
+      [d.status, d.sent, d.ok, d.failed, d.removed, d.error, d.finishedAt, id]);
+  }
+  /** a later receipt turned an accepted ticket into a failure */
+  async receiptFailed(counts: Map<string, { failed: number; removed: number }>) {
+    for (const [id, c] of counts) await this.run('UPDATE push_notifications SET ok=MAX(ok-?,0), failed=failed+?, removed=removed+? WHERE id=?', [c.failed, c.failed, c.removed, id]);
+  }
+  async listNotifications(limit = 50) { return (await this.all('SELECT * FROM push_notifications ORDER BY created_at DESC LIMIT ?', [limit])).map(notification); }
+  async getNotification(id: string) { const r = await this.all('SELECT * FROM push_notifications WHERE id=?', [id]); return r[0] ? notification(r[0]) : null; }
+
+  // ---- Expo tickets awaiting receipts ----
+  async addTickets(rows: { id: string; notificationId: string; deviceId: string }[], now: number) {
+    // D1 allows 100 bound parameters per statement: 4 per row
+    for (let i = 0; i < rows.length; i += 25) {
+      const chunk = rows.slice(i, i + 25);
+      await this.run(`INSERT OR IGNORE INTO push_tickets (id,notification_id,device_id,created_at) VALUES ${chunk.map(() => '(?,?,?,?)').join(',')}`,
+        chunk.flatMap((t) => [t.id, t.notificationId, t.deviceId, now]));
+    }
+  }
+  async dueTickets(before: number, limit: number) {
+    return (await this.all('SELECT * FROM push_tickets WHERE created_at<=? ORDER BY created_at LIMIT ?', [before, limit]))
+      .map((r) => ({ id: String(r.id), notificationId: String(r.notification_id), deviceId: String(r.device_id), createdAt: Number(r.created_at) }));
+  }
+  async deleteTickets(ids: string[]) {
+    for (let i = 0; i < ids.length; i += 90) {
+      const chunk = ids.slice(i, i + 90);
+      await this.run(`DELETE FROM push_tickets WHERE id IN (${chunk.map(() => '?').join(',')})`, chunk);
+    }
+  }
+
+  // ---- automatic notification queue ----
+  /** Claims up to `limit` pending rows (status → sending); rows queued before `staleBefore` are skipped instead. */
+  async claimPending(now: number, staleBefore: number, limit: number): Promise<PushQueueRow[]> {
+    await this.run(`UPDATE push_queue SET status='skipped', updated_at=? WHERE status='pending' AND created_at<?`, [now, staleBefore]);
+    const due = await this.all(`SELECT key FROM push_queue WHERE status='pending' ORDER BY created_at LIMIT ?`, [limit]);
+    const out: PushQueueRow[] = [];
+    for (const { key } of due) {
+      const r = await this.all(`UPDATE push_queue SET status='sending', updated_at=? WHERE key=? AND status='pending' RETURNING *`, [now, key]);
+      if (r[0]) out.push({ key: String(r[0].key), kind: r[0].kind as PushQueueRow['kind'], docId: String(r[0].doc_id), occurrence: r[0].occurrence == null ? null : Number(r[0].occurrence), status: 'sending', createdAt: Number(r[0].created_at) });
+    }
+    return out;
+  }
+  /** Inserts a new key as `sending`; false when it already exists (dedupe for "starting soon"). */
+  async claimKey(key: string, kind: PushQueueRow['kind'], docId: string, occurrence: number | null, now: number): Promise<boolean> {
+    const r = await this.all(`INSERT INTO push_queue (key,kind,doc_id,occurrence,status,notification_id,created_at,updated_at)
+      VALUES (?,?,?,?,'sending',NULL,?,?) ON CONFLICT(key) DO NOTHING RETURNING key`, [key, kind, docId, occurrence, now, now]);
+    return r.length > 0;
+  }
+  async markQueue(key: string, status: 'sent' | 'skipped' | 'failed', notificationId: string | null, now: number) {
+    await this.run('UPDATE push_queue SET status=?, notification_id=?, updated_at=? WHERE key=?', [status, notificationId, now, key]);
+  }
+  async skipPending(now: number) { await this.run(`UPDATE push_queue SET status='skipped', updated_at=? WHERE status='pending'`, [now]); }
+  async queueStatus(key: string) { return (await this.all('SELECT status FROM push_queue WHERE key=?', [key]))[0]?.status as string | undefined; }
+
+  // ---- retention ----
+  /** Devices not seen since `devicesBefore`, log rows older than a year, expired tickets and old occurrence keys. */
+  async purge(now: number, devicesBefore: number): Promise<number> {
+    const gone = await this.all('DELETE FROM push_devices WHERE last_seen_at<? RETURNING id', [devicesBefore]);
+    await (await this.driver()).batch([
+      { sql: 'DELETE FROM push_notifications WHERE created_at<?', args: [now - 365 * 86400000] },
+      { sql: 'DELETE FROM push_tickets WHERE created_at<?', args: [now - 86400000] },
+      { sql: `DELETE FROM push_queue WHERE kind='soon' AND updated_at<?`, args: [now - 30 * 86400000] },
+    ]);
+    return gone.length;
+  }
+}

package/src/lib/push/types.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+
+// '*' in a calendars list = every public event
+const keys = z.array(z.string().min(1).max(200)).max(100);
+export const PushAuto = z.object({
+  /** collection keys whose first publish sends a notification */
+  newPost: z.object({ collections: keys.default([]) }).default({}),
+  /** calendar ids (or '*') whose events notify on first publish */
+  newEvent: z.object({ calendars: keys.default([]) }).default({}),
+  /** "starting soon" reminders, sent `minutes` before each occurrence */
+  startingSoon: z.object({ calendars: keys.default([]), minutes: z.number().int().min(5).max(1440).default(30) }).default({}),
+});
+export type PushAuto = z.infer<typeof PushAuto>;
+export const PushSettings = z.object({ auto: PushAuto.default({}) });
+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[];
+  createdAt: number; updatedAt: number; lastSeenAt: number;
+}
+export type PushSource = 'manual' | 'post' | 'event' | 'soon';
+export interface PushNotification {
+  id: string; title: string; body: string; url: string;
+  /** ['*'] = everyone */
+  topics: string[];
+  source: PushSource; sourceKey: string;
+  status: 'sending' | 'sent' | 'failed';
+  recipients: number; sent: number; ok: number; failed: number;
+  /** devices removed because Expo said they are no longer registered */
+  removed: number;
+  error: string; author: string; createdAt: number; finishedAt: number | null;
+}
+export interface PushQueueRow { key: string; kind: 'post' | 'event' | 'soon'; docId: string; occurrence: number | null; status: string; createdAt: number }
+export interface PushTopic { id: string; label: string; kind: 'general' | 'collection' | 'calendar' }
+export interface PushStats {
+  devices: number;
+  platforms: Record<PushPlatform, number>;
+  /** devices per topic id */
+  topics: Record<string, number>;
+  /** devices whose app checked in during the last 30 days */
+  active30: number;
+}

package/src/lib/repo/migrations.ts

@@ -2,6 +2,9 @@ import { LIVE_MIGRATION } from '../live/migration';
 import { IMPORT_MIGRATION } from '../import/migration';
 import { EMAIL_MIGRATION } from '../email/migration';
 import { WEBHOOK_MIGRATION } from '../webhook-sql';
+import { PUSH_MIGRATION } from '../push/migration';
+import { EDITOR_MIGRATION, EDITOR_GRACE_MIGRATION } from '../editor/migration';
+import { CALENDAR_SETTINGS_MIGRATION, ROOM_HOLD_MIGRATION } from '../calendar/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.
@@ -501,6 +504,17 @@ export const MIGRATIONS: Migration[] = [
   WEBHOOK_MIGRATION,
   LIVE_MIGRATION,
   IMPORT_MIGRATION,
+  // translations: per-language words for posts, pages and events (facts stay shared)
+  { version: 36, statements: [
+    `ALTER TABLE posts ADD COLUMN translations TEXT NOT NULL DEFAULT '{}'`,
+    `ALTER TABLE pages ADD COLUMN translations TEXT NOT NULL DEFAULT '{}'`,
+    `ALTER TABLE events ADD COLUMN translations TEXT NOT NULL DEFAULT '{}'`,
+  ] },
+  PUSH_MIGRATION,
+  EDITOR_MIGRATION,
+  EDITOR_GRACE_MIGRATION,
+  CALENDAR_SETTINGS_MIGRATION,
+  ROOM_HOLD_MIGRATION,
 ];
 
 export const LATEST_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;