mcpbrowser 0.3.35 → 0.3.36

package/src/plugins/gcal/actions/list-events.js

@@ -0,0 +1,96 @@
+/**
+ * list-events.js — List visible events from the current Google Calendar view.
+ *
+ * Tier usage:
+ *   T1: calendarNavigate + buildViewPath for date/view navigation
+ *   T3: extractVisibleEvents for event chip data extraction
+ *   T4: EVENT_CHIP selector via waitForCalendar
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import {
+  checkPrecondition,
+  calendarNavigate,
+  buildViewPath,
+  waitForCalendar,
+  extractVisibleEvents,
+  detectView,
+  GCalActionResponse
+} from '../helpers.js';
+import { EVENT_CHIP } from '../selectors.js';
+
+/**
+ * List events from the current Calendar view or navigate to a specific date/view.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {string} [opts.params.date] - ISO date to navigate to (e.g., '2026-04-10')
+ * @param {string} [opts.params.view] - Calendar view: day, week, month, schedule
+ * @param {number} [opts.params.limit=25] - Maximum events to return
+ * @returns {Promise<GCalActionResponse|ErrorResponse>}
+ */
+export async function listEvents({ page, params }) {
+  // Precondition: must be on Google Calendar
+  const pre = await checkPrecondition(page, 'on_calendar');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://calendar.google.com' }) to open Google Calendar first."
+    ]);
+  }
+
+  const date = params.date || null;
+  const view = params.view || null;
+  const limit = params.limit || 25;
+
+  // Validate view param if provided
+  const validViews = ['day', 'week', 'month', 'schedule', 'custom'];
+  if (view && !validViews.includes(view)) {
+    return new ErrorResponse(
+      `Invalid view "${view}". Must be one of: ${validViews.join(', ')}.`,
+      ['Use list_events({ view: "week" }) or list_events({ view: "day", date: "2026-04-10" })']
+    );
+  }
+
+  // T1: Navigate to date/view if either is provided
+  if (date || view) {
+    const targetView = view || 'week';
+    const path = buildViewPath(targetView, date);
+    await calendarNavigate(page, path);
+  }
+
+  // Wait for event chips to appear (or timeout gracefully)
+  try {
+    await waitForCalendar(page, EVENT_CHIP);
+  } catch {
+    // No events visible — return empty list rather than error
+    const currentView = await detectView(page);
+    return new GCalActionResponse(
+      { events: [], view: currentView, dateRange: date || 'current', total: 0 },
+      'No events found in the current view.',
+      [
+        'Try a different date or view: list_events({ date: "2026-04-10", view: "week" })',
+        'Use search_events to find events by keyword',
+        'Use create_event to add a new event'
+      ]
+    );
+  }
+
+  // T3+T4: Extract visible event data
+  const events = await extractVisibleEvents(page, limit);
+  const currentView = await detectView(page);
+
+  return new GCalActionResponse(
+    {
+      events,
+      view: currentView,
+      dateRange: date || 'current',
+      total: events.length
+    },
+    `Found ${events.length} event(s) in ${currentView} view.`,
+    [
+      'Use read_event({ index: N }) to open a specific event',
+      'Use search_events to find events by keyword',
+      'Use create_event to add a new event'
+    ]
+  );
+}

package/src/plugins/gcal/actions/read-event.js

@@ -0,0 +1,174 @@
+/**
+ * read-event.js — Open an event and read its full details.
+ *
+ * Tier usage:
+ *   T3: selectEvent for clicking event chip, ARIA dialog for detail popup
+ *   T4: EVENT_LOCATION_IN_DETAIL, EVENT_DESCRIPTION_IN_DETAIL,
+ *       ATTENDEE_ROW, ATTENDEE_RSVP_STATUS selectors for data extraction
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import logger from '../../../core/logger.js';
+import {
+  checkPrecondition,
+  selectEvent,
+  waitForCalendar,
+  GCalActionResponse
+} from '../helpers.js';
+import {
+  EVENT_LOCATION_IN_DETAIL,
+  EVENT_DESCRIPTION_IN_DETAIL,
+  ATTENDEE_ROW,
+  ATTENDEE_RSVP_STATUS
+} from '../selectors.js';
+
+/**
+ * Open and read a specific event by index or event ID.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {number} [opts.params.index] - 0-based position in current event list
+ * @param {string} [opts.params.id] - Google Calendar event ID
+ * @returns {Promise<GCalActionResponse|ErrorResponse>}
+ */
+export async function readEvent({ page, params }) {
+  // Validate: at least one identifier required
+  if (params.index == null && params.id == null) {
+    return new ErrorResponse(
+      'Either index or id is required to read an event.',
+      [
+        'Use list_events to see available events and their indices',
+        'Use search_events to find a specific event by keyword'
+      ]
+    );
+  }
+
+  // Precondition: must be on Google Calendar
+  const pre = await checkPrecondition(page, 'on_calendar');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://calendar.google.com' }) to open Google Calendar first."
+    ]);
+  }
+
+  // FR-023: Close any existing dialog before opening a new one
+  const existingDialog = await page.$('div[role="dialog"]');
+  if (existingDialog) {
+    logger.debug('readEvent: closing existing dialog');
+    await page.keyboard.press('Escape');
+    await new Promise(r => setTimeout(r, 300));
+  }
+
+  // T3: Select (click) the target event
+  const sel = await selectEvent(page, { index: params.index, id: params.id });
+  if (!sel.selected) {
+    return new ErrorResponse(
+      sel.error || 'Could not select the event.',
+      ['Use list_events to refresh the event list and check indices']
+    );
+  }
+
+  // Wait for detail popup/dialog to appear
+  try {
+    await waitForCalendar(page, 'div[role="dialog"]');
+  } catch {
+    return new ErrorResponse(
+      'Event detail popup did not appear after clicking the event.',
+      [
+        'The event chip may not be interactive. Try list_events to refresh.',
+        'Try read_event with a different index'
+      ]
+    );
+  }
+
+  // T3+T4: Extract event detail fields from the dialog
+  const eventDetail = await page.evaluate((selectors) => {
+    const dialog = document.querySelector('div[role="dialog"]');
+    if (!dialog) return null;
+
+    // T3: Title from the heading element in the dialog
+    const titleEl = dialog.querySelector('span[role="heading"], [data-eventid]') ||
+                    dialog.querySelector('span');
+    const title = titleEl?.textContent?.trim() || '';
+
+    // T3: Time/date info from aria-label or text content
+    const timeEls = dialog.querySelectorAll('div[data-datekey], span[data-datekey]');
+    let dateTime = '';
+    if (timeEls.length > 0) {
+      dateTime = Array.from(timeEls).map(el => el.textContent?.trim()).join(' ');
+    }
+
+    // T4: Location
+    const locationEl = dialog.querySelector(selectors.location);
+    const location = locationEl?.textContent?.trim() || null;
+
+    // T4: Description
+    const descEl = dialog.querySelector(selectors.description);
+    const description = descEl?.textContent?.trim() || null;
+
+    // T3: Conference link (look for meet or zoom links)
+    const links = dialog.querySelectorAll('a[href]');
+    let conferenceLink = null;
+    for (const link of links) {
+      const href = link.getAttribute('href') || '';
+      if (href.includes('meet.google.com') || href.includes('zoom.us')) {
+        conferenceLink = href;
+        break;
+      }
+    }
+
+    // T4: Attendees
+    const attendeeEls = dialog.querySelectorAll(selectors.attendeeRow);
+    const attendees = Array.from(attendeeEls).map(row => {
+      const email = row.getAttribute('data-guest-email') || '';
+      const name = row.textContent?.trim() || email;
+      const rsvpEl = row.querySelector(selectors.rsvpStatus);
+      const rsvpStatus = rsvpEl?.getAttribute('data-rsvp') || 'unknown';
+      return { email, name, rsvpStatus };
+    });
+
+    // T3: Organizer (first attendee or dialog context)
+    const organizer = attendees.length > 0 ? attendees[0].email : null;
+
+    // T3: Calendar name from color label
+    const calendarEl = dialog.querySelector('[data-calendar-color]');
+    const calendarName = calendarEl?.textContent?.trim() || null;
+
+    return {
+      title,
+      dateTime,
+      location,
+      description,
+      conferenceLink,
+      attendees,
+      organizer,
+      calendarName,
+      attendeeCount: attendees.length
+    };
+  }, {
+    location: EVENT_LOCATION_IN_DETAIL,
+    description: EVENT_DESCRIPTION_IN_DETAIL,
+    attendeeRow: ATTENDEE_ROW,
+    rsvpStatus: ATTENDEE_RSVP_STATUS
+  });
+
+  if (!eventDetail) {
+    return new ErrorResponse(
+      'Could not extract event details from the dialog.',
+      ['Try closing the dialog (press Escape) and re-opening with read_event']
+    );
+  }
+
+  logger.debug(`readEvent: extracted "${eventDetail.title}"`);
+
+  return new GCalActionResponse(
+    eventDetail,
+    `Event: ${eventDetail.title}${eventDetail.dateTime ? ` — ${eventDetail.dateTime}` : ''}`,
+    [
+      'Use edit_event to modify this event',
+      'Use rsvp_event to respond to this invitation',
+      'Use delete_event to remove this event',
+      'Press Escape or use list_events to return to the calendar view'
+    ]
+  );
+}

package/src/plugins/gcal/actions/rsvp-event.js

@@ -0,0 +1,149 @@
+/**
+ * rsvp-event.js — Respond to a calendar invitation (accept, decline, tentative).
+ *
+ * Tier usage:
+ *   T3: selectEvent for clicking event chip, ARIA dialog for detail popup
+ *   T4: RSVP_YES_BUTTON, RSVP_NO_BUTTON, RSVP_MAYBE_BUTTON selectors
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import logger from '../../../core/logger.js';
+import {
+  checkPrecondition,
+  selectEvent,
+  waitForCalendar,
+  GCalActionResponse
+} from '../helpers.js';
+import {
+  RSVP_YES_BUTTON,
+  RSVP_NO_BUTTON,
+  RSVP_MAYBE_BUTTON
+} from '../selectors.js';
+
+/** Map response names to selector keys. */
+const RSVP_MAP = {
+  accept: RSVP_YES_BUTTON,
+  decline: RSVP_NO_BUTTON,
+  tentative: RSVP_MAYBE_BUTTON
+};
+
+/**
+ * RSVP to a calendar invitation.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {number} [opts.params.index] - 0-based position in current event list
+ * @param {string} [opts.params.id] - Google Calendar event ID
+ * @param {string} opts.params.response - "accept", "decline", or "tentative" (required)
+ * @returns {Promise<GCalActionResponse|ErrorResponse>}
+ */
+export async function rsvpEvent({ page, params }) {
+  // Validate: at least one identifier required
+  if (params.index == null && params.id == null) {
+    return new ErrorResponse(
+      'Either index or id is required to RSVP to an event.',
+      [
+        'Use list_events to see available events and their indices',
+        'Use search_events to find a specific event by keyword'
+      ]
+    );
+  }
+
+  // Validate response value
+  const response = (params.response || '').toLowerCase();
+  if (!RSVP_MAP[response]) {
+    return new ErrorResponse(
+      `Invalid RSVP response "${params.response}". Must be one of: accept, decline, tentative.`,
+      ['Use rsvp_event({ index: 0, response: "accept" })']
+    );
+  }
+
+  // Precondition: must be on Google Calendar
+  const pre = await checkPrecondition(page, 'on_calendar');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://calendar.google.com' }) to open Google Calendar first."
+    ]);
+  }
+
+  // T3: Select (click) the target event to open detail popup
+  const sel = await selectEvent(page, { index: params.index, id: params.id });
+  if (!sel.selected) {
+    return new ErrorResponse(
+      sel.error || 'Could not select the event to RSVP.',
+      ['Use list_events to refresh the event list and check indices']
+    );
+  }
+
+  // Wait for detail popup
+  try {
+    await waitForCalendar(page, 'div[role="dialog"]');
+  } catch {
+    return new ErrorResponse(
+      'Event detail popup did not appear after clicking the event.',
+      ['Try list_events to refresh, then rsvp_event with a valid index']
+    );
+  }
+
+  // Detect if the user is the organizer (organizers cannot RSVP to their own events)
+  const isOrganizer = await page.evaluate(() => {
+    const dialog = document.querySelector('div[role="dialog"]');
+    if (!dialog) return false;
+    // Organizer view typically shows "Edit event" but not RSVP buttons
+    const editBtn = dialog.querySelector('button[aria-label="Edit event"]');
+    const rsvpBtn = dialog.querySelector('[data-response]');
+    return editBtn && !rsvpBtn;
+  });
+
+  if (isOrganizer) {
+    return new ErrorResponse(
+      'You are the organizer of this event. Organizers cannot RSVP to their own events.',
+      [
+        'Use edit_event to modify the event instead',
+        'Use delete_event to cancel the event'
+      ]
+    );
+  }
+
+  // T4: Click the appropriate RSVP button
+  const rsvpSelector = RSVP_MAP[response];
+  const rsvpBtn = await page.$(rsvpSelector);
+  if (!rsvpBtn) {
+    // Fallback: look for RSVP button by text content
+    const fallbackBtn = await page.evaluateHandle((resp) => {
+      const buttons = Array.from(document.querySelectorAll('button, div[role="button"]'));
+      const labels = { accept: 'Yes', decline: 'No', tentative: 'Maybe' };
+      return buttons.find(b => b.textContent?.trim() === labels[resp]);
+    }, response);
+
+    if (fallbackBtn && fallbackBtn.asElement()) {
+      await fallbackBtn.asElement().click();
+      logger.debug(`rsvpEvent: clicked RSVP "${response}" via text fallback`);
+    } else {
+      return new ErrorResponse(
+        `Could not find the RSVP "${response}" button. This event may not have RSVP options.`,
+        [
+          'This event may not be an invitation — you can only RSVP to events you were invited to',
+          'Use read_event to inspect the event details'
+        ]
+      );
+    }
+  } else {
+    await rsvpBtn.click();
+    logger.debug(`rsvpEvent: clicked RSVP "${response}" via selector`);
+  }
+
+  await new Promise(r => setTimeout(r, 300));
+
+  return new GCalActionResponse(
+    {
+      response,
+      rsvpSent: true
+    },
+    `RSVP "${response}" sent successfully.`,
+    [
+      'Use list_events to return to the calendar view',
+      'Use read_event to verify the RSVP status'
+    ]
+  );
+}

package/src/plugins/gcal/actions/search-events.js

@@ -0,0 +1,121 @@
+/**
+ * search-events.js — Search Google Calendar for events matching a keyword query.
+ *
+ * Tier usage:
+ *   T2: '/' keyboard shortcut to focus search
+ *   T3: extractVisibleEvents for result extraction
+ *   T4: EVENT_CHIP selector for result detection
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import logger from '../../../core/logger.js';
+import {
+  checkPrecondition,
+  waitForCalendar,
+  extractVisibleEvents,
+  GCalActionResponse
+} from '../helpers.js';
+import { EVENT_CHIP } from '../selectors.js';
+
+/**
+ * Search events by query string using Calendar's search UI.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {string} opts.params.query - Search keywords (required)
+ * @param {number} [opts.params.limit=25] - Maximum results to return
+ * @returns {Promise<GCalActionResponse|ErrorResponse>}
+ */
+export async function searchEvents({ page, params }) {
+  // Validate query
+  if (!params.query || !params.query.trim()) {
+    return new ErrorResponse(
+      'Search query is required.',
+      [
+        'Provide a query: search_events({ query: "team meeting" })',
+        'Use list_events to browse the calendar without searching'
+      ]
+    );
+  }
+
+  // Precondition: must be on Google Calendar
+  const pre = await checkPrecondition(page, 'on_calendar');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://calendar.google.com' }) to open Google Calendar first."
+    ]);
+  }
+
+  const query = params.query.trim();
+  const limit = params.limit || 25;
+
+  // Ensure nothing is focused that would swallow the keystroke
+  await page.evaluate(() => {
+    if (document.activeElement && document.activeElement.tagName !== 'BODY') {
+      document.activeElement.blur();
+    }
+  });
+
+  // T2: Press '/' to focus the search box
+  await page.keyboard.press('/');
+  await new Promise(r => setTimeout(r, 300));
+
+  // T3: Type query into the search input
+  const searchInput = await page.$('input[aria-label="Search"]') ||
+                      await page.$('input[aria-label*="search" i]') ||
+                      await page.$('input[type="text"][role="searchbox"]');
+  if (searchInput) {
+    await searchInput.click({ clickCount: 3 }); // clear existing text
+    await searchInput.type(query);
+    logger.debug(`searchEvents: typed query "${query}"`);
+  } else {
+    // Fallback: type directly if the search field is already focused by '/'
+    await page.keyboard.type(query);
+    logger.debug(`searchEvents: typed query via keyboard "${query}"`);
+  }
+
+  // Press Enter to execute search
+  await page.keyboard.press('Enter');
+
+  // Wait for search results to appear
+  let hasResults = true;
+  try {
+    await waitForCalendar(page, EVENT_CHIP);
+  } catch {
+    // Check for "no results" state
+    const noResults = await page.evaluate(() => {
+      const body = document.body?.textContent || '';
+      return body.includes('No results') || body.includes('No events found');
+    });
+    if (noResults) {
+      hasResults = false;
+    } else {
+      // Re-check — page may still be loading
+      hasResults = false;
+    }
+  }
+
+  if (!hasResults) {
+    return new GCalActionResponse(
+      { events: [], query, resultCount: 0 },
+      `No events found for "${query}".`,
+      [
+        'Try a different or broader search query',
+        'Use list_events to browse the calendar instead'
+      ]
+    );
+  }
+
+  // T3+T4: Extract search results
+  const events = await extractVisibleEvents(page, limit);
+
+  return new GCalActionResponse(
+    { events, query, resultCount: events.length },
+    `Found ${events.length} result(s) for "${query}".`,
+    [
+      'Use read_event({ index: N }) to open a specific result',
+      'Use list_events to return to the calendar view',
+      'Refine your search with more specific keywords'
+    ]
+  );
+}