@acms-subir/core 0.3.54 → 0.3.56

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

@@ -0,0 +1,493 @@
+// Google → site. Every 2 minutes each link asks Google what changed since
+// its sync token (events.list with syncToken; deleted events included). A
+// 410 (or a first run, a resume) reads everything from the link's start date
+// again: a full resync pairs by the pairs it knows, then by the hidden link
+// on each Google copy (extendedProperties.private.acmsEventId), so it makes
+// no doubles, and it sends no member pushes (Q10).
+//
+// What each change becomes on the site:
+// - a new Google event: a published site event in the link's calendar,
+//   holding the link's rooms (Q5); a booked appointment comes in as "Booked"
+//   with the internal #google-booking tag and nothing else (Q16)
+// - a changed field: copied, unless the site changed the same field since
+//   they last agreed; then the site wins and Google's value is kept for
+//   "Use Google's version" (Q4). A description only while it's Google's (Q8).
+// - one date of a series cancelled or moved: C1's cancelOccurrence /
+//   moveOccurrence as GOOGLE_SYNC, so RSVPs, room holds and pushes follow;
+//   a per-date title or description isn't kept (listed instead)
+// - deleted: cancelled on the site (struck through, room freed, restorable,
+//   Q6), or, when the event has another linked copy, just this link's room
+//   and calendar taken off it
+// - "this and following": the new Google series is linked to the same site
+//   event as a later part (kind segment) and listed for staff; C4 ("from this
+//   date on") will apply those later
+import { EventLocation, RoomHold, type CalEvent } from '../../schema';
+import { eventSideEffects } from '../../content-service';
+import { expandEvents } from '../events';
+import { rruleMap } from '../rrule';
+import { cancelOccurrence, restoreOccurrence, uniqueSlug } from '../schedule';
+import { GOOGLE_SYNC, moveOccurrence, moveOccurrenceBack } from '../moves';
+import { clashNote, entry, type SyncContext } from './context';
+import { GoogleError } from './client';
+import {
+  BOOKING_TAG, NONE, asSiteEvent, changed, dateHash, describe, fieldHash, fieldHashes, fieldWord, googleFields, hiddenLink, inWindow, instanceKey,
+  instanceState, isBooking, keyStart, linkCarries, notAnEvent, paragraphsHtml, sameValue, siteFields, siteUpdate, splitFrom, windowStart, type DateState, type Fields,
+} from './map';
+import type { GcalItem, GcalLink, GoogleEvent, Hashes, NewLogEntry } from './types';
+
+export interface InboundOptions {
+  /** a full read: no member pushes (Q10) */
+  quiet: boolean;
+  /** Google ids to take as new events even when they carry a hidden link (the first match's "Not the same") */
+  apart?: Set<string>;
+  /** series paired during this run: their dates as Google has them are recorded, not applied (the agreed starting point, Q18) */
+  adopt?: Set<string>;
+  /** the site's events by sourceUid, read once per batch */
+  uids?: Promise<Map<string, CalEvent[]>>;
+  /** Google ids left alone this run (a reviewed pair whose site event changed since the review) */
+  skip?: Set<string>;
+}
+
+const masterHashes = (h: Hashes) => Object.fromEntries(Object.entries(h).filter(([k]) => !k.startsWith('date:')));
+const setHash = (h: Hashes, name: string, value: string) => { if (value === NONE && name.startsWith('date:')) delete h[name]; else h[name] = value; };
+const rethrowGoogle = (e: unknown) => { if (e instanceof GoogleError) throw e; };
+const errorText = (e: unknown) => (e instanceof Error ? e.message : 'Something went wrong.');
+const same = (a: unknown, b: unknown) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+
+/**
+ * Writes a change from Google to the live event, leaving staged edits staged.
+ * A staged draft holds the editor's whole form, so each field the draft still
+ * has at its old live value takes the new value too: pressing Update on an
+ * unrelated staged edit must not undo Google's change. A field the draft did
+ * change stays as staged (applying it is a site edit, and goes to Google).
+ */
+async function writeSite(ctx: SyncContext, e: CalEvent, update: Partial<CalEvent>, quiet: boolean) {
+  await ctx.repo.updateEvent(e.id, update, { keepDraft: true, quiet });
+  if (e.draft) {
+    const draft = e.draft as Record<string, unknown>;
+    const follow = Object.fromEntries(Object.entries(update).filter(([k]) => Object.hasOwn(draft, k) && same(draft[k], (e as Record<string, unknown>)[k])));
+    if (Object.keys(follow).length) await ctx.repo.saveEventDraft(e.id, follow);
+  }
+  return (await ctx.repo.getEvent(e.id))!;
+}
+
+/** Every page of a link's changes (or of everything, `full`), with the sync token for next time. */
+export async function listChanges(ctx: SyncContext, link: GcalLink, full: boolean) {
+  const items: GoogleEvent[] = [];
+  let pageToken: string | undefined;
+  for (let page = 0; page < 40; page++) {
+    const data = await ctx.client.listEvents(link.googleId, full
+      ? { timeMin: new Date(windowStart(link, ctx.settings)).toISOString(), showDeleted: true, pageToken }
+      : { syncToken: link.syncToken, pageToken });
+    items.push(...data.items);
+    if (data.nextPageToken) { pageToken = data.nextPageToken; continue; }
+    if (!data.nextSyncToken) throw new GoogleError('unavailable', 'Google didn’t finish the list. The sync tries again shortly.');
+    return { items, syncToken: data.nextSyncToken };
+  }
+  throw new GoogleError('unavailable', 'This Google calendar has too many changes to read in one run. The sync continues next time.');
+}
+
+/** Reads one link's changes and applies them. A 410 starts a full resync at once. */
+export async function syncIncoming(ctx: SyncContext, link: GcalLink) {
+  let full = link.fullSync || !link.syncToken;
+  let listing;
+  try { listing = await listChanges(ctx, link, full); }
+  catch (e) {
+    if (!(e instanceof GoogleError && e.code === 'gone') || full) throw e;
+    full = true;
+    await ctx.repo.gcal.log([{ direction: 'info', action: 'resync', linkId: link.id, title: link.googleName, summary: 'Google asked for a full read. Pairs are matched again by their hidden links: nothing is doubled and no notifications go out.' }], ctx.now);
+    listing = await listChanges(ctx, link, true);
+  }
+  const handled = await processEvents(ctx, link, listing.items, { quiet: full });
+  if (full) await sweepMissing(ctx, link, listing.items, { quiet: true });
+  return { handled, syncToken: listing.syncToken, full };
+}
+
+/** Applies a batch of Google events: series and one-offs first (splits before the series they came from), then the single dates. */
+export async function processEvents(ctx: SyncContext, link: GcalLink, events: GoogleEvent[], opts: InboundOptions): Promise<number> {
+  let uids: InboundOptions['uids'];
+  opts = { ...opts, get uids() {
+    return uids ??= ctx.repo.listEvents().then((all) => {
+      const m = new Map<string, CalEvent[]>();
+      for (const e of all) if (e.sourceUid) m.set(e.sourceUid, [...(m.get(e.sourceUid) ?? []), e]);
+      return m;
+    });
+  } };
+  const masters = events.filter((g) => !g.recurringEventId && !notAnEvent(g)).sort((a, b) => Number(!!splitFrom(b.id)) - Number(!!splitFrom(a.id)));
+  const byId = new Map(masters.map((g) => [g.id, g]));
+  const dates = new Map<string, GoogleEvent[]>();
+  for (const g of events) if (g.recurringEventId) dates.set(g.recurringEventId, [...(dates.get(g.recurringEventId) ?? []), g]);
+  let handled = 0;
+  for (const g of masters) {
+    try { await handleEvent(ctx, link, g, opts); handled++; }
+    catch (e) { rethrowGoogle(e); await failed(ctx, link, g, e); }
+  }
+  for (const [masterId, list] of dates) {
+    try { await handleDates(ctx, link, masterId, list, byId.get(masterId), opts); handled += list.length; }
+    catch (e) { rethrowGoogle(e); await failed(ctx, link, byId.get(masterId) ?? list[0], e); }
+  }
+  return handled;
+}
+
+async function failed(ctx: SyncContext, link: GcalLink, g: GoogleEvent, e: unknown) {
+  console.error('acms google sync: incoming change failed', e);
+  await ctx.repo.gcal.log([{ direction: 'info', action: 'failed', linkId: link.id, googleId: g.id, title: g.summary ?? '', summary: `A change from Google couldn’t be applied: ${errorText(e)}` }], ctx.now);
+}
+
+async function handleEvent(ctx: SyncContext, link: GcalLink, g: GoogleEvent, opts: InboundOptions) {
+  if (opts.skip?.has(g.id)) return;
+  const item = await ctx.repo.gcal.getItem(link.id, g.id);
+  if (g.status === 'cancelled') { if (item && !item.gone) await googleDeleted(ctx, link, item, opts); return; }
+  if (item) {
+    if (item.kind === 'segment') return;
+    if (item.gone) await backInGoogle(ctx, link, item, opts);
+    await applyGoogleChange(ctx, link, { ...item, gone: false }, g, opts);
+    return;
+  }
+  if (opts.apart?.has(g.id)) return void await createSiteEvent(ctx, link, g, opts);
+  const base = splitFrom(g.id);
+  if (base) {
+    const from = await ctx.repo.gcal.getItem(link.id, base);
+    if (from && from.kind !== 'segment') return void await recordSplit(ctx, link, from, g);
+  }
+  const hidden = g.extendedProperties?.private;
+  if (hidden?.acmsEventId && hidden.acmsSite === ctx.origin) {
+    const e = await ctx.repo.getEvent(hidden.acmsEventId);
+    const paired = e && (await ctx.repo.gcal.itemsForEvent(e.id)).some((i) => i.linkId === link.id && i.kind !== 'segment');
+    // a copy Google duplicated (with its hidden link), one moved here from another calendar, or an event this site
+    // no longer has (an older backup was restored): a new site event
+    if (e && !paired && linkCarries(e, link)) return void await pairExisting(ctx, link, e, g, opts, 'its hidden link');
+  }
+  if (g.iCalUID) {
+    // made on the site from this calendar's feed before the link ("Make an editable copy", an .ics import)
+    const e = ((await opts.uids)?.get(g.iCalUID) ?? []).find((x) => x.calendarIds.includes(link.calendarId));
+    if (e && linkCarries(e, link) && !(await ctx.repo.gcal.itemsForEvent(e.id)).some((i) => i.linkId === link.id)) return void await pairExisting(ctx, link, e, g, opts, 'the same calendar ID');
+  }
+  await createSiteEvent(ctx, link, g, opts);
+}
+
+/** Pairs an existing site event with a Google event as they are: both sides' fields become the agreed starting point and nothing is rewritten (Q18). */
+export async function pairExisting(ctx: SyncContext, link: GcalLink, e: CalEvent, g: GoogleEvent, opts: InboundOptions, why: string) {
+  const gf = googleFields(g, link, ctx.settings);
+  let g2 = g;
+  if (g.extendedProperties?.private?.acmsEventId !== e.id || g.extendedProperties?.private?.acmsSite !== ctx.origin) {
+    g2 = await ctx.client.patchEvent(link.googleId, g.id, { extendedProperties: hiddenLink(e.id, ctx.origin) }).catch((err) => { if (err instanceof GoogleError && (err.code === 'auth' || err.code === 'quota')) throw err; return g; });
+  }
+  const sf = siteFields(e, link, ctx.map);
+  const item: GcalItem = {
+    linkId: link.id, googleId: g.id, eventId: e.id, icalUid: g.iCalUID ?? '', kind: g.recurrence?.length ? 'series' : 'single', segmentFrom: '', etag: g2.etag ?? '', htmlLink: g2.htmlLink ?? '',
+    // a pair whose site event has no description of its own keeps Google's (Q8)
+    site: fieldHashes(sf), google: gf ? fieldHashes(gf) : {}, descGoogle: !sf.desc && !!gf?.desc, booking: false, gone: false, leftOut: false, conflict: null, syncedAt: ctx.now, createdAt: ctx.now,
+  };
+  await ctx.repo.gcal.putItem(item);
+  opts.adopt?.add(g.id);
+  await ctx.repo.gcal.log([entry(link, item, e.title, { direction: 'info', action: 'paired', summary: `Paired with “${g.summary ?? ''}” in ${link.googleName} by ${why}. Both keep their titles until one is edited.` })], ctx.now);
+}
+
+/** A new Google event: published on the site at once (Q5), in the link's calendar, holding its rooms. */
+async function createSiteEvent(ctx: SyncContext, link: GcalLink, g: GoogleEvent, opts: InboundOptions) {
+  const gf = googleFields(g, link, ctx.settings);
+  if (!gf) return;
+  const shape = asSiteEvent(gf, ctx.settings);
+  if (!inWindow(shape, windowStart(link, ctx.settings), ctx.settings)) return;
+  const { words } = ctx.map;
+  const booking = isBooking(g, link);
+  const title = booking ? words.booked : gf.title || words.untitled;
+  const tags = booking ? [BOOKING_TAG] : link.rules.filter((r) => gf.rules[r.prefix]).map((r) => r.tag);
+  const created = await ctx.repo.createEvent({
+    title: title.slice(0, 300), slug: await uniqueSlug(ctx.repo, title), status: 'draft',
+    start: gf.when.start, end: gf.when.end, allDay: gf.when.allDay, timezone: shape.timezone, rrule: gf.repeat.rrule, exdates: gf.repeat.exdates,
+    calendarIds: [link.calendarId], tags, sourceUid: g.iCalUID ?? '',
+    location: booking ? EventLocation.parse({}) : EventLocation.parse({ name: gf.place.slice(0, 300) }),
+    ...(booking || !gf.desc ? {} : { bodyHtml: paragraphsHtml(gf.desc), excerpt: gf.desc.replace(/\s+/g, ' ').slice(0, 300) }),
+    roomHold: RoomHold.parse({ resourceIds: link.roomIds }),
+  });
+  if (tags.length) await ctx.repo.ensureTags(tags);
+  await ctx.repo.updateEvent(created.id, { status: 'published' }, { quiet: opts.quiet });
+  // the hidden link lets a resync or a later link find this pair again
+  const g2 = await ctx.client.patchEvent(link.googleId, g.id, { extendedProperties: hiddenLink(created.id, ctx.origin) }).catch((err) => {
+    if (err instanceof GoogleError && (err.code === 'auth' || err.code === 'quota')) throw err;
+    return g;
+  });
+  const e = (await ctx.repo.getEvent(created.id))!;
+  const item: GcalItem = {
+    linkId: link.id, googleId: g.id, eventId: e.id, icalUid: g.iCalUID ?? '', kind: gf.repeat.rrule ? 'series' : 'single', segmentFrom: '', etag: g2.etag ?? '', htmlLink: g2.htmlLink ?? g.htmlLink ?? '',
+    site: fieldHashes(siteFields(e, link, ctx.map)), google: fieldHashes(gf), descGoogle: !booking, booking, gone: false, leftOut: false, conflict: null, syncedAt: ctx.now, createdAt: ctx.now,
+  };
+  await ctx.repo.gcal.putItem(item);
+  await eventSideEffects(ctx.repo, ctx.hooks, e);
+  const rooms = new Map((await ctx.repo.listResources()).map((r) => [r.id, r.name]));
+  const held = link.roomIds.map((r) => rooms.get(r)).filter(Boolean);
+  const notes: NewLogEntry[] = [entry(link, item, e.title, { direction: 'in', action: 'created', summary: [`New in ${link.googleName}`, booking ? 'a booked appointment' : 'published',
+    held.length ? `holds ${held.join(' and ')}` : '', tags.filter((t) => t !== BOOKING_TAG).length ? `tagged ${tags.join(', ')}` : ''].filter(Boolean).join(' · ') })];
+  const clash = await clashNote(ctx, link, item, e);
+  if (clash) notes.push(clash);
+  await ctx.repo.gcal.log(notes, ctx.now);
+}
+
+/** Google brought back a copy it had deleted (its trash): the event is no longer cancelled. */
+async function backInGoogle(ctx: SyncContext, link: GcalLink, item: GcalItem, opts: InboundOptions) {
+  const e = await ctx.repo.getEvent(item.eventId);
+  if (e?.cancelled && !item.leftOut) await eventSideEffects(ctx.repo, ctx.hooks, await writeSite(ctx, e, { cancelled: false }, opts.quiet));
+  await ctx.repo.gcal.patchItem(link.id, item.googleId, { gone: false, leftOut: false, site: item.leftOut ? item.site : { ...item.site, status: fieldHash(false) } });
+  await ctx.repo.gcal.log([entry(link, item, e?.title ?? '', { direction: 'in', action: 'restored', summary: `Back in ${link.googleName}: no longer cancelled.` })], ctx.now);
+}
+
+/** True when Google's rule is the site's with an earlier end (an end added or moved sooner): Google dropped dates the site still has. */
+function endsSooner(siteRule: string, googleRule: string): boolean {
+  if (!siteRule || !googleRule) return false;
+  const a = rruleMap(siteRule), b = rruleMap(googleRule);
+  if (!b.UNTIL && !b.COUNT) return false;
+  const rest = (m: Record<string, string>) => JSON.stringify(Object.entries(m).filter(([k]) => k !== 'UNTIL' && k !== 'COUNT').sort());
+  if (rest(a) !== rest(b)) return false;
+  if (!a.UNTIL && !a.COUNT) return true;
+  if (a.COUNT && b.COUNT) return Number(b.COUNT) < Number(a.COUNT);
+  if (a.UNTIL && b.UNTIL) return b.UNTIL.slice(0, 8) < a.UNTIL.slice(0, 8);
+  return true;
+}
+
+/** The value of one field from Google, for "Use Google's version" later. */
+const pick = (f: Fields, name: string): Partial<Fields> =>
+  name === 'title' ? { title: f.title } : name === 'when' ? { when: f.when } : name === 'repeat' ? { repeat: f.repeat } : name === 'place' ? { place: f.place }
+  : name === 'desc' ? { desc: f.desc } : name.startsWith('rule:') ? { rules: { [name.slice(5)]: !!f.rules[name.slice(5)] } } : {};
+
+/** Copies what Google changed since the pair last agreed onto the site event, field by field (the site wins where both changed, Q4). */
+export async function applyGoogleChange(ctx: SyncContext, link: GcalLink, item: GcalItem, g: GoogleEvent, opts: InboundOptions = { quiet: false }) {
+  const e = await ctx.repo.getEvent(item.eventId);
+  const gf = googleFields(g, link, ctx.settings);
+  // the site event is gone (its deletion is queued to go out), or Google's copy has no usable time
+  if (!e || !gf) return;
+  const gh = fieldHashes(gf);
+  // rules no longer on the link are forgotten; one just added starts from what each side has (no write)
+  const rules = new Set(link.rules.map((r) => `rule:${r.prefix}`));
+  item = { ...item, site: { ...item.site }, google: { ...item.google } };
+  for (const n of Object.keys({ ...item.google, ...gh })) {
+    if (!n.startsWith('rule:')) continue;
+    if (!rules.has(n)) { delete item.google[n]; delete item.site[n]; }
+    else if (item.google[n] === undefined) { item.google[n] = gh[n]; item.site[n] ??= fieldHashes(siteFields(e, link, ctx.map))[n]; }
+  }
+  const chg = changed(masterHashes(gh), masterHashes(item.google), (n) => !n.startsWith('rule:') || rules.has(n));
+  if (!chg.length) {
+    await ctx.repo.gcal.patchItem(link.id, item.googleId, { etag: g.etag ?? item.etag, htmlLink: g.htmlLink ?? item.htmlLink, site: item.site, google: item.google });
+    return;
+  }
+  const sf = siteFields(e, link, ctx.map), sh = fieldHashes(sf);
+  const split = (await ctx.repo.gcal.itemsForEvent(e.id)).some((i) => i.linkId === link.id && i.kind === 'segment');
+  const google: Hashes = { ...item.google }, site: Hashes = { ...item.site };
+  const notes: NewLogEntry[] = [];
+  const apply: string[] = [];
+  let conflict = item.conflict, sendBack = false;
+  for (const n of chg) {
+    setHash(google, n, gh[n] ?? '');
+    // a booking keeps "Booked", no place and no description
+    if (item.booking && n !== 'when') continue;
+    if (n === 'desc' && !item.descGoogle) {
+      // once the site has its own description, it wins (Q8): Google gets the site's text back
+      const [id] = await ctx.repo.gcal.log([entry(link, item, e.title, { direction: 'clash', action: 'description', summary: 'Description changed in Google, but the site’s description wins once it’s been edited there (Q8). Google gets the site’s text back.',
+        data: { field: n, site: describe(n, sf), google: describe(n, gf), value: pick(gf, n) } })], ctx.now);
+      conflict = { field: n, at: ctx.now, site: describe(n, sf), google: describe(n, gf), logId: id };
+      site[n] = '';
+      sendBack = true;
+      continue;
+    }
+    if (split && (n === 'when' || n === 'repeat')) {
+      notes.push(entry(link, item, e.title, { direction: 'info', action: 'split', summary: `${fieldWord(n)} changed when Google split this series (“this and following”). The site keeps one event as it was for now: change the later dates on the site by hand if needed.` }));
+      continue;
+    }
+    if (n === 'repeat' && endsSooner(sf.repeat.rrule, gf.repeat.rrule)) {
+      notes.push(entry(link, item, e.title, { direction: 'info', action: 'ended', summary: `Google ended this series sooner (${describe(n, gf)}). The site keeps its later dates: end the series or cancel those dates on the site if that’s right.` }));
+      continue;
+    }
+    // a Google → site link mirrors Google; otherwise a field both sides changed keeps the site's value (Q4)
+    const siteChanged = (sh[n] ?? '') !== (item.site[n] ?? '');
+    if (siteChanged && link.direction !== 'in' && !sameValue(n, sf, gf, link.rules)) {
+      const [id] = await ctx.repo.gcal.log([entry(link, item, e.title, { direction: 'clash', action: 'field', summary: `${fieldWord(n)} changed on both sides: kept the site’s “${describe(n, sf)}” (Google had “${describe(n, gf)}”).`,
+        data: { field: n, site: describe(n, sf), google: describe(n, gf), value: pick(gf, n) } })], ctx.now);
+      conflict = { field: n, at: ctx.now, site: describe(n, sf), google: describe(n, gf), logId: id };
+      sendBack = true;
+      continue;
+    }
+    if (siteChanged && link.direction !== 'in') { setHash(site, n, sh[n] ?? ''); continue; }
+    apply.push(n);
+  }
+  if (apply.length) {
+    const update = siteUpdate(e, gf, apply, { rules: link.rules, descGoogle: item.descGoogle, settings: ctx.settings });
+    if (update) {
+      const after = await writeSite(ctx, e, update, opts.quiet);
+      if (update.tags) await ctx.repo.ensureTags(update.tags);
+      const sf2 = siteFields(after, link, ctx.map), sh2 = fieldHashes(sf2);
+      for (const n of apply) setHash(site, n, sh2[n] ?? '');
+      // a series that moved counts its single dates again
+      if (apply.includes('when') || apply.includes('repeat')) {
+        for (const k of Object.keys(site)) if (k.startsWith('date:')) delete site[k];
+        for (const [k, v] of Object.entries(sh2)) if (k.startsWith('date:')) site[k] = v;
+      }
+      await eventSideEffects(ctx.repo, ctx.hooks, after);
+      notes.unshift(entry(link, item, after.title, { direction: 'in', action: 'updated',
+        summary: apply.map((n) => n === 'when' || n === 'place' || n === 'title' ? `${fieldWord(n)} ${describe(n, sf)} → ${describe(n, gf)}` : fieldWord(n)).join('; ') }));
+      if (apply.includes('when') || apply.includes('repeat')) { const clash = await clashNote(ctx, link, item, after); if (clash) notes.push(clash); }
+      if (conflict && apply.includes(conflict.field)) conflict = null;
+    } else for (const n of apply) setHash(site, n, sh[n] ?? '');
+  }
+  await ctx.repo.gcal.patchItem(link.id, item.googleId, { site, google, conflict, etag: g.etag ?? item.etag, htmlLink: g.htmlLink ?? item.htmlLink, kind: gf.repeat.rrule ? 'series' : 'single', syncedAt: ctx.now });
+  await ctx.repo.gcal.log(notes, ctx.now);
+  if (sendBack) await ctx.repo.gcal.enqueue([e.id], ctx.now);
+}
+
+/** Single dates of a series that changed in Google: cancelled, moved, or back to normal. */
+async function handleDates(ctx: SyncContext, link: GcalLink, masterId: string, list: GoogleEvent[], master: GoogleEvent | undefined, opts: InboundOptions) {
+  const item = await ctx.repo.gcal.getItem(link.id, masterId);
+  // dates of a later part (Google moved them to the split series), of a booking, or of a series no longer paired
+  if (!item || item.kind === 'segment' || item.booking || item.gone) return;
+  let e = await ctx.repo.getEvent(item.eventId);
+  if (!e) return;
+  const m = master ?? await ctx.client.getEvent(link.googleId, masterId).catch((err) => { if (err instanceof GoogleError && (err.code === 'notfound' || err.code === 'gone')) return null; throw err; });
+  let sf = siteFields(e, link, ctx.map);
+  // Google's dates read in the site event's zone, where its date keys are
+  const gf = m && m.status !== 'cancelled' ? googleFields(m, link, ctx.settings, sf.when.tz) : null;
+  if (!gf || !gf.repeat.rrule) return;
+  const adopt = opts.adopt?.has(item.googleId);
+  const google: Hashes = { ...item.google }, site: Hashes = { ...item.site };
+  const notes: NewLogEntry[] = [];
+  let sendBack = false;
+  for (const i of list) {
+    const key = instanceKey(i, gf.when);
+    if (!key) continue;
+    const n = `date:${key}`;
+    const state = instanceState(i, gf, key);
+    const gh = dateHash(state);
+    if (adopt) { setHash(google, n, gh); continue; }
+    if (gh === (item.google[n] ?? NONE)) {
+      if (state === 'none' && i.status !== 'cancelled' && ((i.summary !== undefined && i.summary !== m!.summary) || (i.description ?? '') !== (m!.description ?? ''))) {
+        notes.push(entry(link, item, e.title, { direction: 'info', action: 'date', summary: `The ${key.replace('T', ' ')} date has its own title or description in Google. The site keeps one title for every date, so that edit stays in Google only.` }));
+      }
+      continue;
+    }
+    setHash(google, n, gh);
+    if (link.direction === 'out' || keyStart(key, gf.when, ctx.settings) <= ctx.now) continue;
+    const mine: DateState | 'none' = sf.dates[key] ?? 'none';
+    if (dateHash(mine) === gh) { setHash(site, n, gh); continue; }
+    if (dateHash(mine) !== (item.site[n] ?? NONE) && link.direction !== 'in') {
+      await ctx.repo.gcal.log([entry(link, item, e.title, { direction: 'clash', action: 'date', summary: `The ${key.replace('T', ' ')} date changed on both sides: kept the site’s version.` })], ctx.now);
+      sendBack = true;
+      continue;
+    }
+    try {
+      const words = await applyDate(ctx, e, key, state, mine, sf, opts);
+      e = (await ctx.repo.getEvent(e.id))!;
+      sf = siteFields(e, link, ctx.map);
+      setHash(site, n, dateHash(sf.dates[key] ?? 'none'));
+      notes.push(entry(link, item, e.title, { direction: 'in', action: 'date', summary: `${key.replace('T', ' ')}: ${words}` }));
+    } catch (err) {
+      rethrowGoogle(err);
+      notes.push(entry(link, item, e.title, { direction: 'info', action: 'date', summary: `The ${key.replace('T', ' ')} change from Google wasn’t applied: ${errorText(err)}` }));
+    }
+  }
+  await ctx.repo.gcal.patchItem(link.id, item.googleId, { site, google, syncedAt: ctx.now });
+  await ctx.repo.gcal.log(notes, ctx.now);
+  if (sendBack) await ctx.repo.gcal.enqueue([e.id], ctx.now);
+}
+
+/** One date as Google has it, through C1 (as GOOGLE_SYNC: staff rights, clashes only warn). Returns what happened, in words. */
+async function applyDate(ctx: SyncContext, e: CalEvent, key: string, state: DateState | 'none', mine: DateState | 'none', sf: Fields, opts: InboundOptions): Promise<string> {
+  const quiet = { quiet: opts.quiet };
+  if (state === 'cancelled') { await cancelOccurrence(ctx.repo, e.id, key, ctx.hooks, ctx.now, quiet); return 'cancelled'; }
+  if (mine === 'cancelled') await restoreOccurrence(ctx.repo, e.id, key, ctx.hooks, ctx.now, quiet);
+  if (state === 'none') {
+    if (mine !== 'cancelled') await moveOccurrenceBack(ctx.repo, GOOGLE_SYNC, e.id, key, ctx.hooks, { ...quiet, now: ctx.now });
+    return mine === 'cancelled' ? 'no longer cancelled' : 'back at its usual time';
+  }
+  const location = state.place === sf.place ? null : { name: state.place.slice(0, 300), address: '', placeId: '', lat: null, lng: null, mapImage: '', mapImageDark: '' };
+  const r = await moveOccurrence(ctx.repo, GOOGLE_SYNC, e.id, key, { start: state.start, end: state.end, location }, ctx.hooks, { ...quiet, now: ctx.now });
+  return `moved to ${state.start.replace('T', ' ')}${location ? ` at ${state.place}` : ''}${r.clashes.length ? ' (a room it holds is taken then: check Bookings)' : ''}`;
+}
+
+/** Deleted in Google: just this link's room and calendar come off the event while another linked copy remains; otherwise it's cancelled on the site (Q6). */
+async function googleDeleted(ctx: SyncContext, link: GcalLink, item: GcalItem, opts: InboundOptions) {
+  const e = await ctx.repo.getEvent(item.eventId);
+  if (item.kind === 'segment') {
+    await ctx.repo.gcal.deleteItem(link.id, item.googleId);
+    await ctx.repo.gcal.log([entry(link, item, e?.title ?? '', { direction: 'info', action: 'split', summary: `Google deleted the later part of this series${item.segmentFrom ? ` (from ${item.segmentFrom.replace('T', ' ')})` : ''}. The site keeps those dates: cancel them on the site if that’s right.` })], ctx.now);
+    return;
+  }
+  if (!e) { await ctx.repo.gcal.deleteItem(link.id, item.googleId); return; }
+  const others = (await ctx.repo.gcal.itemsForEvent(e.id)).filter((i) => !(i.linkId === link.id && i.googleId === item.googleId) && !i.gone && i.kind !== 'segment');
+  const otherLinks = ctx.links.filter((l) => others.some((i) => i.linkId === l.id));
+  if (otherLinks.length) {
+    const rooms = e.roomHold.resourceIds.filter((r) => !link.roomIds.includes(r));
+    const calendarIds = otherLinks.some((l) => l.calendarId === link.calendarId) ? e.calendarIds : e.calendarIds.filter((c) => c !== link.calendarId);
+    const update: Partial<CalEvent> = {};
+    if (rooms.length !== e.roomHold.resourceIds.length) update.roomHold = { ...e.roomHold, resourceIds: rooms };
+    if (calendarIds.length !== e.calendarIds.length) update.calendarIds = calendarIds;
+    const others = otherLinks.map((l) => l.googleName).join(' and ');
+    // nothing can come off (the link carries the whole calendar, which another link also has): this Google calendar keeps it out
+    if (linkCarries({ ...e, ...update }, link)) {
+      await ctx.repo.gcal.patchItem(link.id, item.googleId, { gone: true, leftOut: true, syncedAt: ctx.now });
+      await ctx.repo.gcal.log([entry(link, item, e.title, { direction: 'in', action: 'removed', summary: `Deleted from ${link.googleName}: it stays out of that calendar, and stays on the site and in ${others}.` })], ctx.now);
+      return;
+    }
+    await eventSideEffects(ctx.repo, ctx.hooks, await writeSite(ctx, e, update, opts.quiet));
+    await ctx.repo.gcal.deleteItem(link.id, item.googleId);
+    await ctx.repo.gcal.log([entry(link, item, e.title, { direction: 'in', action: 'removed',
+      summary: `Deleted from ${link.googleName}: ${update.roomHold ? 'its room' : 'that calendar'} came off the event, which stays in ${others}.` })], ctx.now);
+    return;
+  }
+  if (e.status === 'published' && !e.cancelled) await eventSideEffects(ctx.repo, ctx.hooks, await writeSite(ctx, e, { cancelled: true }, opts.quiet));
+  await ctx.repo.gcal.patchItem(link.id, item.googleId, { gone: true, syncedAt: ctx.now });
+  await ctx.repo.gcal.log([entry(link, item, e.title, { direction: 'in', action: 'cancelled', summary: `Deleted in ${link.googleName}: cancelled on the site. Restore it there to bring it back in Google.` })], ctx.now);
+}
+
+/** Google split a series ("this and following"): the new series is linked to the same site event as a later part, listed for staff (C4 will apply these). */
+async function recordSplit(ctx: SyncContext, link: GcalLink, base: GcalItem, g: GoogleEvent) {
+  const e = await ctx.repo.getEvent(base.eventId);
+  const gf = googleFields(g, link, ctx.settings);
+  // the first date of the site's series from the new part's first day on
+  let from = '';
+  if (e && gf) {
+    const day = asSiteEvent({ ...gf, when: { ...gf.when, start: gf.when.start.slice(0, 10), end: gf.when.start.slice(0, 10), allDay: true } }, ctx.settings).startAt;
+    from = expandEvents([{ ...e, movedDates: {} }], ctx.settings, { displayTz: ctx.settings.timezone || 'UTC', now: day, windowStartMs: day, windowEndMs: day + 400 * 86_400_000 })
+      .find((o) => o.start >= day)?.key ?? '';
+  }
+  await ctx.repo.gcal.putItem({
+    linkId: link.id, googleId: g.id, eventId: base.eventId, icalUid: g.iCalUID ?? '', kind: 'segment', segmentFrom: from, etag: g.etag ?? '', htmlLink: g.htmlLink ?? '',
+    site: {}, google: gf ? fieldHashes(gf) : {}, descGoogle: false, booking: false, gone: false, leftOut: false, conflict: null, syncedAt: ctx.now, createdAt: ctx.now,
+  });
+  await ctx.repo.gcal.log([entry(link, base, e?.title ?? g.summary ?? '', { direction: 'info', action: 'split',
+    summary: `Google changed this series from ${from ? from.replace('T', ' ') : 'a later date'} on (“this and following”)${gf ? `: ${describe('when', gf)}, ${describe('repeat', gf)}` : ''}. The site keeps one event as it was for now; change the later dates on the site by hand if needed.` })], ctx.now);
+}
+
+/** After a full read: pairs Google didn't list (deleted long ago, or a list that skipped them) are checked one by one. */
+async function sweepMissing(ctx: SyncContext, link: GcalLink, listed: GoogleEvent[], opts: InboundOptions) {
+  const seen = new Set(listed.map((g) => g.id));
+  const startMs = windowStart(link, ctx.settings);
+  const missing = (await ctx.repo.gcal.itemsForLink(link.id)).filter((i) => !i.gone && !seen.has(i.googleId));
+  for (const item of missing.slice(0, 200)) {
+    const e = await ctx.repo.getEvent(item.eventId);
+    if (e && !inWindow(e, startMs, ctx.settings)) continue;
+    const g = await ctx.client.getEvent(link.googleId, item.googleId).catch((err) => { if (err instanceof GoogleError && (err.code === 'notfound' || err.code === 'gone')) return null; throw err; });
+    if (!g || g.status === 'cancelled') await googleDeleted(ctx, link, item, opts);
+    else if (item.kind !== 'segment') await applyGoogleChange(ctx, link, item, g, opts);
+  }
+}
+
+/** "Use Google's version" from a clash: the site takes Google's value for that field (and Google keeps it, since they now agree). */
+export async function useGoogleValue(ctx: Pick<SyncContext, 'repo' | 'settings' | 'map' | 'hooks'>, logId: number) {
+  const log = await ctx.repo.gcal.getLog(logId);
+  const data = log?.data as { field?: string; value?: Partial<Fields> } | null;
+  if (!log || !data?.field || !data.value) throw Object.assign(new Error('That change can’t be used any more.'), { status: 404 });
+  const [link, item, e] = await Promise.all([ctx.repo.gcal.getLink(log.linkId), ctx.repo.gcal.getItem(log.linkId, log.googleId), ctx.repo.getEvent(log.eventId)]);
+  if (!link || !item || !e) throw Object.assign(new Error('That event is no longer synced.'), { status: 404 });
+  const current = siteFields(e, link, ctx.map);
+  const g: Fields = { ...current, ...data.value, rules: { ...current.rules, ...(data.value.rules ?? {}) } };
+  const update = siteUpdate(e, g, [data.field], { rules: link.rules, descGoogle: true, settings: ctx.settings });
+  if (update) {
+    await writeSite(ctx as SyncContext, e, update, false);
+    if (update.tags) await ctx.repo.ensureTags(update.tags);
+  }
+  const after = (await ctx.repo.getEvent(e.id))!;
+  // an ordinary site change from here: every copy gets Google's value (the losing copy had the site's by now)
+  await ctx.repo.gcal.patchItem(link.id, item.googleId, { conflict: item.conflict?.field === data.field ? null : item.conflict });
+  await ctx.repo.gcal.resolveLog(logId);
+  await eventSideEffects(ctx.repo, ctx.hooks, after);
+  return after;
+}

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

@@ -0,0 +1,139 @@
+// Links: one site calendar ⇄ one Google calendar. A site calendar may have
+// several links, one per room (cces: the room calendar ⇄ "Santuario |
+// Sanctuary" holding the Sanctuary, and ⇄ "Multimedia Room #1" holding its
+// room). A new link waits in "matching" until someone reviews the first
+// match (./match.ts) and presses Start syncing; until then nothing is
+// written to either side. A link only runs on the site that made it: a copy
+// of the site (a restored backup elsewhere, staging, a local copy with a
+// different Site URL) pauses its links instead of writing into the real calendar.
+import { z } from 'zod';
+import { ApiError } from '../../api';
+import type { ContentRepository } from '../../repo/types';
+import type { Settings } from '../../schema';
+import { parseWall } from '../events';
+import { siteOriginOf } from './connect';
+import { linkCarries } from './map';
+import { Direction, PrefixRule, type GcalLink } from './types';
+
+export const LinkInput = z.object({
+  calendarId: z.string().min(1).max(100),
+  googleId: z.string().min(1).max(1024),
+  direction: Direction.default('both'),
+  roomIds: z.array(z.string().max(100)).max(50).default([]),
+  noRoom: z.boolean().default(false),
+  rules: z.array(PrefixRule).max(10).default([]),
+  bookingTitles: z.array(z.string().trim().min(1).max(200)).max(20).default([]),
+  /** YYYY-MM-DD; default 30 days ago (Q11) */
+  startDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+}).strict();
+export type LinkInput = z.input<typeof LinkInput>;
+export const LinkChanges = LinkInput.omit({ calendarId: true, googleId: true, startDate: true }).partial().strict();
+
+/** Why a link can't run here (shown on it), or '' when it can. */
+export const PAUSE_WORDS: Record<string, string> = {
+  paused: 'Paused',
+  restored: 'Paused after a restore: check the events, then resume',
+  'other-site': 'This copy isn’t the site that linked Google',
+  disconnected: 'Google is disconnected',
+  reconnect: 'Reconnect Google',
+};
+
+/** '' when the link may run on this site, else the pause reason. */
+export function siteGuard(link: Pick<GcalLink, 'siteUrl'>, settings: Pick<Settings, 'siteUrl'>): '' | 'other-site' {
+  return siteOriginOf(settings.siteUrl) === link.siteUrl ? '' : 'other-site';
+}
+
+const daysAgo = (n: number, now = Date.now()) => new Date(now - n * 86_400_000).toISOString().slice(0, 10);
+
+async function cleanLink(repo: ContentRepository, input: z.infer<typeof LinkChanges>, calendarId: string, selfId?: string) {
+  const rooms = new Set((await repo.listResources()).map((r) => r.id));
+  const roomIds = input.roomIds === undefined ? undefined : [...new Set(input.roomIds)].filter((r) => rooms.has(r));
+  if (input.noRoom) {
+    const other = (await repo.gcal.listLinks()).find((l) => l.calendarId === calendarId && l.noRoom && l.id !== selfId);
+    if (other) throw new ApiError(400, `“${other.googleName}” already gets this calendar’s events that hold no room. Only one link can.`);
+  }
+  const rules = input.rules === undefined ? undefined : input.rules.filter((r, i, all) => all.findIndex((x) => x.prefix.toLowerCase() === r.prefix.toLowerCase()) === i);
+  const bookingTitles = input.bookingTitles === undefined ? undefined : [...new Set(input.bookingTitles.map((t) => t.trim()))];
+  return { ...input, ...(roomIds ? { roomIds } : {}), ...(rules ? { rules } : {}), ...(bookingTitles ? { bookingTitles } : {}) };
+}
+
+/** A new link, waiting for its first-match review. */
+export async function createLink(repo: ContentRepository, raw: unknown): Promise<GcalLink> {
+  const input = LinkInput.parse(raw);
+  const [account, settings, calendar] = await Promise.all([repo.gcal.account(), repo.getSettings(), repo.getCalendar(input.calendarId)]);
+  if (!account || account.status !== 'connected') throw new ApiError(400, 'Connect Google first.');
+  if (!calendar || calendar.kind !== 'native') throw new ApiError(400, 'Pick one of your calendars.');
+  const google = account.calendars.find((c) => c.id === input.googleId);
+  if (!google) throw new ApiError(400, 'Pick a Google calendar this account can edit. If it’s missing, refresh the list.');
+  const taken = (await repo.gcal.listLinks()).find((l) => l.googleId === input.googleId);
+  if (taken) throw new ApiError(409, `“${google.name}” is already linked.`);
+  const origin = siteOriginOf(settings.siteUrl);
+  if (!origin) throw new ApiError(400, 'Set the Site URL in Settings → General first.');
+  const startDate = input.startDate ?? daysAgo(30);
+  if (!parseWall(startDate)) throw new ApiError(400, 'Pick a valid start date.');
+  const clean = await cleanLink(repo, input, calendar.id);
+  return repo.gcal.createLink({ calendarId: calendar.id, googleId: google.id, googleName: google.name, googleTz: google.timeZone, direction: clean.direction ?? 'both',
+    roomIds: clean.roomIds ?? [], noRoom: clean.noRoom ?? false, rules: clean.rules ?? [], bookingTitles: clean.bookingTitles ?? [], startDate, siteUrl: origin });
+}
+
+/**
+ * The site calendar's events, queued to go out (a link started, resumed or
+ * now carries other rooms), with the pairs' events: one deleted on the site
+ * while the link waited is removed from Google. After a restore, though, a
+ * pair whose event the backup doesn't have is forgotten instead, and the full
+ * read brings that event back from Google: an older backup never deletes
+ * anything in Google.
+ */
+async function catchUp(repo: ContentRepository, link: GcalLink, restored = false) {
+  const events = await repo.listEvents();
+  const known = new Set(events.map((e) => e.id));
+  const items = await repo.gcal.itemsForLink(link.id);
+  if (restored) for (const i of items) if (!known.has(i.eventId)) await repo.gcal.deleteItem(link.id, i.googleId);
+  const ids = events.filter((e) => e.calendarIds.includes(link.calendarId)).map((e) => e.id);
+  await repo.gcal.enqueue([...ids, ...items.filter((i) => !restored || known.has(i.eventId)).map((i) => i.eventId)]);
+}
+
+/** Direction, rooms, the "no room" flag, rules and booking titles. Copies follow at the next run: events that now belong here go out, ones that don't leave. */
+export async function updateLink(repo: ContentRepository, id: string, raw: unknown): Promise<GcalLink> {
+  const link = await repo.gcal.getLink(id);
+  if (!link) throw new ApiError(404, 'That link no longer exists.');
+  const clean = await cleanLink(repo, LinkChanges.parse(raw), link.calendarId, link.id);
+  // reading Google again from scratch after "Site → Google only" catches what changed there meanwhile
+  const reread = clean.direction && clean.direction !== link.direction && link.direction === 'out';
+  if (!await repo.gcal.patchLink(id, { ...clean, ...(reread ? { fullSync: true } : {}) }, link.revision)) throw new ApiError(409, 'The link changed meanwhile. Reload and try again.');
+  const next = (await repo.gcal.getLink(id))!;
+  if (next.state === 'active') await catchUp(repo, next);
+  return next;
+}
+
+export async function pauseLink(repo: ContentRepository, id: string) {
+  const link = await repo.gcal.getLink(id);
+  if (!link) throw new ApiError(404, 'That link no longer exists.');
+  if (link.state !== 'paused') await repo.gcal.patchLink(id, { state: 'paused', pausedReason: 'paused' }, link.revision);
+}
+
+/** Resume: a link that never finished its first match goes back to it; otherwise it reads Google again from scratch (quietly, pairing by the hidden links) and catches up. */
+export async function resumeLink(repo: ContentRepository, id: string) {
+  const [link, settings, account] = await Promise.all([repo.gcal.getLink(id), repo.getSettings(), repo.gcal.account()]);
+  if (!link) throw new ApiError(404, 'That link no longer exists.');
+  if (siteGuard(link, settings)) throw new ApiError(400, `${PAUSE_WORDS['other-site']} (it was made on ${link.siteUrl}). Unlink it here, or set the Site URL back.`);
+  if (!account || account.status !== 'connected') throw new ApiError(400, 'Connect Google first.');
+  const matched = link.matchedAt > 0;
+  if (!await repo.gcal.patchLink(id, { state: matched ? 'active' : 'matching', pausedReason: '', error: '', failures: 0, failingSince: 0, nextAt: 0, ...(matched ? { fullSync: true } : { match: null }) }, link.revision)) {
+    throw new ApiError(409, 'The link changed meanwhile. Reload and try again.');
+  }
+  const next = (await repo.gcal.getLink(id))!;
+  if (matched) await catchUp(repo, next, link.pausedReason === 'restored');
+  return next;
+}
+
+/** Unlink: the pairs are forgotten, and both copies of every event stay where they are (a later link finds them again by their hidden link). */
+export async function unlink(repo: ContentRepository, id: string) {
+  await repo.gcal.deleteLink(id);
+}
+
+/** The links an event goes to now (for the editor's badge and docs). */
+export function linksFor(e: Parameters<typeof linkCarries>[0], links: GcalLink[]) {
+  return links.filter((l) => linkCarries(e, l));
+}
+export { catchUp as queueLinkCalendar };