gws-meeting-scheduler

Meeting Scheduler

Find mutual availability and create Google Calendar events using the gws CLI.

Prerequisites

• gws CLI installed and authenticated

Workflow

1. Resolve attendee email

If the user provides a name but no email, search past calendar events:

gws calendar events list --params '{"calendarId":"primary","q":"<name>","maxResults":10}'

Look at the attendees array in results to find the matching email. If multiple matches, ask the user to confirm.

2. Detect timezones

Detect each person's timezone by querying their own calendar directly. When you query a person's calendar via their email as calendarId, the API returns start.dateTime with that person's local UTC offset — this is the most reliable signal.

gws calendar events list --params '{"calendarId":"<user-email>","maxResults":10}'
gws calendar events list --params '{"calendarId":"<attendee-email>","maxResults":10}'

For each person:

• Look at start.dateTime on non-all-day events (skip events with only start.date)
• Extract the UTC offset (e.g., -08:00, +09:00) — this reflects their calendar's timezone
• Tally the most frequent offset to determine their timezone
• Cross-reference with the start.timeZone field on events matching that offset to get the IANA name (e.g., -08:00 → America/Los_Angeles)

Important: Do NOT rely on start.timeZone alone — it often reflects the organizer's or attendee's timezone rather than the calendar owner's. The dateTime offset from the person's own calendar is the source of truth.

If no timezone can be determined for either person, ask the user.

3. Determine date range

Ask the user for a preferred date range, or default to the next 5 business days.

4. Check free/busy

Query both calendars together. The query range must cover work hours in both timezones:

gws calendar freebusy query --json '{
  "timeMin": "<start-RFC3339>",
  "timeMax": "<end-RFC3339>",
  "items": [{"id": "<user-email>"}, {"id": "<attendee-email>"}]
}'