Calendar Tool

Overview

The Calendar tool provides a unified view of all time-based data across the platform — meetings from Google Calendar, leave requests, public holidays, team events, and task deadlines.

Features

• Unified view — Aggregates meetings, leave, holidays, events, and tasks into one calendar
• Multiple views — Month, week, and day views
• Meeting management — View synced Google Calendar meetings with attendee details
• RSVP — Yes / Maybe / No buttons on the event detail Sheet for events you’ve been invited to. Optimistically updates the chip and persists to Google with sendUpdates=all so the organiser sees your response
• Status-aware chips — A meeting’s chip styling reflects your own RSVP at a glance (see Status legend)
• Invite alerts — A meeting_invited notification fires from the bell when a new invite arrives. Driven by a */5 cron that scans the next 14 days; deduped via calendar_invite_seen so an invite only alerts once until the response status changes
• Attendee picker — Searchable picker on create/edit pulls from internal team, CRM contacts, and accepts manual email entry for external guests
• Entity matching — Meetings auto-matched to companies/contacts by attendee email
• Places (desk booking) — Reserve desks and meeting rooms
• Calendar settings — Configure working hours, default view, and sync preferences
• Transcript integration — View meeting transcripts and extracted action items

Status legend

EventChip renders four visually-distinct states based on your own attendee responseStatus. Synthetic events (birthdays, leave, holidays, etc.) keep their type-keyed colours and are unaffected.

Status	Style	Meaning
accepted (or you’re the organiser)	Solid fill	You’ve said yes
tentative	Dotted outline + softer fill	You said maybe
needsAction	Dashed outline + faded fill	You haven’t responded yet
declined	Strikethrough + 50% opacity	You said no

Permissions

Access Level	View	Update	Manage
Executive	Yes	Yes	Yes
Head	Yes	Yes	No
Manager	Yes	Yes	No
Lead	Yes	Yes	No
Employee	Yes	Yes	No

Data Sources

Source	Colour	Description
Meetings	Blue	Synced from Google Calendar
Leave	Orange	Approved leave requests
Holidays	Green	Public holidays for configured state
Events	Purple	Team events (from Events tool)
Tasks	Red	Tasks with due dates

Google Workspace setup

The calendar uses a domain-wide delegated service account. If users hit “insufficient permissions” when creating or editing events, the workspace admin needs to authorise the right scopes:

In Google Workspace Admin → Security → Access and data control → API controls → Domain-wide delegation, locate the Nucleus service account’s client ID and ensure both of these scopes are listed (comma-separated):

• https://www.googleapis.com/auth/calendar
• https://www.googleapis.com/auth/calendar.events

The read-only variants (*.readonly) on their own will let listing succeed but block POST/PATCH/DELETE — which is exactly the failure mode that surfaces as “insufficient permissions” on save.

The frontend now surfaces Google’s detail message in the toast (see apiFetch and ApiError in src/lib/api.ts) so the next failure should include the underlying reason — read the toast first before assuming the problem is in our code.

Components

File	Purpose
src/routes/calendar.tsx	Route definition
src/components/calendar/	Calendar components (month/week/day views, event cards, RSVP buttons, attendee picker)
src/components/calendar/rsvp-buttons.tsx	Yes / Maybe / No segmented control
src/components/calendar/attendee-picker.tsx	Guest picker (Team / CRM contacts / external email)
src/hooks/use-calendar.ts	TanStack Query hooks (incl. useRespondToEvent)
worker/routes/calendar.ts	API endpoints
worker/lib/calendar-invites.ts	Cron-driven scanner that fires meeting_invited notifications