@acms-subir/core 0.3.54 → 0.3.55

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @acms-subir/core
 
+## 0.3.55
+
+### Patch Changes
+
+- 5ae8091: Two-way Google Calendar sync. Site calendars and Google calendars now stay in step, both ways: anything created, changed, moved, cancelled or deleted on one side shows up on the other within a few minutes, and Google keeps a full working copy if the site is ever down. It's in **Calendar settings → Synced with Google**, and the guide is `npx acms docs google-calendar`.
+
+  - **Connect Google** with its own OAuth client (it can share YouTube's Google Cloud project; disconnecting YouTube never cuts off the calendar). The sign-in works like YouTube's: a one-use pending state, a callback at `/api/calendar/google/oauth/callback` that only parks the code, and the signed-in admin finishing it. Tokens are sealed with `LIVE_ENCRYPTION_KEY`, else `SESSION_SECRET`, under their own key. No new environment variable.
+  - **Links:** one site calendar ⇄ one Google calendar, both ways, site → Google, or Google → site. A link can stand for rooms (events from it hold them, and site events holding them go there), so one site calendar can have a link per room, and one link can also take the events that hold no room. Title prefix ⇄ tag rules (`CLASS:` ⇄ `Class`) work both ways, with the prefix kept in the title.
+  - **First match:** a new link writes nothing until someone reviews what's on both sides and presses Start syncing. Pairs are found by the hidden link on Google copies, by Google's calendar ID (`sourceUid`), by title and time; same time and repeat with a different title is suggested. Linked pairs keep both titles as they are. Nothing sends member notifications.
+  - **What goes where:** title (main language), times and time zone, repeat rule and skipped dates, cancelled and moved single dates (through `cancelOccurrence` / `moveOccurrence` as `GOOGLE_SYNC`), place, description (Google's while the event is Google's, then the site's with "Details: <event page>"), rooms. A cancelled site event shows "Cancelled: " in Google. Unpublished or deleted on the site removes the Google copy. Deleted in Google cancels the site event (struck through, room freed, restorable), or, when the event has another linked copy, takes just that link's room or calendar off it. Hosts, RSVPs, private fields, pictures and other tags are never sent, guests are never added, and every write uses `sendUpdates=none`. Only owned fields are patched.
+  - **Titles:** cancelling or changing a tag on the site adjusts Google's own title rather than replacing it. Staged edits stay staged, and a staged field still at its old value follows Google's change.
+  - **Clashes:** field by field, each side keeps what it changed. When both changed a field, the site wins, and Google's value waits in Recent changes and the event editor with **Use Google's version**.
+  - **Booked appointments** from Google booking pages come in as "Booked", holding the link's room, with the internal tag `#google-booking`: a link names its booking pages, since Google's API has no marker for them.
+  - **"This and following"** edits in Google are listed for staff, and the site series stays whole until "from this date on" exists.
+  - **Safety:** links run only on the Site URL they were made on, pause after a restore until someone resumes them, and are never copied by environment sync or backups. Unlinking and disconnecting keep both copies. Google's "full sync required" (410) reads everything again without doubles or pushes. A revoked sign-in shows "Reconnect Google" and changes wait. Staff get one email when a link has failed for an hour. Recent changes are kept for 90 days.
+  - **For site code:** `googleCopies(repo, eventId)`, `googleSyncHistory(repo)`, `syncGoogleCalendar(repo, { locals })` and `GOOGLE_BOOKING_TAG` in `@acms-subir/core/server`. The event repository's `updateEvent` takes `{ keepDraft, quiet }`, and `cancelOccurrence` / `restoreOccurrence` take `{ quiet }`.
+  - The privacy notice gets a Google Calendar section, in English and Spanish, once Google is connected.
+
+  Migration 69 adds the sync's tables (`gcal_account`, `gcal_oauth_states`, `gcal_links`, `gcal_items`, `gcal_queue`, `gcal_log`) and triggers on `events` that queue changes for links. Sites with no links are unaffected. After `npx acms update`, nothing changes until someone connects Google. Set up the Google Cloud client as the guide describes. For a church on Google Workspace, use the "Internal" audience if the project belongs to the organization; otherwise use "External", set to "In production".
+
 ## 0.3.54
 
 ### Patch Changes

package/cli/main.mjs

@@ -10,7 +10,7 @@ import { addMobile, mobileCommand, listApps } from './mobile.mjs';
 import { mobileDoctor, renderDoctor } from './mobile-doctor.mjs';
 import { monitorCommand, renderMonitor } from './monitor.mjs';
 const HELP=`acms — ACMS project, theme and agent tools
-Discovery: inspect | schema theme | docs theme | docs sections | docs mobile | docs sync | docs server | docs calendar
+Discovery: inspect | schema theme | docs theme | docs sections | docs mobile | docs sync | docs server | docs calendar | docs google-calendar
            agent init [--mobile]   write .agents/skills (theme; mobile when an app exists)
 Check:  check [--build]   validate every project theme, refresh section types,
                           report sections without a native app version
@@ -141,6 +141,7 @@ export async function main() {
     else if(cmd==='docs'&&sub==='sync')data={markdown:await readFile(resolve(CORE,'docs/environment-sync.md'),'utf8')};
     else if(cmd==='docs'&&sub==='server')data={markdown:await readFile(resolve(CORE,'docs/server.md'),'utf8')};
     else if(cmd==='docs'&&sub==='calendar')data={markdown:await readFile(resolve(CORE,'docs/calendar.md'),'utf8')};
+    else if(cmd==='docs'&&sub==='google-calendar')data={markdown:await readFile(resolve(CORE,'docs/google-calendar.md'),'utf8')};
     else if(cmd==='section')data=await sectionCommand(sub,rest,flags);
     else if(cmd==='check') {
       const p=await project(),themes=(await listLocalThemes(p)).filter(t=>t.origin==='project');

package/cli/migrations.generated.mjs

@@ -461,6 +461,56 @@ var REQUEST_TABLE = [
   `CREATE INDEX event_requests_event ON event_requests (event_id)`
 ];
 
+// src/lib/calendar/google/migration.ts
+var now5 = "CAST((julianday('now') - 2440587.5) * 86400000 AS INTEGER)";
+var guard = "(SELECT suppressed FROM webhook_control WHERE id=1)=0 AND EXISTS (SELECT 1 FROM gcal_links)";
+var enqueue3 = (id) => `INSERT INTO gcal_queue (event_id,version,due_at,attempts,claimed_until,error) VALUES (${id},1,${now5},0,0,'')
+    ON CONFLICT(event_id) DO UPDATE SET version=version+1,due_at=excluded.due_at,attempts=0,error='';`;
+var GCAL_MIGRATION = { version: 69, statements: [
+  `CREATE TABLE gcal_account (
+    id INTEGER PRIMARY KEY CHECK(id=1), client_id TEXT NOT NULL, encrypted TEXT NOT NULL, email TEXT NOT NULL DEFAULT '',
+    status TEXT NOT NULL DEFAULT 'setup', error TEXT NOT NULL DEFAULT '', site_url TEXT NOT NULL DEFAULT '',
+    calendars TEXT NOT NULL DEFAULT '[]', calendars_at INTEGER NOT NULL DEFAULT 0, connected_by TEXT NOT NULL DEFAULT '',
+    connected_at INTEGER NOT NULL DEFAULT 0, revision INTEGER NOT NULL DEFAULT 1, updated_at INTEGER NOT NULL DEFAULT 0
+  )`,
+  `CREATE TABLE gcal_oauth_states (hash TEXT PRIMARY KEY, session_hash TEXT NOT NULL, revision INTEGER NOT NULL, encrypted TEXT NOT NULL, expires_at INTEGER NOT NULL)`,
+  `CREATE TABLE gcal_links (
+    id TEXT PRIMARY KEY, calendar_id TEXT NOT NULL, google_id TEXT NOT NULL UNIQUE, google_name TEXT NOT NULL DEFAULT '', google_tz TEXT NOT NULL DEFAULT '',
+    direction TEXT NOT NULL DEFAULT 'both' CHECK(direction IN ('both','out','in')), room_ids TEXT NOT NULL DEFAULT '[]',
+    no_room INTEGER NOT NULL DEFAULT 0, rules TEXT NOT NULL DEFAULT '[]', booking_titles TEXT NOT NULL DEFAULT '[]', start_date TEXT NOT NULL,
+    state TEXT NOT NULL DEFAULT 'matching' CHECK(state IN ('matching','active','paused')), paused_reason TEXT NOT NULL DEFAULT '',
+    site_url TEXT NOT NULL, matched_at INTEGER NOT NULL DEFAULT 0, match TEXT,
+    sync_token TEXT NOT NULL DEFAULT '', full_sync INTEGER NOT NULL DEFAULT 1,
+    lease TEXT NOT NULL DEFAULT '', lease_until INTEGER NOT NULL DEFAULT 0, next_at INTEGER NOT NULL DEFAULT 0,
+    failures INTEGER NOT NULL DEFAULT 0, failing_since INTEGER NOT NULL DEFAULT 0, alerted_at INTEGER NOT NULL DEFAULT 0,
+    last_ok_at INTEGER NOT NULL DEFAULT 0, error TEXT NOT NULL DEFAULT '', revision INTEGER NOT NULL DEFAULT 1,
+    created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+  )`,
+  `CREATE TABLE gcal_items (
+    link_id TEXT NOT NULL, google_id TEXT NOT NULL, event_id TEXT NOT NULL, ical_uid TEXT NOT NULL DEFAULT '',
+    kind TEXT NOT NULL DEFAULT 'single' CHECK(kind IN ('series','single','segment')), segment_from TEXT NOT NULL DEFAULT '',
+    etag TEXT NOT NULL DEFAULT '', html_link TEXT NOT NULL DEFAULT '', site TEXT NOT NULL DEFAULT '{}', google TEXT NOT NULL DEFAULT '{}',
+    desc_google INTEGER NOT NULL DEFAULT 0, booking INTEGER NOT NULL DEFAULT 0, gone INTEGER NOT NULL DEFAULT 0, conflict TEXT,
+    synced_at INTEGER NOT NULL DEFAULT 0, created_at INTEGER NOT NULL,
+    PRIMARY KEY (link_id, google_id), UNIQUE (link_id, event_id, segment_from)
+  )`,
+  `CREATE INDEX gcal_items_event ON gcal_items (event_id)`,
+  `CREATE TABLE gcal_queue (
+    event_id TEXT PRIMARY KEY, version INTEGER NOT NULL DEFAULT 1, due_at INTEGER NOT NULL, attempts INTEGER NOT NULL DEFAULT 0,
+    claimed_until INTEGER NOT NULL DEFAULT 0, error TEXT NOT NULL DEFAULT ''
+  )`,
+  `CREATE TABLE gcal_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT, at INTEGER NOT NULL, link_id TEXT NOT NULL DEFAULT '', event_id TEXT NOT NULL DEFAULT '',
+    google_id TEXT NOT NULL DEFAULT '', direction TEXT NOT NULL CHECK(direction IN ('in','out','clash','info')), action TEXT NOT NULL,
+    title TEXT NOT NULL DEFAULT '', summary TEXT NOT NULL DEFAULT '', data TEXT, resolved INTEGER NOT NULL DEFAULT 0
+  )`,
+  `CREATE INDEX gcal_log_at ON gcal_log (at)`,
+  `CREATE INDEX gcal_log_event ON gcal_log (event_id, at)`,
+  `CREATE TRIGGER gcal_queue_insert AFTER INSERT ON events WHEN ${guard} BEGIN ${enqueue3("NEW.id")} END`,
+  `CREATE TRIGGER gcal_queue_update AFTER UPDATE ON events WHEN ${guard} BEGIN ${enqueue3("NEW.id")} END`,
+  `CREATE TRIGGER gcal_queue_delete AFTER DELETE ON events WHEN ${guard} BEGIN ${enqueue3("OLD.id")} END`
+] };
+
 // src/lib/repo/migrations.ts
 var CONTENT_VERSION_COLUMNS = {
   settings: [
@@ -1298,7 +1348,10 @@ var MIGRATIONS = [
   SCREENS_MIGRATION,
   // calendar requests on their own rows (RequestRecord): new events and
   // changes asked for without an account, and hosts' date moves
-  { version: 68, statements: REQUEST_TABLE }
+  { version: 68, statements: REQUEST_TABLE },
+  // two-way Google Calendar sync: the account, links, pairs, outgoing queue
+  // (triggers on events) and Recent changes. Not public, so no cache trigger.
+  GCAL_MIGRATION
 ];
 var CURRENT_CONTENT_VERSION_COLUMNS = {
   ...CONTENT_VERSION_COLUMNS,
@@ -1327,7 +1380,7 @@ async function pendingMigrations(db) {
   return { applied, pending: MIGRATIONS.filter((m) => m.version > applied) };
 }
 async function runMigrations(db, opts = {}) {
-  const now5 = opts.now ?? Date.now;
+  const now6 = opts.now ?? Date.now;
   const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   const first = await pendingMigrations(db);
   if (!first.pending.length) return { from: first.applied, to: first.applied, applied: [] };
@@ -1335,10 +1388,10 @@ async function runMigrations(db, opts = {}) {
   if (refused) return { from: first.applied, to: first.applied, applied: [], deferred: refused.version };
   await db.run(MIGRATION_LOCK_TABLE);
   const owner = crypto.randomUUID();
-  const deadline = now5() + (opts.waitMs ?? 6e4);
+  const deadline = now6() + (opts.waitMs ?? 6e4);
   let waited = false;
   for (; ; ) {
-    const t = now5();
+    const t = now6();
     await db.run(
       `INSERT INTO migration_lock (id, owner, expires_at) VALUES (1, ?, ?)
        ON CONFLICT(id) DO UPDATE SET owner = excluded.owner, expires_at = excluded.expires_at WHERE migration_lock.expires_at < ?`,
@@ -1356,13 +1409,13 @@ async function runMigrations(db, opts = {}) {
   try {
     const { applied, pending } = await pendingMigrations(db);
     if (applied === 1 && !await appliedVersion(db)) {
-      await db.run("INSERT INTO migrations (version, applied_at) VALUES (1, ?)", [now5()]);
+      await db.run("INSERT INTO migrations (version, applied_at) VALUES (1, ?)", [now6()]);
     }
     for (const m of pending) {
       opts.log?.(`Applying migration ${m.version}`);
       await db.batch([
         ...m.statements.map((sql) => ({ sql })),
-        { sql: "INSERT INTO migrations (version, applied_at) VALUES (?, ?)", args: [m.version, now5()] }
+        { sql: "INSERT INTO migrations (version, applied_at) VALUES (?, ?)", args: [m.version, now6()] }
       ]);
     }
     return { from: applied, to: pending.length ? pending[pending.length - 1].version : applied, applied: pending.map((m) => m.version) };

package/docs/calendar.md

@@ -286,3 +286,32 @@ A theme's `theme.css` loads after the board's own styles. The simplest way to re
 ```
 
 Keep blocks flat: the built-in look has no accent stripes or gradients. The display leaves out the site's header, footer, head code and analytics. A site file at `src/pages/display/calendar.astro` (or `display/s/[key].astro`) replaces that page.
+
+## Google Calendar sync
+
+Calendar settings → **Synced with Google** keeps linked site calendars and Google
+calendars in step, both ways, within a few minutes. The full guide is
+`acms docs google-calendar`. What it means for the calendar features above:
+
+- **Single dates.** A date deleted or moved in Google goes through `cancelOccurrence`
+  and `moveOccurrence` with the `GOOGLE_SYNC` actor, so RSVPs, room holds and pushes
+  follow as they do for staff. A taken room only warns. Cancelled and moved dates on the
+  site change that date's instance in Google.
+- **Rooms.** A link can stand for one or more rooms: events from that Google calendar
+  hold them, and site events holding them go there. One site calendar can have a link
+  per room.
+- **Deleted in Google** means **cancelled** on the site (struck through, room freed,
+  restorable), never deleted. The exception is an event with another linked copy: only
+  that link's room or calendar comes off it.
+- **Cancelled on the site** shows in Google as "Cancelled: " in front of the title.
+  Unpublished or deleted on the site removes the Google copy.
+- **Writes from the sync** keep staged edits staged (`updateEvent(id, data, { keepDraft: true })`).
+  Changes from Google push to members like an admin edit, except during the first match
+  and full resyncs (`quiet`).
+- **Booked appointments** from Google booking pages come in as "Booked" with the
+  internal tag `#google-booking` (`GOOGLE_BOOKING_TAG`), holding the link's room. Treat
+  them as bookings: the tag never shows publicly.
+- **"This and following"** in Google is listed for staff, and the site series stays whole
+  until "from this date on" exists.
+- Site code can read an event's Google copies with `googleCopies(repo, eventId)`, and
+  Recent changes with `googleSyncHistory(repo)`.

package/docs/google-calendar.md

@@ -0,0 +1,302 @@
+# Google Calendar sync
+
+Keeps site calendars and Google calendars in step, both ways. Anything
+created, changed, moved, cancelled or deleted on one side shows up on the
+other within a few minutes, and Google keeps a full working copy if the site
+is ever down. The site is the main calendar.
+
+It's set up in the admin, under **Calendar settings → Synced with Google**.
+Only calendars you link are synced.
+
+- Site changes go out on every scheduler run (once a minute).
+- Each link asks Google what changed every 2 minutes (`events.list` with a sync token).
+- The scheduler has to run: on Node, the `acms-email-runner` sidecar; on
+  Workers, the cron trigger.
+
+## Google Cloud setup
+
+The sync uses its **own OAuth client**. It can live in the same Google Cloud
+project as YouTube live video, but it needs a separate client, so
+disconnecting YouTube never cuts off the calendar.
+
+1. In Google Cloud console, open the project. Under **APIs & Services →
+   Credentials**, create an **OAuth client ID** of type **Web application**
+   named "Calendar".
+2. Enable the **Google Calendar API** in the same project.
+3. Add the return address shown in Calendar settings as an **Authorized
+   redirect URI**: `https://<your site>/api/calendar/google/oauth/callback`.
+4. Set the **Audience** (OAuth consent screen):
+   - **Internal** if the project belongs to your Google Workspace
+     organization (Google Cloud console → IAM & Admin → Settings shows it).
+     There's no "unverified app" screen and no expiry. Internal applies to the
+     whole project, so YouTube must also be connected with an account in that
+     organization.
+   - Otherwise **External**, set to **In production**. In "Testing", Google
+     ends the connection every 7 days. You click through "Google hasn't
+     verified this app" once.
+5. If your Workspace admin restricts third-party apps, mark this client as
+   trusted: Google Admin console → Security → API controls.
+6. Paste the client ID and secret into Calendar settings → Synced with Google
+   and press **Connect Google**. Sign in with the account that owns the
+   calendars (for a church, its Workspace account).
+
+The site asks for two permissions:
+
+- `calendar.events`: see and edit events on calendars the account can edit.
+- `calendar.calendarlist.readonly`: list those calendars for the link picker.
+
+The tokens are sealed with `LIVE_ENCRYPTION_KEY`, else `SESSION_SECRET`
+(32+ characters), using their own key and data. There's no new environment
+variable. Changing that secret means connecting Google again.
+
+Permissions:
+
+- **Connected services** (`services.manage`) connects and disconnects Google.
+- **Manage rooms and calendars** (`schedule.manage`) links, pauses, resumes
+  and reviews matches.
+
+## Linking a calendar
+
+**+ Link a Google calendar** pairs one site calendar with one Google calendar
+the account can edit. The settings:
+
+- **Direction**:
+  - Both ways.
+  - Site → Google only: Google mirrors the site. Start here, then switch.
+  - Google → site only: site edits stay on the site.
+- **Rooms**: the room(s) this Google calendar stands for. Events that come in
+  from it hold those rooms. Site events holding one of them go to it.
+  - **Also gets this calendar's events that hold no room**: one link per site
+    calendar may have this.
+  - A link with no rooms carries its whole site calendar.
+- **Titles that set a tag**: a title prefix paired with a site tag, both ways,
+  for example `CLASS:` ⇄ `Class`.
+  - A Google title starting with the prefix gives the site event the tag.
+  - A tagged site event gets the prefix in Google.
+  - The prefix stays in the title on both sides. The tag stays the source of
+    truth for site features (class schedule, "Class changes" pushes).
+- **Booking pages**: the titles of the Google calendar's appointment
+  schedules. See below.
+- **Start from**: default 30 days ago. Events from that date on are synced,
+  plus every repeating series still running.
+
+One site calendar can have several links, one per room. Example: the room
+calendar ⇄ "Santuario | Sanctuary" holding the Sanctuary, and the room
+calendar ⇄ "Multimedia Room #1" holding that room.
+
+- An event in two linked site calendars, or holding two linked rooms, gets
+  one Google copy per link. An edit to any copy updates the site event, and
+  the other copies follow.
+- Deleting one copy in Google removes only that link's room, or calendar,
+  from the event. When neither applies (a link that carries the whole
+  calendar, which another link also has), that Google calendar just keeps the
+  event out. The event is cancelled (below) only when no linked copy is left.
+
+### The first match
+
+A new link writes nothing until someone reviews it. The match page lists:
+
+- **On both**:
+  - Paired for sure, each with **Undo**: a Google copy carrying the site's hidden link; the same
+    calendar ID (copies made with "Make an editable copy…" or imported from
+    Google's .ics keep Google's ID); or the same title (prefixes and case
+    aside) at the same time.
+  - Suggested: same time and repeat, different title. **Link** or **Not the
+    same**.
+- **Only on the site**: copied to Google when you start.
+- **Only in Google**: come to the site as published events in the linked
+  calendar, holding its rooms.
+
+Decisions are saved as you make them. **Start syncing** needs every
+suggestion decided.
+
+- Linked pairs keep **both titles as they are**: a Spanish Google title and
+  an English site title both stay. Every field, and every changed date of a
+  series, is recorded as the agreed starting point, and only a later edit on
+  one side copies over. A pair whose site event has no description keeps
+  Google's.
+- A pair whose site event was unpublished, deleted or moved to another
+  calendar or room after the review is left alone: it isn't paired, deleted
+  or copied, and Recent changes names it.
+- "Not the same" pairs are treated as two events.
+- No member notifications are sent for any of it.
+
+## What goes where
+
+| Site | Google | Direction |
+| --- | --- | --- |
+| Title (main language) | Title | both ways. A Google title edit sets the main-language title as typed; translations stay on the site |
+| Cancelled event | "Cancelled: " in front of Google's title | site → Google |
+| Date, time, all day, time zone | start, end | both ways (the site's inclusive all-day end ⇄ Google's exclusive one; each event keeps its zone) |
+| Repeat rule, skipped dates | `RRULE`, `EXDATE` | both ways |
+| Cancelled single date | that date's instance removed | both ways |
+| Moved single date (new time or place) | that date's instance changed | both ways |
+| Place name and address | location | both ways (from Google, the text becomes the place name; saved places and pins aren't guessed) |
+| Description | plain-text description | while the event is Google's, from Google (below); after that, site → Google |
+| Map or meeting link, event page | lines in the description | site → Google |
+| Tag of a prefix rule | title prefix | both ways |
+| Rooms | which linked Google calendar | both ways |
+| Draft, scheduled | nothing | not sent until published, scheduled publishing included |
+| Unpublished or deleted | deleted in Google | site → Google |
+| Deleted in Google | **cancelled** on the site (struck through, room freed, restorable) | Google → site |
+| Hidden link | `extendedProperties.private` `{ acmsEventId, acmsSite }` | site → Google |
+
+Never sent:
+
+- hosts, RSVPs, private fields, member requests, pictures, buttons, custom
+  fields, other tags;
+- guests. Every write uses `sendUpdates=none`, so Google emails no one.
+
+Only the fields above are patched. Guests, reminders, colours, attachments
+and Meet links someone added in Google are left alone. Cancelling an event or
+changing a rule's tag on the site adjusts Google's own title (adds or removes
+"Cancelled: " or the prefix) rather than replacing it, so a Spanish Google
+title stays Spanish until someone edits the title itself.
+
+Changes from Google keep staff's staged edits staged. A staged field still at
+its old value follows Google's change, so pressing Update later doesn't undo
+it. A field staff did change stays as they staged it.
+
+If Google refuses to change one event (for example, someone else's event
+that only invites the room's calendar), Recent changes lists it once and the
+other links still get the change.
+
+**Descriptions.** An event created in Google takes its description from
+Google, as simple paragraphs, until someone edits the description on the
+site. From then on the site's text wins, and Google gets a plain-text copy
+plus "Details: <event page>". A Google description edit after that is listed
+under Recent changes with **Use Google's version**.
+
+**New events from Google** are published on the site at once, in the linked
+calendar, holding its rooms. Changes from Google send member pushes the way an
+admin edit does, except during the first match and full resyncs. RSVP emails
+always go, because those people's own booking changed.
+
+## Repeating events
+
+A series is one event with a rule on both sides. Single dates:
+
+- **Cancelled.** Deleting one date in Google cancels it on the site with
+  `cancelOccurrence`: struck through, room freed, RSVPs cancelled with their
+  email. A date cancelled on the site is deleted from the Google series.
+- **Moved.** A Google date with a new time, day or place becomes a moved date
+  on the site, through `moveOccurrence` with the `GOOGLE_SYNC` actor (see
+  [calendar](calendar.md)): RSVPs move and get the "new time" email, and a
+  taken room only warns. A date moved on the site moves that Google instance.
+- **Per-date titles or descriptions** from Google aren't applied, because the
+  site keeps one title for every date. They're listed under Recent changes.
+- **"This and following"** in Google splits the series in two. Until the site
+  has "from this date on", the new Google series is linked to the same site
+  event as a later part. The split is listed for staff, and the site series
+  stays whole: its time and rule don't change from either side. Likewise, a
+  series Google ends sooner keeps its later dates on the site, listed for
+  staff to end or cancel.
+
+## Clashes
+
+Changes are compared field by field against what the pair last agreed:
+
+- Each side keeps what it changed.
+- If both sides changed the same field, **the site wins**. Google's value is
+  kept in Recent changes and in the event editor's bar, with **Use Google's
+  version**.
+- A change from Google that puts an event on a room another event holds still
+  applies, because it already happened in Google. The clash shows in Recent
+  changes and the event editor.
+
+## Booking pages (appointment schedules)
+
+Google's API has no marker for appointments booked through a booking page.
+Its event types don't include them, and open booking times aren't returned at
+all, so those are never copied. Google copies the booking page's title into
+each booked event. So a link names its booking pages ("Band", "Rehearsal
+Time"), and an event with one of those titles (alone, or followed by
+" (…)", " - …" or ": …") and a guest is treated as a booked appointment. So
+is an event whose description links to a Google booking page
+(`calendar.app.google`, `…/calendar/appointments/…`).
+
+Booked appointments come in:
+
+- titled "Booked" (in the site's main language), with no guests, place or
+  description;
+- holding the link's room, with the internal tag `#google-booking`, which is
+  never shown publicly.
+
+They're Google's: never written back, and deleting one on the site only
+unpairs it.
+
+Check this against a real booking before relying on it: book one and look
+at it in Recent changes and on the site.
+
+## Safety
+
+- **Nothing before review.** A new link only reads, until Start syncing.
+- **Only the real site writes.** A link remembers the Site URL it was made
+  on, and runs only while Settings → Site URL matches. A restored backup, a
+  staging copy or a local copy with another Site URL pauses its links ("This
+  copy isn't the site that linked Google").
+  - A raw database copy keeps the same Site URL. Change the copy's Site URL,
+    or run it with another `SESSION_SECRET`, so it can't use the sign-in.
+- **Restore** pauses every link until someone presses Resume. Resuming reads
+  Google again from scratch, pairing by the hidden links:
+  - Google's copies take the restored details, because the site is the main
+    calendar. That replaces changes made since the backup, on either side.
+  - Events Google has that the backup doesn't come back to the site: an older
+    backup never deletes anything in Google.
+- **Environment sync and backups** never copy the Google account, links or
+  pairs. Nothing is stored on the event row.
+- **Unlink** and **Disconnect** keep both copies of every event. Linking again
+  pairs them by their hidden links.
+- **Loops**: each pair stores a hash of every synced field, per side, as last
+  agreed. A change that already matches is never sent back.
+- **Failures** back off like YouTube's, and honour Google's rate limits:
+  - when Google refuses the saved sign-in, the account shows "Reconnect
+    Google" and changes wait in the queue;
+  - a link failing for an hour emails the owners and people who can manage
+    rooms and calendars, once;
+  - a Google "full sync required" (410) reads everything again quietly, with
+    no doubles and no pushes.
+- **Recent changes** keeps every change the sync made, and its clashes, for
+  90 days.
+
+## For site code
+
+`@acms-subir/core/server`:
+
+- `googleCopies(repo, eventId)`: an event's Google copies: calendar, link,
+  last sync, whether its description is Google's, an unresolved clash.
+- `googleSyncHistory(repo, { eventId?, limit? })`: Recent changes.
+- `syncGoogleCalendar(repo, { locals })`: run the sync once now.
+- `GOOGLE_BOOKING_TAG`: `'#google-booking'`.
+
+Inside the framework, the sync lives in `lib/calendar/google/`:
+
+- `map.ts`: the field mapping, as pure functions;
+- `outbound.ts`, `inbound.ts`, `match.ts`;
+- `client.ts`: Google's API over `fetch`;
+- `service.ts`: the scheduler job and Sync now.
+
+Its tables (migration 69): `gcal_account`, `gcal_oauth_states`, `gcal_links`,
+`gcal_items` (one row per pair), `gcal_queue` (filled by triggers on every
+insert, update and delete of `events`) and `gcal_log`.
+
+## Not yet
+
+- **Google push notifications** (`events.watch`) for near-instant updates.
+  Reading every 2 minutes is the mechanism.
+- **"This and following"** as a real change on the site, once "from this date
+  on" exists. Until then, splits are listed and both Google series stay linked
+  to the one site event.
+
+## Troubleshooting
+
+- **"Reconnect Google"**: Google refused the saved sign-in. It was revoked,
+  unused for 6 months, the project is still in "Testing", or a Workspace admin
+  policy applies. Press Reconnect; changes made meanwhile go out afterwards.
+- **"This copy isn't the site that linked Google"**: Site URL differs from the
+  one the link was made on. Set it back, or unlink on this copy.
+- **A Google calendar is missing from the picker**: the account needs "Make
+  changes to events" on it. Share it with the account, then **Refresh
+  calendars**.
+- **Nothing syncs**: check that the scheduler runs. Calendar settings warns
+  when it hasn't run for a few minutes.

package/docs/server.md

@@ -41,6 +41,12 @@ moveOccurrenceBack(repo: Repo, who: ServerUser | null | typeof GOOGLE_SYNC, even
 eventRoomClashes(repo: Repo, event: string | CalEvent, opts?: { horizonDays?: number; now?: Date | number }): Promise<EventClash[]>
 roomBusy(repo: Repo, q: { roomIds: string[]; from: Date | number; to: Date | number; ignore?: { eventId: string; key?: string } }): Promise<BusySlot[]>
 
+// Google Calendar sync (acms docs google-calendar): read-only, names Google calendars, staff only
+googleCopies(repo: Repo, eventId: string): Promise<GoogleCopy[]>
+googleSyncHistory(repo: Repo, opts?: { eventId?: string; limit?: number }): Promise<{ id: number; at: number; eventId: string; direction: 'in' | 'out' | 'clash' | 'info'; action: string; title: string; summary: string; resolved: boolean }[]>
+syncGoogleCalendar(repo: Repo, ctx: { locals: unknown }): Promise<number>
+GOOGLE_BOOKING_TAG = '#google-booking'
+
 // event requests: `who` is currentUser()'s result (anything with `id` and `can()` works)
 listMyEvents(repo: Repo, who: ServerUser | null): Promise<CalEvent[]>
 listEventRequests(repo: Repo, who: ServerUser | null): Promise<CalEvent[]>
@@ -72,6 +78,7 @@ interface Hold { resourceId: string; eventId: string; key: string; title: string
 interface EventClash { hold: Hold; other: Hold }
 interface BusySlot { resourceId: string; start: number; end: number; kind: 'event' | 'booking' | 'block' | 'calendar'; title: string; eventId?: string; key?: string; bookingId?: string }
 interface WriteContext { url: URL; locals: unknown }
+interface GoogleCopy { googleCalendar: string; googleCalendarId: string; htmlLink: string; syncedAt: number; descriptionFromGoogle: boolean; booking: boolean; clash: { field: string; site: string; google: string; at: number } | null }
 ```
 
 The types `Repo`, `Role`, `ServerUser`, `CalEvent`, `Occurrence`, `ListEventsOptions`,

package/integration.mjs

@@ -888,6 +888,10 @@ export default function acms(options = {}) {
       ['/admin/calendar/events/[id]', 'admin/calendar/events/[id].astro'],
       ['/admin/calendar/calendars', 'admin/calendar/calendars.astro'],
       ['/admin/calendar/integrations', 'admin/calendar/integrations.astro'],
+      // two-way Google Calendar sync: the forms' handler, the first-match review, Google's sign-in callback
+      ['/admin/calendar/google', 'admin/calendar/google.astro'],
+      ['/admin/calendar/google/match', 'admin/calendar/google/match.astro'],
+      ['/api/calendar/google/oauth/callback', 'api/calendar/google/oauth/callback.ts'],
       ['/api/calendar/docs', 'api/calendar/docs.ts'],
       [`${calendar.bookBase}/manage/[token]`, 'book/manage/[token].astro'],
       // the booker's own booking from an app (token in the Booking-Token header)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acms-subir/core",
-  "version": "0.3.54",
+  "version": "0.3.55",
   "publishConfig": {
     "access": "public"
   },

package/src/components/LegalSettings.tsx

@@ -29,7 +29,7 @@ function covered(c: LegalAdminState['covers']): string[] {
     ...(c.guestSignIn ? ['email-code sign-in in the app'] : []),
     ...(c.push ? ['the app and push notifications'] : []),
     ...(c.email ? [`email (${c.email})`] : []), ...(c.maps ? [`maps (${c.maps})`] : []),
-    ...(c.live ? ['live video'] : []),
+    ...(c.live ? ['live video'] : []), ...(c.googleCalendar ? ['Google Calendar sync'] : []),
     ...(c.analytics.umami ? ['Umami statistics'] : []), ...(c.analytics.meta ? ['Meta Pixel'] : []), ...(c.analytics.tiktok ? ['TikTok Pixel'] : []),
     ...(c.ai ? ['AI writing tools'] : []),
     'embedded content and Google Fonts', 'cookies', 'service providers', 'retention', 'rights (including ARCO)', 'children',