@acms-subir/core 0.3.54 → 0.3.56

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @acms-subir/core
 
+## 0.3.56
+
+### Patch Changes
+
+- 191830f: Anyone can now ask for an event, or for a change to one, without an account. Turn it on with `acms({ requests: true })`; it needs the calendar.
+
+  - **On the website**, a form at `/request` (and `/es/request` and so on), in the visitor's language and themed through the site's tokens. It asks what they're planning, the kind, date and times, how it repeats, rooms (or "Not sure"), how many people, and anything else. "Change to an event" asks which event, optionally which date, and what should change. A live line says whether the chosen rooms look free then (free or busy only). `requests: { path: '/ask' }` moves it; `requests: { page: false }` drops it but keeps the rest, and a site file at the path replaces it.
+  - **In apps**, `GET /api/v1/requests/options` (open or closed, the kinds and requestable rooms, the reply time, notice and office phone, in the asked language) and `POST /api/v1/requests` (Idempotency-Key; returns `{ id }`; refusals carry a code such as `title`, `past`, `room`, `closed` or `busy`). `site.features.requests` says the site has it. 10 requests a minute and 20 a day per address, 5 a day per email address, plus the site's daily cap.
+  - **Calendar → Requests** lists requests from the app, the website and hosts on My events (new events, suggested changes and date moves, each answered there) in one place, with Pending, Approved and Declined tabs and, on each new request, what takes its rooms then (12 weeks for weekly ones). **Approve** makes a draft that's already filled in: title, times, weekly when asked, the kind's tag and calendar, and the rooms held while it's a draft. The person's details stay on the request, never on the event. Approving a change opens the event, or that date's Move… form. **Reply** and **Decline** (with an optional reason) email the person in the language they asked in. **Delete as spam** removes one without an email. The list shows 50 at a time. Reading the list needs "Create and edit content"; answering needs "Publish content".
+  - **Settings** on that page (needs "Manage rooms and calendars"): open or closed (closed forms and apps say so and show the office phone, and never disappear), the kinds with their label in each language, tag and calendar, the reply time and opening notice in each language, the office phone, who hears about new requests (else `members.notify`, else the owners), an optional push to their linked phones, the daily cap (100) and how long requests are kept (180 days after the answer, or after they arrive if nobody answers). Rooms marked **Anyone can check if it's free** are the ones people can choose.
+  - **Emails:** the person gets "We got your request" in their language. It never repeats what they typed, so the form can't be used to send someone else a message, and each address gets at most 3 a day. Staff get every detail, with Reply-To set to the person, and only while the request still waits.
+  - **Privacy:** the generated privacy notice gets an "Event requests" section (what's kept, why, and when it's deleted), and the app store answers list event requests under contact info and user content. Requests are in backups.
+  - **Server API** (`@acms-subir/core/server`): `requestOptions`, `submitRequest` (for a site's own form), `listRequests`, `approveRequest`, `declineRequest` and `replyToRequest`. See `npx acms docs calendar` and `npx acms docs server`.
+
+  Requests use the `event_requests` table that came with hosts' date moves (migration 68); this release adds no migration. After updating, a site that wants requests adds `requests: true`, marks the rooms people may ask for as **Anyone can check if it's free**, and sets the kinds, reply time and office phone in Calendar → Requests → Settings. Update the privacy notice and the app's store answers, which now include requests.
+
+## 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

@@ -1,6 +1,7 @@
-# Calendar: repeats, single dates, rooms and clashes
+# Calendar: repeats, single dates, rooms, clashes and requests
 
-How events repeat, how one date of a series is changed, and how events hold rooms.
+How events repeat, how one date of a series is changed, how events hold rooms, and
+how people ask for events.
 Read it with `npx acms docs calendar`. The functions named here come from
 `@acms-subir/core/server` (`npx acms docs server` has their signatures), and the app
 API is in `docs/mobile-api-v1.md` in the framework repository.
@@ -286,3 +287,104 @@ 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)`.
+
+## Requests without an account
+
+`acms({ requests: true })` lets anyone ask for a new event, or for a change to one,
+without an account:
+
+- from the website's form at `/request` (and `/es/request` and so on);
+- from an app (`GET /api/v1/requests/options`, `POST /api/v1/requests`);
+- from the site's own form, through `submitRequest`.
+
+Staff answer them on **Calendar → Requests**. That one list also shows hosts'
+requests from My events. `requests: { path: '/ask' }` moves the form, and
+`requests: { page: false }` drops it but keeps the API and the admin. A site file at
+the form's path replaces it.
+
+Each request is a row of its own (`RequestRecord`), not an event:
+
+- `kind`:
+  - `'new'`: `data` has `type`, `title`, `start`, `end`, `repeat` (`once`, `weekly`
+    or `other` with `repeatText`), `roomIds`, `roomsUnsure` and `people`;
+  - `'change'`: `eventId`, plus `key` for one date (`''` = every date).
+- `state`: `pending`, `approved`, `declined` or `withdrawn`.
+- `source`: `app`, `web` or `member`.
+- `requester`: `{ name, email, phone, locale }`, for a person without an account.
+- `note`: their own words to staff.
+- `reply`: staff's last answer.
+
+Hosts' date moves (C3/C4) use the same table with kinds `move` and `from-date`.
+
+**Settings** (Calendar → Requests → Settings, in `settings.calendar.requests`):
+
+- **Open or closed.** Closed forms and apps say so and show the office phone; they never
+  disappear.
+- **Kinds.** Each has a label per language, plus the tag and calendar an approved
+  draft gets.
+- **Reply time and notice**, per language.
+- **Office phone.**
+- **Who hears about new requests.** Their email, else `members.notify`, else the owners.
+  Optionally a push to their linked phones, without names.
+- **A daily cap** on new requests (100), on top of 10 a minute and 20 a day per
+  address and 5 a day per email address.
+- **How long requests are kept** (180 days) after their answer, or after they
+  arrived if nobody answered. The scheduler deletes them then.
+
+**Rooms** people can choose are the ones marked **Anyone can check if it’s free**
+(`requestable`). The form's live "free then" line uses `GET /api/v1/rooms/free`, which
+says free or busy, never what or who.
+
+**Answering** (needs **Publish content**; reading the list needs **Create and edit
+content**):
+
+- **Approve** a new request: makes a draft that's already filled in. It has the
+  title and times, `FREQ=WEEKLY` when asked, the kind's tag and calendar (else the
+  default calendar), and the rooms held while it's a draft. The draft opens in the
+  editor. The person's details stay on the request, never on the event.
+- **Approve** a change: opens the event, or that date's Move… form
+  (`/admin/calendar/events/<id>?move=<key>`).
+- Both email the person, with an optional message, unless you untick it.
+- **Decline**, with an optional reason, and **Reply** email the person in the
+  language they asked in. A reply leaves the request as it is. **Delete as spam**
+  removes a request from the app or the website without emailing anyone.
+- Each row shows what takes its rooms then. Weekly requests are checked for 12
+  weeks.
+
+**Emails.** The person gets "We got your request" in their language. It never
+repeats what they typed (the title or message), so the form can't be used to send
+someone else a message, and each address gets at most 3 a day. Staff get every
+detail in the site's main language, with Reply-To set to the person.
+
+**Privacy.** The generated privacy notice gets an "Event requests" section, and
+the store answers list event requests under contact info and user content.
+Requests are in backups.

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/mobile.md

@@ -114,7 +114,7 @@ Read the app's `AGENTS.md` too: it holds the same rules, next to the code.
 
 | Hook | For |
 | --- | --- |
-| `useSite()` | name, menu, languages, features (`calendar`, `bookings`, `rsvp`, `blog`, `search`, `bookingChanges`, `guestSignIn`, `forms`, `links`, `live`) |
+| `useSite()` | name, menu, languages, features (`calendar`, `bookings`, `rsvp`, `blog`, `search`, `bookingChanges`, `guestSignIn`, `forms`, `links`, `live`, `announcements`, `requests`) |
 | `usePage(slug)` | a published page: `mode` (`sections`/`content`), `sections`, `body.html`; 404 when missing |
 | `usePosts({ collection, limit, q })` / `usePost(slug)` | posts (infinite: `items`, `fetchNextPage`); `q` gives ranked search matches |
 | `useSearch(text, { types, collection, limit })` | site-wide search: `data.posts`, `data.pages`, `data.events` (each with `snippet.text` + `snippet.highlights`), `data.more`; debounced, blank text fetches nothing |
@@ -128,6 +128,7 @@ Read the app's `AGENTS.md` too: it holds the same rules, next to the code.
 | `useLive()` | live video: `snapshot`, `status` (`live`/`upcoming`/`offline`), `isLive`, localized `view` text, the owner's `display` choices (`style`, `bar`, `header`, `dock`). Polls every 30 s only in the foreground, rechecks on resume, drops an expired "live" even offline; idle while `features.live` is false. Render `<LiveCard>` / `<LiveTag>` |
 | `useResources()` / `useAvailability({ resource, link })` / `useBooking()` | bookings |
 | `useRoomFree({ room, start, end })` | bookings: is a requestable room free (no names) |
+| `useRequestOptions()` / `useSubmitRequest()` | event requests without an account (`features.requests`): the form's kinds, rooms, words and office phone (`open: false` = say so and show the phone, never hide the screen), and sending one with its own Idempotency-Key; `problem` and `field` say what to fix |
 | `useLocale()`, `useTheme()`, `useLayout()`, `useRefresh()`, `useOpenLink()` | language, tokens, layout, refresh, links |
 | `usePushRegistration({ topics })` / `usePushTopics()` / `useNewPushTopics()` / `useNotificationTaps()` | push notifications (see Push notifications); topic names come in the app's language |
 | `useAnnouncements({ kind, pinned })` / `useAnnouncement(id)` / `useAnnouncementState()` | announcements up right now; unread and closed banners kept on the phone (a dot, never a number); idle while `features.announcements` is false |
@@ -150,6 +151,7 @@ npx acms mobile recipe add news      # posts list, article
 npx acms mobile recipe add booking   # resources → slots → form → confirmation  (expo-crypto)
 npx acms mobile recipe add push      # notifications: turn on, topic toggles, taps open the page  (expo-notifications, expo-device)
 npx acms mobile recipe add announcements  # list with kind tabs and unread dots, detail, home banners (site needs announcements on)
+npx acms mobile recipe add event-request  # "Request an event" screen, a More row and an events-list link, no account (site needs requests on; expo-crypto, expo-secure-store)
 ```
 
 Each prints the `npx expo install …` line for its packages: run it (doctor