google-calendar

What this skill does

## Troubleshooting

If requests fail, run `zero doctor check-connector --env-name GOOGLE_CALENDAR_TOKEN` or `zero doctor check-connector --url https://www.googleapis.com/calendar/v3/users/me/calendarList --method GET`

## How to Use

Base URL: `https://www.googleapis.com/calendar/v3`

## Calendar List

### List All Calendars

Get all calendars the user has access to:

```bash
curl -s "https://www.googleapis.com/calendar/v3/users/me/calendarList" --header "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" | jq '.items[]? | {id, summary, primary, accessRole}'
```

### Get Calendar Details

Get metadata for a specific calendar:

```bash
curl -s "https://www.googleapis.com/calendar/v3/calendars/{calendar-id}" --header "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" | jq '{id, summary, description, timeZone}'
```

For primary calendar, use `primary` as the calendar ID:

```bash
curl -s "https://www.googleapis.com/calendar/v3/calendars/primary" --header "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" | jq '{id, summary, description, timeZone}'
```

## Events

### List Events

List upcoming events from the primary calendar:

```bash
curl -s "https://www.googleapis.com/calendar/v3/calendars/primary/events?maxResults=10&orderBy=startTime&singleEvents=true&timeMin=$(date -u +%Y-%m-%dT%H:%M:%SZ)" --header "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" | jq '.items[]? | {id, summary, start, end}'
```

### List Events with Time Filter

Get events within a specific date range:

```bash
curl -s "https://www.googleapis.com/calendar/v3/calendars/primary/events?timeMin=2024-01-01T00:00:00Z&timeMax=2024-12-31T23:59:59Z&singleEvents=true&orderBy=startTime" --header "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" | jq '.items[]? | {id, summary, start, end}'
```

### Search Events

Search events by query string:

```bash
curl -s "https://www.googleapis.com/calendar/v3/calendars/primary/events?q=meeting&singleEvents=true" --header "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" | jq '.items[]? | {id, summary, start, end}'
```

### Get Event Details

Get full details for a specific event:

```bash
curl -s "https://www.googleapis.com/calendar/v3/calendars/primary/events/{event-id}" --header "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" | jq '.'
```

### Create Event

Create a new event. Write to `/tmp/calendar_request.json`:

```json
{
  "summary": "Team Meeting",
  "description": "Weekly sync-up meeting",
  "location": "Conference Room A",
  "start": {
    "dateTime": "2024-03-15T10:00:00",
    "timeZone": "America/New_York"
  },
  "end": {
    "dateTime": "2024-03-15T11:00:00",
    "timeZone": "America/New_York"
  },
  "attendees": [
    {
      "email": "[email protected]"
    }
  ],
  "reminders": {
    "useDefault": false,
    "overrides": [
      {
        "method": "email",
        "minutes": 30
      },
      {
        "method": "popup",
        "minutes": 10
      }
    ]
  }
}
```

Then run:

```bash
curl -s -X POST "https://www.googleapis.com/calendar/v3/calendars/primary/events" --header "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" --header "Content-Type: application/json" -d @/tmp/calendar_request.json | jq '.error // {id, summary, htmlLink}'
```

### Create All-Day Event

Write to `/tmp/calendar_request.json`:

```json
{
  "summary": "Company Holiday",
  "start": {
    "date": "2024-07-04"
  },
  "end": {
    "date": "2024-07-05"
  }
}
```

Then run:

```bash
curl -s -X POST "https://www.googleapis.com/calendar/v3/calendars/primary/events" --header "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" --header "Content-Type: application/json" -d @/tmp/calendar_request.json | jq '.error // {id, summary, htmlLink}'
```

### Quick Add Event

Create event from natural language text:

```bash
curl -s -X POST "https://www.googleapis.com/calendar/v3/calendars/primary/events/quickAdd?text=Lunch%20with%20Sarah%20tomorrow%20at%2012pm" --header "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" | jq '.error // {id, summary, start, end}'
```

### Update Event

Update an existing event. Write to `/tmp/calendar_request.json`:

```json
{
  "summary": "Updated Team Meeting",
  "description": "Updated description",
  "start": {
    "dateTime": "2024-03-15T14:00:00",
    "timeZone": "America/New_York"
  },
  "end": {
    "dateTime": "2024-03-15T15:00:00",
    "timeZone": "America/New_York"
  }
}
```

Then run:

```bash
curl -s -X PUT "https://www.googleapis.com/calendar/v3/calendars/primary/events/{event-id}" --header "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" --header "Content-Type: application/json" -d @/tmp/calendar_request.json | jq '.error // {id, summary, updated}'
```

### Patch Event

Partially update an event (only specified fields). Write to `/tmp/calendar_request.json`:

```json
{
  "summary": "Updated Title Only"
}
```

Then run:

```bash
curl -s -X PATCH "https://www.googleapis.com/calendar/v3/calendars/primary/events/{event-id}" --header "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" --header "Content-Type: application/json" -d @/tmp/calendar_request.json | jq '.error // {id, summary, updated}'
```

### Delete Event

Delete an event:

```bash
curl -s -X DELETE "https://www.googleapis.com/calendar/v3/calendars/primary/events/{event-id}" --header "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN"
```

Send deletion notifications to attendees:

```bash
curl -s -X DELETE "https://www.googleapis.com/calendar/v3/calendars/primary/events/{event-id}?sendUpdates=all" --header "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN"
```

## Attendees

### Set Attendees on Event

> **Note:** PATCH replaces the entire attendees array — always include all intended attendees in the list, not just the ones you're adding.

Write the full attendees list to `/tmp/calendar_request.json`:

```json
{
  "attendees": [
    {
      "email": "[email protected]",
      "optional": false
    },
    {
      "email": "[email protected]",
      "optional": true
    }
  ]
}
```

Then run:

```bash
curl -s -X PATCH "https://www.googleapis.com/calendar/v3/calendars/primary/events/{event-id}?sendUpdates=all" --header "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" --header "Content-Type: application/json" -d @/tmp/calendar_request.json | jq '.error // {id, summary, attendees}'
```

### Remove Attendee from Event

Patch the event with the updated attendees list (omit the attendee you want to remove). Write to `/tmp/calendar_request.json`:

```json
{
  "attendees": [
    {
      "email": "[email protected]"
    }
  ]
}
```

Then run:

```bash
curl -s -X PATCH "https://www.googleapis.com/calendar/v3/calendars/primary/events/{event-id}?sendUpdates=all" --header "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" --header "Content-Type: application/json" -d @/tmp/calendar_request.json | jq '.error // {id, summary, attendees}'
```

## Reminders

### Set Custom Reminders

Update event with custom reminders. Write to `/tmp/calendar_request.json`:

```json
{
  "reminders": {
    "useDefault": false,
    "overrides": [
      {
        "method": "email",
        "minutes": 1440
      },
      {
        "method": "popup",
        "minutes": 30
      }
    ]
  }
}
```

Then run:

```bash
curl -s -X PATCH "https://www.googleapis.com/calendar/v3/calendars/primary/events/{event-id}" --header "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" --header "Content-Type: application/json" -d @/tmp/calendar_request.json | jq '.error // {id, summary, reminders}'
```

### Use Default Reminders

Write to `/tmp/calendar_request.json`:

```json
{
  "reminders": {
    "useDefault": true
  }
}
```

Then run:

```bash
curl -s -X PATCH "https://www.googleapis.com/calendar/v3/calendars/primary/events/{event-id}" --header "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" --header "Content-Type: application/json" -d @/tmp/calendar_request.json | jq '.error // {id, summary, reminders}'
```

## Recurring Events

### Create Recurring Event

Create an event with recurrence rule. Write to `/tmp/calendar_request.json`:

```json
{
  "summary": "Weekly Team St