@acms-subir/core 0.3.54 → 0.3.55

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

@@ -0,0 +1,241 @@
+import { randomInt } from 'node:crypto';
+import type { SqlDriver, SqlStatement } from '../../repo/sql';
+import type { Conflict, GcalAccount, GcalItem, GcalLink, GoogleCalendarEntry, Hashes, LogEntry, MatchState, NewLogEntry, PrefixRule } from './types';
+
+// Storage for the Google Calendar sync (tables: ./migration.ts). Links use
+// the live module's job fields: a claim takes a lease (90 s, so a crashed run
+// frees it), a write that holds the lease releases it, and the revision
+// rejects late results after someone edits, pauses or removes the link.
+
+type Row = Record<string, unknown>;
+const parse = <T>(raw: unknown, fallback: T): T => { try { return raw ? JSON.parse(String(raw)) as T : fallback; } catch { return fallback; } };
+const LOG_DAYS = 90;
+
+function account(r: Row): GcalAccount {
+  return { clientId: String(r.client_id), encrypted: String(r.encrypted), email: String(r.email ?? ''), status: (r.status as GcalAccount['status']) ?? 'setup',
+    error: String(r.error ?? ''), siteUrl: String(r.site_url ?? ''), calendars: parse<GoogleCalendarEntry[]>(r.calendars, []), calendarsAt: Number(r.calendars_at ?? 0),
+    connectedBy: String(r.connected_by ?? ''), connectedAt: Number(r.connected_at ?? 0), revision: Number(r.revision), updatedAt: Number(r.updated_at ?? 0) };
+}
+function link(r: Row): GcalLink {
+  return {
+    id: String(r.id), calendarId: String(r.calendar_id), googleId: String(r.google_id), googleName: String(r.google_name ?? ''), googleTz: String(r.google_tz ?? ''),
+    direction: r.direction as GcalLink['direction'], roomIds: parse<string[]>(r.room_ids, []), noRoom: !!r.no_room, rules: parse<PrefixRule[]>(r.rules, []), bookingTitles: parse<string[]>(r.booking_titles, []),
+    startDate: String(r.start_date), state: r.state as GcalLink['state'], pausedReason: String(r.paused_reason ?? ''), siteUrl: String(r.site_url),
+    matchedAt: Number(r.matched_at ?? 0), match: parse<MatchState | null>(r.match, null), syncToken: String(r.sync_token ?? ''), fullSync: !!r.full_sync,
+    lease: String(r.lease ?? ''), leaseUntil: Number(r.lease_until ?? 0), nextAt: Number(r.next_at ?? 0), failures: Number(r.failures ?? 0),
+    failingSince: Number(r.failing_since ?? 0), alertedAt: Number(r.alerted_at ?? 0), lastOkAt: Number(r.last_ok_at ?? 0), error: String(r.error ?? ''),
+    revision: Number(r.revision), createdAt: Number(r.created_at), updatedAt: Number(r.updated_at),
+  };
+}
+function item(r: Row): GcalItem {
+  return {
+    linkId: String(r.link_id), googleId: String(r.google_id), eventId: String(r.event_id), icalUid: String(r.ical_uid ?? ''), kind: r.kind as GcalItem['kind'],
+    segmentFrom: String(r.segment_from ?? ''), etag: String(r.etag ?? ''), htmlLink: String(r.html_link ?? ''), site: parse<Hashes>(r.site, {}), google: parse<Hashes>(r.google, {}),
+    // gone: 0 live, 1 deleted in Google, 2 deleted from this Google calendar only (left out)
+    descGoogle: !!r.desc_google, booking: !!r.booking, gone: !!r.gone, leftOut: Number(r.gone) === 2, conflict: parse<Conflict | null>(r.conflict, null), syncedAt: Number(r.synced_at ?? 0), createdAt: Number(r.created_at),
+  };
+}
+function logEntry(r: Row): LogEntry {
+  return { id: Number(r.id), at: Number(r.at), linkId: String(r.link_id ?? ''), eventId: String(r.event_id ?? ''), googleId: String(r.google_id ?? ''),
+    direction: r.direction as LogEntry['direction'], action: String(r.action), title: String(r.title ?? ''), summary: String(r.summary ?? ''),
+    data: parse<Record<string, unknown> | null>(r.data, null), resolved: !!r.resolved };
+}
+
+const accountColumns: Record<string, string> = { clientId: 'client_id', encrypted: 'encrypted', email: 'email', status: 'status', error: 'error', siteUrl: 'site_url',
+  calendars: 'calendars', calendarsAt: 'calendars_at', connectedBy: 'connected_by', connectedAt: 'connected_at' };
+const linkColumns: Record<string, string> = { googleName: 'google_name', googleTz: 'google_tz', direction: 'direction', roomIds: 'room_ids', noRoom: 'no_room', rules: 'rules', bookingTitles: 'booking_titles',
+  startDate: 'start_date', state: 'state', pausedReason: 'paused_reason', siteUrl: 'site_url', matchedAt: 'matched_at', match: 'match', syncToken: 'sync_token',
+  fullSync: 'full_sync', nextAt: 'next_at', failures: 'failures', failingSince: 'failing_since', alertedAt: 'alerted_at', lastOkAt: 'last_ok_at', error: 'error' };
+const itemColumns: Record<string, string> = { eventId: 'event_id', icalUid: 'ical_uid', kind: 'kind', segmentFrom: 'segment_from', etag: 'etag', htmlLink: 'html_link',
+  site: 'site', google: 'google', descGoogle: 'desc_google', booking: 'booking', gone: 'gone', conflict: 'conflict', syncedAt: 'synced_at' };
+const jsonish = new Set(['calendars', 'roomIds', 'rules', 'bookingTitles', 'match', 'site', 'google', 'conflict']);
+const goneValue = (i: Pick<GcalItem, 'gone' | 'leftOut'>) => (i.gone ? (i.leftOut ? 2 : 1) : 0);
+function sets(data: Record<string, unknown>, columns: Record<string, string>) {
+  if ('leftOut' in data && data.leftOut !== undefined) data = { ...data, gone: goneValue({ gone: data.gone !== undefined ? !!data.gone : true, leftOut: !!data.leftOut }) };
+  const entries = Object.entries(data).filter(([k, v]) => columns[k] && v !== undefined);
+  return { sql: entries.map(([k]) => `${columns[k]}=?`), args: entries.map(([k, v]) => jsonish.has(k) ? (v === null ? null : JSON.stringify(v)) : typeof v === 'boolean' ? Number(v) : v) };
+}
+
+export interface QueueRow { eventId: string; version: number; attempts: number }
+
+export class GcalStore {
+  constructor(private driver: () => Promise<SqlDriver>) {}
+  private async db() { return this.driver(); }
+
+  // ---- the connected account ----
+  async account() { const r = (await (await this.db()).all('SELECT * FROM gcal_account WHERE id=1'))[0]; return r ? account(r) : null; }
+  /** Saves the OAuth client (a new client signs out: status setup). A fresh random revision invalidates any sign-in in progress. */
+  async saveClient(clientId: string, encrypted: string, now = Date.now()) {
+    await (await this.db()).run(`INSERT INTO gcal_account (id,client_id,encrypted,status,revision,updated_at) VALUES (1,?,?,'setup',?,?)
+      ON CONFLICT(id) DO UPDATE SET client_id=excluded.client_id,encrypted=excluded.encrypted,status='setup',error='',email='',calendars='[]',calendars_at=0,
+      connected_by='',connected_at=0,revision=revision+1,updated_at=excluded.updated_at`, [clientId, encrypted, randomInt(1, 2 ** 48 - 1), now]);
+  }
+  /** Changes the account if its revision still matches; `bump` invalidates sign-ins in progress. */
+  async patchAccount(data: Partial<GcalAccount>, revision: number, bump = false) {
+    const s = sets(data, accountColumns);
+    if (!s.sql.length) return false;
+    const rows = await (await this.db()).all(`UPDATE gcal_account SET ${s.sql.join(',')},updated_at=?${bump ? ',revision=revision+1' : ''} WHERE id=1 AND revision=? RETURNING id`, [...s.args, Date.now(), revision]);
+    return rows.length > 0;
+  }
+  /** Saves refreshed tokens without touching anything else (several links may refresh in one run). */
+  async saveTokens(encrypted: string, revision: number) {
+    await (await this.db()).run('UPDATE gcal_account SET encrypted=? WHERE id=1 AND revision=?', [encrypted, revision]);
+  }
+  /** Disconnect: the account and pending sign-ins go; links stay, paused, and so do both copies of every event. */
+  async removeAccount() {
+    await (await this.db()).batch([
+      { sql: 'DELETE FROM gcal_account WHERE id=1' },
+      { sql: 'DELETE FROM gcal_oauth_states' },
+      // links already paused (by hand, after a restore) keep their reason
+      { sql: "UPDATE gcal_links SET state='paused',paused_reason='disconnected',lease='',lease_until=0,revision=revision+1,updated_at=? WHERE state<>'paused'", args: [Date.now()] },
+    ]);
+  }
+
+  // ---- one-use pending sign-ins (same contract as LiveStore's) ----
+  async state(hash: string, sessionHash: string, revision: number, encrypted: string, expiresAt: number) {
+    await (await this.db()).batch([{ sql: 'DELETE FROM gcal_oauth_states WHERE expires_at<? OR session_hash=?', args: [Date.now(), sessionHash] },
+      { sql: 'INSERT INTO gcal_oauth_states (hash,session_hash,revision,encrypted,expires_at) VALUES (?,?,?,?,?)', args: [hash, sessionHash, revision, encrypted, expiresAt] }]);
+  }
+  async pendingState(hash: string, now: number) {
+    const r = (await (await this.db()).all('SELECT encrypted,expires_at FROM gcal_oauth_states WHERE hash=? AND expires_at>?', [hash, now]))[0];
+    return r ? { encrypted: String(r.encrypted), expiresAt: Number(r.expires_at) } : null;
+  }
+  /** Compare-and-swap on the old ciphertext: only the first callback counts. */
+  async attachCode(hash: string, before: string, after: string, expiresAt: number, now: number) {
+    return (await (await this.db()).all('UPDATE gcal_oauth_states SET encrypted=?,expires_at=? WHERE hash=? AND encrypted=? AND expires_at>? RETURNING hash', [after, expiresAt, hash, before, now])).length > 0;
+  }
+  async consumeSessionStates(sessionHash: string, now: number) {
+    const rows = await (await this.db()).all('DELETE FROM gcal_oauth_states WHERE session_hash=? AND expires_at>? RETURNING revision,encrypted', [sessionHash, now]);
+    return rows.map((r) => ({ revision: Number(r.revision), encrypted: String(r.encrypted) }));
+  }
+
+  // ---- links ----
+  async listLinks() { return (await (await this.db()).all('SELECT * FROM gcal_links ORDER BY created_at, id')).map(link); }
+  async getLink(id: string) { const r = (await (await this.db()).all('SELECT * FROM gcal_links WHERE id=?', [id]))[0]; return r ? link(r) : null; }
+  async createLink(data: Pick<GcalLink, 'calendarId' | 'googleId' | 'googleName' | 'googleTz' | 'direction' | 'roomIds' | 'noRoom' | 'rules' | 'bookingTitles' | 'startDate' | 'siteUrl'>, now = Date.now()) {
+    const id = crypto.randomUUID();
+    await (await this.db()).run(`INSERT INTO gcal_links (id,calendar_id,google_id,google_name,google_tz,direction,room_ids,no_room,rules,booking_titles,start_date,site_url,revision,created_at,updated_at)
+      VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`, [id, data.calendarId, data.googleId, data.googleName, data.googleTz, data.direction, JSON.stringify(data.roomIds),
+      data.noRoom ? 1 : 0, JSON.stringify(data.rules), JSON.stringify(data.bookingTitles), data.startDate, data.siteUrl, randomInt(1, 2 ** 48 - 1), now, now]);
+    return (await this.getLink(id))!;
+  }
+  /**
+   * Writes link fields if the revision still matches. With the lease (a sync run finishing) the
+   * revision stays and the lease is released; without it (a person's change) the revision moves on,
+   * so a run still in flight can't write its late result over the change.
+   */
+  async patchLink(id: string, data: Partial<GcalLink>, revision: number, lease?: string) {
+    const s = sets(data, linkColumns);
+    const rows = await (await this.db()).all(`UPDATE gcal_links SET ${[...s.sql, 'updated_at=?'].join(',')},${lease ? "lease='',lease_until=0" : 'revision=revision+1'}
+      WHERE id=? AND revision=?${lease ? ' AND lease=?' : ''} RETURNING id`, [...s.args, Date.now(), id, revision, ...(lease ? [lease] : [])]);
+    return rows.length > 0;
+  }
+  /**
+   * Takes the link for one run: an active link that is due, or (forced: "Sync now", "Start syncing") any link that isn't paused.
+   * The lease outlasts a run's Google calls (110 s), so a second run can't take the link while the first is still working.
+   */
+  async claimLink(id: string, now: number, force = false) {
+    const lease = crypto.randomUUID();
+    const rows = await (await this.db()).all(`UPDATE gcal_links SET lease=?,lease_until=? WHERE id=? AND lease_until<=?
+      AND ${force ? "state<>'paused'" : "state='active' AND next_at<=?"} RETURNING *`, force ? [lease, now + 150_000, id, now] : [lease, now + 150_000, id, now, now]);
+    return rows[0] ? link(rows[0]) : null;
+  }
+  /** Unlink: the pairs go, both copies of every event stay. Recent changes are kept. */
+  async deleteLink(id: string) {
+    await (await this.db()).batch([{ sql: 'DELETE FROM gcal_items WHERE link_id=?', args: [id] }, { sql: 'DELETE FROM gcal_links WHERE id=?', args: [id] }]);
+  }
+  /** Restore: every link waits for someone to check it, and changes queued before it describe content it replaced. */
+  static restoreStatements(): SqlStatement[] {
+    return [
+      { sql: "UPDATE gcal_links SET state='paused',paused_reason='restored',lease='',lease_until=0,revision=revision+1" },
+      { sql: 'DELETE FROM gcal_queue' },
+      { sql: 'DELETE FROM gcal_oauth_states' },
+    ];
+  }
+
+  // ---- pairs ----
+  async itemsForLink(linkId: string) { return (await (await this.db()).all('SELECT * FROM gcal_items WHERE link_id=?', [linkId])).map(item); }
+  async itemsForEvent(eventId: string) { return (await (await this.db()).all('SELECT * FROM gcal_items WHERE event_id=?', [eventId])).map(item); }
+  async getItem(linkId: string, googleId: string) { const r = (await (await this.db()).all('SELECT * FROM gcal_items WHERE link_id=? AND google_id=?', [linkId, googleId]))[0]; return r ? item(r) : null; }
+  async countItems() {
+    const rows = await (await this.db()).all('SELECT link_id, COUNT(*) AS n FROM gcal_items WHERE gone=0 GROUP BY link_id');
+    return new Map(rows.map((r) => [String(r.link_id), Number(r.n)]));
+  }
+  async putItem(i: GcalItem) {
+    await (await this.db()).run(`INSERT INTO gcal_items (link_id,google_id,event_id,ical_uid,kind,segment_from,etag,html_link,site,google,desc_google,booking,gone,conflict,synced_at,created_at)
+      VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?) ON CONFLICT(link_id,google_id) DO UPDATE SET event_id=excluded.event_id,ical_uid=excluded.ical_uid,kind=excluded.kind,
+      segment_from=excluded.segment_from,etag=excluded.etag,html_link=excluded.html_link,site=excluded.site,google=excluded.google,desc_google=excluded.desc_google,
+      booking=excluded.booking,gone=excluded.gone,conflict=excluded.conflict,synced_at=excluded.synced_at`,
+    [i.linkId, i.googleId, i.eventId, i.icalUid, i.kind, i.segmentFrom, i.etag, i.htmlLink, JSON.stringify(i.site), JSON.stringify(i.google), i.descGoogle ? 1 : 0,
+      i.booking ? 1 : 0, goneValue(i), i.conflict ? JSON.stringify(i.conflict) : null, i.syncedAt, i.createdAt]);
+  }
+  async patchItem(linkId: string, googleId: string, data: Partial<GcalItem>) {
+    const s = sets(data, itemColumns);
+    if (s.sql.length) await (await this.db()).run(`UPDATE gcal_items SET ${s.sql.join(',')} WHERE link_id=? AND google_id=?`, [...s.args, linkId, googleId]);
+  }
+  /** The Google copy was made again (a new Google id): one write, so the pair is never lost in between. */
+  async replaceItem(oldGoogleId: string, next: GcalItem) {
+    await (await this.db()).batch([
+      { sql: 'DELETE FROM gcal_items WHERE link_id=? AND google_id=?', args: [next.linkId, oldGoogleId] },
+      { sql: `INSERT INTO gcal_items (link_id,google_id,event_id,ical_uid,kind,segment_from,etag,html_link,site,google,desc_google,booking,gone,conflict,synced_at,created_at)
+        VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`, args: [next.linkId, next.googleId, next.eventId, next.icalUid, next.kind, next.segmentFrom, next.etag, next.htmlLink,
+        JSON.stringify(next.site), JSON.stringify(next.google), next.descGoogle ? 1 : 0, next.booking ? 1 : 0, goneValue(next), next.conflict ? JSON.stringify(next.conflict) : null, next.syncedAt, next.createdAt] },
+    ]);
+  }
+  async deleteItem(linkId: string, googleId: string) { await (await this.db()).run('DELETE FROM gcal_items WHERE link_id=? AND google_id=?', [linkId, googleId]); }
+
+  // ---- the outgoing queue ----
+  /** Due events, oldest first, each held for `leaseMs` (another run skips them meanwhile). */
+  async claimQueue(now: number, limit: number, leaseMs: number): Promise<QueueRow[]> {
+    const rows = await (await this.db()).all(`UPDATE gcal_queue SET claimed_until=?,attempts=attempts+1 WHERE event_id IN (
+      SELECT event_id FROM gcal_queue WHERE due_at<=? AND claimed_until<=? ORDER BY due_at LIMIT ?) RETURNING event_id,version,attempts`, [now + leaseMs, now, now, limit]);
+    return rows.map((r) => ({ eventId: String(r.event_id), version: Number(r.version), attempts: Number(r.attempts) }));
+  }
+  /** Done with the change it claimed; a newer change to the same event (version moved on) stays queued, free for the next run. */
+  async finishQueue(eventId: string, version: number) {
+    await (await this.db()).batch([
+      { sql: 'DELETE FROM gcal_queue WHERE event_id=? AND version=?', args: [eventId, version] },
+      { sql: 'UPDATE gcal_queue SET claimed_until=0 WHERE event_id=?', args: [eventId] },
+    ]);
+  }
+  async retryQueue(eventId: string, version: number, at: number, error: string) {
+    await (await this.db()).batch([
+      { sql: 'UPDATE gcal_queue SET due_at=?,claimed_until=0,error=? WHERE event_id=? AND version=?', args: [at, error.slice(0, 500), eventId, version] },
+      { sql: 'UPDATE gcal_queue SET claimed_until=0 WHERE event_id=? AND version<>?', args: [eventId, version] },
+    ]);
+  }
+  /** Queues events by hand (a link starting or resuming catches up on its calendar). */
+  async enqueue(eventIds: string[], now = Date.now()) {
+    const stmts = [...new Set(eventIds)].map((id) => ({ sql: `INSERT INTO gcal_queue (event_id,version,due_at,attempts,claimed_until,error) VALUES (?,1,?,0,0,'')
+      ON CONFLICT(event_id) DO UPDATE SET version=version+1,due_at=excluded.due_at,attempts=0,error=''`, args: [id, now] as unknown[] }));
+    const db = await this.db();
+    for (let i = 0; i < stmts.length; i += 100) await db.batch(stmts.slice(i, i + 100));
+  }
+  async queueStats(now = Date.now()) {
+    const r = (await (await this.db()).all("SELECT COUNT(*) AS n, SUM(CASE WHEN error<>'' THEN 1 ELSE 0 END) AS failing, MIN(due_at) AS oldest FROM gcal_queue"))[0];
+    return { waiting: Number(r?.n ?? 0), failing: Number(r?.failing ?? 0), oldestMs: r?.oldest ? Math.max(0, now - Number(r.oldest)) : 0 };
+  }
+
+  // ---- Recent changes ----
+  async log(entries: NewLogEntry[], now = Date.now()) {
+    const db = await this.db();
+    const ids: number[] = [];
+    for (const e of entries) {
+      const r = (await db.all(`INSERT INTO gcal_log (at,link_id,event_id,google_id,direction,action,title,summary,data) VALUES (?,?,?,?,?,?,?,?,?) RETURNING id`,
+        [e.at ?? now, e.linkId ?? '', e.eventId ?? '', e.googleId ?? '', e.direction, e.action, (e.title ?? '').slice(0, 300), (e.summary ?? '').slice(0, 1000), e.data ? JSON.stringify(e.data) : null]))[0];
+      ids.push(Number(r?.id ?? 0));
+    }
+    return ids;
+  }
+  async listLog(q: { linkId?: string; eventId?: string; limit?: number; before?: number } = {}) {
+    const where: string[] = [], args: unknown[] = [];
+    if (q.linkId) { where.push('link_id=?'); args.push(q.linkId); }
+    if (q.eventId) { where.push('event_id=?'); args.push(q.eventId); }
+    if (q.before) { where.push('id<?'); args.push(q.before); }
+    const rows = await (await this.db()).all(`SELECT * FROM gcal_log${where.length ? ` WHERE ${where.join(' AND ')}` : ''} ORDER BY at DESC, id DESC LIMIT ?`, [...args, Math.min(500, q.limit ?? 50)]);
+    return rows.map(logEntry);
+  }
+  async getLog(id: number) { const r = (await (await this.db()).all('SELECT * FROM gcal_log WHERE id=?', [id]))[0]; return r ? logEntry(r) : null; }
+  async resolveLog(id: number) { await (await this.db()).run('UPDATE gcal_log SET resolved=1 WHERE id=?', [id]); }
+  async purgeLog(now = Date.now()) { await (await this.db()).run('DELETE FROM gcal_log WHERE at<?', [now - LOG_DAYS * 86_400_000]); }
+}

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

@@ -0,0 +1,188 @@
+import { z } from 'zod';
+
+// Two-way Google Calendar sync: the stored records (lib/calendar/google/store.ts)
+// and the parts of Google's API responses the sync reads.
+
+/** both ways; site → Google only; Google → site only */
+export const Direction = z.enum(['both', 'out', 'in']);
+export type Direction = z.infer<typeof Direction>;
+
+/** A title prefix ⇄ a site tag ("CLASS:" ⇄ Class), both ways, the prefix kept in the title on both sides. */
+export const PrefixRule = z.object({
+  prefix: z.string().trim().min(1).max(40),
+  tag: z.string().trim().min(1).max(80),
+}).strict();
+export type PrefixRule = z.infer<typeof PrefixRule>;
+
+/** One Google calendar the connected account can edit (from calendarList). */
+export interface GoogleCalendarEntry { id: string; name: string; timeZone: string; accessRole: string; primary: boolean; color: string }
+
+export interface GcalAccount {
+  clientId: string;
+  /** sealed GcalCredentials */
+  encrypted: string;
+  /** the account's address (its primary calendar id), once connected */
+  email: string;
+  /** setup: client saved, not signed in; connected; reconnect: Google refused the saved sign-in */
+  status: 'setup' | 'connected' | 'reconnect';
+  error: string;
+  /** the site origin it was connected on */
+  siteUrl: string;
+  calendars: GoogleCalendarEntry[];
+  calendarsAt: number;
+  connectedBy: string;
+  connectedAt: number;
+  revision: number;
+  updatedAt: number;
+}
+export interface GcalCredentials { clientSecret: string; accessToken?: string; refreshToken?: string; tokenExpiresAt?: number; scope?: string; callbackUrl?: string }
+
+/** The first-match review, saved on the link until "Start syncing" (lib/calendar/google/match.ts). */
+export interface MatchPair {
+  eventId: string;
+  googleId: string;
+  /** why they were paired: the hidden id, the imported UID, or title and time */
+  reason: 'hidden-id' | 'uid' | 'title-time' | 'time-repeat';
+  /** linked (sure, or confirmed), suggested (waits for a person), apart ("Not the same") */
+  state: 'linked' | 'suggested' | 'apart';
+}
+/** What the review page shows about a Google event (it isn't fetched again for every page view). */
+export interface MatchGoogle { title: string; start: number; allDay: boolean; repeats: boolean; booking: boolean }
+export interface MatchState { builtAt: number; pairs: MatchPair[]; siteOnly: string[]; googleOnly: string[]; google: Record<string, MatchGoogle> }
+
+export interface GcalLink {
+  id: string;
+  /** the site calendar */
+  calendarId: string;
+  /** the Google calendar */
+  googleId: string;
+  googleName: string;
+  googleTz: string;
+  direction: Direction;
+  /** the rooms this Google calendar stands for: its events hold them, and site events holding them go here */
+  roomIds: string[];
+  /** also gets the site calendar's events that hold no room */
+  noRoom: boolean;
+  rules: PrefixRule[];
+  /** titles of the Google calendar's booking pages (appointment schedules): booked appointments come in as "Booked" (Q16) */
+  bookingTitles: string[];
+  /** YYYY-MM-DD: events from this date on, plus repeating series still running */
+  startDate: string;
+  /** matching: waiting for the first-match review; active; paused (pausedReason says why) */
+  state: 'matching' | 'active' | 'paused';
+  pausedReason: string;
+  /** the site origin that made the link: it only runs there */
+  siteUrl: string;
+  /** when "Start syncing" ran (0 = never: resuming goes back to matching) */
+  matchedAt: number;
+  match: MatchState | null;
+  syncToken: string;
+  /** the next read lists everything (first run, Google's 410, a resume): quiet, pairs by hidden id first */
+  fullSync: boolean;
+  lease: string;
+  leaseUntil: number;
+  nextAt: number;
+  failures: number;
+  failingSince: number;
+  alertedAt: number;
+  lastOkAt: number;
+  error: string;
+  revision: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+/** hashes of each synced field (lib/calendar/google/map.ts fieldHashes) */
+export type Hashes = Record<string, string>;
+
+/** The latest field both sides changed, until someone picks a version or edits it again (sent: the site's value has gone to Google since). */
+export interface Conflict { field: string; at: number; site: string; google: string; logId: number; sent?: boolean }
+
+export interface GcalItem {
+  linkId: string;
+  googleId: string;
+  eventId: string;
+  icalUid: string;
+  /** series (repeating), single, or segment: a later part from Google's "this and following" (C4 takes these over) */
+  kind: 'series' | 'single' | 'segment';
+  /** segment: the occurrence key it takes over from */
+  segmentFrom: string;
+  etag: string;
+  htmlLink: string;
+  /** each side's fields as last agreed */
+  site: Hashes;
+  google: Hashes;
+  /** created in Google and its description never edited on the site: Google's description is used (Q8) */
+  descGoogle: boolean;
+  /** a booked appointment from a Google booking page: Google's, never written back */
+  booking: boolean;
+  /** the Google copy was deleted in Google: not recreated unless the event comes back on the site */
+  gone: boolean;
+  /** (with gone) deleted from this Google calendar only, while the event stays in its other linked copies: it stays out of this one */
+  leftOut: boolean;
+  conflict: Conflict | null;
+  syncedAt: number;
+  createdAt: number;
+}
+
+export type LogDirection = 'in' | 'out' | 'clash' | 'info';
+export interface LogEntry {
+  id: number;
+  at: number;
+  linkId: string;
+  eventId: string;
+  googleId: string;
+  direction: LogDirection;
+  action: string;
+  title: string;
+  /** what changed, in words */
+  summary: string;
+  /** before/after values; a clash keeps Google's value for "Use Google's version" */
+  data: Record<string, unknown> | null;
+  resolved: boolean;
+}
+export type NewLogEntry = Pick<LogEntry, 'direction' | 'action'> & Partial<Pick<LogEntry, 'at' | 'linkId' | 'eventId' | 'googleId' | 'data' | 'title' | 'summary'>>;
+
+// ---- Google's API (only what the sync reads; unknown fields are dropped) ----
+
+const text = (max: number) => z.string().max(max);
+export const GoogleTime = z.object({ date: text(20).optional(), dateTime: text(40).optional(), timeZone: text(100).optional() });
+export type GoogleTime = z.infer<typeof GoogleTime>;
+const Person = z.object({ email: text(320).optional(), displayName: text(500).optional(), self: z.boolean().optional() });
+export const GoogleEvent = z.object({
+  id: text(1024),
+  status: text(20).optional(),
+  etag: text(200).optional(),
+  htmlLink: text(2048).optional(),
+  summary: text(8192).optional(),
+  description: text(65536).optional(),
+  location: text(8192).optional(),
+  start: GoogleTime.optional(),
+  end: GoogleTime.optional(),
+  originalStartTime: GoogleTime.optional(),
+  recurringEventId: text(1024).optional(),
+  recurrence: z.array(text(8192)).max(100).optional(),
+  iCalUID: text(1024).optional(),
+  eventType: text(40).optional(),
+  updated: text(40).optional(),
+  created: text(40).optional(),
+  organizer: Person.optional(),
+  creator: Person.optional(),
+  attendees: z.array(Person.extend({ organizer: z.boolean().optional(), resource: z.boolean().optional() })).max(1000).optional(),
+  extendedProperties: z.object({ private: z.record(text(1024)).optional(), shared: z.record(text(1024)).optional() }).optional(),
+  source: z.object({ url: text(2048).optional(), title: text(1000).optional() }).optional(),
+});
+export type GoogleEvent = z.infer<typeof GoogleEvent>;
+export const GoogleEventPage = z.object({
+  items: z.array(GoogleEvent).max(2500).default([]),
+  nextPageToken: text(4096).optional(),
+  nextSyncToken: text(4096).optional(),
+  timeZone: text(100).optional(),
+});
+export const GoogleCalendarListPage = z.object({
+  items: z.array(z.object({
+    id: text(1024), summary: text(1000).optional(), summaryOverride: text(1000).optional(), timeZone: text(100).optional(),
+    accessRole: text(40).optional(), primary: z.boolean().optional(), backgroundColor: text(20).optional(), deleted: z.boolean().optional(),
+  })).max(250).default([]),
+  nextPageToken: text(4096).optional(),
+});

package/src/lib/calendar/schedule.ts

@@ -194,7 +194,7 @@ export async function undoMove(repo: ContentRepository, actor: MoveActor, undo:
 // checks: callers (admin actions, site code through @acms-subir/core/server)
 // decide who may do this.
 
-async function setOccurrenceCancelled(repo: ContentRepository, id: string, key: string, cancel: boolean, hooks: SaveHooks, now = Date.now()): Promise<CalEvent> {
+async function setOccurrenceCancelled(repo: ContentRepository, id: string, key: string, cancel: boolean, hooks: SaveHooks, now = Date.now(), opts: { quiet?: boolean } = {}): Promise<CalEvent> {
   const e = await repo.getEvent(id);
   if (!e) throw new ApiError(404, 'Event not found.');
   // error.code as for moves (lib/calendar/moves.ts MoveRefusal)
@@ -210,22 +210,22 @@ async function setOccurrenceCancelled(repo: ContentRepository, id: string, key:
   // a date is moved or cancelled, never both: cancelling a moved date drops its move (its RSVPs, at the new time, are cancelled below)
   if (cancel && Object.hasOwn(e.movedDates, key)) {
     const { [key]: _moved, ...moved } = e.movedDates;
-    await repo.setEventMovedDates(id, moved, cancelledDates);
-  } else await repo.setEventCancelledDates(id, cancelledDates);
+    await repo.setEventMovedDates(id, moved, cancelledDates, opts);
+  } else await repo.setEventCancelledDates(id, cancelledDates, opts);
   if (cancel && await repo.cancelOccurrenceRsvps(id, o.start)) await kickEmail(repo, hooks.locals, waitUntilFrom(hooks.locals));
   const after = (await repo.getEvent(id))!;
   await eventSideEffects(repo, hooks, after);
   return after;
 }
 
-/** Cancel one date of a repeating event, at once (also on a published event). Idempotent. */
-export function cancelOccurrence(repo: ContentRepository, id: string, key: string, hooks: SaveHooks, now?: number): Promise<CalEvent> {
-  return setOccurrenceCancelled(repo, id, key, true, hooks, now);
+/** Cancel one date of a repeating event, at once (also on a published event). Idempotent. quiet: no app notice (RSVP emails still go). */
+export function cancelOccurrence(repo: ContentRepository, id: string, key: string, hooks: SaveHooks, now?: number, opts?: { quiet?: boolean }): Promise<CalEvent> {
+  return setOccurrenceCancelled(repo, id, key, true, hooks, now, opts);
 }
 
 /** Undo cancelOccurrence for one date. Idempotent. */
-export function restoreOccurrence(repo: ContentRepository, id: string, key: string, hooks: SaveHooks, now?: number): Promise<CalEvent> {
-  return setOccurrenceCancelled(repo, id, key, false, hooks, now);
+export function restoreOccurrence(repo: ContentRepository, id: string, key: string, hooks: SaveHooks, now?: number, opts?: { quiet?: boolean }): Promise<CalEvent> {
+  return setOccurrenceCancelled(repo, id, key, false, hooks, now, opts);
 }
 
 export async function duplicateEvent(repo: ContentRepository, id: string): Promise<CalEvent> {

package/src/lib/display/board.ts

@@ -18,7 +18,9 @@ import { renderBoard, type DisplayItem, type DisplayModel, type DisplayRoom } fr
 import { displayStrings, isBookedWord } from './words';
 import { qrSvg } from './http';
 
-export const GOOGLE_BOOKING_TAG = '#google-booking';
+// booked appointments from Google booking pages (lib/calendar/google/map.ts)
+export { BOOKING_TAG as GOOGLE_BOOKING_TAG } from '../calendar/google/map';
+import { BOOKING_TAG as GOOGLE_BOOKING_TAG } from '../calendar/google/map';
 const pad = (n: number) => String(n).padStart(2, '0');
 const isoOf = (p: { y: number; m: number; d: number }) => `${p.y}-${pad(p.m)}-${pad(p.d)}`;
 

package/src/lib/email/service.ts

@@ -1,7 +1,7 @@
 import type { ContentRepository } from '../repo/types';
 import { resolveConfig, decrypt, encrypt, runtimeValue } from './config';
 import { sendWithProvider } from './providers';
-import { accountMail, canonicalOrigin, eventRequestMail, guestCodeMail, phoneLinkedMail, EmailLinkError, type EventRequestMailKind } from './templates';
+import { accountMail, canonicalOrigin, eventRequestMail, googleSyncAlertMail, guestCodeMail, phoneLinkedMail, EmailLinkError, type EventRequestMailKind } from './templates';
 import { formatDate, siteLang } from '../dates';
 import { I18N } from '../i18n';
 import { bookingMail } from '../booking/service';
@@ -73,6 +73,16 @@ async function render(repo: ContentRepository, job: EmailJob, locals?: unknown,
     const url = staff ? `${origin}/admin/calendar/events/${e.id}` : `${origin}${MEMBERS.enabled ? memberEventsPath() : '/'}`;
     return eventRequestMail(p.kind, job.recipient, settings.siteTitle, { title: e.title, when: formatDate(e.startAt, settings), by: by?.name ?? '', note: e.request?.note ?? '' }, p.reply, url);
   }
+  if (job.kind === 'gcal-alert') {
+    // only while that link is still failing since the same time
+    const p = JSON.parse(job.payload) as { linkId: string; since: number };
+    const link = await repo.gcal.getLink(p.linkId);
+    if (!link || link.state !== 'active' || link.failingSince !== p.since) return null;
+    let since: string;
+    try { since = new Intl.DateTimeFormat(siteLang(settings), { dateStyle: 'medium', timeStyle: 'short', timeZone: settings.timezone || 'UTC' }).format(p.since); }
+    catch { since = new Date(p.since).toISOString(); }
+    return googleSyncAlertMail(job.recipient, settings.siteTitle, { google: link.googleName, error: link.error, since }, `${origin}/admin/calendar/settings#google`);
+  }
   if (job.kind === 'welcome' || job.kind === 'password-changed') return accountMail(job.kind, job.recipient, settings.siteTitle, `${origin}/admin/login`);
   if (job.kind === 'email-changed') return accountMail(job.kind, job.recipient, settings.siteTitle);
   return null;

package/src/lib/email/templates.ts

@@ -38,6 +38,14 @@ export function eventRequestMail(kind: EventRequestMailKind, to: string, site: s
   return { to, subject: `${copy[0]} · ${site}`, text: [copy[0], '', copy[1], ...(extra ? ['', extra] : []), '', `${copy[2]}: ${url}`].join('\n'),
     html: `<!doctype html><html><body style="margin:0;background:#f6f5f2;color:#24211c;font:16px/1.6 system-ui,sans-serif"><div style="max-width:520px;margin:auto;padding:32px 24px"><p style="color:#7d776e">${escape(site)}</p><h1 style="font-size:22px">${escape(copy[0])}</h1><p>${escape(copy[1])}</p>${extra ? `<p style="background:#efebe4;border-radius:8px;padding:10px 12px">${escape(extra)}</p>` : ''}<p><a style="display:inline-block;background:#ee5d20;color:#fff;padding:10px 18px;border-radius:8px;text-decoration:none" href="${escape(url)}">${escape(copy[2])}</a></p></div></body></html>` };
 }
+/** staff: a Google Calendar link has been failing for an hour (lib/calendar/google/service.ts) */
+export function googleSyncAlertMail(to: string, site: string, link: { google: string; error: string; since: string }, url: string): Mail {
+  const subject = `Google Calendar sync stopped: ${link.google}`;
+  const intro = `The site hasn’t been able to sync with “${link.google}” since ${link.since}. Changes on either side wait until it works again; nothing is lost.`;
+  const reason = link.error ? `Google said: ${link.error}` : '';
+  return { to, subject: `${subject} · ${site}`, text: [subject, '', intro, ...(reason ? ['', reason] : []), '', `Check it in Calendar settings: ${url}`].join('\n'),
+    html: `<!doctype html><html><body style="margin:0;background:#f6f5f2;color:#24211c;font:16px/1.6 system-ui,sans-serif"><div style="max-width:520px;margin:auto;padding:32px 24px"><p style="color:#7d776e">${escape(site)}</p><h1 style="font-size:22px">${escape(subject)}</h1><p>${escape(intro)}</p>${reason ? `<p style="background:#efebe4;border-radius:8px;padding:10px 12px">${escape(reason)}</p>` : ''}<p><a style="display:inline-block;background:#ee5d20;color:#fff;padding:10px 18px;border-radius:8px;text-decoration:none" href="${escape(url)}">Open Calendar settings</a></p></div></body></html>` };
+}
 /** a guest's app sign-in code; no link, so it works on any device */
 export function guestCodeMail(to: string, site: string, code: string): Mail {
   const intro = `Enter this code in the ${site} app to see your bookings. It expires in 10 minutes. If you did not ask for it, ignore this message.`;

package/src/lib/legal/admin.ts

@@ -40,7 +40,7 @@ export async function legalAdminState(repo: ContentRepository, url: URL, locals?
     updated: LEGAL.enabled ? { privacy: await policyUpdated(repo, 'privacy', facts, settings), terms: await policyUpdated(repo, 'terms', facts, settings) } : null,
     covers: {
       calendar: facts.calendar, bookings: facts.bookings, guestSignIn: facts.guestSignIn, push: facts.push.enabled, auth: facts.auth,
-      email: facts.email, maps: facts.maps, live: facts.live, analytics: facts.analytics, ai: facts.ai,
+      email: facts.email, maps: facts.maps, live: facts.live, googleCalendar: facts.googleCalendar, analytics: facts.analytics, ai: facts.ai,
     },
     warnings,
     answers: appPrivacyAnswers(facts, link('privacy') ?? `${origin}/privacy`),

package/src/lib/legal/facts.ts

@@ -40,6 +40,8 @@ export interface LegalFacts {
   /** maps provider name, or '' */
   maps: string;
   live: boolean;
+  /** a Google account is connected for the two-way Google Calendar sync (lib/calendar/google/) */
+  googleCalendar: boolean;
   /** acms({ announcements }): urgent ones reach every device; read and closed state stays in the app */
   announcements: boolean;
   analytics: { umami: boolean; replay: boolean; meta: boolean; tiktok: boolean };
@@ -82,6 +84,7 @@ export async function legalFacts(repo: ContentRepository, settings: Settings, lo
     email: email && !email.error && email.provider !== 'none' && email.config.enabled ? EMAIL_NAMES[email.provider] ?? email.provider : '',
     maps: (() => { const m = mapsStatus(locals); return m.enabled ? m.label.replace(/ \(self-hosted\)$/, '') : ''; })(),
     live: settings.live.mode !== 'off',
+    googleCalendar: CALENDAR.enabled && await repo.gcal.account().then((a) => !!a && a.status !== 'setup').catch(() => false),
     announcements: ANNOUNCEMENTS.enabled,
     analytics: {
       umami: a.umami.enabled && !!a.umami.websiteId,

package/src/lib/legal/text-en.ts

@@ -14,6 +14,7 @@ function processors(f: LegalFacts): string[] {
     ...(f.push.enabled ? ['Expo, Apple and Google (app notifications)'] : []),
     ...(f.auth === 'clerk' ? ['Clerk (sign-in)'] : []),
     ...(f.maps ? [`${f.maps} (maps)`] : []),
+    ...(f.googleCalendar ? ['Google (Google Calendar)'] : []),
     ...(f.analytics.umami ? ['Umami (visit statistics)'] : []),
     ...(f.ai ? ['OpenAI or another AI service we choose (writing tools used by staff)'] : []),
     ...(f.offsiteBackups ? ['our backup storage provider'] : []),
@@ -61,6 +62,9 @@ export function privacyEn(f: LegalFacts, country: string): PolicySection[] {
   if (f.maps) s.push({ id: 'maps', title: 'Maps', text: [
     `When staff enter an event’s address, we look it up with ${f.maps}. Your browser doesn’t contact the map service: map images are stored on this site. Directions links open Google Maps only if you choose them.`,
   ] });
+  if (f.googleCalendar) s.push({ id: 'google-calendar', title: 'Google Calendar', text: [
+    'We keep a copy of our calendar in our own Google Calendar account, and changes made there come back to this site. That copy holds what our calendar shows: event titles, times, places and descriptions. It never includes your RSVPs, your name or what you tell us when you sign up for an event, and Google sends no invitations. Appointments booked through our Google booking pages show on this site only as “Booked”, without names. Google applies its own privacy policy to its copy.',
+  ] });
   if (f.live) s.push({ id: 'live', title: 'Live video', text: [
     'When we stream, the site shows our broadcast from YouTube or Twitch. Until you press play, your browser only contacts this site: preview images come through it. Pressing play, or opening the broadcast on YouTube or Twitch, loads that platform, which applies its own privacy policy.',
   ] });

package/src/lib/legal/text-es.ts

@@ -14,6 +14,7 @@ function processors(f: LegalFacts): string[] {
     ...(f.push.enabled ? ['Expo, Apple y Google (notificaciones de la app)'] : []),
     ...(f.auth === 'clerk' ? ['Clerk (inicio de sesión)'] : []),
     ...(f.maps ? [`${f.maps} (mapas)`] : []),
+    ...(f.googleCalendar ? ['Google (Google Calendar)'] : []),
     ...(f.analytics.umami ? ['Umami (estadísticas de visitas)'] : []),
     ...(f.ai ? ['OpenAI u otro servicio de inteligencia artificial que elijamos (herramientas de redacción que usa el personal)'] : []),
     ...(f.offsiteBackups ? ['nuestro proveedor de almacenamiento de respaldos'] : []),
@@ -62,6 +63,9 @@ export function privacyEs(f: LegalFacts, country: string): PolicySection[] {
   if (f.maps) s.push({ id: 'maps', title: 'Mapas', text: [
     `Cuando el personal escribe la dirección de un evento, la buscamos con ${f.maps}. Su navegador no se conecta con el servicio de mapas: las imágenes de los mapas se guardan en este sitio. Los enlaces para llegar abren Google Maps solo si usted los elige.`,
   ] });
+  if (f.googleCalendar) s.push({ id: 'google-calendar', title: 'Google Calendar', text: [
+    'Guardamos una copia de nuestro calendario en nuestra propia cuenta de Google Calendar, y los cambios que se hacen allí regresan a este sitio. Esa copia contiene lo que muestra nuestro calendario: títulos, horarios, lugares y descripciones de los eventos. Nunca incluye sus confirmaciones de asistencia, su nombre ni lo que nos dice al inscribirse en un evento, y Google no envía invitaciones. Las citas reservadas en nuestras páginas de reserva de Google aparecen en este sitio solo como “Reservado”, sin nombres. Google aplica su propia política de privacidad a su copia.',
+  ] });
   if (f.live) s.push({ id: 'live', title: 'Video en vivo', text: [
     'Cuando transmitimos, el sitio muestra nuestra transmisión de YouTube o Twitch. Hasta que usted presiona reproducir, su navegador solo se conecta con este sitio: las imágenes de vista previa pasan por él. Al presionar reproducir, o al abrir la transmisión en YouTube o Twitch, se carga esa plataforma, que aplica su propia política de privacidad.',
   ] });