@acms-subir/core 0.3.54 → 0.3.55

package/src/lib/calendar/google/map.ts

@@ -0,0 +1,543 @@
+// Site event ⇄ Google event, as pure functions (no repo, no fetch): the
+// fields the sync owns on each side, their hashes, and the bodies written to
+// either side. Everything else (Google's guests, reminders, colours,
+// attachments and conference data; the site's hosts, RSVPs, pictures,
+// buttons, custom fields and other tags) is never read or written.
+//
+// Each pair remembers both sides' hashes as last agreed (GcalItem.site /
+// .google). A field changed on a side when its hash moved; that is what gets
+// copied over, field by field. The two sides never have to be equal: at the
+// first match a Spanish Google title and an English site title are recorded
+// as they are (Q18), and later only an edit on one side copies over.
+//
+// Field names (hash keys): title, when, repeat, place, desc, link (site:
+// the map/meeting URL and page link in Google's description), status (site:
+// cancelled), rule:<prefix> (a title prefix ⇄ a tag), date:<key> (one date
+// of a series: cancelled, or at another time or place).
+import { createHash } from 'node:crypto';
+import type { CalEvent, Settings } from '../../schema';
+import { EventLocation, hasTag } from '../../schema';
+import { addWallDays, eventInstants, eventTimeZone, expandEvents, findOccurrence, formatWall, isValidTimeZone, locationLine, normalizeEventTimes, parseWall } from '../events';
+import { tzParts, zonedToUtc } from '../ics';
+import { cleanRrule, describeRepeat, rruleMap } from '../rrule';
+import type { GcalLink, GoogleEvent, GoogleTime, Hashes, PrefixRule } from './types';
+
+const DAY = 86_400_000;
+const pad = (n: number) => String(n).padStart(2, '0');
+
+/** The internal tag on booked appointments from Google booking pages (Q16): never shown publicly. */
+export const BOOKING_TAG = '#google-booking';
+
+/** The few words the sync writes, in the site's main language (Q9). */
+export interface SyncWords { cancelled: string; details: string; link: string; booked: string; untitled: string }
+const WORDS: Record<string, SyncWords> = {
+  en: { cancelled: 'Cancelled: ', details: 'Details: ', link: 'Link: ', booked: 'Booked', untitled: 'Untitled event' },
+  es: { cancelled: 'Cancelado: ', details: 'Detalles: ', link: 'Enlace: ', booked: 'Reservado', untitled: 'Evento sin título' },
+};
+export const syncWords = (lang: string): SyncWords => WORDS[(lang || 'en').toLowerCase().split('-')[0]] ?? WORDS.en;
+// every language's "Cancelled: ", so a Google title reads the same whichever one wrote it
+const CANCELLED = [...new Set(Object.values(WORDS).map((w) => w.cancelled.trim().toLowerCase()))];
+
+// ---- the fields ----
+
+/** wall-clock in the event's zone, like CalEvent; all-day: dates, end inclusive, tz '' */
+export interface When { allDay: boolean; start: string; end: string; tz: string }
+export interface Repeat { rrule: string; exdates: string[] }
+/** one date of a series that isn't as the series has it */
+export type DateState = 'cancelled' | { start: string; end: string; place: string };
+export interface Fields {
+  title: string;
+  when: When;
+  repeat: Repeat;
+  place: string;
+  desc: string;
+  /** rule prefix → whether it applies (site: has the tag; Google: the title starts with it) */
+  rules: Record<string, boolean>;
+  dates: Record<string, DateState>;
+}
+export interface SiteFields extends Fields { status: boolean; link: { url: string; page: string } }
+
+export interface MapContext {
+  settings: Pick<Settings, 'timezone'>;
+  /** the site origin (the page link in Google's description) */
+  origin: string;
+  /** the event page path for a slug (lib/calendar/config.ts eventUrl) */
+  pagePath: (slug: string) => string;
+  words: SyncWords;
+}
+
+const titleKey = (s: string) => s.replace(/\s+/g, ' ').trim();
+export const hasPrefix = (title: string, prefix: string) => title.trimStart().toLowerCase().startsWith(prefix.trim().toLowerCase());
+
+/** A Google title without the "Cancelled: " the site puts in front of cancelled events (Q7). */
+export function stripCancelled(title: string): string {
+  const t = title.trimStart();
+  const hit = CANCELLED.find((c) => t.toLowerCase().startsWith(c));
+  return titleKey(hit ? t.slice(hit.length) : t);
+}
+
+/** For matching and clash checks only: no "Cancelled: ", no rule prefixes, any case and spacing. Never written anywhere. */
+export function comparableTitle(title: string, rules: PrefixRule[]): string {
+  let t = stripCancelled(title);
+  for (const r of rules) if (hasPrefix(t, r.prefix)) t = t.trimStart().slice(r.prefix.trim().length);
+  return titleKey(t).toLowerCase();
+}
+
+/**
+ * Google's own title, adjusted for what changed on the site without its title
+ * changing: "Cancelled: " added or removed, and the prefixes of these rules
+ * added or removed to match the site's tags. A Spanish Google title stays
+ * Spanish (Q18): only a title edit copies the site's title over.
+ */
+export function adjustTitle(googleSummary: string, e: Pick<CalEvent, 'tags' | 'cancelled'>, rules: PrefixRule[], words: SyncWords): string {
+  let t = stripCancelled(googleSummary);
+  for (const r of rules) {
+    const has = hasPrefix(t, r.prefix);
+    if (hasTag(e.tags, r.tag) && !has) t = `${r.prefix.trim()} ${t}`;
+    if (!hasTag(e.tags, r.tag) && has) t = titleKey(t.trimStart().slice(r.prefix.trim().length));
+  }
+  t = t || words.untitled;
+  return e.cancelled ? `${words.cancelled}${t}` : t;
+}
+
+/** The site title with each rule's prefix whose tag the event has (kept when it's there already), and "Cancelled: " for a cancelled event. */
+export function googleTitle(e: Pick<CalEvent, 'title' | 'tags' | 'cancelled'>, rules: PrefixRule[], words: SyncWords): string {
+  let t = titleKey(e.title) || words.untitled;
+  for (const r of [...rules].reverse()) if (hasTag(e.tags, r.tag) && !hasPrefix(t, r.prefix)) t = `${r.prefix.trim()} ${t}`;
+  return e.cancelled ? `${words.cancelled}${t}` : t;
+}
+
+// ---- text ----
+
+const ENTITIES: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', '#39': "'" };
+const decode = (s: string) => s.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+\d*|#39);/gi, (m, e: string) => {
+  if (e[0] === '#') { const n = e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : Number(e.slice(1)); return n > 0 && n <= 0x10ffff ? String.fromCodePoint(n) : ' '; }
+  return ENTITIES[e.toLowerCase()] ?? m;
+});
+
+/** Plain text with paragraphs from a site body or a Google description (which may be HTML after an edit in Google). */
+export function plainText(html: string): string {
+  if (!html) return '';
+  let s = html.replace(/\r\n?/g, '\n');
+  if (/<[a-z/!][^>]*>/i.test(s)) {
+    s = s.replace(/\n/g, ' ')
+      .replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1>/gi, '')
+      .replace(/<br\s*\/?>/gi, '\n')
+      .replace(/<li\b[^>]*>/gi, '\n• ')
+      .replace(/<\/(p|div|h[1-6]|blockquote|pre|ul|ol|table|tr)>/gi, '\n\n')
+      .replace(/<[^>]*>/g, '');
+  }
+  return decode(s).split('\n').map((l) => l.replace(/[ \t ]+/g, ' ').trim()).join('\n').replace(/\n{3,}/g, '\n\n').trim();
+}
+
+const escHtml = (s: string) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+/** Plain text as simple paragraphs (how .ics imports bring descriptions in). */
+export const paragraphsHtml = (text: string) =>
+  text.split(/\n{2,}/).map((p) => p.trim()).filter(Boolean).map((p) => `<p>${escHtml(p).replace(/\n/g, '<br>')}</p>`).join('');
+
+/** What Google gets once the site's description wins (Q8): its text, the map or meeting link, and the event page. */
+export function googleDescription(text: string, link: { url: string; page: string }, words: SyncWords): string {
+  return [text.trim(), link.url ? `${words.link}${link.url}` : '', link.page ? `${words.details}${link.page}` : ''].filter(Boolean).join('\n\n');
+}
+
+// ---- times ----
+
+const isZone = (tz: string | undefined): tz is string => !!tz && isValidTimeZone(tz);
+const wallOfMs = (ms: number, tz: string) => { const p = tzParts(ms, tz); return `${p.y}-${pad(p.m)}-${pad(p.d)}T${pad(p.hh)}:${pad(p.mm)}`; };
+const wallToMs = (wall: string, tz: string) => { const w = parseWall(wall)!; return zonedToUtc(w.y, w.m, w.d, w.dateOnly ? 0 : w.hh, w.dateOnly ? 0 : w.mm, 0, tz); };
+
+/** A Google start/end as wall-clock in `tz` (dates stay dates), or null when unusable. */
+export function wallFromGoogle(t: GoogleTime | undefined, tz: string): string | null {
+  if (!t) return null;
+  if (t.date) return parseWall(t.date)?.dateOnly ? t.date : null;
+  if (!t.dateTime) return null;
+  // an offset (or Z) is an instant; without one it's a wall time in its own zone
+  if (/(?:Z|[+-]\d{2}:?\d{2})$/i.test(t.dateTime)) {
+    const ms = Date.parse(t.dateTime);
+    return Number.isFinite(ms) ? wallOfMs(ms, tz) : null;
+  }
+  const w = parseWall(t.dateTime.slice(0, 16));
+  if (!w) return null;
+  const own = isZone(t.timeZone) ? t.timeZone : tz;
+  return own === tz ? formatWall(w) : wallOfMs(wallToMs(formatWall(w), own), tz);
+}
+
+/** The event's zone in Google: its own, else the Google calendar's, else the site's. */
+export const googleZone = (g: Pick<GoogleEvent, 'start'>, link: Pick<GcalLink, 'googleTz'>, settings: Pick<Settings, 'timezone'>) =>
+  [g.start?.timeZone, link.googleTz, settings.timezone, 'UTC'].find(isZone)!;
+
+/**
+ * start/end for Google: dates (end exclusive) or wall times with their zone
+ * (no offset needed; recurring events need the zone). A patch merges start
+ * and end, so it clears the other form (an event switching to or from all day).
+ */
+export function googleTimes(when: When, patch = false): { start: Record<string, string | null>; end: Record<string, string | null> } {
+  if (when.allDay) {
+    const end = addWallDays(parseWall(when.end || when.start)!, 1);
+    const clear: Record<string, null> = patch ? { dateTime: null, timeZone: null } : {};
+    return { start: { date: when.start, ...clear }, end: { date: formatWall({ ...end, dateOnly: true }), ...clear } };
+  }
+  const clear: Record<string, null> = patch ? { date: null } : {};
+  return { start: { dateTime: `${when.start}:00`, timeZone: when.tz, ...clear }, end: { dateTime: `${when.end}:00`, timeZone: when.tz, ...clear } };
+}
+
+function whenFromGoogle(g: GoogleEvent, tz: string): When | null {
+  const s = wallFromGoogle(g.start, tz);
+  if (!s) return null;
+  if (g.start?.date) {
+    const endEx = g.end?.date ? parseWall(g.end.date) : null;
+    const end = endEx ? formatWall({ ...addWallDays(endEx, -1), dateOnly: true }) : s;
+    return { allDay: true, ...normalizeEventTimes({ start: s, end: end < s ? s : end, allDay: true }), tz: '' };
+  }
+  const e = wallFromGoogle(g.end, tz) ?? s;
+  return { allDay: false, ...normalizeEventTimes({ start: s, end: e, allDay: false }), tz };
+}
+
+// ---- recurrence ----
+
+const icsDate = (wall: string) => wall.replace(/[-:]/g, '').replace(/^(\d{8})T(\d{4})$/, '$1T$200');
+
+/**
+ * The site's rule as Google wants it: RRULE plus EXDATE in the event's zone.
+ * A timed series' UNTIL must be UTC when the start has a zone (RFC 5545), so
+ * a date or floating UNTIL is read in the event's zone (a date counts its
+ * whole day, as the site's expander does); an all-day series keeps a date.
+ */
+export function googleRecurrence(repeat: Repeat, when: When): string[] {
+  if (!repeat.rrule) return [];
+  const parts = rruleMap(repeat.rrule);
+  let rule = repeat.rrule;
+  if (parts.UNTIL) {
+    const u = parts.UNTIL;
+    let until = u;
+    if (when.allDay) until = u.slice(0, 8);
+    else if (!u.endsWith('Z')) {
+      const wall = `${u.slice(0, 4)}-${u.slice(4, 6)}-${u.slice(6, 8)}T${u.length > 8 ? `${u.slice(9, 11)}:${u.slice(11, 13)}` : '23:59'}`;
+      const ms = wallToMs(wall, when.tz) + (u.length > 8 ? 0 : 59_000);
+      const d = new Date(ms);
+      until = `${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}T${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}${pad(d.getUTCSeconds())}Z`;
+    }
+    rule = rule.replace(/UNTIL=[^;]*/, `UNTIL=${until}`);
+  }
+  const out = [`RRULE:${rule}`];
+  if (repeat.exdates.length) out.push(when.allDay ? `EXDATE;VALUE=DATE:${repeat.exdates.map((d) => icsDate(d.slice(0, 10))).join(',')}` : `EXDATE;TZID=${when.tz}:${repeat.exdates.map(icsDate).join(',')}`);
+  return out;
+}
+
+// an ICS date or date-time value → a wall key in `tz` (dates stay dates)
+function keyFromIcs(value: string, tzid: string | undefined, tz: string, allDay: boolean): string | null {
+  const m = /^(\d{4})(\d{2})(\d{2})(?:T(\d{2})(\d{2})(\d{2})?(Z)?)?$/.exec(value.trim());
+  if (!m) return null;
+  const date = `${m[1]}-${m[2]}-${m[3]}`;
+  if (!m[4]) return allDay ? date : null;
+  const wall = `${date}T${m[4]}:${m[5]}`;
+  if (allDay) return date;
+  if (m[7]) return wallOfMs(Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], Number(m[6] ?? 0)), tz);
+  const own = isZone(tzid) ? tzid : tz;
+  return own === tz ? wall : wallOfMs(wallToMs(wall, own), tz);
+}
+
+/** Google's recurrence lines in site terms; `unsupported` lists what the site can't hold (RDATE, rule parts it drops). */
+export function repeatFromGoogle(lines: string[] | undefined, tz: string, allDay: boolean): Repeat & { unsupported: string[] } {
+  let rrule = '';
+  const exdates = new Set<string>();
+  const unsupported: string[] = [];
+  for (const line of lines ?? []) {
+    const colon = line.indexOf(':');
+    if (colon < 0) continue;
+    const head = line.slice(0, colon).toUpperCase(), value = line.slice(colon + 1);
+    const name = head.split(';')[0];
+    if (name === 'RRULE') {
+      rrule = cleanRrule(value);
+      const dropped = Object.keys(rruleMap(value)).filter((k) => !Object.hasOwn(rruleMap(rrule), k));
+      if (!rrule) unsupported.push('repeat rule'); else if (dropped.length) unsupported.push(`rule parts ${dropped.join(', ')}`);
+    } else if (name === 'EXDATE') {
+      const tzid = /;TZID=([^;:]+)/i.exec(line.slice(0, colon))?.[1];
+      for (const v of value.split(',')) { const k = keyFromIcs(v, tzid, tz, allDay); if (k) exdates.add(k); }
+    } else unsupported.push(name);
+  }
+  return { rrule, exdates: rrule ? [...exdates].sort() : [], unsupported };
+}
+
+// ---- each side's fields ----
+
+/** The site event's synced fields. A series' changed dates count from the link's start date on. */
+export function siteFields(e: CalEvent, link: Pick<GcalLink, 'rules' | 'startDate'>, ctx: MapContext): SiteFields {
+  const tz = eventTimeZone(e, ctx.settings);
+  const when: When = e.allDay ? { allDay: true, start: e.start, end: e.end || e.start, tz: '' } : { allDay: false, start: e.start, end: e.end || e.start, tz };
+  const repeat: Repeat = e.rrule ? { rrule: cleanRrule(e.rrule), exdates: [...new Set(e.exdates)].sort() } : { rrule: '', exdates: [] };
+  const place = locationLine(e.location);
+  const dates: Record<string, DateState> = {};
+  if (e.rrule) {
+    const series = { ...e, movedDates: {} };
+    for (const key of e.cancelledDates) if (key >= link.startDate && findOccurrence(series, key, ctx.settings)) dates[key] = 'cancelled';
+    for (const [key, m] of Object.entries(e.movedDates)) {
+      if (key < link.startDate || dates[key] || !findOccurrence(series, key, ctx.settings)) continue;
+      dates[key] = { start: m.start, end: m.end, place: m.location ? locationLine(m.location) : place };
+    }
+  }
+  return {
+    title: titleKey(e.title), when, repeat, place, desc: plainText(e.bodyHtml),
+    rules: Object.fromEntries(link.rules.map((r) => [r.prefix, hasTag(e.tags, r.tag)])),
+    dates, status: e.cancelled,
+    link: { url: e.location.url.trim(), page: e.slug ? `${ctx.origin}${ctx.pagePath(e.slug)}` : '' },
+  };
+}
+
+/**
+ * A Google event's synced fields in site terms (its dates come separately,
+ * from its instances), or null when it has no usable time. `inZone` reads the
+ * times in another zone (the site event's, so single-date keys match the site's).
+ */
+export function googleFields(g: GoogleEvent, link: Pick<GcalLink, 'rules' | 'googleTz'>, settings: Pick<Settings, 'timezone'>, inZone?: string): (Fields & { unsupported: string[] }) | null {
+  const tz = inZone && isZone(inZone) ? inZone : googleZone(g, link, settings);
+  const when = whenFromGoogle(g, tz);
+  if (!when) return null;
+  const repeat = repeatFromGoogle(g.recurrence, tz, when.allDay);
+  const title = stripCancelled(g.summary ?? '');
+  return {
+    title, when, repeat: { rrule: repeat.rrule, exdates: repeat.exdates }, place: (g.location ?? '').trim(), desc: plainText(g.description ?? ''),
+    rules: Object.fromEntries(link.rules.map((r) => [r.prefix, hasPrefix(title, r.prefix)])), dates: {}, unsupported: repeat.unsupported,
+  };
+}
+
+/** The occurrence key a Google instance stands for (its original start, in the series' zone), or null. */
+export function instanceKey(i: Pick<GoogleEvent, 'originalStartTime'>, master: When): string | null {
+  const t = i.originalStartTime;
+  if (!t) return null;
+  if (master.allDay) return t.date ?? (t.dateTime ? t.dateTime.slice(0, 10) : null);
+  return wallFromGoogle(t, master.tz);
+}
+
+/** One Google instance as a date state: cancelled, moved (another time or place), or 'none' (as the series has it). */
+export function instanceState(i: GoogleEvent, master: Fields, key: string): DateState | 'none' {
+  if (i.status === 'cancelled') return 'cancelled';
+  const own = whenFromGoogle(i, master.when.tz || 'UTC');
+  if (!own || own.allDay !== master.when.allDay) return 'none';
+  const place = i.location === undefined ? master.place : i.location.trim();
+  const usual = seriesDate(master.when, key);
+  if (own.start === usual.start && own.end === usual.end && place === master.place) return 'none';
+  return { start: own.start, end: own.end, place };
+}
+
+/** Where a series puts one date: its key and the series' length. */
+export function seriesDate(when: When, key: string): { start: string; end: string } {
+  const s = parseWall(when.start)!, e = parseWall(when.end) ?? s, k = parseWall(key);
+  if (!k) return { start: key, end: key };
+  const minutes = (Date.UTC(e.y, e.m - 1, e.d, e.hh, e.mm) - Date.UTC(s.y, s.m - 1, s.d, s.hh, s.mm)) / 60_000;
+  const end = new Date(Date.UTC(k.y, k.m - 1, k.d, k.hh, k.mm) + minutes * 60_000);
+  const w = { y: end.getUTCFullYear(), m: end.getUTCMonth() + 1, d: end.getUTCDate(), hh: end.getUTCHours(), mm: end.getUTCMinutes(), dateOnly: when.allDay };
+  return { start: key, end: formatWall(w) };
+}
+
+// ---- hashes ----
+
+export const fieldHash = (value: unknown) => createHash('sha256').update(JSON.stringify(value)).digest('hex').slice(0, 16);
+
+/** Every field's hash; date keys only for dates that aren't as the series has them. */
+export function fieldHashes(f: Fields & Partial<Pick<SiteFields, 'status' | 'link'>>): Hashes {
+  const out: Hashes = { title: fieldHash(f.title), when: fieldHash(f.when), repeat: fieldHash(f.repeat), place: fieldHash(f.place), desc: fieldHash(f.desc) };
+  if (f.status !== undefined) out.status = fieldHash(f.status);
+  if (f.link !== undefined) out.link = fieldHash(f.link);
+  for (const [prefix, on] of Object.entries(f.rules)) out[`rule:${prefix}`] = fieldHash(on);
+  for (const [key, d] of Object.entries(f.dates)) out[`date:${key}`] = fieldHash(d);
+  return out;
+}
+export const NONE = fieldHash('none');
+export const dateHash = (d: DateState | 'none') => d === 'none' ? NONE : fieldHash(d);
+
+/** The fields whose hash moved since the pair last agreed (a date missing on one side counts as "as the series has it"). */
+export function changed(current: Hashes, agreed: Hashes, only?: (name: string) => boolean): string[] {
+  const names = new Set([...Object.keys(current), ...Object.keys(agreed)]);
+  return [...names].filter((n) => (!only || only(n)) && (current[n] ?? (n.startsWith('date:') ? NONE : '')) !== (agreed[n] ?? (n.startsWith('date:') ? NONE : ''))).sort();
+}
+
+/** Two sides' values that mean the same (so both changing a field to these isn't a clash). */
+export function sameValue(name: string, site: Fields, google: Fields, rules: PrefixRule[]): boolean {
+  if (name === 'title') return comparableTitle(site.title, rules) === comparableTitle(google.title, rules);
+  if (name === 'when') return JSON.stringify(site.when) === JSON.stringify(google.when);
+  if (name === 'repeat') return JSON.stringify(site.repeat) === JSON.stringify(google.repeat);
+  if (name === 'place') return site.place.toLowerCase() === google.place.toLowerCase();
+  if (name === 'desc') return site.desc === google.desc;
+  if (name.startsWith('rule:')) return site.rules[name.slice(5)] === google.rules[name.slice(5)];
+  return false;
+}
+
+// ---- which link an event goes to ----
+
+/**
+ * Whether this link carries the event: published, in the link's site
+ * calendar, and holding one of the link's rooms (a link without rooms carries
+ * its whole calendar; "no room" also carries the calendar's events that hold
+ * none). Booked appointments are Google's and never go out as new copies.
+ */
+export function linkCarries(e: Pick<CalEvent, 'status' | 'calendarIds' | 'roomHold' | 'tags'>, link: Pick<GcalLink, 'calendarId' | 'roomIds' | 'noRoom'>): boolean {
+  if (e.status !== 'published' || !e.calendarIds.includes(link.calendarId)) return false;
+  if (!link.roomIds.length) return true;
+  const rooms = e.roomHold.resourceIds;
+  return rooms.some((r) => link.roomIds.includes(r)) || (link.noRoom && rooms.length === 0);
+}
+
+/** The link's start date as an instant (midnight in the site's zone). */
+export const windowStart = (link: Pick<GcalLink, 'startDate'>, settings: Pick<Settings, 'timezone'>) => wallToMs(link.startDate, settings.timezone || 'UTC');
+
+/** Within the link's range: ends on or after its start date, or a series with a date from then on (Q11). */
+export function inWindow(e: Pick<CalEvent, 'endAt' | 'rrule'> & Partial<CalEvent>, startMs: number, settings: Pick<Settings, 'timezone'>): boolean {
+  if (e.endAt >= startMs) return true;
+  if (!e.rrule) return false;
+  return expandEvents([e as CalEvent], settings, { displayTz: settings.timezone || 'UTC', now: startMs, windowStartMs: startMs, windowEndMs: startMs + 800 * DAY }).length > 0;
+}
+
+/** A Google event's fields as an unsaved site event, for range checks and matching. */
+export function asSiteEvent(f: Fields, settings: Pick<Settings, 'timezone'>, id = 'google'): CalEvent {
+  const timezone = f.when.allDay || f.when.tz === (settings.timezone || 'UTC') ? '' : f.when.tz;
+  const tz = eventTimeZone({ timezone }, settings);
+  const { startAt, endAt } = eventInstants({ start: f.when.start, end: f.when.end, allDay: f.when.allDay }, tz);
+  return {
+    id, slug: '', title: f.title, bodyJson: '', bodyHtml: '', excerpt: '', cover: '', coverAlt: '', seoTitle: '', seoDesc: '', status: 'published', featured: false,
+    tags: [], template: '', start: f.when.start, end: f.when.end, allDay: f.when.allDay, timezone, rrule: f.repeat.rrule, exdates: f.repeat.exdates, cancelled: false,
+    cancelledDates: [], movedDates: {}, location: EventLocation.parse({ name: f.place }), cta: { label: '', href: '', style: 'primary' }, calendarIds: [], fields: {},
+    sourceUid: '', rsvp: { enabled: false, capacity: 0, autoConfirm: true, maxSeats: 4, closesAt: null, closeBefore: 0, notifyStaff: true, waitlist: false },
+    roomHold: { resourceIds: [], span: 'event', before: 0, after: 0, whileDraft: false, keep: [] }, hostIds: [], request: null, startAt, endAt,
+    translations: {}, draft: null, publishedAt: null, scheduledAt: null, createdAt: 0, updatedAt: 0,
+  };
+}
+
+// ---- what comes from Google ----
+
+/** Status blocks, not events: focus time, out of office, working location, birthdays. */
+export const notAnEvent = (g: Pick<GoogleEvent, 'eventType'>) => !!g.eventType && !['default', 'fromGmail'].includes(g.eventType);
+
+/**
+ * A booked appointment from one of the calendar's booking pages (Q16).
+ * Google's API has no marker for these (its event types don't include them,
+ * and open booking times aren't listed at all). Google copies the booking
+ * page's title into each booked event, so a link names its booking pages: an
+ * event with one of those titles (or that title and the booker's name after
+ * it) and a guest is a booking. So is one whose description links to a
+ * Google booking page.
+ */
+export function isBooking(g: GoogleEvent, link: Pick<GcalLink, 'bookingTitles'>): boolean {
+  const title = titleKey(g.summary ?? '').toLowerCase();
+  const guest = (g.attendees ?? []).some((a) => !a.self && !a.organizer && !a.resource);
+  const named = link.bookingTitles.some((t) => {
+    const b = titleKey(t).toLowerCase();
+    return !!b && (title === b || title.startsWith(`${b} (`) || title.startsWith(`${b} - `) || title.startsWith(`${b}: `));
+  });
+  return (named && guest) || /calendar\.app\.google\/|calendar\.google\.com\/calendar\/(?:u\/\d+\/)?appointments\//i.test(g.description ?? '');
+}
+
+/** A later part made by Google's "this and following" ("<series id>_R<when>"): the series it was split from. */
+export const splitFrom = (googleId: string) => /^(.+)_R\d{8}(?:T\d{6}Z?)?$/.exec(googleId)?.[1] ?? null;
+
+// ---- what Google gets ----
+
+/**
+ * The Google id for a site event's copy: chosen by the site (Google allows
+ * 0-9 and a-v), so a run that crashed after Google saved it finds that copy
+ * again instead of making a second one. A copy made again after Google
+ * deleted the first gets a new id (deleted ids stay taken).
+ */
+export function googleIdFor(eventId: string, again = 0): string | undefined {
+  const hex = eventId.toLowerCase().replace(/-/g, '');
+  if (!/^[0-9a-f]{32}$/.test(hex)) return undefined;
+  return `acms${hex}${again ? `r${again.toString(32)}` : ''}`;
+}
+
+export const hiddenLink = (eventId: string, origin: string) => ({ private: { acmsEventId: eventId, acmsSite: origin } });
+
+/** A whole new Google event for the site event (description left out while it's Google's). */
+export function googleBody(e: CalEvent, f: SiteFields, link: Pick<GcalLink, 'rules'>, ctx: MapContext, opts: { desc: boolean }): Record<string, unknown> {
+  return {
+    summary: googleTitle(e, link.rules, ctx.words),
+    ...(opts.desc ? { description: googleDescription(f.desc, f.link, ctx.words) } : {}),
+    location: f.place,
+    ...googleTimes(f.when),
+    ...(f.repeat.rrule ? { recurrence: googleRecurrence(f.repeat, f.when) } : {}),
+    extendedProperties: hiddenLink(e.id, ctx.origin),
+  };
+}
+
+/** Just the Google fields for these changed site fields. `googleSummary`: Google's title now (kept, adjusted, unless the site's title changed). */
+export function googlePatch(e: CalEvent, f: SiteFields, link: Pick<GcalLink, 'rules'>, ctx: MapContext, fields: string[], opts: { desc: boolean; googleSummary?: string }): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  const has = (n: string) => fields.includes(n);
+  const rules = link.rules.filter((r) => has(`rule:${r.prefix}`));
+  if (has('title')) out.summary = googleTitle(e, link.rules, ctx.words);
+  else if (has('status') || rules.length) out.summary = opts.googleSummary === undefined ? googleTitle(e, link.rules, ctx.words) : adjustTitle(opts.googleSummary, e, rules, ctx.words);
+  if (opts.desc && (has('desc') || has('link'))) out.description = googleDescription(f.desc, f.link, ctx.words);
+  if (has('place')) out.location = f.place;
+  if (has('when') || has('repeat')) Object.assign(out, googleTimes(f.when, true));
+  // a rule change rewrites the whole list; [] makes a one-off of a series
+  if (has('repeat') || (has('when') && f.repeat.rrule)) out.recurrence = googleRecurrence(f.repeat, f.when);
+  return out;
+}
+
+/** start/end/location for one date of the series in Google (an instance). */
+export function instanceBody(d: DateState | 'none', f: Fields, key: string): Record<string, unknown> {
+  if (d === 'cancelled') return { status: 'cancelled' };
+  const at = d === 'none' ? { ...seriesDate(f.when, key), place: f.place } : d;
+  return { status: 'confirmed', ...googleTimes({ allDay: f.when.allDay, start: at.start, end: at.end, tz: f.when.tz }, true), location: at.place };
+}
+
+/** The originalStart a Google instance is asked for by (events.instances): RFC 3339 in the series' zone, or the date. */
+export function originalStart(key: string, when: When): string {
+  if (when.allDay) return key.slice(0, 10);
+  return new Date(wallToMs(key, when.tz)).toISOString().replace('.000Z', 'Z');
+}
+
+/** The site's write for these changed Google fields (null when none applies): the main-language title as typed (Q9), tags from prefixes (Q15). */
+export function siteUpdate(e: CalEvent, g: Fields, fields: string[], opts: { rules: PrefixRule[]; descGoogle: boolean; settings: Pick<Settings, 'timezone'> }) {
+  const out: Partial<Pick<CalEvent, 'title' | 'tags' | 'start' | 'end' | 'allDay' | 'timezone' | 'rrule' | 'exdates' | 'location' | 'bodyHtml' | 'bodyJson' | 'excerpt'>> = {};
+  const has = (n: string) => fields.includes(n);
+  if (has('title') && g.title) out.title = g.title.slice(0, 300);
+  const ruleFields = fields.filter((n) => n.startsWith('rule:'));
+  if (ruleFields.length) {
+    let tags = [...e.tags];
+    for (const n of ruleFields) {
+      const rule = opts.rules.find((r) => r.prefix === n.slice(5));
+      if (!rule) continue;
+      if (g.rules[rule.prefix] && !hasTag(tags, rule.tag)) tags.push(rule.tag);
+      if (!g.rules[rule.prefix]) tags = tags.filter((t) => !hasTag([t], rule.tag));
+    }
+    out.tags = tags;
+  }
+  if (has('when')) {
+    Object.assign(out, { start: g.when.start, end: g.when.end, allDay: g.when.allDay });
+    if (!g.when.allDay) out.timezone = g.when.tz === (opts.settings.timezone || 'UTC') ? '' : g.when.tz;
+  }
+  if (has('repeat')) Object.assign(out, { rrule: g.repeat.rrule, exdates: g.repeat.exdates });
+  // the place as typed in Google; a saved place or pin no longer applies (the map or meeting link stays)
+  if (has('place')) out.location = EventLocation.parse({ name: g.place.slice(0, 300), url: e.location.url, showMap: e.location.showMap });
+  if (has('desc') && opts.descGoogle) Object.assign(out, { bodyHtml: paragraphsHtml(g.desc), bodyJson: '', excerpt: g.desc.replace(/\s+/g, ' ').slice(0, 300) });
+  return Object.keys(out).length ? out : null;
+}
+
+// a wall time in words ("Wed, Oct 28" and "3:30 PM"), read as written: no zone conversion
+function wallWords(wall: string) {
+  const p = parseWall(wall);
+  if (!p) return { day: wall, time: '' };
+  const d = Date.UTC(p.y, p.m - 1, p.d, p.hh, p.mm);
+  return { day: new Intl.DateTimeFormat('en-US', { weekday: 'short', month: 'short', day: 'numeric', timeZone: 'UTC' }).format(d),
+    time: p.dateOnly ? '' : new Intl.DateTimeFormat('en-US', { hour: 'numeric', minute: '2-digit', timeZone: 'UTC' }).format(d) };
+}
+
+/** Field values in words for Recent changes and clash notes (staff read these in English, like the rest of the admin). */
+export function describe(name: string, f: Fields): string {
+  if (name === 'title') return f.title;
+  if (name === 'place') return f.place || '(no place)';
+  if (name === 'desc') return f.desc ? (f.desc.length > 140 ? `${f.desc.slice(0, 140)}…` : f.desc) : '(no description)';
+  if (name === 'when') {
+    const a = wallWords(f.when.start), b = wallWords(f.when.end);
+    if (f.when.allDay) return a.day === b.day ? `${a.day}, all day` : `${a.day} – ${b.day}`;
+    return a.day === b.day ? `${a.day}, ${a.time} – ${b.time}` : `${a.day}, ${a.time} – ${b.day}, ${b.time}`;
+  }
+  if (name === 'repeat') return f.repeat.rrule ? `${describeRepeat(f.repeat.rrule, f.when.start)}${f.repeat.exdates.length ? `, skipping ${f.repeat.exdates.length}` : ''}` : 'one date';
+  if (name.startsWith('rule:')) return f.rules[name.slice(5)] ? `“${name.slice(5)}” in the title` : `no “${name.slice(5)}”`;
+  return '';
+}
+export const FIELD_WORDS: Record<string, string> = { title: 'Title', when: 'Time', repeat: 'Repeat', place: 'Place', desc: 'Description', link: 'Links', status: 'Cancelled' };
+export const fieldWord = (name: string) => FIELD_WORDS[name] ?? (name.startsWith('rule:') ? `“${name.slice(5)}”` : name.startsWith('date:') ? `Date ${name.slice(5).replace('T', ' ')}` : name);
+
+/** Plain milliseconds of a wall key in the series' zone (for "has this date passed?"). */
+export const keyStart = (key: string, when: When, settings: Pick<Settings, 'timezone'>) => wallToMs(key, when.allDay ? settings.timezone || 'UTC' : when.tz);

package/src/lib/calendar/google/match.ts

@@ -0,0 +1,103 @@
+// The first match: before a link writes anything, staff see what's on both
+// sides. Events typed by hand into both calendars are already doubles, so
+// they're paired here and nothing is written until "Start syncing":
+// - sure pairs: the hidden link on a Google copy, then the same calendar ID
+//   (copies made from a Google feed keep Google's iCalUID as sourceUid), then
+//   the same title (prefixes and case aside) at the same time → Linked (undoable)
+// - likely pairs: same start and same repeat, different title → suggested,
+//   waiting for "Link" or "Not the same"
+// Starting records every linked pair as it is: both titles stay as they are
+// (Q18), and so does every other field and date, as the agreed starting point.
+// Events only in Google come to the site, events only on the site go to
+// Google, pairs marked "Not the same" count as two events, and no member
+// notifications are sent for any of it (Q10).
+import { ApiError } from '../../api';
+import { hasTag } from '../../schema';
+import type { SyncContext } from './context';
+import { processEvents, listChanges, pairExisting } from './inbound';
+import { queueLinkCalendar } from './links';
+import { BOOKING_TAG, asSiteEvent, comparableTitle, googleFields, inWindow, isBooking, linkCarries, notAnEvent, windowStart } from './map';
+import type { GcalLink, MatchPair, MatchState } from './types';
+
+const REASON_WORDS: Record<MatchPair['reason'], string> = {
+  'hidden-id': 'its hidden link', uid: 'the same calendar ID', 'title-time': 'the same title and time', 'time-repeat': 'the same time and repeat',
+};
+export const reasonWords = (r: MatchPair['reason']) => REASON_WORDS[r];
+
+/** Reads both sides and proposes pairs. Writes nothing to either calendar. */
+export async function buildMatch(ctx: SyncContext, link: GcalLink): Promise<MatchState> {
+  const startMs = windowStart(link, ctx.settings);
+  const { items } = await listChanges(ctx, link, true);
+  const google = items.filter((g) => !g.recurringEventId && g.status !== 'cancelled' && !notAnEvent(g))
+    .map((g) => { const f = googleFields(g, link, ctx.settings); return f ? { g, f, shape: asSiteEvent(f, ctx.settings) } : null; })
+    .filter((x): x is NonNullable<typeof x> => !!x && inWindow(x.shape, startMs, ctx.settings));
+  const site = (await ctx.repo.listEvents()).filter((e) => linkCarries(e, link) && !hasTag(e.tags, BOOKING_TAG) && inWindow(e, startMs, ctx.settings));
+  const pairs: MatchPair[] = [];
+  const usedSite = new Set<string>(), usedGoogle = new Set<string>();
+  const pair = (eventId: string, googleId: string, reason: MatchPair['reason'], state: MatchPair['state']) => {
+    pairs.push({ eventId, googleId, reason, state }); usedSite.add(eventId); usedGoogle.add(googleId);
+  };
+  const passes: [MatchPair['reason'], MatchPair['state'], (e: (typeof site)[number], x: (typeof google)[number]) => boolean][] = [
+    ['hidden-id', 'linked', (e, x) => x.g.extendedProperties?.private?.acmsEventId === e.id && x.g.extendedProperties?.private?.acmsSite === ctx.origin],
+    ['uid', 'linked', (e, x) => !!e.sourceUid && e.sourceUid === x.g.iCalUID],
+    ['title-time', 'linked', (e, x) => e.startAt === x.shape.startAt && !!e.rrule === !!x.f.repeat.rrule && comparableTitle(e.title, link.rules) === comparableTitle(x.f.title, link.rules)],
+    ['time-repeat', 'suggested', (e, x) => e.startAt === x.shape.startAt && e.allDay === x.f.when.allDay && e.rrule === x.f.repeat.rrule],
+  ];
+  for (const [reason, state, same] of passes) {
+    for (const x of google) {
+      if (usedGoogle.has(x.g.id) || isBooking(x.g, link)) continue;
+      const e = site.find((s) => !usedSite.has(s.id) && same(s, x));
+      if (e) pair(e.id, x.g.id, reason, state);
+    }
+  }
+  return {
+    builtAt: ctx.now, pairs,
+    siteOnly: site.filter((e) => !usedSite.has(e.id)).map((e) => e.id),
+    googleOnly: google.filter((x) => !usedGoogle.has(x.g.id)).map((x) => x.g.id),
+    google: Object.fromEntries(google.map((x) => [x.g.id, { title: x.g.summary ?? '', start: x.shape.startAt, allDay: x.f.when.allDay, repeats: !!x.f.repeat.rrule, booking: isBooking(x.g, link) }])),
+  };
+}
+
+/** Link, Not the same, or Undo (an automatic pair becomes two events) for one proposed pair. Saved on the link ("Save and finish later"). */
+export async function decideMatch(ctx: Pick<SyncContext, 'repo'>, linkId: string, googleId: string, decision: 'link' | 'apart') {
+  const link = await ctx.repo.gcal.getLink(linkId);
+  if (!link || link.state !== 'matching' || !link.match) throw new ApiError(409, 'This link isn’t waiting for a match any more. Reload the page.');
+  const pairs = link.match.pairs.map((p) => p.googleId === googleId ? { ...p, state: decision === 'link' ? 'linked' as const : 'apart' as const } : p);
+  if (!await ctx.repo.gcal.patchLink(linkId, { match: { ...link.match, pairs } }, link.revision)) throw new ApiError(409, 'The link changed meanwhile. Reload and try again.');
+}
+
+/** "Start syncing": pairs as they are, the rest copied each way, quietly. The caller holds the link's lease. */
+export async function startSyncing(ctx: SyncContext, link: GcalLink) {
+  const m = link.match;
+  if (link.state !== 'matching' || !m) throw new ApiError(409, 'This link isn’t waiting for a match. Reload the page.');
+  const waiting = m.pairs.filter((p) => p.state === 'suggested').length;
+  if (waiting) throw new ApiError(400, `Decide the ${waiting} suggested pair${waiting === 1 ? '' : 's'} first: Link, or Not the same.`);
+  const { items, syncToken } = await listChanges(ctx, link, true);
+  const byId = new Map(items.map((g) => [g.id, g]));
+  const adopt = new Set<string>(), skip = new Set<string>();
+  const apart = new Set(m.pairs.filter((p) => p.state === 'apart').map((p) => p.googleId));
+  let paired = 0;
+  const changedSince: string[] = [];
+  for (const p of m.pairs.filter((x) => x.state === 'linked')) {
+    const [g, e] = [byId.get(p.googleId), await ctx.repo.getEvent(p.eventId)];
+    if (!g || g.status === 'cancelled') continue;
+    // the site event was unpublished, deleted or moved out of this calendar or room since the review:
+    // its Google twin is left alone (neither paired, nor deleted, nor copied as a new event)
+    if (!e || !linkCarries(e, link)) { skip.add(g.id); changedSince.push(g.summary || e?.title || 'an event'); continue; }
+    if ((await ctx.repo.gcal.getItem(link.id, g.id))) continue;
+    await pairExisting(ctx, link, e, g, { quiet: true, adopt }, REASON_WORDS[p.reason]);
+    paired++;
+  }
+  // the rest as a quiet full read: only-in-Google events come in, pairs' dates are recorded as they are
+  // (a site → Google link leaves Google's own events in Google)
+  if (link.direction !== 'out') await processEvents(ctx, link, items, { quiet: true, apart, adopt, skip });
+  if (!await ctx.repo.gcal.patchLink(link.id, { state: 'active', matchedAt: ctx.now, match: null, syncToken, fullSync: false, failures: 0, failingSince: 0, error: '', lastOkAt: ctx.now, nextAt: ctx.now + 120_000 }, link.revision, link.lease)) {
+    throw new ApiError(409, 'The link changed meanwhile. Reload and try again.');
+  }
+  // the site's events go out: only-on-site ones are copied, pairs have nothing to send (a Google → site link sends none)
+  if (link.direction !== 'in') await queueLinkCalendar(ctx.repo, link);
+  if (changedSince.length) await ctx.repo.gcal.log([{ direction: 'info', action: 'started', linkId: link.id, title: link.googleName,
+    summary: `Left alone because their site event changed since the review (unpublished, deleted or moved): ${changedSince.slice(0, 10).map((t) => `“${t}”`).join(', ')}${changedSince.length > 10 ? ` and ${changedSince.length - 10} more` : ''}. They stay as they are in Google.` }], ctx.now);
+  await ctx.repo.gcal.log([{ direction: 'info', action: 'started', linkId: link.id, title: link.googleName,
+    summary: `Started syncing: ${paired} pair${paired === 1 ? '' : 's'} kept as they are, ${m.googleOnly.length + apart.size} event${m.googleOnly.length + apart.size === 1 ? '' : 's'} from Google, ${m.siteOnly.length + apart.size} going to Google. No notifications were sent.` }], ctx.now);
+}