Maintain Calendar events by identity

const CALENDAR_WORKFLOW = {
  calendarId: '',
  setupConfirmation: '', // PRIVATE UTC CALENDAR WITHOUT NOTIFICATIONS
  allowEventWrites: false,
  recoveryKey: '',
  recoveryICalUID: '',
  recoveryConfirmation: '',
};

// Supplied fictional data. Keep each key and kind stable after its first attempt.
const CALENDAR_ITEMS = [
  {
    key: 'plan-review',
    kind: 'timed',
    title: 'Exhibit plan review',
    start: '2030-06-17T13:00:00Z',
    end: '2030-06-17T14:00:00Z',
    description: 'Fictional rehearsal. Review the exhibit layout.',
  },
  {
    key: 'quiet-days',
    kind: 'all-day',
    title: 'Quiet preparation days',
    start: '2030-06-18',
    end: '2030-06-20', // Exclusive: June 18 and June 19 are included.
    description: 'Fictional rehearsal. Prepare the display notes.',
  },
];

const CALENDAR_LEDGER_KEY = 'calendar-workflows.v1';
const PRACTICE_START = '2030-06-15T00:00:00Z';
const PRACTICE_END = '2030-06-23T00:00:00Z';
const MAX_CALENDAR_ITEMS = 3;
const RECOVERY_PAGE_SIZE = 10;

function previewCalendarPlan() {
  const context = readCalendarContext_();
  const plan = buildCalendarPlan_(context);
  for (const entry of plan) {
    console.log(JSON.stringify({
      key: entry.item.key,
      kind: entry.item.kind,
      title: entry.item.title,
      start: entry.item.start.toISOString(),
      endExclusive: entry.item.end.toISOString(),
      state: entry.record ? entry.record.state : 'NEW',
      iCalUID: entry.record ? entry.record.iCalUID : '',
      action: entry.action,
      changes: entry.changes,
    }));
  }
  console.log(JSON.stringify({
    plannedItems: plan.length,
    trackedItems: context.ledger.records.length,
    blocked: plan.some(/** @param {*} entry */ (entry) => entry.action === 'BLOCKED'),
    eventWrites: 0,
  }));
}

function applyCalendarPlan() {
  if (CALENDAR_WORKFLOW.allowEventWrites !== true) {
    throw new Error('Event writes are disabled. Preview and review before enabling them.');
  }
  withCalendarUserLock_(() => {
    const context = readCalendarContext_();
    const plan = buildCalendarPlan_(context);
    if (plan.some(/** @param {*} entry */ (entry) => entry.action === 'BLOCKED')) {
      throw new Error('An uncertain create blocks all event writes. Inspect and reconcile it.');
    }
    for (const entry of plan) {
      if (entry.action === 'CREATE') {
        createCalendarItem_(context, entry.item);
      } else if (entry.action === 'UPDATE') {
        updateCalendarItem_(context.ledger, entry);
      } else if (entry.action === 'CHECKPOINT_ONLY') {
        entry.record.state = 'READY';
        saveCalendarLedger_(context.ledger);
      }
      console.log(JSON.stringify({ key: entry.item.key, action: entry.action }));
    }
  });
}

function inspectCalendarLedger() {
  console.log(JSON.stringify(readCalendarLedger_()));
}

function findCalendarRecoveryCandidates() {
  const context = readCalendarContext_();
  const record = requireUncertainRecord_(context.ledger);
  const scan = scanCalendarRecovery_(context.calendar, record);
  console.log(JSON.stringify({
    key: record.key,
    marker: record.marker,
    windowStart: PRACTICE_START,
    windowEndExclusive: PRACTICE_END,
    pageMayBeTruncated: scan.truncated,
    matchingCandidates: scan.matches.map(/** @param {CalendarApp.CalendarEvent} event */ (event) => ({
      iCalUID: event.getId(),
      title: event.getTitle(),
      allDay: event.isAllDayEvent(),
      start: event.getStartTime().toISOString(),
      endExclusive: event.getEndTime().toISOString(),
    })),
  }));
}

function adoptCalendarRecovery() {
  withCalendarUserLock_(() => {
    const context = readCalendarContext_();
    const record = requireUncertainRecord_(context.ledger);
    const id = CALENDAR_WORKFLOW.recoveryICalUID;
    const confirmation = 'ADOPT ' + id + ' FOR ' + record.key;
    if (!isCalendarText_(id, 512) || CALENDAR_WORKFLOW.recoveryConfirmation !== confirmation) {
      throw new Error('Supply the inspected CalendarApp iCalUID and exact ADOPT confirmation.');
    }
    const scan = scanCalendarRecovery_(context.calendar, record);
    if (scan.truncated || scan.matches.length !== 1 || scan.matches[0].getId() !== id) {
      throw new Error('Adoption requires one matching candidate in a non-full recovery page. Stop and inspect.');
    }
    const item = context.items.find(/** @param {*} candidate */ (candidate) => candidate.key === record.key);
    requireSafeCalendarEvent_(scan.matches[0], record, item);
    if (context.ledger.records.some(/** @param {*} candidate */ (candidate) => candidate.iCalUID === id)) {
      throw new Error('This event identity is already recorded. Preserve the ledger.');
    }
    record.iCalUID = id;
    record.state = 'ID_KNOWN';
    saveCalendarLedger_(context.ledger);
    console.log(JSON.stringify({ key: record.key, state: record.state, iCalUID: id }));
  });
}

function illustrateCalendarInstants() {
  // This function only calculates and logs. It does not read or write Calendar.
  const first = new Date('2017-11-05T01:30:00-04:00');
  const second = new Date('2017-11-05T01:30:00-05:00');
  console.log(JSON.stringify({
    firstUtc: first.toISOString(),
    secondUtc: second.toISOString(),
    minutesApart: (second.getTime() - first.getTime()) / 60000,
    firstInNewYork: Utilities.formatDate(first, 'America/New_York', 'yyyy-MM-dd HH:mm Z'),
    secondInNewYork: Utilities.formatDate(second, 'America/New_York', 'yyyy-MM-dd HH:mm Z'),
  }));
}

function readCalendarContext_() {
  const config = CALENDAR_WORKFLOW;
  if (!isCalendarText_(config.calendarId, 256) || /\s|\//.test(config.calendarId) ||
      config.calendarId.toLowerCase() === 'primary') {
    throw new Error('Set the exact ID of the new secondary practice calendar, not a URL or primary.');
  }
  if (config.setupConfirmation !== 'PRIVATE UTC CALENDAR WITHOUT NOTIFICATIONS') {
    throw new Error('Complete the private UTC calendar and notification setup before confirming it.');
  }
  const items = readCalendarItems_();
  const ledger = readCalendarLedger_();
  if (ledger.calendarId && ledger.calendarId !== config.calendarId) {
    throw new Error('This ledger belongs to a different calendar. Do not retarget or reset it.');
  }
  for (const record of ledger.records) {
    const item = items.find((candidate) => candidate.key === record.key);
    if (!item || item.kind !== record.kind) {
      throw new Error('Keep every tracked source key and kind unchanged: ' + record.key);
    }
  }
  const newCount = items.filter(/** @param {*} item */ (item) => !ledger.records.some(/** @param {*} record */ (record) => record.key === item.key)).length;
  if (ledger.records.length + newCount > MAX_CALENDAR_ITEMS) {
    throw new Error('The three-item lifetime cap is full. Do not erase an old identity.');
  }
  if (!isUtcCalendarZone_(Session.getScriptTimeZone())) {
    throw new Error('The script time zone must be UTC. Restore the supplied manifest.');
  }
  const calendar = CalendarApp.getCalendarById(config.calendarId);
  if (!calendar || calendar.isMyPrimaryCalendar() || !calendar.isOwnedByMe() ||
      calendar.getName() !== 'Book Calendar Practice' || !isUtcCalendarZone_(calendar.getTimeZone())) {
    throw new Error('Target must be your owned secondary Book Calendar Practice calendar in UTC.');
  }
  ledger.calendarId = config.calendarId;
  return { calendar: calendar, items: items, ledger: ledger };
}

/** @param {*} context */
function buildCalendarPlan_(context) {
  return context.items.map(/** @param {*} item */ (item) => {
    const record = context.ledger.records.find(/** @param {*} candidate */ (candidate) => candidate.key === item.key);
    if (!record) return { item: item, record: null, event: null, action: 'CREATE', changes: [] };
    if (record.state === 'CREATE_UNCERTAIN') {
      return { item: item, record: record, event: null, action: 'BLOCKED', changes: [] };
    }
    const event = context.calendar.getEventById(record.iCalUID);
    requireSafeCalendarEvent_(event, record, item);
    const changes = [];
    if (event.getTitle() !== item.title) changes.push('title');
    if (event.getDescription() !== calendarDescription_(item, record)) changes.push('description');
    const start = item.kind === 'all-day' ? event.getAllDayStartDate() : event.getStartTime();
    const end = item.kind === 'all-day' ? event.getAllDayEndDate() : event.getEndTime();
    if (start.getTime() !== item.start.getTime() || end.getTime() !== item.end.getTime()) changes.push('time');
    if (event.getEmailReminders().length || event.getPopupReminders().length) changes.push('reminders');
    const action = changes.length ? 'UPDATE' : record.state === 'READY' ? 'NO_CHANGE' : 'CHECKPOINT_ONLY';
    return { item: item, record: record, event: event, action: action, changes: changes };
  });
}

/** @param {CalendarApp.CalendarEvent|null} event @param {*} record @param {*} item */
function requireSafeCalendarEvent_(event, record, item) {
  if (!event) throw new Error('Known event is missing or inaccessible: ' + record.key + '. Do not recreate it.');
  if (!event.isOwnedByMe() || event.isRecurringEvent() || event.getGuestList().length ||
      !event.getDescription().split('\n').includes(record.marker)) {
    throw new Error('Event ownership, guests, recurrence or marker changed: ' + record.key + '. Stop and inspect.');
  }
  if (event.isAllDayEvent() !== (item.kind === 'all-day')) {
    throw new Error('Do not change a tracked event between timed and all-day: ' + record.key);
  }
}

/** @param {*} context @param {*} item */
function createCalendarItem_(context, item) {
  const record = {
    key: item.key,
    kind: item.kind,
    marker: '[BookCalendar-' + Utilities.getUuid() + ']',
    iCalUID: '',
    state: 'CREATE_UNCERTAIN',
  };
  if (context.ledger.records.some(/** @param {*} candidate */ (candidate) => candidate.marker === record.marker)) {
    throw new Error('Marker collision. No event was attempted for this item.');
  }
  context.ledger.records.push(record);
  saveCalendarLedger_(context.ledger); // Intent before dispatch, for this item.
  const options = { description: calendarDescription_(item, record), sendInvites: false };
  const event = item.kind === 'all-day'
    ? context.calendar.createAllDayEvent(item.title, item.start, item.end, options)
    : context.calendar.createEvent(item.title, item.start, item.end, options);
  const id = event.getId();
  if (!isCalendarText_(id, 512)) throw new Error('Creation returned no usable identity. Inspect the saved marker.');
  record.iCalUID = id;
  record.state = 'ID_KNOWN';
  saveCalendarLedger_(context.ledger); // Save identity before any further event mutation.
  event.removeAllReminders();
  record.state = 'READY';
  saveCalendarLedger_(context.ledger); // Finish this item before starting the next.
}

/** @param {*} ledger @param {*} entry */
function updateCalendarItem_(ledger, entry) {
  const item = entry.item;
  const record = entry.record;
  const event = entry.event;
  record.state = 'UPDATING';
  saveCalendarLedger_(ledger);
  if (entry.changes.includes('title')) event.setTitle(item.title);
  if (entry.changes.includes('description')) event.setDescription(calendarDescription_(item, record));
  if (entry.changes.includes('time')) {
    if (item.kind === 'all-day') event.setAllDayDates(item.start, item.end);
    else event.setTime(item.start, item.end);
  }
  if (entry.changes.includes('reminders')) event.removeAllReminders();
  record.state = 'READY';
  saveCalendarLedger_(ledger);
}

/** @param {*} ledger */
function requireUncertainRecord_(ledger) {
  const record = ledger.records.find(/** @param {*} candidate */ (candidate) => candidate.key === CALENDAR_WORKFLOW.recoveryKey);
  if (!record || record.state !== 'CREATE_UNCERTAIN') {
    throw new Error('Set recoveryKey to a saved CREATE_UNCERTAIN item from inspectCalendarLedger.');
  }
  return record;
}

/** @param {CalendarApp.Calendar} calendar @param {*} record */
function scanCalendarRecovery_(calendar, record) {
  // No search option: CalendarApp applies search after the start/max slice.
  const events = calendar.getEvents(new Date(PRACTICE_START), new Date(PRACTICE_END), {
    start: 0,
    max: RECOVERY_PAGE_SIZE,
  });
  return {
    truncated: events.length >= RECOVERY_PAGE_SIZE,
    matches: events.filter(/** @param {CalendarApp.CalendarEvent} event */ (event) => event.getDescription().split('\n').includes(record.marker)),
  };
}

/** @param {*} item @param {*} record */
function calendarDescription_(item, record) {
  return item.description + '\n\n' + record.marker;
}

function readCalendarItems_() {
  if (!Array.isArray(CALENDAR_ITEMS) || CALENDAR_ITEMS.length < 1 || CALENDAR_ITEMS.length > MAX_CALENDAR_ITEMS) {
    throw new Error('Supply one through three fictional items, not an unbounded source.');
  }
  const keys = new Set();
  const windowStart = new Date(PRACTICE_START).getTime();
  const windowEnd = new Date(PRACTICE_END).getTime();
  return CALENDAR_ITEMS.map(/** @param {*} item */ (item) => {
    if (!item || !isCalendarKey_(item.key) || keys.has(item.key) ||
        !['timed', 'all-day'].includes(item.kind) || !isCalendarText_(item.title, 120) ||
        /[\r\n<>]/.test(item.title) || !isCalendarText_(item.description, 500) ||
        /[<>]|BookCalendar-/.test(item.description)) {
      throw new Error('Use unique short keys, timed/all-day kinds, and short plain-text titles and descriptions.');
    }
    keys.add(item.key);
    const start = parseCalendarDate_(item.start, item.kind);
    const end = parseCalendarDate_(item.end, item.kind);
    if (end.getTime() <= start.getTime() || start.getTime() < windowStart || end.getTime() > windowEnd) {
      throw new Error('Use a positive interval entirely within June 15 through June 22, 2030.');
    }
    return { key: item.key, kind: item.kind, title: item.title, description: item.description, start: start, end: end };
  });
}

/** @param {string} text @param {'timed'|'all-day'} kind */
function parseCalendarDate_(text, kind) {
  const pattern = kind === 'all-day' ? /^\d{4}-\d{2}-\d{2}$/ : /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
  if (typeof text !== 'string' || !pattern.test(text)) {
    throw new Error('Use YYYY-MM-DD for all-day dates and YYYY-MM-DDTHH:mm:ssZ for timed instants.');
  }
  const date = new Date(kind === 'all-day' ? text + 'T00:00:00Z' : text);
  if (!Number.isFinite(date.getTime())) throw new Error('Invalid calendar date: ' + text);
  const roundTrip = kind === 'all-day' ? date.toISOString().slice(0, 10) : date.toISOString().replace('.000Z', 'Z');
  if (roundTrip !== text) throw new Error('Date normalization changed the supplied value: ' + text);
  return date;
}

function readCalendarLedger_() {
  const raw = PropertiesService.getUserProperties().getProperty(CALENDAR_LEDGER_KEY);
  if (raw === null) return { calendarId: '', records: [] };
  let ledger;
  try { ledger = JSON.parse(raw); }
  catch (error) { throw new Error('Ledger JSON is invalid. Preserve it; do not reset it.'); }
  if (!ledger || !isCalendarText_(ledger.calendarId, 256) ||
      !Array.isArray(ledger.records) || ledger.records.length > MAX_CALENDAR_ITEMS) {
    throw new Error('Ledger shape or size is invalid. Preserve it; do not reset it.');
  }
  const keys = new Set();
  const markers = new Set();
  const ids = new Set();
  for (const record of ledger.records) {
    if (!record || !isCalendarKey_(record.key) || keys.has(record.key) ||
        !['timed', 'all-day'].includes(record.kind) || typeof record.marker !== 'string' ||
        !/^\[BookCalendar-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\]$/i.test(record.marker) ||
        markers.has(record.marker) || typeof record.iCalUID !== 'string' ||
        !['CREATE_UNCERTAIN', 'ID_KNOWN', 'UPDATING', 'READY'].includes(record.state) ||
        (record.state === 'CREATE_UNCERTAIN' ? record.iCalUID !== '' : !isCalendarText_(record.iCalUID, 512)) ||
        (record.iCalUID && ids.has(record.iCalUID))) {
      throw new Error('Ledger record is invalid. Preserve the identities and inspect the saved data.');
    }
    keys.add(record.key);
    markers.add(record.marker);
    if (record.iCalUID) ids.add(record.iCalUID);
  }
  return ledger;
}

/** @param {*} ledger */
function saveCalendarLedger_(ledger) {
  const text = JSON.stringify(ledger);
  if (Utilities.newBlob(text).getBytes().length > 8000) {
    throw new Error('Ledger exceeds this example\'s storage allowance. Do not delete recovery records.');
  }
  PropertiesService.getUserProperties().setProperty(CALENDAR_LEDGER_KEY, text);
}

/** @param {function(): void} operation */
function withCalendarUserLock_(operation) {
  const lock = LockService.getUserLock();
  if (!lock.tryLock(1000)) throw new Error('Another run holds this user lock. Wait and inspect its outcome.');
  try { operation(); }
  finally { lock.releaseLock(); }
}

/** @param {unknown} value @returns {value is string} */
function isCalendarKey_(value) {
  return typeof value === 'string' && /^[a-z][a-z0-9-]{0,39}$/.test(value);
}

/** @param {unknown} value @param {number} maxLength @returns {value is string} */
function isCalendarText_(value, maxLength) {
  return typeof value === 'string' && value.trim().length > 0 && value.length <= maxLength;
}

/** @param {string} zone */
function isUtcCalendarZone_(zone) {
  return ['Etc/UTC', 'Etc/GMT', 'UTC', 'GMT'].includes(zone);
}

{
  "timeZone": "Etc/UTC",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/calendar"
  ]
}

{"plannedItems":2,"trackedItems":0,"blocked":false,"eventWrites":0}