CalBlock.gs

// ============================================================================
// CalBlock — Clockwise Replacement
// Google Apps Script — runs under your work Google account
// ============================================================================

// ---------------------------------------------------------------------------
// CONFIGURATION — Update these values during setup
// ---------------------------------------------------------------------------
const CONFIG = {
  // Calendar IDs
  personalCalendarId: 'your-personal-email@gmail.com',   // Shared TO work account (read-only)
  workCalendarId: 'primary',                       // Native work calendar

  // Travel time
  homeAddress: '',                                 // TODO: Set your home address
  mapsApiKey: '',                                  // TODO: Set your Google Maps API key
  travelTimeBufferMin: 10,                         // Extra buffer on top of Maps estimate
  defaultTravelMinutes: 30,                        // Fallback if Maps API fails or location is vague
  maxDriveTravelMinutes: 180,                      // Skip travel blocks if drive time exceeds this (interstate/overseas — you'd fly)

  // Sync behaviour
  syncWindowDays: 14,                              // How far ahead to sync
  syncAllDayEvents: false,                         // Whether to sync all-day personal events
  syncTentativeEvents: true,                       // Whether to sync tentative/maybe personal events

  // Event identification tags
  syncTagPrefix: '[CalBlock]',
  travelTagPrefix: '[Travel]',

  // Error notification
  errorNotifyEmail: 'your-email@gmail.com',

  // Maps API cache duration (hours)
  mapsCacheDurationHours: 24,
};

// ---------------------------------------------------------------------------
// ADAPTIVE THROTTLE — Slows down API calls when rate limits are encountered
// ---------------------------------------------------------------------------
var _throttleMs = 250;        // Current delay between Calendar API writes (ms)
var _rateLimitHitCount = 0;   // Number of rate limit errors this execution

/** Pause between Calendar API writes to stay within quotas. */
function calendarThrottle_() {
  Utilities.sleep(_throttleMs);
}

/** Escalate throttle after a rate limit hit — doubles the inter-call delay. */
function escalateThrottle_() {
  _rateLimitHitCount++;
  _throttleMs = Math.min(3000, 250 * Math.pow(2, _rateLimitHitCount));
  Logger.log('CalBlock: Throttle escalated to ' + _throttleMs + 'ms (rate limit hit #' + _rateLimitHitCount + ')');
}

/**
 * Set all metadata on a newly created calendar block with throttling between
 * each API call to avoid triggering Google's rate limits.
 *
 * @param {CalendarEvent} block - The event to configure.
 * @param {string} description - The description text.
 * @param {Object} tags - Key-value pairs to set as tags.
 */
function setBlockMetadata_(block, description, tags) {
  block.setVisibility(CalendarApp.Visibility.PRIVATE);
  calendarThrottle_();
  block.removeAllReminders();
  calendarThrottle_();
  block.setDescription(description);
  calendarThrottle_();
  var keys = Object.keys(tags);
  for (var i = 0; i < keys.length; i++) {
    block.setTag(keys[i], tags[keys[i]]);
    if (i < keys.length - 1) calendarThrottle_();
  }
}

// ---------------------------------------------------------------------------
// MAIN ENTRY POINT — Called by the 10-minute trigger
// ---------------------------------------------------------------------------
function syncAll() {
  // Prevent concurrent runs — if a previous trigger is still executing, skip
  var lock = LockService.getScriptLock();
  if (!lock.tryLock(30000)) {
    Logger.log('CalBlock: Another sync is already running — skipping this run');
    return;
  }

  const stats = {
    personalSynced: 0,
    personalUpdated: 0,
    personalDeleted: 0,
    travelCreated: 0,
    travelUpdated: 0,
    travelDeleted: 0,
    errors: [],
  };

  try {
    Logger.log('CalBlock: Starting sync run...');

    syncPersonalToWork_(stats);
    syncTravelBlocks_(stats);
    cleanupOrphans_(stats);

    // Store stats for debugging
    PropertiesService.getScriptProperties().setProperty(
      'lastSync',
      JSON.stringify({
        timestamp: new Date().toISOString(),
        stats: stats,
      })
    );

    Logger.log('CalBlock: Sync complete. Stats: ' + JSON.stringify(stats));

    // Send alert if there were non-fatal errors
    if (stats.errors.length > 0) {
      MailApp.sendEmail(
        CONFIG.errorNotifyEmail,
        '[CalBlock] Sync completed with errors',
        'CalBlock ran but encountered errors:\n\n' +
          stats.errors.join('\n\n') +
          '\n\nStats: ' +
          JSON.stringify(stats, null, 2)
      );
    }
  } catch (e) {
    Logger.log('CalBlock: CRITICAL ERROR — ' + e.message);
    try {
      MailApp.sendEmail(
        CONFIG.errorNotifyEmail,
        '[CalBlock] CRITICAL: Sync failed',
        'CalBlock failed entirely.\n\nError: ' +
          e.message +
          '\nStack: ' +
          e.stack +
          '\n\nPartial stats: ' +
          JSON.stringify(stats, null, 2)
      );
    } catch (mailErr) {
      Logger.log('CalBlock: Could not send error email — ' + mailErr.message);
    }
  } finally {
    lock.releaseLock();
  }
}

// ---------------------------------------------------------------------------
// FEATURE 1: Personal Calendar → Work Calendar Sync
// ---------------------------------------------------------------------------
function syncPersonalToWork_(stats) {
  const now = new Date();
  const endDate = new Date(now.getTime() + CONFIG.syncWindowDays * 24 * 60 * 60 * 1000);

  // 1. Fetch personal events using CalendarApp (reliable for shared calendars)
  var personalCal;
  try {
    personalCal = CalendarApp.getCalendarById(CONFIG.personalCalendarId);
  } catch (e) {
    stats.errors.push(
      'Cannot access personal calendar (' +
        CONFIG.personalCalendarId +
        '). Is it shared with this account? Error: ' + e.message
    );
    return;
  }

  if (!personalCal) {
    stats.errors.push(
      'Personal calendar not found: ' +
        CONFIG.personalCalendarId +
        '. Make sure it is shared with this work account.'
    );
    return;
  }

  var personalEvents = personalCal.getEvents(now, endDate);
  Logger.log('CalBlock: Found ' + personalEvents.length + ' personal events in window');

  // 2. Build transparency lookup using Advanced Calendar Service (best-effort)
  //    CalendarApp doesn't expose transparency (free/busy). We attempt the
  //    Calendar API v3 to get it. If it fails (common with cross-account shared
  //    calendars), we degrade gracefully — all non-declined events get synced.
  var transparencyMap = {};  // eventId → 'transparent' | 'opaque'
  var hasTransparencyData = false;

  try {
    var apiEvents = fetchPersonalEventsAdvanced_(CONFIG.personalCalendarId, now, endDate);
    if (apiEvents && apiEvents.length > 0) {
      apiEvents.forEach(function (ae) {
        if (ae.id && ae.transparency) {
          transparencyMap[ae.id] = ae.transparency;
        }
      });
      hasTransparencyData = true;
      Logger.log('CalBlock: Advanced Calendar API succeeded — transparency data for ' +
        Object.keys(transparencyMap).length + ' events');
    }
  } catch (e) {
    Logger.log('CalBlock: Advanced Calendar API unavailable (' + e.message +
      '). Free/busy filtering disabled — all non-declined events will sync.');
  }

  // 3. Get existing CalBlock blocks from work calendar
  var workCal = CalendarApp.getCalendarById(CONFIG.workCalendarId);
  var existingBlocks = getTaggedEvents_(workCal, CONFIG.syncTagPrefix, now, endDate);
  Logger.log('CalBlock: Found ' + existingBlocks.length + ' existing sync blocks');

  // Build lookup of existing blocks by source event ID (normalized)
  // Uses tag first, then falls back to parsing the description (tags can be
  // unreliable in CalendarApp across runs). Also deduplicates — if multiple
  // blocks share the same sourceId, keep the first and delete the rest.
  var blocksBySourceId = {};
  existingBlocks.forEach(function (block) {
    var sourceId = block.getTag('sourceEventId');
    if (!sourceId) {
      sourceId = extractIdFromDescription_(block.getDescription(), 'sourceId');
    }
    if (sourceId) {
      var normId = normalizeEventId_(sourceId);
      if (blocksBySourceId[normId]) {
        // Duplicate detected — delete this one, keep the first
        try {
          block.deleteEvent();
          stats.personalDeleted++;
          Logger.log('CalBlock: Deleted duplicate sync block for: ' + normId);
        } catch (e) {
          stats.errors.push('Error deleting duplicate sync block: ' + e.message);
        }
      } else {
        blocksBySourceId[normId] = block;
      }
    }
  });

  // 4. Process personal events
  var processedSourceIds = {};

  personalEvents.forEach(function (personalEvent) {
    try {
      // Skip all-day events unless configured to sync them
      if (personalEvent.isAllDayEvent() && !CONFIG.syncAllDayEvents) {
        return;
      }

      // Skip declined events
      if (personalEvent.getMyStatus() === CalendarApp.GuestStatus.NO) {
        return;
      }

      // Skip tentative events if configured
      if (
        !CONFIG.syncTentativeEvents &&
        personalEvent.getMyStatus() === CalendarApp.GuestStatus.MAYBE
      ) {
        return;
      }

      // Skip events marked as "free" (if transparency data is available)
      var rawId = personalEvent.getId();
      var baseId = normalizeEventId_(rawId);
      // Create a unique instance ID for recurring events by appending the start time.
      // CalendarApp.getId() returns the same base ID for every instance of a
      // recurring event, so without this, all instances would collide on the same key.
      var eventId = baseId;
      if (!personalEvent.isAllDayEvent()) {
        eventId = baseId + '_' + personalEvent.getStartTime().getTime();
      } else {
        eventId = baseId + '_' + personalEvent.getAllDayStartDate().getTime();
      }
      if (hasTransparencyData) {
        var transparency = transparencyMap[rawId] || transparencyMap[baseId];
        if (transparency === 'transparent') {
          Logger.log('CalBlock: Skipping free/transparent personal event');
          return;
        }
      }

      processedSourceIds[eventId] = true;

      // Check if this personal event has a physical address for travel blocking
      var personalLocation = personalEvent.getLocation();
      var hasPhysicalAddress =
        personalLocation &&
        personalLocation.trim().length > 0 &&
        isPhysicalAddress_(personalLocation.trim());

      var eventHash = hashEventCalApp_(personalEvent);

      if (blocksBySourceId[eventId]) {
        // Existing block — check if it needs updating
        var existingBlock = blocksBySourceId[eventId];
        var existingHash = existingBlock.getTag('lastSyncHash');

        if (existingHash !== eventHash) {
          // Update times
          if (personalEvent.isAllDayEvent()) {
            existingBlock.setAllDayDate(personalEvent.getAllDayStartDate());
          } else {
            existingBlock.setTime(
              personalEvent.getStartTime(),
              personalEvent.getEndTime()
            );
          }
          // Update hidden location tag (for travel blocking)
          if (hasPhysicalAddress) {
            existingBlock.setTag('physicalAddress', personalLocation.trim());
          } else {
            existingBlock.setTag('physicalAddress', '');
          }
          existingBlock.setTag('lastSyncHash', eventHash);
          stats.personalUpdated++;
          Logger.log('CalBlock: Updated block for: ' + eventId);
        }
      } else {
        // New event — create a block (with rate-limit retry)
        var newBlock = withCalendarRetry_(function () {
          if (personalEvent.isAllDayEvent()) {
            return workCal.createAllDayEvent('Busy', personalEvent.getAllDayStartDate());
          } else {
            return workCal.createEvent(
              'Busy',
              personalEvent.getStartTime(),
              personalEvent.getEndTime()
            );
          }
        });

        var blockTags = {
          sourceEventId: eventId,
          sourceCalendar: CONFIG.personalCalendarId,
          lastSyncHash: eventHash,
          managedBy: CONFIG.syncTagPrefix,
        };
        if (hasPhysicalAddress) {
          blockTags.physicalAddress = personalLocation.trim();
        }
        setBlockMetadata_(
          newBlock,
          CONFIG.syncTagPrefix + ' Auto-synced — do not edit manually\n[sourceId:' + eventId + ']',
          blockTags
        );
        // Add to lookup so recurring instances don't create duplicate blocks
        blocksBySourceId[eventId] = newBlock;

        stats.personalSynced++;
        Logger.log('CalBlock: Created block for personal event: ' + eventId);
      }
    } catch (e) {
      stats.errors.push('Error processing personal event: ' + e.message);
    }
  });

  // 5. Delete blocks for personal events that no longer exist
  Object.keys(blocksBySourceId).forEach(function (sourceId) {
    if (!processedSourceIds[sourceId]) {
      try {
        withCalendarRetry_(function () {
          blocksBySourceId[sourceId].deleteEvent();
        });
        stats.personalDeleted++;
        Logger.log('CalBlock: Deleted orphaned block for: ' + sourceId);
      } catch (e) {
        stats.errors.push('Error deleting orphaned block: ' + e.message);
      }
    }
  });
}

// ---------------------------------------------------------------------------
// FEATURE 2: Travel Time Blocking
// ---------------------------------------------------------------------------
function syncTravelBlocks_(stats) {
  if (!CONFIG.mapsApiKey || !CONFIG.homeAddress) {
    Logger.log('CalBlock: Skipping travel blocks — Maps API key or home address not configured');
    return;
  }

  const now = new Date();
  const endDate = new Date(now.getTime() + CONFIG.syncWindowDays * 24 * 60 * 60 * 1000);
  const workCal = CalendarApp.getCalendarById(CONFIG.workCalendarId);

  // 1. Get ALL work calendar events (real + synced) that have a physical address
  //    For regular work events: check the visible location field
  //    For [CalBlock] blocks: check the hidden 'physicalAddress' tag
  //    (personal events don't have a visible location — it's stored as a tag to preserve privacy)
  const allWorkEvents = workCal.getEvents(now, endDate);
  const eventsWithLocation = allWorkEvents.filter(function (event) {
    // Skip travel blocks themselves
    if (isTaggedEvent_(event, CONFIG.travelTagPrefix)) return false;
    // Get the effective physical address (visible location or hidden tag)
    var addr = getEffectiveAddress_(event);
    if (!addr) return false;
    // Skip events AT the home address — no travel needed
    if (normalizeAddress_(addr) === normalizeAddress_(CONFIG.homeAddress)) {
      Logger.log('CalBlock: Skipping travel for event at home address');
      return false;
    }
    return true;
  });

  Logger.log(
    'CalBlock: Found ' + eventsWithLocation.length + ' events with physical addresses for travel blocking'
  );

  // 2. Get existing travel blocks — build lookup with normalized IDs
  //    CalendarApp.getId() returns IDs in inconsistent formats:
  //      - "abc123" or "abc123@google.com" for regular events
  //      - "abc123_20260325T060000Z" for recurring instances
  //    We normalize to avoid duplicate blocks on each sync cycle.
  const existingTravelBlocks = getTaggedEvents_(workCal, CONFIG.travelTagPrefix, now, endDate);
  const travelBlocksByLinkedId = {};
  existingTravelBlocks.forEach(function (block) {
    var linkedId = block.getTag('linkedEventId');
    if (!linkedId) {
      linkedId = extractIdFromDescription_(block.getDescription(), 'linkedId');
    }
    var direction = block.getTag('travelDirection');
    if (!direction) {
      direction = extractIdFromDescription_(block.getDescription(), 'direction');
    }
    if (!direction) {
      direction = 'to';
    }
    if (linkedId) {
      var normKey = normalizeEventId_(linkedId) + '_' + direction;
      if (travelBlocksByLinkedId[normKey]) {
        // Duplicate detected — delete this one, keep the first
        try {
          block.deleteEvent();
          stats.travelDeleted++;
          Logger.log('CalBlock: Deleted duplicate travel block: ' + normKey);
        } catch (e) {
          stats.errors.push('Error deleting duplicate travel block: ' + e.message);
        }
      } else {
        travelBlocksByLinkedId[normKey] = block;
      }
    }
  });

  Logger.log('CalBlock: Found ' + existingTravelBlocks.length + ' existing travel blocks');

  // Sort events by start time for chaining
  eventsWithLocation.sort(function (a, b) {
    return a.getStartTime().getTime() - b.getStartTime().getTime();
  });

  const processedKeys = {};

  // 3. Create/update travel blocks
  for (var i = 0; i < eventsWithLocation.length; i++) {
    var event = eventsWithLocation[i];
    var rawEventId = event.getId();
    var eventId = normalizeEventId_(rawEventId);  // Normalized for consistent matching
    var eventLocation = getEffectiveAddress_(event); // reads visible location or hidden tag
    var eventTitle = event.getTitle();

    // For [CalBlock] blocks, the title is "Busy" — use a more descriptive travel block title
    var travelLabel = isTaggedEvent_(event, CONFIG.syncTagPrefix) ? 'Personal event' : eventTitle;

    try {
      // --- TRAVEL TO EVENT ---
      var origin;
      if (i > 0) {
        var prevEvent = eventsWithLocation[i - 1];
        var prevLoc = getEffectiveAddress_(prevEvent);
        // Only chain from previous event if it ends within 4 hours of this one starting
        var gap = event.getStartTime().getTime() - prevEvent.getEndTime().getTime();
        if (prevLoc && gap < 4 * 60 * 60 * 1000) {
          origin = prevLoc;
        } else {
          origin = CONFIG.homeAddress;
        }
      } else {
        origin = CONFIG.homeAddress;
      }

      var travelMinutes = getCachedTravelTime_(origin, eventLocation);

      // Skip travel blocks for long-distance trips (interstate/overseas — you'd fly, not drive)
      if (CONFIG.maxDriveTravelMinutes && travelMinutes > CONFIG.maxDriveTravelMinutes) {
        Logger.log(
          'CalBlock: Skipping travel block — drive time ' +
            travelMinutes +
            ' min exceeds threshold (' +
            CONFIG.maxDriveTravelMinutes +
            ' min)'
        );
        continue;
      }

      var totalMinutes = travelMinutes + CONFIG.travelTimeBufferMin;
      var travelHash = hashString_(
        event.getStartTime().getTime() + '|' + eventLocation + '|' + origin + '|to'
      );

      var toKey = eventId + '_to';
      processedKeys[toKey] = true;

      if (travelBlocksByLinkedId[toKey]) {
        // Update existing travel block if needed
        var existingBlock = travelBlocksByLinkedId[toKey];
        var existingHash = existingBlock.getTag('lastSyncHash');

        if (existingHash !== travelHash) {
          var toStart = new Date(event.getStartTime().getTime() - totalMinutes * 60 * 1000);
          existingBlock.setTime(toStart, event.getStartTime());
          existingBlock.setTitle(CONFIG.travelTagPrefix + ' → ' + travelLabel);
          existingBlock.setTag('lastSyncHash', travelHash);
          existingBlock.setTag('travelMinutes', String(totalMinutes));
          stats.travelUpdated++;
        }
      } else {
        // Create new travel-to block (with rate-limit retry)
        var toStart = new Date(event.getStartTime().getTime() - totalMinutes * 60 * 1000);
        var toBlock = withCalendarRetry_(function () {
          return workCal.createEvent(
            CONFIG.travelTagPrefix + ' → ' + travelLabel,
            toStart,
            event.getStartTime()
          );
        });

        setBlockMetadata_(
          toBlock,
          CONFIG.travelTagPrefix +
            ' Auto-generated travel time — do not edit manually\n' +
            '[linkedId:' + eventId + '][direction:to]\n' +
            'From: ' + origin + '\n' +
            'To: ' + eventLocation + '\n' +
            'Estimated: ' + travelMinutes + ' min + ' + CONFIG.travelTimeBufferMin + ' min buffer',
          {
            linkedEventId: eventId,
            travelDirection: 'to',
            travelMinutes: String(totalMinutes),
            lastSyncHash: travelHash,
            managedBy: CONFIG.travelTagPrefix,
          }
        );

        stats.travelCreated++;
        Logger.log('CalBlock: Created travel-to block for event ' + redactIdentifier_(eventId));
      }

      // --- RETURN TRAVEL (from event → home) ---
      // Only create return travel if next event is far away or doesn't have a location
      var needsReturn = true;
      if (i < eventsWithLocation.length - 1) {
        var nextEvent = eventsWithLocation[i + 1];
        var nextGap = nextEvent.getStartTime().getTime() - event.getEndTime().getTime();
        // If the next event with a location is within 4 hours, we'll chain to it instead
        if (nextGap < 4 * 60 * 60 * 1000) {
          needsReturn = false;
        }
      }

      if (needsReturn) {
        var returnMinutes = getCachedTravelTime_(eventLocation, CONFIG.homeAddress);
        var returnTotal = returnMinutes + CONFIG.travelTimeBufferMin;
        var returnHash = hashString_(
          event.getEndTime().getTime() + '|' + eventLocation + '|' + CONFIG.homeAddress + '|from'
        );

        var fromKey = eventId + '_from';
        processedKeys[fromKey] = true;

        if (travelBlocksByLinkedId[fromKey]) {
          var existingReturn = travelBlocksByLinkedId[fromKey];
          var existingReturnHash = existingReturn.getTag('lastSyncHash');

          if (existingReturnHash !== returnHash) {
            var fromEnd = new Date(event.getEndTime().getTime() + returnTotal * 60 * 1000);
            existingReturn.setTime(event.getEndTime(), fromEnd);
            existingReturn.setTitle(CONFIG.travelTagPrefix + ' ← ' + travelLabel);
            existingReturn.setTag('lastSyncHash', returnHash);
            existingReturn.setTag('travelMinutes', String(returnTotal));
            stats.travelUpdated++;
          }
        } else {
          // Create new return travel block (with rate-limit retry)
          var fromEnd = new Date(event.getEndTime().getTime() + returnTotal * 60 * 1000);
          var fromBlock = withCalendarRetry_(function () {
            return workCal.createEvent(
              CONFIG.travelTagPrefix + ' ← ' + travelLabel,
              event.getEndTime(),
              fromEnd
            );
          });

          setBlockMetadata_(
            fromBlock,
            CONFIG.travelTagPrefix +
              ' Auto-generated return travel time — do not edit manually\n' +
              '[linkedId:' + eventId + '][direction:from]\n' +
              'From: ' + eventLocation + '\n' +
              'To: ' + CONFIG.homeAddress + '\n' +
              'Estimated: ' + returnMinutes + ' min + ' + CONFIG.travelTimeBufferMin + ' min buffer',
            {
              linkedEventId: eventId,
              travelDirection: 'from',
              travelMinutes: String(returnTotal),
              lastSyncHash: returnHash,
              managedBy: CONFIG.travelTagPrefix,
            }
          );

          stats.travelCreated++;
          Logger.log('CalBlock: Created return travel block for event ' + redactIdentifier_(eventId));
        }
      }
    } catch (e) {
      stats.errors.push(
        'Error processing travel for event ' + redactIdentifier_(eventId) + ': ' + e.message
      );
    }
  }

  // 4. Delete orphaned travel blocks
  Object.keys(travelBlocksByLinkedId).forEach(function (key) {
    if (!processedKeys[key]) {
      try {
        withCalendarRetry_(function () {
          travelBlocksByLinkedId[key].deleteEvent();
        });
        stats.travelDeleted++;
        Logger.log('CalBlock: Deleted orphaned travel block: ' + key);
      } catch (e) {
        stats.errors.push('Error deleting orphaned travel block: ' + e.message);
      }
    }
  });
}

// ---------------------------------------------------------------------------
// CLEANUP — Remove any orphaned managed events
// ---------------------------------------------------------------------------
function cleanupOrphans_(stats) {
  // This is handled within each sync function above.
  // This function exists as a hook for any additional cleanup logic.
  Logger.log('CalBlock: Cleanup pass complete');
}

// ---------------------------------------------------------------------------
// GOOGLE MAPS API — Travel Time Calculation with Caching
// ---------------------------------------------------------------------------
function getCachedTravelTime_(origin, destination) {
  var cache = CacheService.getScriptCache();
  var cacheKey = 'travel_' + hashString_(origin + '|' + destination);
  var cached = cache.get(cacheKey);

  if (cached) {
    Logger.log('CalBlock: Cache hit for travel route ' + redactIdentifier_(cacheKey));
    return parseInt(cached, 10);
  }

  var minutes = fetchTravelTime_(origin, destination);

  // Cache for configured duration (max 6 hours — Apps Script cache limit)
  var cacheSecs = Math.min(CONFIG.mapsCacheDurationHours * 3600, 21600);
  cache.put(cacheKey, String(minutes), cacheSecs);

  return minutes;
}

function fetchTravelTime_(origin, destination) {
  try {
    var url =
      'https://maps.googleapis.com/maps/api/directions/json' +
      '?origin=' + encodeURIComponent(origin) +
      '&destination=' + encodeURIComponent(destination) +
      '&mode=driving' +
      '&traffic_model=pessimistic' +
      '&departure_time=now' +
      '&key=' + CONFIG.mapsApiKey;

    var response = UrlFetchApp.fetch(url, { muteHttpExceptions: true });
    var data = JSON.parse(response.getContentText());

    if (data.status === 'OK' && data.routes && data.routes.length > 0) {
      var leg = data.routes[0].legs[0];
      // Prefer duration_in_traffic if available (pessimistic)
      var seconds = leg.duration_in_traffic
        ? leg.duration_in_traffic.value
        : leg.duration.value;
      var minutes = Math.ceil(seconds / 60);
      Logger.log(
        'CalBlock: Maps API returned ' + minutes + ' min for route ' + redactIdentifier_(origin + '|' + destination)
      );
      return minutes;
    } else {
      Logger.log('CalBlock: Maps API returned status: ' + data.status + ' — using default');
      return CONFIG.defaultTravelMinutes;
    }
  } catch (e) {
    Logger.log('CalBlock: Maps API error — ' + e.message + ' — using default');
    return CONFIG.defaultTravelMinutes;
  }
}

// ---------------------------------------------------------------------------
// ADVANCED CALENDAR SERVICE — Fetch events with full API fields
// ---------------------------------------------------------------------------

/**
 * Fetch events from a calendar using the Advanced Calendar Service (Calendar API v3).
 * This gives us access to fields not available in the basic CalendarApp, including:
 * - transparency ('transparent' = free, 'opaque' = busy)
 * - location
 * - full attendee details with response status
 *
 * Requires the Advanced Calendar Service to be enabled in the Apps Script project:
 *   Services → Calendar API → Add
 *
 * Returns an array of raw event objects from the API.
 */
function fetchPersonalEventsAdvanced_(calendarId, startDate, endDate) {
  var allEvents = [];
  var pageToken = null;

  do {
    var options = {
      timeMin: startDate.toISOString(),
      timeMax: endDate.toISOString(),
      singleEvents: true,        // Expand recurring events into instances
      orderBy: 'startTime',
      maxResults: 250,
    };
    if (pageToken) {
      options.pageToken = pageToken;
    }

    var response = Calendar.Events.list(calendarId, options);

    if (response.items) {
      allEvents = allEvents.concat(response.items);
    }

    pageToken = response.nextPageToken;
  } while (pageToken);

  return allEvents;
}

// ---------------------------------------------------------------------------
// HELPER FUNCTIONS
// ---------------------------------------------------------------------------

/**
 * Get the effective physical address for an event.
 * - For regular work events: checks the visible location field
 * - For [CalBlock] blocks (synced personal events): checks the hidden
 *   'physicalAddress' tag (location is not set on the visible event to
 *   preserve privacy — the block just shows "Busy")
 *
 * Returns the address string if it's a valid physical address, or null if not.
 */
function getEffectiveAddress_(event) {
  // First check the visible location field
  var loc = event.getLocation();
  if (loc && loc.trim().length > 0 && isPhysicalAddress_(loc.trim())) {
    return loc.trim();
  }

  // For CalBlock blocks, check the hidden tag
  var taggedAddress = event.getTag('physicalAddress');
  if (taggedAddress && taggedAddress.trim().length > 0) {
    // Already validated as physical when it was stored — but re-check
    // in case the validation logic has been updated
    if (isPhysicalAddress_(taggedAddress.trim())) {
      return taggedAddress.trim();
    }
  }

  return null;
}

/**
 * Get all events in a range that are managed by CalBlock (identified by tag).
 */
function getTaggedEvents_(calendar, tagPrefix, startDate, endDate) {
  var allEvents = calendar.getEvents(startDate, endDate);
  return allEvents.filter(function (event) {
    return isTaggedEvent_(event, tagPrefix);
  });
}

/**
 * Check if an event is managed by CalBlock.
 */
function isTaggedEvent_(event, tagPrefix) {
  var managedBy = event.getTag('managedBy');
  if (managedBy === tagPrefix) return true;

  // Fallback: check description for tag prefix
  var desc = event.getDescription() || '';
  return desc.indexOf(tagPrefix) === 0;
}

/**
 * Determine if a location string is a real physical address (not a URL,
 * video call link, or generic label like "Office" or "TBD").
 *
 * Uses a two-layer approach:
 *   1. Heuristic reject — instantly filter out obvious non-addresses
 *   2. Google Maps Geocoding API — confirm the location resolves to a
 *      physical place (street address, establishment, point of interest)
 *
 * Results are cached to avoid redundant API calls.
 */
function isPhysicalAddress_(location) {
  // --- Layer 1: Heuristic reject ---
  var loc = location.toLowerCase().trim();

  // Reject URLs and video call links
  if (/^https?:\/\//.test(loc)) return false;
  if (/^meet\.google\.com/.test(loc)) return false;
  if (/^zoom\.us/.test(loc)) return false;
  if (/^teams\.microsoft\.com/.test(loc)) return false;

  // Reject known virtual / non-place keywords (exact match or starts with)
  var rejectExact = [
    'zoom', 'google meet', 'microsoft teams', 'teams', 'webex', 'slack',
    'slack huddle', 'skype', 'facetime', 'discord', 'phone', 'call',
    'online', 'virtual', 'remote', 'wfh', 'work from home', 'home office',
    'tbd', 'tba', 'tbc', 'n/a', 'none', 'anywhere',
  ];
  if (rejectExact.indexOf(loc) !== -1) return false;

  // Reject if it looks like a phone number (digits, spaces, dashes, plus, parens)
  if (/^[\d\s\-\+\(\)]{7,}$/.test(loc)) return false;

  // Reject very short generic strings (1-3 chars) — unlikely to be addresses
  if (loc.length <= 3) return false;

  // --- Layer 2: Google Maps Geocoding API validation ---
  if (!CONFIG.mapsApiKey) return false;
  return isGeocodableAddress_(location);
}

/**
 * Use the Google Maps Geocoding API to check if a location string resolves
 * to a physical place. Returns true only if the result type indicates a
 * real-world location you could drive to.
 *
 * Results are cached for mapsCacheDurationHours to avoid repeat API calls.
 */
function isGeocodableAddress_(location) {
  var cache = CacheService.getScriptCache();
  var cacheKey = 'geo_' + hashString_(location.toLowerCase().trim());
  var cached = cache.get(cacheKey);

  if (cached !== null) {
    return cached === 'true';
  }

  try {
    var url =
      'https://maps.googleapis.com/maps/api/geocode/json' +
      '?address=' + encodeURIComponent(location) +
      '&key=' + CONFIG.mapsApiKey;

    var response = UrlFetchApp.fetch(url, { muteHttpExceptions: true });
    var data = JSON.parse(response.getContentText());

    var isPhysical = false;

    if (data.status === 'OK' && data.results && data.results.length > 0) {
      var result = data.results[0];
      var types = result.types || [];

      // These result types indicate a real physical place
      var physicalTypes = [
        'street_address',    // "123 Collins St, Melbourne"
        'premise',           // A named building or complex
        'subpremise',        // A unit/suite within a building
        'establishment',     // A business / named place
        'point_of_interest', // A landmark or POI
        'route',             // A street name (partial address)
        'intersection',      // A street intersection
        'airport',           // An airport
        'park',              // A park
        'train_station',     // A station
        'transit_station',   // A transit hub
        'bus_station',       // A bus station
      ];

      for (var i = 0; i < types.length; i++) {
        if (physicalTypes.indexOf(types[i]) !== -1) {
          isPhysical = true;
          break;
        }
      }

      // Also accept if the result has a geometry location_type of ROOFTOP or
      // RANGE_INTERPOLATED — these indicate precise street-level geocoding
      if (!isPhysical && result.geometry) {
        var locationType = result.geometry.location_type;
        if (locationType === 'ROOFTOP' || locationType === 'RANGE_INTERPOLATED') {
          isPhysical = true;
        }
      }

      Logger.log(
        'CalBlock: Geocode ' +
          redactIdentifier_(location) +
          ' → ' +
          (isPhysical ? 'PHYSICAL' : 'NOT PHYSICAL') +
          ' (types: ' +
          types.join(', ') +
          ')'
      );
    } else {
      Logger.log(
        'CalBlock: Geocode ' +
          redactIdentifier_(location) +
          ' → NO RESULTS (status: ' +
          data.status +
          ')'
      );
    }

    // Cache the result
    var cacheSecs = Math.min(CONFIG.mapsCacheDurationHours * 3600, 21600);
    cache.put(cacheKey, String(isPhysical), cacheSecs);

    return isPhysical;
  } catch (e) {
    Logger.log('CalBlock: Geocoding error for ' + redactIdentifier_(location) + ': ' + e.message);
    // On error, assume it's NOT a physical address (safe default — don't create wrong blocks)
    return false;
  }
}

/**
 * Extract an embedded ID from an event description.
 * Descriptions contain fallback IDs in the format [key:value] because
 * CalendarApp.getTag() can be unreliable across script executions.
 * e.g. extractIdFromDescription_("[CalBlock]...\n[sourceId:abc123]", "sourceId") → "abc123"
 */
function extractIdFromDescription_(description, keyName) {
  if (!description) return null;
  var pattern = new RegExp('\\[' + keyName + ':([^\\]]+)\\]');
  var match = description.match(pattern);
  return match ? match[1] : null;
}

/**
 * Normalize a Google Calendar event ID for consistent matching.
 * CalendarApp.getId() returns IDs in inconsistent formats:
 *   - "abc123" (short form)
 *   - "abc123@google.com" (with domain suffix)
 *   - "abc123_20260325T060000Z" (recurring instance with timestamp)
 * We strip the @domain suffix to get a stable base ID.
 */
function normalizeEventId_(eventId) {
  if (!eventId) return '';
  return eventId.replace(/@.*$/, '');
}

/**
 * Normalize an address string for comparison (e.g. checking if event is at home).
 * Lowercases, strips extra whitespace, removes common punctuation.
 */
function normalizeAddress_(address) {
  if (!address) return '';
  return address
    .toLowerCase()
    .replace(/[,.\-\/\\]/g, ' ')   // Replace punctuation with spaces
    .replace(/\s+/g, ' ')          // Collapse multiple spaces
    .trim();
}

/**
 * Create a hash of a CalendarApp event's time, status, and location for change detection.
 */
function hashEventCalApp_(event) {
  var str;
  if (event.isAllDayEvent()) {
    str = 'allday|' + event.getAllDayStartDate().getTime();
  } else {
    str = event.getStartTime().getTime() + '|' + event.getEndTime().getTime();
  }
  str += '|' + (event.getMyStatus() || 'owner');
  str += '|' + (event.getLocation() || '');
  return hashString_(str);
}

/**
 * Simple string hash (djb2).
 */
function hashString_(str) {
  var hash = 5381;
  for (var i = 0; i < str.length; i++) {
    hash = (hash * 33) ^ str.charCodeAt(i);
  }
  return (hash >>> 0).toString(36);
}

/**
 * Redact an identifier or address for logs while keeping enough stability for debugging.
 */
function redactIdentifier_(value) {
  if (!value) return 'unknown';
  return hashString_(String(value)).substring(0, 8);
}

// ---------------------------------------------------------------------------
// RATE LIMIT HANDLING — Retry with exponential backoff
// ---------------------------------------------------------------------------

/**
 * Wrap a Calendar API call with retry logic for Google's rate limit errors.
 * Google Calendar returns "You have been creating or deleting too many
 * calendars or calendar events in a short time" when the quota is exceeded.
 *
 * Retries up to maxRetries times with exponential backoff (5s, 10s, 20s, 40s, 80s).
 * Uses the adaptive throttle system to pace consecutive writes — the inter-call
 * delay escalates automatically when rate limits are hit, slowing down ALL
 * subsequent Calendar API calls for the remainder of the execution.
 *
 * @param {Function} fn - A zero-argument function that performs the API call
 *   and returns the result (e.g., the created CalendarEvent).
 * @param {number} [maxRetries=5] - Maximum number of retry attempts.
 * @return {*} The return value of fn().
 * @throws {Error} The original error if all retries are exhausted.
 */
function withCalendarRetry_(fn, maxRetries) {
  maxRetries = maxRetries || 5;
  var baseDelay = 5000; // 5 seconds

  for (var attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      var result = fn();
      calendarThrottle_();
      return result;
    } catch (e) {
      var isRateLimit =
        e.message &&
        (e.message.indexOf('too many calendars or calendar events') !== -1 ||
         e.message.indexOf('Rate Limit Exceeded') !== -1 ||
         e.message.indexOf('Calendar usage limits exceeded') !== -1);

      if (isRateLimit && attempt < maxRetries) {
        escalateThrottle_();
        var delay = baseDelay * Math.pow(2, attempt); // 5s, 10s, 20s, 40s, 80s
        Logger.log(
          'CalBlock: Rate limited — retrying in ' + (delay / 1000) +
          's (attempt ' + (attempt + 1) + '/' + maxRetries + ')'
        );
        Utilities.sleep(delay);
      } else {
        throw e; // Not a rate limit error, or retries exhausted
      }
    }
  }
}

// ---------------------------------------------------------------------------
// TRIGGER MANAGEMENT
// ---------------------------------------------------------------------------

/**
 * Run this once to set up the 10-minute trigger.
 * Execute manually from the Apps Script editor: Run → setupTriggers
 */
function setupTriggers() {
  // Remove any existing CalBlock triggers to avoid duplicates
  var triggers = ScriptApp.getProjectTriggers();
  triggers.forEach(function (trigger) {
    if (trigger.getHandlerFunction() === 'syncAll') {
      ScriptApp.deleteTrigger(trigger);
    }
  });

  // Create 10-minute trigger
  ScriptApp.newTrigger('syncAll').timeBased().everyMinutes(10).create();

  Logger.log('CalBlock: Trigger set — syncAll will run every 10 minutes');
}

/**
 * Run this to remove all CalBlock triggers (pause the sync).
 */
function removeTriggers() {
  var triggers = ScriptApp.getProjectTriggers();
  triggers.forEach(function (trigger) {
    if (trigger.getHandlerFunction() === 'syncAll') {
      ScriptApp.deleteTrigger(trigger);
    }
  });

  Logger.log('CalBlock: All triggers removed — sync is paused');
}

// ---------------------------------------------------------------------------
// MANUAL UTILITIES
// ---------------------------------------------------------------------------

/**
 * Run a sync immediately (for testing).
 */
function runSyncNow() {
  syncAll();
}

/**
 * View the last sync stats (check Logs after running).
 */
function viewLastSyncStats() {
  var lastSync = PropertiesService.getScriptProperties().getProperty('lastSync');
  if (lastSync) {
    Logger.log('Last sync: ' + lastSync);
  } else {
    Logger.log('No sync has run yet.');
  }
}

/**
 * DANGER: Delete ALL CalBlock-managed events from work calendar.
 * Also cleans up legacy [CalSync] tagged events from before the rename.
 * Use this to clean up if something goes wrong or to remove duplicates.
 */
function purgeAllCalBlockEvents() {
  var workCal = CalendarApp.getCalendarById(CONFIG.workCalendarId);
  var now = new Date();
  var endDate = new Date(now.getTime() + CONFIG.syncWindowDays * 24 * 60 * 60 * 1000);
  var allEvents = workCal.getEvents(now, endDate);

  var deleted = 0;
  allEvents.forEach(function (event) {
    var shouldDelete = false;

    // Check current tags
    if (
      isTaggedEvent_(event, CONFIG.syncTagPrefix) ||
      isTaggedEvent_(event, CONFIG.travelTagPrefix)
    ) {
      shouldDelete = true;
    }

    // Also check legacy [CalSync] tags from before rename
    if (
      isTaggedEvent_(event, '[CalSync]') ||
      isTaggedEvent_(event, '[Travel]')
    ) {
      shouldDelete = true;
    }

    if (shouldDelete) {
      event.deleteEvent();
      deleted++;
    }
  });

  Logger.log('CalBlock: Purged ' + deleted + ' managed events (including legacy [CalSync] events)');
}