Sync with Google Calendar

// lib/google-calendar-api.ts
import type { GoogleEvent } from "./google-calendar";

export interface GoogleCalendarApiOptions {
  /**
   * `https://www.googleapis.com/calendar/v3` on your server, with `headers` adding the user's
   * access token. In the browser, your own route that adds it.
   */
  readonly baseUrl: string;
  /** "primary", or a calendar's ID from `calendarList.list`. */
  readonly calendarId?: string;
  readonly fetch?: typeof fetch;
  /** Headers for every request, such as `Authorization: Bearer <access token>`. */
  readonly headers?: () => HeadersInit | Promise<HeadersInit>;
  /** How often to retry a rate-limited or failed request before giving up. */
  readonly retries?: number;
  /** How long to wait before retry `attempt`, from 0, when Google doesn't say. */
  readonly retryDelay?: (attempt: number) => number;
}

/** A request Google refused: its status, and the reason its error body gives. */
export class GoogleApiError extends Error {
  override readonly name = "GoogleApiError";
  readonly reason: string | undefined;
  readonly status: number;

  constructor(status: number, reason: string | undefined, message: string) {
    super(message);
    this.reason = reason;
    this.status = status;
  }
}

/**
 * The events that end after `timeMin` and start before `timeMax`, if given, or the changes since a
 * sync token. Google doesn't take both at once.
 */
export type GoogleEventsQuery =
  | { readonly timeMax?: Temporal.Instant; readonly timeMin: Temporal.Instant }
  | { readonly syncToken: string };

export interface GoogleEventTimeWrite {
  readonly date?: string | null;
  readonly dateTime?: string | null;
  readonly timeZone?: string | null;
}

/**
 * What a write sends: these fields, and any other of the Event resource. In a patch, `null` clears a
 * field, as a move between all-day and timed needs.
 */
export interface GoogleEventWrite {
  readonly colorId?: string;
  readonly end?: GoogleEventTimeWrite;
  /** Insert only: lowercase a–v and digits, 5 to 1024 of them, so you can pick it up front. */
  readonly id?: string;
  readonly originalStartTime?: GoogleEventTimeWrite;
  readonly recurrence?: readonly string[];
  readonly recurringEventId?: string;
  readonly start?: GoogleEventTimeWrite;
  readonly status?: "confirmed" | "tentative";
  readonly summary?: string;
  readonly transparency?: "opaque" | "transparent";
}

interface GoogleEventsPage {
  readonly items?: readonly GoogleEvent[];
  readonly nextPageToken?: string;
  readonly nextSyncToken?: string;
}

const rateLimits = new Set(["rateLimitExceeded", "userRateLimitExceeded"]);

/** 1, 2, 4… seconds, up to 32, plus up to a second at random, so clients don't retry in step. */
const backoff = (attempt: number) => Math.min(2 ** attempt, 32) * 1000 + Math.random() * 1000;

/** The Calendar API's events, over `fetch`. */
export function createGoogleCalendarApi({
  baseUrl,
  calendarId = "primary",
  fetch: send = fetch,
  headers,
  retries = 5,
  retryDelay = backoff,
}: GoogleCalendarApiOptions) {
  const events = `${baseUrl}/calendars/${encodeURIComponent(calendarId)}/events`;

  async function request<T>(
    method: "DELETE" | "GET" | "PATCH" | "POST" | "PUT",
    url: string,
    { body, etag }: { readonly body?: GoogleEventWrite; readonly etag?: string | undefined } = {},
  ): Promise<T> {
    const sent = new Headers(await headers?.());
    if (body !== undefined) sent.set("Content-Type", "application/json");
    // Google writes only over the version you read, and answers 412 if it has changed since.
    if (etag !== undefined) sent.set("If-Match", etag);

    for (let attempt = 0; ; attempt++) {
      const response = await send(url, {
        body: body === undefined ? null : JSON.stringify(body),
        headers: sent,
        method,
      });
      if (response.ok) return (response.status === 204 ? undefined : await response.json()) as T;

      const error = await errorOf(response);
      const rateLimited =
        error.status === 429 || (error.status === 403 && rateLimits.has(error.reason ?? ""));
      if (attempt >= retries || !(rateLimited || error.status >= 500)) throw error;
      const retryAfter = Number(response.headers.get("Retry-After"));
      await sleep(retryAfter > 0 ? retryAfter * 1000 : retryDelay(attempt));
    }
  }

  return {
    /**
     * Every page of `events.list`. Series come as their masters, with their changed and cancelled
     * occurrences, since `singleEvents` stays off. The sync token is on the last page.
     */
    async list(query: GoogleEventsQuery) {
      const items: GoogleEvent[] = [];
      let pageToken: string | undefined;
      for (;;) {
        const params = new URLSearchParams(
          "syncToken" in query
            ? { syncToken: query.syncToken }
            : { timeMin: query.timeMin.toString() },
        );
        if ("timeMax" in query && query.timeMax !== undefined) {
          params.set("timeMax", query.timeMax.toString());
        }
        if (pageToken !== undefined) params.set("pageToken", pageToken);
        const page = await request<GoogleEventsPage>("GET", `${events}?${params}`);
        items.push(...(page.items ?? []));
        pageToken = page.nextPageToken;
        if (pageToken === undefined) return { items, nextSyncToken: page.nextSyncToken };
      }
    },

    /**
     * The occurrence a series' rule puts at `originalStart`, with its own ID and etag, cancelled
     * or not.
     */
    async instance(seriesId: string, originalStart: string) {
      const params = new URLSearchParams({ originalStart, showDeleted: "true" });
      for (;;) {
        const page = await request<GoogleEventsPage>(
          "GET",
          `${events}/${encodeURIComponent(seriesId)}/instances?${params}`,
        );
        const [instance] = page.items ?? [];
        if (instance !== undefined) return instance;
        // A page may be empty and still have more.
        if (page.nextPageToken === undefined) break;
        params.set("pageToken", page.nextPageToken);
      }
      throw new GoogleApiError(
        404,
        "notFound",
        `${seriesId} has no occurrence at ${originalStart}`,
      );
    },

    insert: (event: GoogleEventWrite) => request<GoogleEvent>("POST", events, { body: event }),

    patch: (id: string, fields: GoogleEventWrite, etag: string | undefined) =>
      request<GoogleEvent>("PATCH", `${events}/${encodeURIComponent(id)}`, { body: fields, etag }),

    remove: (id: string, etag: string | undefined) =>
      request<void>("DELETE", `${events}/${encodeURIComponent(id)}`, { etag }),

    /** Replaces the whole event: a field the write leaves out is cleared. */
    update: (id: string, event: GoogleEventWrite, etag: string | undefined) =>
      request<GoogleEvent>("PUT", `${events}/${encodeURIComponent(id)}`, { body: event, etag }),
  };
}

export type GoogleCalendarApi = ReturnType<typeof createGoogleCalendarApi>;

/** Google's error body: `{ error: { code, message, errors: [{ reason }] } }`. */
async function errorOf(response: Response): Promise<GoogleApiError> {
  const body = (await response.json().catch(() => undefined)) as
    | { error?: { errors?: { reason?: string }[]; message?: string } }
    | undefined;
  return new GoogleApiError(
    response.status,
    body?.error?.errors?.[0]?.reason,
    body?.error?.message ?? response.statusText,
  );
}

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

// app/api/google-calendar/[...path]/route.ts
import type { NextRequest } from "next/server";

/**
 * The signed-in user's Google access token, from your auth library, with the
 * `https://www.googleapis.com/auth/calendar.events` scope. `null` when they aren't signed in.
 */
declare function googleAccessToken(request: NextRequest): Promise<string | null>;

const calendarApi = "https://www.googleapis.com/calendar/v3";

/** The query parameters the client sends. */
const parameters = new Set([
  "originalStart",
  "pageToken",
  "showDeleted",
  "syncToken",
  "timeMax",
  "timeMin",
]);

/** Which calls go through: the methods each path takes, below `calendars/primary/events`. */
function allowed(method: string, event: readonly string[]): boolean {
  const [id, instances, ...rest] = event;
  if (id === undefined) return method === "GET" || method === "POST"; // list, insert
  if (id === "." || id === ".." || rest.length > 0) return false;
  if (instances !== undefined) return instances === "instances" && method === "GET";
  return method === "PATCH" || method === "PUT" || method === "DELETE";
}

/**
 * Sends the browser's Calendar API requests on to Google with the user's access token, which never
 * reaches the browser. Only the calls the client makes, on the user's own events.
 */
async function forward(request: NextRequest, { params }: { params: Promise<{ path: string[] }> }) {
  // Only your own pages: browsers mark a request from another site.
  if (request.headers.get("Sec-Fetch-Site") === "cross-site") {
    return Response.json({ error: { code: 403, message: "Forbidden" } }, { status: 403 });
  }
  const { path } = await params;
  const [calendars, calendarId, events, ...event] = path;
  const { searchParams } = request.nextUrl;
  if (
    calendars !== "calendars" ||
    calendarId !== "primary" ||
    events !== "events" ||
    !allowed(request.method, event) ||
    [...searchParams.keys()].some((name) => !parameters.has(name))
  ) {
    return Response.json({ error: { code: 404, message: "Not found" } }, { status: 404 });
  }

  const token = await googleAccessToken(request);
  if (token === null) {
    return Response.json({ error: { code: 401, message: "Sign in again" } }, { status: 401 });
  }

  const url = new URL(`${calendarApi}/${path.map(encodeURIComponent).join("/")}`);
  url.search = searchParams.toString();
  const headers = new Headers({ Authorization: `Bearer ${token}` });
  for (const name of ["Content-Type", "If-Match"]) {
    const value = request.headers.get(name);
    if (value !== null) headers.set(name, value);
  }
  const response = await fetch(url, {
    body: request.method === "GET" || request.method === "DELETE" ? null : await request.text(),
    headers,
    method: request.method,
  });

  // The status, Retry-After and Google's error body pass through, so the browser handles 410, 412
  // and 429 itself.
  const passed = new Headers();
  for (const name of ["Content-Type", "Retry-After"]) {
    const value = response.headers.get(name);
    if (value !== null) passed.set(name, value);
  }
  return new Response(response.body, { headers: passed, status: response.status });
}

export const GET = forward;
export const POST = forward;
export const PATCH = forward;
export const PUT = forward;
export const DELETE = forward;

"use client";

import {
  createCalendar,
  eventIdOf,
  weekRange,
  type CalendarEventChange,
  type CalendarFocus,
  type CalendarSelection,
  type CalendarVisibleRange,
  type EventId,
} from "@moltenship/calendar";
import {
  createCanonicalRecurrenceAdapter,
  createOccurrenceAdapter,
  createOccurrenceExpander,
  isRecurringChange,
  recurrenceEditScopes,
  resolveRecurrenceEdit,
  type RecurrenceAdapters,
  type RecurrenceEditScope,
  type RecurrenceOccurrence,
} from "@moltenship/calendar-recurrence";
import { useEffect, useMemo, useState, useSyncExternalStore, type MouseEvent } from "react";

import { calendarAnnouncements } from "@/components/calendar/announcements";
import { CalendarToolbar } from "@/components/calendar/calendar-toolbar";
import type { CalendarEventColor } from "@/components/calendar/event-colors";
import { useRecurrenceScopePrompt } from "@/components/calendar/recurrence-scope-dialog/use-recurrence-scope-prompt";
import { createWeekView } from "@/components/calendar/time-grid-view/time-grid-view";
import { Button } from "@/components/ui/button";

import type { GoogleCalendarEvent, GoogleEvent } from "@/lib/google-calendar";
import { createGoogleCalendarApi, GoogleApiError } from "@/lib/google-calendar-api";
import {
  createGoogleCalendarSync,
  newGoogleId,
  type GoogleCalendarSync,
} from "@/lib/google-calendar-sync";

/** What the calendar shows: an occurrence of a series, or a one-off event. */
export type GoogleOccurrence = RecurrenceOccurrence<GoogleCalendarEvent, string>;

const canonical = createCanonicalRecurrenceAdapter<GoogleEvent>();

export const adapters: RecurrenceAdapters<GoogleCalendarEvent, string, string> = {
  ...canonical,
  event: {
    ...canonical.event,
    // Google's "Show as": a free event doesn't make you busy, for `busyAt`, `useBusyResources`
    // and `conflictPolicy` alike. Without `transparency`, Google counts an event as busy, all-day
    // ones too; its own app saves new all-day events as free.
    isBusy: (event) => event.data.transparency !== "transparent",
  },
};

/**
 * Google's event colors, "1" (Lavender) to "11" (Tomato), as the theme's nearest. `colors.get`
 * has their hex values, if you'd rather show Google's own.
 */
const googleColors: Readonly<Record<string, CalendarEventColor>> = {
  "1": "purple",
  "2": "green",
  "3": "purple",
  "4": "pink",
  "5": "yellow",
  "6": "orange",
  "7": "teal",
  "8": "gray",
  "9": "blue",
  "10": "green",
  "11": "red",
};

export const Calendar = createCalendar<GoogleOccurrence>()({
  eventAdapter: createOccurrenceAdapter(adapters.event),
  views: [
    createWeekView<GoogleOccurrence>({
      describeEvent: ({ event }) =>
        event.data.transparency === "transparent" ? "free" : undefined,
      // Without `colorId`, an event has its calendar's color, here blue.
      getEventColor: ({ event }) => googleColors[event.data.colorId ?? ""] ?? "blue",
    }),
  ],
});

/**
 * An interval as Google's `start` and `end`, on `timeZone`'s clock unless the event has its own.
 * Each sets the field it uses and clears the other, so a move between all-day and timed works.
 */
export function toGoogleTimes(
  interval: CalendarEventInterval,
  timeZone: string,
): Pick<GoogleEventWrite, "end" | "start"> {
  if (interval.kind === "all-day") {
    // Google's `end.date` is the day after the last one, as the calendar's `end` is.
    const date = (day: Temporal.PlainDate) => ({ date: day.toString(), dateTime: null });
    return { end: date(interval.end), start: date(interval.start) };
  }
  const zone = (interval.kind === "timed" && interval.sourceTimeZone) || timeZone;
  const time = (at: Temporal.Instant | Temporal.PlainDateTime) => ({
    date: null,
    // RFC 3339 with the offset, such as 2026-10-20T11:00:00+02:00.
    dateTime: (at instanceof Temporal.Instant
      ? at.toZonedDateTimeISO(zone)
      : at.toZonedDateTime(zone)
    ).toString({ timeZoneName: "never" }),
    timeZone: zone,
  });
  return { end: time(interval.end), start: time(interval.start) };
}

/** Google event IDs are base32hex: lowercase a–v and digits. A UUID's hex digits fit. */
export const newGoogleId = () => crypto.randomUUID().replaceAll("-", "");

export function GoogleCalendar({ sync, timeZone }: GoogleCalendarProps) {
  const [today] = useState(() => Temporal.Now.plainDateISO(timeZone));
  const events = useSyncExternalStore(sync.subscribe, sync.getEvents, sync.getEvents);
  // One expander while the calendar is mounted, so series that didn't change keep their work.
  const [expander] = useState(() => createOccurrenceExpander(adapters));
  const [range, setRange] = useState(() => weekRange(today, { weekStartsOn: weekRules.firstDay }));
  const { occurrences } = useMemo(
    () => expander.expand(events, { range, timeZone }),
    [expander, events, range, timeZone],
  );
  const [selection, setSelection] = useState<CalendarSelection | null>(null);
  const [focus, setFocus] = useState<CalendarFocus | null>(null);
  const [status, setStatus] = useState("");
  const { ask, dialog } = useRecurrenceScopePrompt();

  function onVisibleRangeChange({ loadInstantRange, loadRange }: CalendarVisibleRange) {
    setRange(loadRange);
    // `timeMin` and `timeMax` for the dates on screen, and the pages a scrolling view keeps ready.
    sync
      .load(loadInstantRange)
      .then(loaded, (error) => setStatus(`Couldn't load: ${reasonOf(error)}`));
  }

  // A later load or sync that works clears a load error.
  function loaded() {
    setStatus((current) => (current.startsWith("Couldn't load") ? "" : current));
  }

// lib/google-calendar-sync.ts
import type { CalendarEventChange, CalendarEventInterval } from "@moltenship/calendar";
import {
  createCanonicalRecurrenceAdapter,
  createOccurrenceExpander,
  recurrenceOverrideEdit,
  type RecurrenceDate,
  type RecurrenceEdit,
  type RecurrenceSeriesEdit,
} from "@moltenship/calendar-recurrence";

import {
  fromGoogleEvents,
  readGoogleRecurrence,
  toGoogleRecurrence,
  type GoogleCalendarEvent,
  type GoogleEvent,
} from "./google-calendar";
import {
  GoogleApiError,
  type GoogleCalendarApi,
  type GoogleEventWrite,
} from "./google-calendar-api";

/** Instants to load events for, half-open, as `onVisibleRangeChange`'s `loadInstantRange`. */
export interface TimeRange {
  readonly end: Temporal.Instant;
  readonly start: Temporal.Instant;
}

/** What `resolveRecurrenceEdit` returns for a change it accepted. */
export type GoogleEdit = Exclude<
  RecurrenceEdit<GoogleCalendarEvent, string, string>,
  { type: "rejected" }
>;

export interface GoogleCalendarSync {
  /** The events loaded so far, for the expander: the same array until one changes. */
  readonly getEvents: () => readonly GoogleCalendarEvent[];
  /** Calls `listener` whenever the events change, and returns a function that stops it. */
  readonly subscribe: (listener: () => void) => () => void;
  /** Loads the events `range` needs that aren't loaded yet. */
  readonly load: (range: TimeRange) => Promise<void>;
  /** Applies every change since the last sync, or syncs again from scratch after a 410. */
  readonly sync: () => Promise<void>;
  /** Writes an edit to Google, then syncs. Throws, after the sync, if Google refused a write. */
  readonly save: (edit: GoogleEdit, timeZone: string) => Promise<void>;
}

const day = { hours: 24 };

export function createGoogleCalendarSync(api: GoogleCalendarApi): GoogleCalendarSync {
  /** Google's events by ID: masters, changed and cancelled occurrences, one-off events. */
  const stored = new Map<string, GoogleEvent>();
  const mapped = new WeakMap<GoogleEvent, GoogleCalendarEvent | null>();
  const listeners = new Set<() => void>();
  let events: readonly GoogleCalendarEvent[] = [];
  /** The sync covers every event from here on. */
  let syncedFrom: Temporal.Instant | undefined;
  /** Dates before `syncedFrom` loaded since, sorted and apart. */
  let earlier: TimeRange[] = [];
  let lastRange: TimeRange | undefined;
  let syncToken: string | undefined;

  // One request chain at a time, so an older answer never overwrites a newer one.
  let queue: Promise<unknown> = Promise.resolve();
  function enqueue<T>(task: () => Promise<T>): Promise<T> {
    const run = queue.then(task, task);
    queue = run.catch(() => undefined);
    return run;
  }

  function changed() {
    // Each Google event maps once, so the expander reuses its work for the ones that didn't change.
    const next = [...stored.values()].flatMap((item) => {
      if (!mapped.has(item)) {
        const { events: mappedEvents, problems } = fromGoogleEvents([item]);
        for (const problem of problems) console.warn(`Google Calendar: ${problem}`);
        mapped.set(item, mappedEvents[0] ?? null);
      }
      return mapped.get(item) ?? [];
    });
    if (next.length === events.length && next.every((event, index) => event === events[index])) {
      return;
    }
    events = next;
    for (const listener of listeners) listener();
  }

  /** Google's answer, by ID. A cancelled occurrence stays, since it hides that occurrence. */
  function apply(items: readonly GoogleEvent[]) {
    const deleted = new Set<string>();
    for (const item of items) {
      if (item.recurringEventId !== undefined && deleted.has(item.recurringEventId)) continue;
      if (item.status !== "cancelled" || item.recurringEventId !== undefined) {
        stored.set(item.id, item);
        continue;
      }
      stored.delete(item.id);
      // A deleted series takes its changed and cancelled occurrences with it, in this answer too.
      deleted.add(item.id);
      for (const [id, other] of stored) if (other.recurringEventId === item.id) stored.delete(id);
    }
  }
  /** The etags of a series' master and changed occurrences, or of one occurrence's, by ID. */
  function versions(seriesId: string, recurrenceId?: RecurrenceDate) {
    const found = new Map<string, string | undefined>();
    for (const { data, override } of events) {
      const inSeries = data.id === seriesId || override?.seriesId === seriesId;
      const at =
        recurrenceId === undefined ||
        (override !== undefined &&
          keyOf(override.seriesId, override.recurrenceId) === keyOf(seriesId, recurrenceId));
      if (inSeries && at) found.set(data.id, data.etag);
    }
    return found;
  }

/**
 * The full sync, as Google's sync guide does it: every event that ends after the first date on
 * screen, with no `timeMax`, and the token that syncs them from then on.
 */
async function fullSync(range: TimeRange) {
  // All-day events are dates on the Google calendar's own clock, which may not be the one on
  // screen, so lists reach a day further.
  const { items, nextSyncToken } = await api.list({ timeMin: range.start.subtract(day) });
  // Swapped in once the list has worked, so a failure leaves the store as it was.
  stored.clear();
  apply(items);
  syncedFrom = range.start;
  earlier = [];
  syncToken = nextSyncToken;
  changed();
}

async function loadNow(range: TimeRange) {
  lastRange = range;
  if (syncedFrom === undefined) return fullSync(range);
  // Later dates are in the store already. Earlier ones load once, between two bounds.
  const end = Temporal.Instant.compare(range.end, syncedFrom) < 0 ? range.end : syncedFrom;
  for (const gap of missing(earlier, { end, start: range.start })) {
    const { items } = await api.list({
      timeMax: gap.end.add(day),
      timeMin: gap.start.subtract(day),
    });
    apply(items);
    earlier = merged(earlier, gap);
    changed();
  }
}

async function syncNow() {
  if (syncToken === undefined) {
    // The first load failed: try it again.
    if (syncedFrom === undefined && lastRange !== undefined) await fullSync(lastRange);
    return;
  }
  try {
    // Every change since the last sync, whatever its dates.
    const { items, nextSyncToken } = await api.list({ syncToken });
    apply(items);
    syncToken = nextSyncToken ?? syncToken;
    changed();
  } catch (error) {
    // 410 Gone: the token expired. Sync again from scratch, from the dates on screen. Until that
    // works, the old events stay, and the next sync tries again.
    if (!isStatus(error, 410) || lastRange === undefined) throw error;
    await fullSync(lastRange);
  }
}

useEffect(() => {
  // Catch up when the tab comes back, and every minute: push notifications can be late, or lost.
  const catchUp = () => {
    if (document.visibilityState === "visible") sync.sync().then(loaded, () => undefined);
  };
  document.addEventListener("visibilitychange", catchUp);
  const timer = setInterval(catchUp, 60_000);
  return () => {
    document.removeEventListener("visibilitychange", catchUp);
    clearInterval(timer);
  };
}, [sync]);

POST https://www.googleapis.com/calendar/v3/calendars/primary/events/watch
Authorization: Bearer <access token>
Content-Type: application/json

{ "id": "<a new UUID>", "type": "web_hook", "address": "https://example.com/api/google-calendar/notifications" }

async function onEventChange(change: OccurrenceChange) {
  let scope: RecurrenceEditScope = "this";
  // Google keeps deleted instances as cancelled overrides, which hide occurrences as EXDATEs do.
  const options = { overrides: events, timeZone };
  if (isRecurringChange(change)) {
    const scopes = recurrenceEditScopes(change, adapters, options);
    if (scopes.length === 0) {
      setStatus("This repeating event can't change that way.");
      throw new Error("No scope applies");
    }
    const picked = await ask({
      action: change.cause === "delete" ? "delete" : "edit",
      eventTitle: change.event.event.title,
      scopes,
    });
    if (picked === null) throw new DOMException("Cancelled", "AbortError");
    scope = picked;
  }
  const edit = resolveRecurrenceEdit(change, scope, adapters, {
    ...options,
    // Google takes IDs you pick, so a "following" edit's new series is known before it's saved.
    newSeriesId: newGoogleId(),
    occurrences,
  });
  if (edit.type === "rejected") {
    setStatus(edit.message);
    throw new Error(edit.message);
  }

  setStatus("Saving…");
  try {
    // The change shows, pending, until Google answers. Throwing rolls it back.
    await sync.save(edit, timeZone);
  } catch (error) {
    setStatus(`Not saved: ${reasonOf(error)}`);
    throw error;
  }
  setStatus("Saved.");
  if (edit.type === "series") {
    setSelection((current) => renamed(current, edit.occurrenceIds));
    setFocus((current) => renamed(current, edit.occurrenceIds));
  }
}

async function saveNow(edit: GoogleEdit, timeZone: string) {
  try {
    if (edit.type === "event") await saveEvent(edit.change, timeZone);
    else await saveSeries(edit, timeZone);
  } finally {
    // Picks up what Google did, such as the newer version a 412 refused to overwrite.
    await syncNow().catch((error: unknown) => console.warn("Google Calendar sync failed", error));
    changed();
  }
}

/** A new event, or a change to a one-off event. */
async function saveEvent(
  change: CalendarEventChange<GoogleCalendarEvent, string, string>,
  timeZone: string,
) {
  if (change.cause === "create") {
    const times = toGoogleTimes(change.proposed, timeZone);
    await insert({ id: newGoogleId(), summary: "New event", ...times });
    return;
  }
  // The etag of the version on screen: if someone changed it since, Google answers 412.
  const { data } = change.event;
  if (change.cause === "delete") {
    await remove(data, data.etag);
    return;
  }
  const times = toGoogleTimes(change.proposed, data.start?.timeZone ?? timeZone);
  apply([await api.patch(data.id, times, data.etag)]);
}

/** Inserts an event with the ID it names. A 409 means a try whose answer was lost got there. */
async function insert(event: GoogleEventWrite) {
  try {
    apply([await api.insert(event)]);
  } catch (error) {
    if (!isStatus(error, 409)) throw error;
  }
}

/** Deletes an event, which Google keeps as cancelled. One already gone is done. */
async function remove(event: GoogleEvent, etag: string | undefined) {
  if (event.status === "cancelled") return;
  try {
    await api.remove(event.id, etag);
  } catch (error) {
    if (!isStatus(error, 404, 410)) throw error;
  }
  // Google's answer to a delete has no body, so the cancelled one's etag isn't known.
  apply([{ ...event, etag: undefined, status: "cancelled" }]);
}

/** Why Google refused a request, for the user. */
function reasonOf(error: unknown): string {
  if (!(error instanceof GoogleApiError)) return error instanceof Error ? error.message : "";
  if (error.status === 412) return "it changed in Google Calendar. This is the latest.";
  if (error.status === 410) return "it was deleted in Google Calendar.";
  const rateLimited = ["rateLimitExceeded", "userRateLimitExceeded"].includes(error.reason ?? "");
  if (error.status === 429 || rateLimited) return "Google is busy. Try again in a minute.";
  return error.message;
}

async function saveSeries(
  edit: RecurrenceSeriesEdit<GoogleCalendarEvent, string, string>,
  timeZone: string,
) {
  const { newSeries, override, series, seriesId } = edit;
  const zoneOf = (event: GoogleEvent) => event.start?.timeZone ?? timeZone;
  // Google deletes a series' changed and cancelled occurrences with it.
  if (series.action === "delete") {
    await remove(series.event.data, series.event.data.etag);
    return;
  }
  // The writes below replace instances the store read, some without etags. So sync first, and
  // stop if the series changed in Google since the user saw it: the master and the changed
  // occurrences, or for "this", the occurrence's own instance. The edit holds what they saw of
  // the master and the edited occurrence; the store may have newer versions already.
  const only = edit.scope === "this" ? edit.recurrenceId : undefined;
  const edited = override?.action === "create" ? undefined : override?.event;
  const before = versions(seriesId, only);
  if (only !== undefined) before.clear();
  // The edited occurrence as the user saw it: its exception, or none.
  else for (const id of versions(seriesId, edit.recurrenceId).keys()) before.delete(id);
  if (series.action === "update" && only === undefined) {
    before.set(seriesId, series.event.data.etag);
  }
  if (edited !== undefined) before.set(edited.data.id, edited.data.etag);
  await syncNow();
  const after = versions(seriesId, only);
  if (only !== undefined) {
    // Cancelled in Google meanwhile: a delete is done, and a move would bring it back.
    const now = events.find(
      (event) => event.override?.seriesId === seriesId && after.has(event.data.id),
    );
    if (now?.override?.cancelled === true && before.get(now.data.id) !== now.data.etag) {
      if (edit.cause === "delete") return;
      throw new GoogleApiError(410, "deleted", "The occurrence was deleted in Google Calendar.");
    }
  }
  const changedInGoogle = [...after].some(([id, etag]) => {
    if (!before.has(id)) return true;
    // Undefined: cancelled here, and Google's answer to a delete has no etag.
    const seen = before.get(id);
    return seen !== undefined && seen !== etag;
  });
  if (changedInGoogle || (before.has(seriesId) && !after.has(seriesId))) {
    throw new GoogleApiError(412, "conditionNotMet", "The series changed in Google Calendar.");
  }

  // "This event" deletes cancel the occurrence's instance, as Google does, and leave the master.
  if (edit.scope === "this" && edit.cause === "delete") {
    const write: OccurrenceWrite = {
      from: edited,
      placement: "cancel",
      recurrenceId: edit.recurrenceId,
      seriesId,
    };
    await writeOccurrences([write], [], timeZone);
    return;
  }
  // The new `recurrence` is written from what `fromGoogleEvents` read, which would drop the
  // lines it couldn't, such as EXRULE.
  const master = series.action === "update" ? series.event.data : undefined;
  if (master !== undefined && readGoogleRecurrence(master.recurrence ?? []).problems.length > 0) {
    throw new Error("This series has rules the app can't write back. Change it in Google.");
  }
  // The series' other changed and cancelled occurrences, which the edit moves or ends.
  const others = events
    .filter((event) => event.override?.seriesId === seriesId && event.data.id !== edited?.data.id)
    .map((event) => ({ event, next: recurrenceOverrideEdit(edit, event.override!.recurrenceId) }))
    .filter(({ next }) => next.action !== "keep");

  // "This and following events" is Google's split: a new series from the occurrence on, and the
  // old one ended before it. The new one goes first, so a failure leaves the old one whole.
  const newSeriesId = newSeries?.id ?? newGoogleId();
  if (newSeries !== undefined) {
    const zone = zoneOf(newSeries.from.data);
    await insert({
      ...contentOf(newSeries.from.data),
      id: newSeriesId,
      ...toGoogleTimes(newSeries.placement, zone),
      recurrence: toGoogleRecurrence(newSeries.recurrence, zone),
    });
  }
  if (series.action === "update") {
    const zone = zoneOf(series.event.data);
    const fields = {
      ...toGoogleTimes(series.placement, zone),
      recurrence: toGoogleRecurrence(series.recurrence, zone),
    };
    try {
      apply([await api.patch(seriesId, fields, series.event.data.etag)]);
    } catch (error) {
      // With the old series still whole, the new one would repeat it: take it back.
      if (newSeries !== undefined) {
        await remove({ id: newSeriesId }, undefined).catch(() => undefined);
      }
      throw error;
    }
  }

  // The edited occurrence, and the others, which follow the series' new times or end with it.
  const writes: OccurrenceWrite[] = [];
  const left: GoogleCalendarEvent[] = [];
  if (override?.action === "create") {
    writes.push({ placement: override.placement, recurrenceId: override.recurrenceId, seriesId });
  } else if (override?.action === "update") {
    writes.push({
      from: override.event,
      placement: override.cancelled ? "cancel" : override.placement,
      recurrenceId: override.recurrenceId,
      seriesId: override.series === "new" ? newSeriesId : seriesId,
    });
  } else if (override?.action === "delete") {
    left.push(override.event);
  }
  for (const { event, next } of others) {
    if (next.action === "delete") left.push(event);
    if (next.action !== "update") continue;
    writes.push({
      from: event,
      placement: event.override!.cancelled ? "cancel" : event,
      recurrenceId: next.recurrenceId,
      seriesId: next.series === "new" ? newSeriesId : seriesId,
    });
  }
  await writeOccurrences(writes, left, timeZone);
}

/**
 * Writes each occurrence to the instance at its series and original start, then clears the
 * instances the moved ones leave. Google names an exception by its series and original start,
 * and neither can change, so an occurrence that moves to another original start is written to
 * the instance there. One may land where another leaves, so every write comes first.
 */
async function writeOccurrences(
  writes: readonly OccurrenceWrite[],
  left: readonly GoogleCalendarEvent[],
  timeZone: string,
) {
  const written = new Set<string>();
  const vacated = [...left];
  for (const { from, placement, recurrenceId, seriesId } of writes) {
    written.add(keyOf(seriesId, recurrenceId));
    const stays =
      from?.override !== undefined &&
      keyOf(from.override.seriesId, from.override.recurrenceId) === keyOf(seriesId, recurrenceId);
    // The etag of the version on screen, or of the instance just read.
    let instance: GoogleEvent;
    try {
      instance = stays ? from.data : await api.instance(seriesId, recurrenceId.toString());
    } catch (error) {
      // An occurrence to cancel whose series is gone is gone too.
      if (placement === "cancel" && !stored.has(seriesId) && isStatus(error, 404, 410)) continue;
      throw error;
    }
    // Cancelled in Google since it loaded: a change to it would bring it back.
    if (from === undefined && instance.status === "cancelled" && placement !== "cancel") {
      throw new GoogleApiError(410, "deleted", "The occurrence was deleted in Google Calendar.");
    }
    if (placement === "cancel") await remove(instance, instance.etag);
    // The moved occurrence's own title, color and the rest, not the instance's.
    else await replace(instance, from?.data ?? instance, placement, instance.etag, timeZone);
    if (from !== undefined && !stays) vacated.push(from);
  }
  for (const { data, override } of vacated) {
    if (override === undefined || written.has(keyOf(override.seriesId, override.recurrenceId))) {
      continue;
    }
    // No etags: the edit replaces these, whatever changed on them since.
    const master = stored.get(override.seriesId);
    const occurrence = master && occurrenceAt(master, override.recurrenceId);
    // The series' rule still has an occurrence there, so it shows as the series has it.
    if (master !== undefined && occurrence !== undefined) {
      await replace(data, master, occurrence, undefined, timeZone);
    } else {
      await remove(data, undefined);
    }
  }
}

/**
 * Replaces `instance` with `content` at `interval`: all of it, with `events.update`, so nothing
 * of what was there before stays.
 */
async function replace(
  instance: GoogleEvent,
  content: GoogleEvent,
  interval: CalendarEventInterval,
  etag: string | undefined,
  timeZone: string,
) {
  const fields: GoogleEventWrite = {
    ...contentOf(content),
    ...toGoogleTimes(interval, content.start?.timeZone ?? timeZone),
    originalStartTime: instance.originalStartTime,
    recurringEventId: instance.recurringEventId,
    // A cancelled instance comes back.
    status: content.status === "tentative" ? "tentative" : "confirmed",
  };
  try {
    apply([await api.update(instance.id, fields, etag)]);
  } catch (error) {
    // An instance the edit clears may be gone already.
    if (etag !== undefined || !isStatus(error, 404, 410)) throw error;
  }
}

/** The calendar a page renders, with one sync store for as long as it's mounted. */
export function SyncedCalendar({ timeZone }: { readonly timeZone: string }) {
  // The browser calls your route, which adds the user's access token.
  const [sync] = useState(() =>
    createGoogleCalendarSync(createGoogleCalendarApi({ baseUrl: "/api/google-calendar" })),
  );
  return <GoogleCalendar sync={sync} timeZone={timeZone} />;
}