@acms-subir/core 0.3.54 → 0.3.55

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

@@ -0,0 +1,167 @@
+// Google Calendar API v3 over fetch, modelled on the live module's request()
+// (lib/live/providers.ts): no redirects, a timeout and a response-size cap on
+// every call, quota errors with Retry-After, one token refresh per call, and
+// Google refusing the saved sign-in (invalid_grant) surfacing as "auth" so the
+// account shows "Reconnect Google". Every write passes sendUpdates=none: the
+// site never adds guests and never makes Google email anyone.
+import { z } from 'zod';
+import { readResponseJson } from '../../api';
+import { GoogleCalendarListPage, GoogleEvent, GoogleEventPage, type GcalCredentials, type GoogleCalendarEntry } from './types';
+
+export const GOOGLE_API = 'https://www.googleapis.com/calendar/v3';
+export const GOOGLE_TOKEN = 'https://oauth2.googleapis.com/token';
+export const GOOGLE_REVOKE = 'https://oauth2.googleapis.com/revoke';
+export const GOOGLE_AUTH = 'https://accounts.google.com/o/oauth2/v2/auth';
+/** see and edit events on calendars the account can edit, and list those calendars for the link picker */
+export const GOOGLE_SCOPES = ['https://www.googleapis.com/auth/calendar.events', 'https://www.googleapis.com/auth/calendar.calendarlist.readonly'];
+
+export type GoogleErrorCode = 'auth' | 'quota' | 'gone' | 'notfound' | 'conflict' | 'forbidden' | 'invalid' | 'unavailable';
+export class GoogleError extends Error {
+  constructor(public code: GoogleErrorCode, message: string, public status = 0, public retryAfter = 0) { super(message); }
+}
+
+const QUOTA = ['quotaExceeded', 'dailyLimitExceeded', 'rateLimitExceeded', 'userRateLimitExceeded', 'usageLimits', 'calendarUsageLimitsExceeded'];
+const ErrorBody = z.object({
+  error: z.union([z.string(), z.object({ message: z.string().max(2000).optional(), errors: z.array(z.object({ reason: z.string().max(200).optional() })).max(20).optional() })]).optional(),
+});
+
+function retryAfterMs(r: Response) {
+  const header = r.headers.get('retry-after');
+  const seconds = header && /^\d+$/.test(header) ? Number(header) : header ? (Date.parse(header) - Date.now()) / 1000 : 0;
+  return Math.min(86_400_000, Math.max(60_000, Number.isFinite(seconds) ? seconds * 1000 : 0));
+}
+
+async function request(url: URL | string, init: RequestInit, signal: AbortSignal, cap = 4_000_000): Promise<unknown> {
+  let r: Response;
+  try {
+    r = await fetch(url, { ...init, redirect: 'error', signal: AbortSignal.any([signal, AbortSignal.timeout(20_000)]) });
+  } catch {
+    throw new GoogleError('unavailable', 'Google didn’t answer in time. The sync tries again shortly.');
+  }
+  if (r.status === 204) { await r.body?.cancel(); return null; }
+  const body = await readResponseJson(r, cap).catch(() => null);
+  if (r.ok) {
+    if (body === null) throw new GoogleError('unavailable', 'Google sent an answer the sync couldn’t read. It tries again shortly.', r.status);
+    return body;
+  }
+  const parsed = ErrorBody.safeParse(body);
+  const error = parsed.success ? parsed.data.error : undefined;
+  const reasons = typeof error === 'object' ? (error.errors ?? []).map((e) => e.reason ?? '') : [];
+  if (r.status === 429 || (r.status === 403 && reasons.some((x) => QUOTA.includes(x)))) {
+    throw new GoogleError('quota', 'Google’s rate limit was reached. The sync waits and tries again.', r.status, retryAfterMs(r));
+  }
+  if (r.status === 401 || error === 'invalid_grant' || error === 'invalid_client' || error === 'unauthorized_client') {
+    throw new GoogleError('auth', 'Google refused the saved sign-in. Reconnect Google in Calendar settings.', r.status);
+  }
+  if (r.status === 403 && reasons.includes('forbiddenForNonOrganizer')) throw new GoogleError('forbidden', 'Google only lets the organizer change this event: someone invited the calendar to their own event.', r.status);
+  if (r.status === 403) throw new GoogleError('forbidden', 'Google says this account can’t change that calendar. Check its sharing settings, or link another calendar.', r.status);
+  if (r.status === 404) throw new GoogleError('notfound', 'Google doesn’t have that event or calendar any more.', r.status);
+  if (r.status === 410) throw new GoogleError('gone', 'Google asked for a full sync.', r.status);
+  if (r.status === 409 || r.status === 412) throw new GoogleError('conflict', 'The Google event changed meanwhile.', r.status);
+  if (r.status >= 400 && r.status < 500) {
+    // Google's own words help here ("Invalid recurrence rule"); they never carry secrets
+    const detail = typeof error === 'object' && error.message ? `: ${error.message.slice(0, 200)}` : '';
+    throw new GoogleError('invalid', `Google didn’t accept the change (HTTP ${r.status})${detail}.`, r.status);
+  }
+  throw new GoogleError('unavailable', `Google couldn’t complete the request (HTTP ${r.status}). The sync tries again shortly.`, r.status);
+}
+
+const Token = z.object({ access_token: z.string().min(1).max(8192), expires_in: z.number().positive(), refresh_token: z.string().max(8192).optional(), scope: z.string().max(4000).optional() });
+
+/** Exchanges the authorization code (with its PKCE verifier) for tokens. Both scopes and offline access are required. */
+export async function exchangeCode(clientId: string, clientSecret: string, code: string, verifier: string, callbackUrl: string, signal: AbortSignal): Promise<GcalCredentials> {
+  const token = Token.parse(await request(GOOGLE_TOKEN, { method: 'POST', body: new URLSearchParams({ client_id: clientId, client_secret: clientSecret, code, code_verifier: verifier, redirect_uri: callbackUrl, grant_type: 'authorization_code' }) }, signal, 64_000));
+  if (!token.refresh_token) throw new GoogleError('auth', 'Google didn’t give lasting access. Connect again and approve the calendar permissions.');
+  const granted = (token.scope ?? '').split(' ');
+  if (!GOOGLE_SCOPES.every((s) => granted.includes(s))) throw new GoogleError('auth', 'Google didn’t grant both calendar permissions. Connect again and leave both boxes ticked.');
+  return { clientSecret, accessToken: token.access_token, refreshToken: token.refresh_token, tokenExpiresAt: Date.now() + token.expires_in * 1000, scope: token.scope, callbackUrl };
+}
+
+/** Best effort: disconnecting always removes the local credentials. */
+export async function revokeToken(creds: GcalCredentials) {
+  const token = creds.refreshToken || creds.accessToken;
+  if (!token) return;
+  try { await fetch(GOOGLE_REVOKE, { method: 'POST', body: new URLSearchParams({ token }), redirect: 'error', signal: AbortSignal.timeout(5_000) }); } catch { /* nothing about Google in logs */ }
+}
+
+export interface ListQuery { syncToken?: string; timeMin?: string; pageToken?: string; showDeleted?: boolean }
+
+/**
+ * One account's API calls. `creds` is refreshed in place; `onTokens` saves a
+ * refreshed token (sealed) so the next run doesn't refresh again.
+ */
+export class GoogleClient {
+  private refreshed = false;
+  constructor(private clientId: string, private creds: GcalCredentials, private signal: AbortSignal, private onTokens?: (creds: GcalCredentials) => Promise<void>) {}
+
+  private async token(force = false) {
+    if (!force && this.creds.accessToken && (this.creds.tokenExpiresAt ?? 0) > Date.now() + 60_000) return this.creds.accessToken;
+    if (!this.creds.refreshToken) throw new GoogleError('auth', 'Connect Google first.');
+    const token = Token.parse(await request(GOOGLE_TOKEN, { method: 'POST', body: new URLSearchParams({ client_id: this.clientId, client_secret: this.creds.clientSecret, refresh_token: this.creds.refreshToken, grant_type: 'refresh_token' }) }, this.signal, 64_000));
+    this.creds.accessToken = token.access_token;
+    this.creds.tokenExpiresAt = Date.now() + token.expires_in * 1000;
+    if (token.refresh_token) this.creds.refreshToken = token.refresh_token;
+    await this.onTokens?.(this.creds);
+    return token.access_token;
+  }
+
+  async call(method: 'GET' | 'POST' | 'PATCH' | 'DELETE', path: string, opts: { query?: Record<string, string | undefined>; body?: unknown; cap?: number } = {}): Promise<unknown> {
+    const url = new URL(`${GOOGLE_API}${path}`);
+    for (const [k, v] of Object.entries(opts.query ?? {})) if (v !== undefined) url.searchParams.set(k, v);
+    const send = async (token: string) => request(url, {
+      method, headers: { Authorization: `Bearer ${token}`, ...(opts.body !== undefined ? { 'Content-Type': 'application/json' } : {}) },
+      ...(opts.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
+    }, this.signal, opts.cap);
+    try { return await send(await this.token()); }
+    catch (e) {
+      // an access token Google stopped taking: one refresh, never a loop
+      if (!(e instanceof GoogleError) || e.code !== 'auth' || e.status !== 401 || this.refreshed) throw e;
+      this.refreshed = true;
+      return send(await this.token(true));
+    }
+  }
+
+  /** Calendars the account can edit (owner or writer), for the link picker. */
+  async calendars(): Promise<GoogleCalendarEntry[]> {
+    const out: GoogleCalendarEntry[] = [];
+    let page: string | undefined;
+    for (let i = 0; i < 10; i++) {
+      const data = GoogleCalendarListPage.parse(await this.call('GET', '/users/me/calendarList', { query: { minAccessRole: 'writer', maxResults: '250', pageToken: page } }));
+      for (const c of data.items) {
+        if (c.deleted || !['owner', 'writer'].includes(c.accessRole ?? '')) continue;
+        out.push({ id: c.id, name: c.summaryOverride || c.summary || c.id, timeZone: c.timeZone ?? '', accessRole: c.accessRole ?? '', primary: !!c.primary, color: c.backgroundColor ?? '' });
+      }
+      page = data.nextPageToken;
+      if (!page) break;
+    }
+    return out.sort((a, b) => Number(b.primary) - Number(a.primary) || a.name.localeCompare(b.name));
+  }
+
+  /** One page of events: everything from timeMin (a full sync), or what changed since syncToken. Repeating events come as one series plus their changed dates. */
+  async listEvents(calendarId: string, q: ListQuery) {
+    return GoogleEventPage.parse(await this.call('GET', `/calendars/${encodeURIComponent(calendarId)}/events`, { query: {
+      singleEvents: 'false', maxResults: '250', showDeleted: q.syncToken || q.showDeleted ? 'true' : undefined,
+      syncToken: q.syncToken || undefined, timeMin: q.syncToken ? undefined : q.timeMin, pageToken: q.pageToken,
+    }, cap: 8_000_000 }));
+  }
+  async getEvent(calendarId: string, eventId: string) {
+    return GoogleEvent.parse(await this.call('GET', `/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(eventId)}`));
+  }
+  async insertEvent(calendarId: string, body: Record<string, unknown>) {
+    return GoogleEvent.parse(await this.call('POST', `/calendars/${encodeURIComponent(calendarId)}/events`, { query: { sendUpdates: 'none' }, body }));
+  }
+  /** Patch semantics: only the fields given change (Google keeps guests, reminders, colours, attachments and conference data). */
+  async patchEvent(calendarId: string, eventId: string, body: Record<string, unknown>) {
+    return GoogleEvent.parse(await this.call('PATCH', `/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(eventId)}`, { query: { sendUpdates: 'none' }, body }));
+  }
+  /** Deleting what's already gone counts as done. */
+  async deleteEvent(calendarId: string, eventId: string) {
+    try { await this.call('DELETE', `/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(eventId)}`, { query: { sendUpdates: 'none' } }); }
+    catch (e) { if (!(e instanceof GoogleError) || (e.code !== 'notfound' && e.code !== 'gone')) throw e; }
+  }
+  /** One date of a series by its original start (cancelled ones included), or null when the series has no such date. */
+  async instance(calendarId: string, masterId: string, originalStart: string) {
+    const data = GoogleEventPage.parse(await this.call('GET', `/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(masterId)}/instances`, { query: { originalStart, showDeleted: 'true', maxResults: '5' } }));
+    return data.items[0] ?? null;
+  }
+}

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

@@ -0,0 +1,161 @@
+// Connecting a Google account for the calendar sync: its own OAuth client
+// (in the same Google Cloud project as YouTube, if you like), so
+// disconnecting YouTube never cuts off the calendar, and the same sign-in
+// flow as the YouTube callback: a one-use sealed pending state, a callback
+// that only parks Google's code, and the signed-in admin page finishing it
+// with a same-origin POST bound to the session that began it.
+import { ApiError } from '../../api';
+import type { ContentRepository } from '../../repo/types';
+import { hash, randomToken, sealer } from '../../sealed';
+import { exchangeCode, GOOGLE_AUTH, GOOGLE_SCOPES, GoogleClient, GoogleError, revokeToken } from './client';
+import type { GcalAccount, GcalCredentials } from './types';
+import { queueLinkCalendar } from './links';
+
+/** Google Calendar credentials (lib/sealed.ts): their own key and data, never readable as live video's. */
+export const gcalSeal = sealer('gcal', 'Google Calendar credentials');
+
+/** The path Google sends the browser back to. */
+export const CALLBACK_PATH = '/api/calendar/google/oauth/callback';
+/** Where the admin finishes signing in (Calendar settings → Synced with Google). */
+export const SETTINGS_PATH = '/admin/calendar/settings';
+
+const LOOPBACK = ['localhost', '127.0.0.1', '[::1]'];
+/** The site's own origin from Settings → Site URL (HTTPS, or HTTP on localhost for development), or null when it isn't usable. */
+export function siteOriginOf(siteUrl: string): string | null {
+  const raw = siteUrl.trim();
+  if (!raw) return null;
+  try {
+    const url = new URL(raw.includes('://') ? raw : `https://${raw}`);
+    if (url.username || url.password || (url.protocol !== 'https:' && !(url.protocol === 'http:' && LOOPBACK.includes(url.hostname)))) return null;
+    return url.origin;
+  } catch { return null; }
+}
+function requireOrigin(siteUrl: string, requestUrl: URL) {
+  const origin = siteOriginOf(siteUrl);
+  if (!origin) throw new ApiError(400, 'Set the Site URL in Settings → General first (HTTPS, or localhost while developing).');
+  if (origin !== requestUrl.origin) throw new ApiError(400, `Open the admin at ${origin} (the Site URL) to connect Google.`);
+  return origin;
+}
+
+/** Saves the OAuth client. The same client ID without a secret keeps the saved secret; a new client signs the account out. */
+export async function saveGoogleClient(repo: ContentRepository, input: { clientId: string; clientSecret: string }, locals?: unknown) {
+  const clientId = input.clientId.trim(), secret = input.clientSecret.trim();
+  if (!/^[\w.-]{8,200}\.apps\.googleusercontent\.com$/.test(clientId)) throw new ApiError(400, 'Paste the client ID from Google Cloud. It ends in .apps.googleusercontent.com.');
+  const current = await repo.gcal.account();
+  if (current?.clientId === clientId && !secret) return;
+  if (!secret) throw new ApiError(400, 'Paste the client secret too.');
+  if (current) await disconnectGoogle(repo, locals);
+  await repo.gcal.saveClient(clientId, gcalSeal.encrypt({ clientSecret: secret } satisfies GcalCredentials, 'account', locals));
+}
+
+/** The Google sign-in URL for this admin session (10 minutes, one use). */
+export async function beginGoogleConnect(repo: ContentRepository, session: string, url: URL, locals?: unknown) {
+  const account = await repo.gcal.account();
+  if (!account) throw new ApiError(400, 'Save the client ID and secret first.');
+  const creds = gcalSeal.decrypt<GcalCredentials>(account.encrypted, 'account', locals);
+  if (!creds.clientSecret) throw new ApiError(400, 'Save the client secret first.');
+  const origin = requireOrigin((await repo.getSettings()).siteUrl, url);
+  const callbackUrl = `${origin}${CALLBACK_PATH}`, state = randomToken(), verifier = randomToken();
+  await repo.gcal.state(hash(state), hash(session), account.revision, gcalSeal.encrypt({ verifier, callbackUrl }, 'oauth', locals), Date.now() + 600_000);
+  const auth = new URL(GOOGLE_AUTH);
+  const params = { client_id: account.clientId, redirect_uri: callbackUrl, response_type: 'code', scope: GOOGLE_SCOPES.join(' '), access_type: 'offline',
+    prompt: 'consent select_account', state, code_challenge: Buffer.from(hash(verifier), 'hex').toString('base64url'), code_challenge_method: 'S256' };
+  for (const [k, v] of Object.entries(params)) auth.searchParams.set(k, v);
+  return auth.href;
+}
+
+type Pending = { verifier: string; callbackUrl: string; code?: string };
+/** Google's redirect back: parks the code on its pending state (no sign-in needed; only the admin who began it can finish). */
+export async function receiveGoogleCallback(repo: ContentRepository, url: URL, locals?: unknown) {
+  const state = url.searchParams.get('state') ?? '';
+  if (!/^[\w-]{43}$/.test(state)) throw new ApiError(400, 'Invalid sign-in state. Start again.');
+  if (url.searchParams.has('error')) throw new ApiError(400, 'Google sign-in wasn’t completed.');
+  const code = url.searchParams.get('code');
+  if (!code || code.length > 8192) throw new ApiError(400, 'Missing authorization code.');
+  const now = Date.now(), stored = await repo.gcal.pendingState(hash(state), now);
+  if (!stored) throw new ApiError(400, 'The sign-in expired. Start again.');
+  const pending = gcalSeal.decrypt<Pending>(stored.encrypted, 'oauth', locals);
+  if (pending.code) throw new ApiError(409, 'This sign-in already came back. Start again.');
+  if (new URL(pending.callbackUrl).origin !== url.origin) throw new ApiError(400, 'The callback address doesn’t match the site.');
+  if (!await repo.gcal.attachCode(hash(state), stored.encrypted, gcalSeal.encrypt({ ...pending, code }, 'oauth', locals), Math.min(stored.expiresAt, now + 120_000), now)) {
+    throw new ApiError(409, 'This sign-in already came back. Start again.');
+  }
+}
+
+/** The signed-in admin finishes: tokens for the parked code, the account's address and the calendars it can edit. */
+export async function finishGoogleConnect(repo: ContentRepository, session: string, url: URL, userId: string, locals?: unknown): Promise<GcalAccount> {
+  const rows = session ? await repo.gcal.consumeSessionStates(hash(session), Date.now()) : [];
+  const stored = rows.map((r) => ({ ...r, ...gcalSeal.decrypt<Pending>(r.encrypted, 'oauth', locals) })).find((r) => r.code);
+  const account = await repo.gcal.account();
+  if (!stored || !account || stored.revision !== account.revision) throw new ApiError(400, 'The sign-in expired or the Google client changed. Start again.');
+  if (new URL(stored.callbackUrl).origin !== url.origin) throw new ApiError(400, 'The callback address doesn’t match the site.');
+  const old = gcalSeal.decrypt<GcalCredentials>(account.encrypted, 'account', locals);
+  try {
+    const creds = await exchangeCode(account.clientId, old.clientSecret, stored.code!, stored.verifier, stored.callbackUrl, AbortSignal.timeout(30_000));
+    const calendars = await new GoogleClient(account.clientId, creds, AbortSignal.timeout(30_000)).calendars();
+    const primary = calendars.find((c) => c.primary)?.id ?? '';
+    const email = primary.includes('@') ? primary : '';
+    const switched = !!account.email && !!email && account.email !== email;
+    const ok = await repo.gcal.patchAccount({ encrypted: gcalSeal.encrypt(creds, 'account', locals), email, status: 'connected', error: '', siteUrl: url.origin,
+      calendars, calendarsAt: Date.now(), connectedBy: userId, connectedAt: Date.now() }, account.revision, true);
+    if (!ok) throw new ApiError(409, 'The Google connection changed meanwhile. Connect again.');
+    // reconnecting the same account picks up where Disconnect stopped (reading Google again, catching up on the
+    // site's changes); another account leaves the links paused for a person to check. Links paused by hand or
+    // after a restore stay paused.
+    if (!switched) {
+      for (const l of await repo.gcal.listLinks()) {
+        if (l.state !== 'paused' || l.pausedReason !== 'disconnected') continue;
+        await repo.gcal.patchLink(l.id, l.matchedAt ? { state: 'active', pausedReason: '', error: '', nextAt: 0, fullSync: true } : { state: 'matching', pausedReason: '', match: null }, l.revision);
+        if (l.matchedAt) await queueLinkCalendar(repo, (await repo.gcal.getLink(l.id))!);
+      }
+    }
+    return (await repo.gcal.account())!;
+  } catch (e) {
+    if (e instanceof ApiError) throw e;
+    throw new ApiError(400, e instanceof GoogleError ? e.message : 'Google didn’t finish the sign-in. Try again.');
+  }
+}
+
+/**
+ * Disconnect (or a new client replacing the old one): Google's grant is
+ * revoked (best effort) and the credentials go. Links stay, paused, and both
+ * copies of every event stay as they are.
+ */
+export async function disconnectGoogle(repo: ContentRepository, locals?: unknown) {
+  const account = await repo.gcal.account();
+  await repo.gcal.removeAccount();
+  if (account) {
+    try { await revokeToken(gcalSeal.decrypt<GcalCredentials>(account.encrypted, 'account', locals)); } catch { /* local removal still happened */ }
+  }
+}
+
+/** An API client for the connected account; refreshed tokens are saved sealed. Throws GoogleError('auth') when there's no usable sign-in. */
+export async function accountClient(repo: ContentRepository, signal: AbortSignal, locals?: unknown) {
+  const account = await repo.gcal.account();
+  if (!account || account.status === 'setup') throw new GoogleError('auth', 'Connect Google in Calendar settings first.');
+  if (account.status === 'reconnect') throw new GoogleError('auth', account.error || 'Google refused the saved sign-in. Reconnect Google in Calendar settings.');
+  let creds: GcalCredentials;
+  try { creds = gcalSeal.decrypt<GcalCredentials>(account.encrypted, 'account', locals); }
+  catch { throw new GoogleError('auth', 'The saved Google sign-in can’t be read here (the site’s secret changed). Reconnect Google.'); }
+  const client = new GoogleClient(account.clientId, creds, signal, (c) => repo.gcal.saveTokens(gcalSeal.encrypt(c, 'account', locals), account.revision));
+  return { account, client };
+}
+
+/** Google refused the sign-in: the account shows "Reconnect Google"; links wait (their changes stay queued). */
+export async function markReconnect(repo: ContentRepository, message: string) {
+  const account = await repo.gcal.account();
+  if (account && account.status === 'connected') await repo.gcal.patchAccount({ status: 'reconnect', error: message }, account.revision);
+}
+
+/** Lists the calendars the account can edit again (the link picker). */
+export async function refreshGoogleCalendars(repo: ContentRepository, locals?: unknown) {
+  try {
+    const { account, client } = await accountClient(repo, AbortSignal.timeout(30_000), locals);
+    const calendars = await client.calendars();
+    await repo.gcal.patchAccount({ calendars, calendarsAt: Date.now() }, account.revision);
+    return calendars;
+  } catch (e) {
+    if (e instanceof GoogleError && e.code === 'auth') await markReconnect(repo, e.message);
+    throw new ApiError(400, e instanceof GoogleError || e instanceof ApiError ? e.message : 'Couldn’t list the Google calendars. Try again.');
+  }
+}

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

@@ -0,0 +1,50 @@
+import type { ContentRepository } from '../../repo/types';
+import type { CalEvent, Settings } from '../../schema';
+import type { SaveHooks } from '../../content-service';
+import { I18N } from '../../i18n';
+import { siteLang } from '../../dates';
+import { eventUrl } from '../config';
+import { eventClashes } from '../../booking/holds';
+import type { GoogleClient } from './client';
+import { syncWords, type MapContext } from './map';
+import type { GcalItem, GcalLink, NewLogEntry } from './types';
+
+/** What one sync run shares: the account's client, the site's settings and origin, and the links. */
+export interface SyncContext {
+  repo: ContentRepository;
+  client: GoogleClient;
+  settings: Settings;
+  origin: string;
+  map: MapContext;
+  /** the site's own writes (side effects use the site origin) */
+  hooks: SaveHooks;
+  now: number;
+  links: GcalLink[];
+}
+
+/** The site half of a context (no Google calls): enough for "Use Google's version". */
+export function siteContext(repo: ContentRepository, settings: Settings, origin: string, locals?: unknown) {
+  const lang = (I18N.enabled && I18N.defaultLocale) || siteLang(settings);
+  return { repo, settings, origin, map: { settings, origin, pagePath: eventUrl, words: syncWords(lang) } satisfies MapContext, hooks: { url: new URL(origin), locals } satisfies SaveHooks };
+}
+
+export function syncContext(repo: ContentRepository, client: GoogleClient, settings: Settings, origin: string, links: GcalLink[], locals?: unknown, now = Date.now()): SyncContext {
+  return { ...siteContext(repo, settings, origin, locals), client, links, now };
+}
+
+/** A Recent changes entry about one pair. */
+export const entry = (link: GcalLink, item: Pick<GcalItem, 'googleId' | 'eventId'> | null, title: string, e: Omit<NewLogEntry, 'linkId' | 'googleId' | 'eventId' | 'title'>): NewLogEntry =>
+  ({ ...e, linkId: link.id, googleId: item?.googleId ?? '', eventId: item?.eventId ?? '', title });
+
+/** Room clashes after a change from Google: it applies anyway (it already happened there), and staff see the clash. */
+export async function clashNote(ctx: SyncContext, link: GcalLink, item: Pick<GcalItem, 'googleId' | 'eventId'>, e: CalEvent): Promise<NewLogEntry | null> {
+  if (e.status !== 'published' || e.cancelled || !e.roomHold.resourceIds.length) return null;
+  const { clashes } = await eventClashes(ctx.repo, ctx.settings, e, { now: ctx.now, horizonDays: 120 }).catch(() => ({ clashes: [] as Awaited<ReturnType<typeof eventClashes>>['clashes'] }));
+  if (!clashes.length) return null;
+  const rooms = new Map((await ctx.repo.listResources()).map((r) => [r.id, r.name]));
+  const first = clashes[0];
+  const room = rooms.get(first.hold.resourceId) ?? 'A room';
+  return entry(link, item, e.title, { direction: 'clash', action: 'room',
+    summary: `${room} is also held by “${first.other.title}”${clashes.length > 1 ? ` and ${clashes.length - 1} more` : ''}. The change from Google stays: check Bookings.`,
+    data: { clashes: clashes.slice(0, 10).map((c) => ({ room: rooms.get(c.hold.resourceId) ?? '', start: c.hold.eventStart, other: c.other.title, otherId: c.other.eventId })) } });
+}