Google Calendar Port

Purpose

This is the reference integration for the Google Calendar API and Harbor's Action Model.

Use it when:

• building Google Calendar actions in Harbor
• extending the Dock / Hub Google Calendar entry
• teaching Codex or OpenClaw how to map a scheduling API into Harbor Ports and Harbor Actions without turning Harbor into a generic proxy

Harbor Port worksheet

Product

• Product: Google Calendar API
• Publisher slug: google
• Publisher name: Google
• Category: Calendar
• Tags: google, calendar, events, productivity, scheduling

Safe Harbor Port metadata

• Kind: http_api
• Label: Google Calendar API
• Description: Google Calendar API connection managed locally through Harbor.
• Base URL: https://www.googleapis.com/
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bearer

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Harbor action design notes

Google Calendar is a good Harbor fit today when we stay on account-scoped and primary-calendar routes and keep write payloads in input.body. If future list filters or scheduling options are added, keep them in typed input.query fields rather than raw query strings.

Good Harbor Google Calendar actions:

• stable GET routes for account calendar list, settings, colors, and primary calendar metadata
• one bounded POST read-like route for free/busy queries
• explicit POST routes for event or calendar creation
• requestBodyMode: "none" for reads
• requestBodyMode: "json" for bounded writes or free/busy queries
• resultMode: "json_summary" for all starter actions

Avoid for now:

• giant event-management surfaces with many optional query parameters
• watch/channel management
• automatic publish of create or mutate actions

Starter Google Calendar actions

Automatic read actions

• list-calendar-list -> GET /calendar/v3/users/me/calendarList
• list-settings -> GET /calendar/v3/users/me/settings
• get-colors -> GET /calendar/v3/colors
• get-primary-calendar -> GET /calendar/v3/calendars/primary
• list-primary-events -> GET /calendar/v3/calendars/primary/events
• list-primary-acl -> GET /calendar/v3/calendars/primary/acl
• query-freebusy -> POST /calendar/v3/freeBusy

Approval-friendly write actions

• create-primary-event -> POST /calendar/v3/calendars/primary/events
• create-calendar -> POST /calendar/v3/calendars

Why these actions

These routes fit Harbor's Action Model well because they:

• stay under one fixed Google API origin
• use fixed account or primary-calendar paths relative to the Harbor Port
• keep inputs bounded and reviewable
• can be reviewed as named capabilities
• keep hidden auth entirely local to Harbor Node

Suggested operator workflow

1. Import the Google Calendar Dock entry from Dock / Hub.
2. Configure the local Google bearer token in Harbor Node.
3. Use the low-risk read actions first.
4. Keep create-primary-event and create-calendar on require_approval unless there is a very deliberate local policy reason not to.

Suggested agent workflow

1. Inspect the existing Google Calendar Harbor Port.
2. Inspect live actions and drafts.
3. Propose additional fixed-path actions only.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored token
• edit hidden Google Calendar auth
• widen Google Calendar into a generic arbitrary proxy

Current update strategy

For now, Google Calendar updates are manual:

• update the Dock / Hub Google Calendar integration document in apps/hub/catalog/integrations/google/google-calendar.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Future options such as richer event-scoped templates or Hub-driven update checks are intentionally deferred until Harbor has clearer version and update semantics.

Official reference starting points

• Google Calendar API reference root: https://developers.google.com/workspace/calendar/api/v3/reference
• Calendar list: https://developers.google.com/workspace/calendar/api/v3/reference/calendarList/list
• Settings list: https://developers.google.com/workspace/calendar/api/v3/reference/settings/list
• Colors get: https://developers.google.com/workspace/calendar/api/v3/reference/colors/get
• Calendars get: https://developers.google.com/workspace/calendar/api/v3/reference/calendars/get
• Events list: https://developers.google.com/workspace/calendar/api/v3/reference/events/list
• Events insert: https://developers.google.com/workspace/calendar/api/v3/reference/events/insert
• ACL list: https://developers.google.com/workspace/calendar/api/v3/reference/acl/list
• FreeBusy query: https://developers.google.com/workspace/calendar/api/v3/reference/freebusy/query