Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
fix(calendar): refuse Add to calendar while a join request is open (#8655)
gbirmand355d986e5af
diff --git a/apps/web/src/features/calendar-view/components/SharedEventActions.test.tsx b/apps/web/src/features/calendar-view/components/SharedEventActions.test.tsxindex 5f335afdb8..cf82b4c774 100644--- a/apps/web/src/features/calendar-view/components/SharedEventActions.test.tsx+++ b/apps/web/src/features/calendar-view/components/SharedEventActions.test.tsx@@ -37,6 +37,8 @@ vi.mock('@queries/calendar/copy', () => ({(error as { code?: string }).code === 'already_on_calendar',isCopyRefused: (error: unknown) =>(error as { code?: string }).code === 'copy_refused',+ isJoinRequestOpen: (error: unknown) =>+ (error as { code?: string }).code === 'join_request_open',useCopySharedCalendarEventMutation: (callbacks?: {onSuccess?: () => void;onError?: (error: unknown) => void;diff --git a/apps/web/src/features/calendar-view/components/SharedEventActions.tsx b/apps/web/src/features/calendar-view/components/SharedEventActions.tsxindex cc51cf685c..d2fec66b51 100644--- a/apps/web/src/features/calendar-view/components/SharedEventActions.tsx+++ b/apps/web/src/features/calendar-view/components/SharedEventActions.tsx@@ -13,6 +13,7 @@ import { useVisibleCalendarsQuery } from '@queries/calendar/calendars';import {isAlreadyOnCalendar,isCopyRefused,+ isJoinRequestOpen,useCopySharedCalendarEventMutation,} from '@queries/calendar/copy';import {@@ -68,6 +69,10 @@ export function SharedEventActions(props: {onError: (error) => {if (isAlreadyOnCalendar(error)) {toast.failure('This event is already on your calendar');+ } else if (isJoinRequestOpen(error)) {+ toast.failure("You've asked to join this event", {+ subtext: "It reaches your calendar once you're added as a guest.",+ });} else if (isCopyRefused(error)) {toast.failure("Google Calendar won't add this event to that calendar", {subtext: 'Download the .ics file to add it another way.',diff --git a/apps/web/src/lib/queries/calendar/copy.ts b/apps/web/src/lib/queries/calendar/copy.tsindex 722df5a577..6690e30a39 100644--- a/apps/web/src/lib/queries/calendar/copy.ts+++ b/apps/web/src/lib/queries/calendar/copy.ts@@ -23,6 +23,17 @@ export function isAlreadyOnCalendar(error: unknown): boolean {);}+/**+ * Whether the viewer's request to join the event is pending or accepted, so+ * the meeting reaches their calendar as an invitation instead of a copy.+ */+export function isJoinRequestOpen(error: unknown): boolean {+ return thrownResultErrorHasCode(+ error,+ CalendarMutationErrorCode.join_request_open+ );+}+/** Whether Google refused to add the copy to the picked calendar. */export function isCopyRefused(error: unknown): boolean {return thrownResultErrorHasCode(@@ -33,6 +44,7 @@ export function isCopyRefused(error: unknown): boolean {function copyFailureOutcome(error: unknown) {if (isAlreadyOnCalendar(error)) return 'already_on_calendar';+ if (isJoinRequestOpen(error)) return 'join_request_open';if (isCopyRefused(error)) return 'copy_refused';return 'failed';}diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/client.ts b/apps/web/src/lib/service-clients/service-calendar/generated/client.tsindex c57c2aa320..fc3e33fcef 100644--- a/apps/web/src/lib/service-clients/service-calendar/generated/client.ts+++ b/apps/web/src/lib/service-clients/service-calendar/generated/client.ts@@ -431,6 +431,9 @@ export const updateCalendarEvent = async (one of their Google calendars and return the synced snapshot. Thesnapshot keeps the meeting's iCalendar UID and organizer, lists only therequester as a guest, and carries no join link; nobody is notified.+While the requester's request to join the event is pending or accepted,+the copy is refused with `join_request_open`: the meeting reaches their+calendar as the invitation, which a copy would otherwise take in.*/export type copyCalendarEventResponse201 = {data: CalendarEvent;diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMutationErrorCode.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMutationErrorCode.tsindex 22f75af292..494d1d894e 100644--- a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMutationErrorCode.ts+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMutationErrorCode.ts@@ -23,6 +23,7 @@ export const CalendarMutationErrorCode = {guest_list_hidden: 'guest_list_hidden',guests_cannot_modify: 'guests_cannot_modify',already_on_calendar: 'already_on_calendar',+ join_request_open: 'join_request_open',copy_refused: 'copy_refused',snapshot: 'snapshot',invalid_input: 'invalid_input',diff --git a/apps/web/src/lib/service-clients/service-calendar/openapi.json b/apps/web/src/lib/service-clients/service-calendar/openapi.jsonindex f6fe893dee..6f32e7f503 100644--- a/apps/web/src/lib/service-clients/service-calendar/openapi.json+++ b/apps/web/src/lib/service-clients/service-calendar/openapi.json@@ -355,7 +355,7 @@"/events/{event_id}/copy": {"post": {"tags": ["calendar_events"],- "summary": "Add a snapshot of an event shared with one of the requester's channels to\none of their Google calendars and return the synced snapshot. The\nsnapshot keeps the meeting's iCalendar UID and organizer, lists only the\nrequester as a guest, and carries no join link; nobody is notified.",+ "summary": "Add a snapshot of an event shared with one of the requester's channels to\none of their Google calendars and return the synced snapshot. The\nsnapshot keeps the meeting's iCalendar UID and organizer, lists only the\nrequester as a guest, and carries no join link; nobody is notified.\nWhile the requester's request to join the event is pending or accepted,\nthe copy is refused with `join_request_open`: the meeting reaches their\ncalendar as the invitation, which a copy would otherwise take in.","operationId": "copy_calendar_event","parameters": [{@@ -424,7 +424,7 @@}},"409": {- "description": "Already on the requester's calendar, no writable calendar, or the provider refused the copy",+ "description": "Already on the requester's calendar, a request to join it is pending or accepted, no writable calendar, or the provider refused the copy","content": {"application/json": {"schema": {@@ -1685,6 +1685,7 @@"guest_list_hidden","guests_cannot_modify","already_on_calendar",+ "join_request_open","copy_refused","snapshot","invalid_input",diff --git a/crates/agent_code_mode/src/domain/documentation.json b/crates/agent_code_mode/src/domain/documentation.jsonindex b4f14227ce..5ea735163c 100644--- a/crates/agent_code_mode/src/domain/documentation.json+++ b/crates/agent_code_mode/src/domain/documentation.json@@ -69,7 +69,7 @@"name": "calendar","description": "Find and manage calendar events.","overview": "<!-- src/entities/calendar/namespace/classes/CalendarNamespace.md -->\n# Class: CalendarNamespace\n\nThe calendar surface: the caller's visible calendars, event creation, and\nhandles to individual events and calendars. Backed by calendar_service (the\nSDK reaches it on the gateway's `/calendar` route).\n\n## Constructors\n\n### Constructor\n\n> **new CalendarNamespace**(`client`): `CalendarNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`CalendarNamespace`\n\n## Methods\n\n### availabilityCalendars()\n\n> **availabilityCalendars**(): `Promise`\\<\\{ `calendar`: [`Calendar`](../../calendar/classes/Calendar.md); `contributesToAvailability`: `boolean`; `isPrimary`: `boolean`; `name`: `string`; \\}[]\\>\n\nCalendar availability settings, each referring to a typed calendar.\n\n#### Returns\n\n`Promise`\\<\\{ `calendar`: [`Calendar`](../../calendar/classes/Calendar.md); `contributesToAvailability`: `boolean`; `isPrimary`: `boolean`; `name`: `string`; \\}[]\\>\n\n***\n\n### calendar()\n\n> **calendar**(`id`): [`Calendar`](../../calendar/classes/Calendar.md)\n\nA handle to a calendar by id. Detail loads on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Calendar`](../../calendar/classes/Calendar.md)\n\n***\n\n### calendars()\n\n> **calendars**(): `Promise`\\<[`Calendar`](../../calendar/classes/Calendar.md)[]\\>\n\nThe caller's visible calendars, primaries and writable first.\n\n#### Returns\n\n`Promise`\\<[`Calendar`](../../calendar/classes/Calendar.md)[]\\>\n\n***\n\n### createEvent()\n\n> **createEvent**(`options`): `Promise`\\<[`CalendarEvent`](../../event/classes/CalendarEvent.md)\\>\n\nCreate a calendar event and return a handle to its synced record.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`CreateEventOptions`](../interfaces/CreateEventOptions.md) |\n\n#### Returns\n\n`Promise`\\<[`CalendarEvent`](../../event/classes/CalendarEvent.md)\\>\n\n***\n\n### event()\n\n> **event**(`id`): [`CalendarEvent`](../../event/classes/CalendarEvent.md)\n\nA handle to a calendar event by id, for driving mutations.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`CalendarEvent`](../../event/classes/CalendarEvent.md)\n\n***\n\n### noteDocuments()\n\n> **noteDocuments**(`query?`): `Promise`\\<\\{ `documents`: \\{ `document`: [`Document`](../../../documents/document/classes/Document.md); `name`: `string`; \\}[]; `teams`: \\{ `name`: `string`; `team`: [`Team`](../../../teams/team/classes/Team.md); \\}[]; \\}\\>\n\nFind up to 30 owned markdown documents for meeting notes, plus available extra team audiences.\n\n#### Parameters\n\n| Parameter | Type | Default value |\n| ------ | ------ | ------ |\n| `query?` | `string` | `''` |\n\n#### Returns\n\n`Promise`\\<\\{ `documents`: \\{ `document`: [`Document`](../../../documents/document/classes/Document.md); `name`: `string`; \\}[]; `teams`: \\{ `name`: `string`; `team`: [`Team`](../../../teams/team/classes/Team.md); \\}[]; \\}\\>\n\n***\n\n### occurrences()\n\n> **occurrences**(`options`): `AsyncGenerator`\\<\\{ `event`: [`CalendarEvent`](../../event/classes/CalendarEvent.md); `occurrence`: [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md); \\}, `any`, `any`\\>\n\nCalendar occurrences in a viewport, automatically paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | `Omit`\\<[`ListOccurrencesData`](../../../../../generated/storage/types.gen/type-aliases/ListOccurrencesData.md)\\[`\"query\"`\\], `\"cursor\"`\\> |\n\n#### Returns\n\n`AsyncGenerator`\\<\\{ `event`: [`CalendarEvent`](../../event/classes/CalendarEvent.md); `occurrence`: [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md); \\}, `any`, `any`\\>\n\n***\n\n### replacement()\n\n> **replacement**(`operationId`): [`CalendarReplacement`](../../replacement/classes/CalendarReplacement.md)\n\nRecover a saved replacement, including after its original event was retired.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `operationId` | `string` |\n\n#### Returns\n\n[`CalendarReplacement`](../../replacement/classes/CalendarReplacement.md)\n\n***\n\n### setTeamSharing()\n\n> **setTeamSharing**(`sharing`): `Promise`\\<[`TeamCalendarSharing`](../../../../../generated/calendar/types.gen/type-aliases/TeamCalendarSharing.md)\\>\n\nReplace the team calendar sharing preference.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `sharing` | [`TeamCalendarSharing`](../../../../../generated/calendar/types.gen/type-aliases/TeamCalendarSharing.md) |\n\n#### Returns\n\n`Promise`\\<[`TeamCalendarSharing`](../../../../../generated/calendar/types.gen/type-aliases/TeamCalendarSharing.md)\\>\n\n***\n\n### teamOutOfOffice()\n\n> **teamOutOfOffice**(`options`): `Promise`\\<\\{ `hasMore`: `boolean`; `items`: \\{ `event`: [`CalendarEvent`](../../event/classes/CalendarEvent.md); `occurrenceKey`: `string`; `owner`: [`User`](../../../users/user/classes/User.md); `time`: [`EventTime`](../../../../../generated/storage/types.gen/type-aliases/EventTime.md); `title`: `string` \\| `undefined`; \\}[]; \\}\\>\n\nTeammates' out-of-office occurrences in a bounded viewport. Check hasMore for truncation.\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `options` | \\{ `end`: `string`; `endDate?`: `string`; `limit?`: `number`; `start`: `string`; `startDate?`: `string`; \\} | - |\n| `options.end` | `string` | Exclusive UTC viewport end. |\n| `options.endDate?` | `string` | Exclusive local date boundary for all-day events. |\n| `options.limit?` | `number` | Maximum number of occurrences, from 1 through 2,000. |\n| `options.start` | `string` | Inclusive UTC viewport start. |\n| `options.startDate?` | `string` | Inclusive local date boundary for all-day events. |\n\n#### Returns\n\n`Promise`\\<\\{ `hasMore`: `boolean`; `items`: \\{ `event`: [`CalendarEvent`](../../event/classes/CalendarEvent.md); `occurrenceKey`: `string`; `owner`: [`User`](../../../users/user/classes/User.md); `time`: [`EventTime`](../../../../../generated/storage/types.gen/type-aliases/EventTime.md); `title`: `string` \\| `undefined`; \\}[]; \\}\\>\n\n***\n\n### teamPage()\n\n> **teamPage**(`options`): `Promise`\\<\\{ `items`: (\\{ `contributesToAvailability`: `boolean`; `id`: `string`; `kind`: `\"busy\"`; `owner`: [`User`](../../../users/user/classes/User.md); `time`: [`EventTime`](../../../../../generated/storage/types.gen/type-aliases/EventTime.md); \\} \\| \\{ `contributesToAvailability`: `boolean`; `details`: [`TeamCalendarDetails`](../../../../../generated/storage/types.gen/type-aliases/TeamCalendarDetails.md); `id`: `string`; `kind`: `\"details\"`; `owner`: [`User`](../../../users/user/classes/User.md); `time`: [`EventTime`](../../../../../generated/storage/types.gen/type-aliases/EventTime.md); \\})[]; `members`: \\{ `coverage`: [`TeamCalendarCoverage`](../../../../../generated/storage/types.gen/type-aliases/TeamCalendarCoverage.md); `sharing`: [`TeamCalendarSharing`](../../../../../generated/storage/types.gen/type-aliases/TeamCalendarSharing.md); `user`: [`User`](../../../users/user/classes/User.md); \\}[]; `nextCursor`: `string` \\| `undefined`; \\}\\>\n\nA page of team availability, including its roster and continuation cursor.\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `options` | \\{ `cursor?`: `string` \\| `null`; `end`: `string`; `limit?`: `number` \\| `null`; `start`: `string`; \\} | - |\n| `options.cursor?` | `string` \\| `null` | Continuation returned by the preceding page. |\n| `options.end` | `string` | Exclusive instant. |\n| `options.limit?` | `number` \\| `null` | Maximum source occurrences, at most 2,000. Zero returns the roster only. |\n| `options.start` | `string` | Inclusive instant. |\n\n#### Returns\n\n`Promise`\\<\\{ `items`: (\\{ `contributesToAvailability`: `boolean`; `id`: `string`; `kind`: `\"busy\"`; `owner`: [`User`](../../../users/user/classes/User.md); `time`: [`EventTime`](../../../../../generated/storage/types.gen/type-aliases/EventTime.md); \\} \\| \\{ `contributesToAvailability`: `boolean`; `details`: [`TeamCalendarDetails`](../../../../../generated/storage/types.gen/type-aliases/TeamCalendarDetails.md); `id`: `string`; `kind`: `\"details\"`; `owner`: [`User`](../../../users/user/classes/User.md); `time`: [`EventTime`](../../../../../generated/storage/types.gen/type-aliases/EventTime.md); \\})[]; `members`: \\{ `coverage`: [`TeamCalendarCoverage`](../../../../../generated/storage/types.gen/type-aliases/TeamCalendarCoverage.md); `sharing`: [`TeamCalendarSharing`](../../../../../generated/storage/types.gen/type-aliases/TeamCalendarSharing.md); `user`: [`User`](../../../users/user/classes/User.md); \\}[]; `nextCursor`: `string` \\| `undefined`; \\}\\>\n\n***\n\n### teamSharing()\n\n> **teamSharing**(): `Promise`\\<[`TeamCalendarSharing`](../../../../../generated/calendar/types.gen/type-aliases/TeamCalendarSharing.md)\\>\n\nCurrent sharing preference for the team calendar.\n\n#### Returns\n\n`Promise`\\<[`TeamCalendarSharing`](../../../../../generated/calendar/types.gen/type-aliases/TeamCalendarSharing.md)\\>\n\n\n<!-- src/entities/calendar/namespace/interfaces/CreateEventOptions.md -->\n# Interface: CreateEventOptions\n\nFields for a new calendar event.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attendees\"></a> `attendees?` | [`CalendarAttendeeInputBody`](../../../../../generated/calendar/types.gen/type-aliases/CalendarAttendeeInputBody.md)[] | Invited attendees. |\n| <a id=\"property-calendar\"></a> `calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) | Exact calendar to create the event on; takes precedence over the inbox default. |\n| <a id=\"property-conference\"></a> `conference?` | [`ConferenceChange`](../../../../../generated/calendar/types.gen/type-aliases/ConferenceChange.md) | Conference to attach; omit to create the event without one. |\n| <a id=\"property-description\"></a> `description?` | `string` | Optional event body. |\n| <a id=\"property-emaillink\"></a> `emailLink?` | [`Link`](../../../email/link/classes/Link.md) | Connected inbox whose primary calendar receives the event; defaults to the requester's primary inbox. |\n| <a id=\"property-guestpolicy\"></a> `guestPolicy?` | [`GuestPolicy`](../../../../../generated/calendar/types.gen/type-aliases/GuestPolicy.md) | What guests may do; omit for Google's defaults. Google calendars only. |\n| <a id=\"property-location\"></a> `location?` | `string` | Optional location label. |\n| <a id=\"property-macrocall\"></a> `macroCall?` | `boolean` | Mint a Macro call with the event; its join link lands in the description and location. Cannot be combined with `conference`. |\n| <a id=\"property-outofoffice\"></a> `outOfOffice?` | [`OutOfOfficeProperties`](../../../../../generated/calendar/types.gen/type-aliases/OutOfOfficeProperties.md) | Out-of-office properties; present to create an out-of-office event. |\n| <a id=\"property-recurrencelines\"></a> `recurrenceLines?` | `string`[] | Raw RFC 5545 recurrence properties (`RRULE`, `RDATE`, `EXDATE`). |\n| <a id=\"property-reminders\"></a> `reminders?` | [`EventReminders`](../../../../../generated/calendar/types.gen/type-aliases/EventReminders.md) | Reminder configuration; omit to keep the calendar defaults. |\n| <a id=\"property-time\"></a> `time` | [`EventTime`](../../../../../generated/calendar/types.gen/type-aliases/EventTime.md) | Timed or all-day shape. |\n| <a id=\"property-title\"></a> `title` | `string` | Display title. |\n| <a id=\"property-transparency\"></a> `transparency?` | [`EventTransparency`](../../../../../generated/calendar/types.gen/type-aliases/EventTransparency.md) | Availability behavior. |\n| <a id=\"property-visibility\"></a> `visibility?` | [`EventVisibility`](../../../../../generated/calendar/types.gen/type-aliases/EventVisibility.md) | Event visibility. |\n",- "documentation": "# Macro SDK: calendar\n\nGenerated by TypeDoc. Paths below refer to the canonical Markdown hierarchy. Other entity handles are documented in their named section; request core for shared SDK helpers.\n\n<!-- generated/calendar/types.gen/type-aliases/AttendeeResponseStatus.md -->\n# Type Alias: AttendeeResponseStatus\n\n> **AttendeeResponseStatus** = `\"needs_action\"` \\| `\"accepted\"` \\| `\"declined\"` \\| `\"tentative\"`\n\nRSVP state for an attendee.\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarAttendee.md -->\n# Type Alias: CalendarAttendee\n\n> **CalendarAttendee** = \\{ `comment?`: `string` \\| `null`; `displayName?`: `string` \\| `null`; `email`: `string`; `isOptional`: `boolean`; `isOrganizer`: `boolean`; `isSelf`: `boolean`; `responseStatus`: [`AttendeeResponseStatus`](AttendeeResponseStatus.md); \\}\n\nAn attendee on a calendar event.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-comment\"></a> `comment?` | `string` \\| `null` | Optional attendee comment. |\n| <a id=\"property-displayname\"></a> `displayName?` | `string` \\| `null` | Provider display name. |\n| <a id=\"property-email\"></a> `email` | `string` | Normalized email address. |\n| <a id=\"property-isoptional\"></a> `isOptional` | `boolean` | Whether attendance is optional. |\n| <a id=\"property-isorganizer\"></a> `isOrganizer` | `boolean` | Whether this attendee is the organizer. |\n| <a id=\"property-isself\"></a> `isSelf` | `boolean` | Whether this attendee is one of the viewing requester's inboxes. |\n| <a id=\"property-responsestatus\"></a> `responseStatus` | [`AttendeeResponseStatus`](AttendeeResponseStatus.md) | RSVP state. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarAttendeeInputBody.md -->\n# Type Alias: CalendarAttendeeInputBody\n\n> **CalendarAttendeeInputBody** = \\{ `email`: `string`; `isOptional?`: `boolean`; \\}\n\nAn attendee supplied to a calendar mutation.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-email\"></a> `email` | `string` | Attendee email address. |\n| <a id=\"property-isoptional\"></a> `isOptional?` | `boolean` | Whether attendance is optional. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarCapabilities.md -->\n# Type Alias: CalendarCapabilities\n\n> **CalendarCapabilities** = \\{ `autoDecline`: `boolean`; `conferenceProvider?`: `null` \\| [`ConferenceProvider`](ConferenceProvider.md); `customRecurrence`: `boolean`; `emailReminders`: `boolean`; `guestPolicy`: `boolean`; `removeConference`: `boolean`; `resetRsvp`: `boolean`; \\}\n\nActual provider capabilities used by calendar editors.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-autodecline\"></a> `autoDecline` | `boolean` | Whether event-level automatic invitation declines are supported. |\n| <a id=\"property-conferenceprovider\"></a> `conferenceProvider?` | `null` \\| [`ConferenceProvider`](ConferenceProvider.md) | - |\n| <a id=\"property-customrecurrence\"></a> `customRecurrence` | `boolean` | Whether arbitrary RFC 5545 recurrence properties can be written. |\n| <a id=\"property-emailreminders\"></a> `emailReminders` | `boolean` | Whether email reminders are delivered by the provider or Macro. |\n| <a id=\"property-guestpolicy\"></a> `guestPolicy` | `boolean` | Whether the organizer can set what guests may do. |\n| <a id=\"property-removeconference\"></a> `removeConference` | `boolean` | Whether an existing conference can be detached. |\n| <a id=\"property-resetrsvp\"></a> `resetRsvp` | `boolean` | Whether an attendee can reset their RSVP to unanswered. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarDeletionScopeParam.md -->\n# Type Alias: CalendarDeletionScopeParam\n\n> **CalendarDeletionScopeParam** = `\"all\"` \\| `\"this_event\"` \\| `\"this_and_following\"`\n\nHow much of a recurring series a deletion removes.\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarEvent.md -->\n# Type Alias: CalendarEvent\n\n> **CalendarEvent** = \\{ `attendees`: [`CalendarAttendee`](CalendarAttendee.md)[]; `calendarId?`: `string` \\| `null`; `conferenceProvider?`: `null` \\| [`ConferenceProvider`](ConferenceProvider.md); `conferenceUrl?`: `string` \\| `null`; `createdAt`: `string`; `creatorEmail?`: `string` \\| `null`; `creatorName?`: `string` \\| `null`; `description?`: `string` \\| `null`; `eventType?`: [`EventType`](EventType.md); `guestPolicy`: [`GuestPolicy`](GuestPolicy.md); `icalUid`: `string`; `id`: `string`; `isReadOnly`: `boolean`; `isSnapshot`: `boolean`; `location?`: `string` \\| `null`; `organizerEmail?`: `string` \\| `null`; `organizerName?`: `string` \\| `null`; `ownerId`: `string`; `recurrenceLines`: `string`[]; `reminders?`: [`EventReminders`](EventReminders.md); `sequence`: `number`; `sources?`: [`CalendarEventSourceContent`](CalendarEventSourceContent.md)[]; `status`: [`EventStatus`](EventStatus.md); `time`: [`EventTime`](EventTime.md); `title`: `string`; `transparency`: [`EventTransparency`](EventTransparency.md); `updatedAt`: `string`; `viewerCan`: [`ViewerCapabilities`](ViewerCapabilities.md); `visibility`: [`EventVisibility`](EventVisibility.md); \\}\n\nA stable, first-class Macro calendar event entity.\n\nContent fields hold the canonical source's values: the account's primary\ncalendar copy when one is synced, else the freshest remaining copy.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attendees\"></a> `attendees` | [`CalendarAttendee`](CalendarAttendee.md)[] | Attendees, keyed by email during persistence. |\n| <a id=\"property-calendarid\"></a> `calendarId?` | `string` \\| `null` | Calendar the canonical source belongs to, when known. Absent only in projections stored before calendars were attributed. |\n| <a id=\"property-conferenceprovider\"></a> `conferenceProvider?` | `null` \\| [`ConferenceProvider`](ConferenceProvider.md) | - |\n| <a id=\"property-conferenceurl\"></a> `conferenceUrl?` | `string` \\| `null` | Direct join URL when known. |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | Entity creation time. |\n| <a id=\"property-creatoremail\"></a> `creatorEmail?` | `string` \\| `null` | Provider-reported creator email. Distinct from the organizer when someone writes onto a calendar they do not own. Omitted from stored projections when unknown so events ingested before this field still compare equal. |\n| <a id=\"property-creatorname\"></a> `creatorName?` | `string` \\| `null` | Provider-reported creator display name. |\n| <a id=\"property-description\"></a> `description?` | `string` \\| `null` | Optional event body. |\n| <a id=\"property-eventtype\"></a> `eventType?` | [`EventType`](EventType.md) | Provider event type. Skipped when it is the regular type so projections stored before event types were modeled still compare equal. |\n| <a id=\"property-guestpolicy\"></a> `guestPolicy` | [`GuestPolicy`](GuestPolicy.md) | What the organizer lets guests do: the canonical copy's values, or Google's defaults for an event synced before the policy was modeled. |\n| <a id=\"property-icaluid\"></a> `icalUid` | `string` | RFC 5545 UID used to reconcile provider and email sources. |\n| <a id=\"property-id\"></a> `id` | `string` | Macro entity identifier. |\n| <a id=\"property-isreadonly\"></a> `isReadOnly` | `boolean` | Whether the canonical source's calendar prohibits editing it. |\n| <a id=\"property-issnapshot\"></a> `isSnapshot` | `boolean` | Whether this is a snapshot of a meeting shared with the owner, which Macro added to their calendar as a private copy: the meeting's changes never reach it, and nothing done to it reaches the meeting. |\n| <a id=\"property-location\"></a> `location?` | `string` \\| `null` | Optional physical or virtual location label. |\n| <a id=\"property-organizeremail\"></a> `organizerEmail?` | `string` \\| `null` | Organizer email. |\n| <a id=\"property-organizername\"></a> `organizerName?` | `string` \\| `null` | Organizer display name. |\n| <a id=\"property-ownerid\"></a> `ownerId` | `string` | Macro user who owns this event entity. |\n| <a id=\"property-recurrencelines\"></a> `recurrenceLines` | `string`[] | Raw RFC 5545 recurrence properties (`RRULE`, `RDATE`, `EXDATE`). |\n| <a id=\"property-reminders\"></a> `reminders?` | [`EventReminders`](EventReminders.md) | Per-user reminder configuration. Skipped when it is the provider default so projections stored before reminders were modeled still compare equal. |\n| <a id=\"property-sequence\"></a> `sequence` | `number` | Provider/iCalendar sequence number. |\n| <a id=\"property-sources\"></a> `sources?` | [`CalendarEventSourceContent`](CalendarEventSourceContent.md)[] | Content of every active copy of this event, canonical first: the primary calendar's copy, then the freshest. A client picks the copy whose calendar it is showing and falls back to the first. Populated only on the read path, so stored projections omit it. |\n| <a id=\"property-status\"></a> `status` | [`EventStatus`](EventStatus.md) | Event status. |\n| <a id=\"property-time\"></a> `time` | [`EventTime`](EventTime.md) | Timed or all-day shape. |\n| <a id=\"property-title\"></a> `title` | `string` | Display title. |\n| <a id=\"property-transparency\"></a> `transparency` | [`EventTransparency`](EventTransparency.md) | Availability behavior. |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `string` | Entity update time. |\n| <a id=\"property-viewercan\"></a> `viewerCan` | [`ViewerCapabilities`](ViewerCapabilities.md) | What the viewing requester may do with the event. Resolved only on the read path, alongside each attendee's `is_self`; nothing when no viewer is known. Source projections never store it. |\n| <a id=\"property-visibility\"></a> `visibility` | [`EventVisibility`](EventVisibility.md) | Event visibility. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarEventSourceContent.md -->\n# Type Alias: CalendarEventSourceContent\n\n> **CalendarEventSourceContent** = \\{ `calendarId`: `string`; `creatorEmail?`: `string` \\| `null`; `creatorName?`: `string` \\| `null`; `description?`: `string` \\| `null`; `eventType`: [`EventType`](EventType.md); `isReadOnly`: `boolean`; `location?`: `string` \\| `null`; `reminders`: [`EventReminders`](EventReminders.md); `title`: `string`; `transparency`: [`EventTransparency`](EventTransparency.md); `visibility`: [`EventVisibility`](EventVisibility.md); \\}\n\nThe content one provider copy of an event carries.\n\nGoogle keeps these fields per calendar copy: a shared calendar's copy of a\nmember's event can have its own title, type, reminders, and access role.\nThe entity holds its canonical source's values. Every other copy's values\nare read from here so a client can show the copy that belongs to the\ncalendar being viewed.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-calendarid\"></a> `calendarId` | `string` | Calendar this copy lives on. |\n| <a id=\"property-creatoremail\"></a> `creatorEmail?` | `string` \\| `null` | Provider-reported creator email. |\n| <a id=\"property-creatorname\"></a> `creatorName?` | `string` \\| `null` | Provider-reported creator display name. |\n| <a id=\"property-description\"></a> `description?` | `string` \\| `null` | Optional event body. |\n| <a id=\"property-eventtype\"></a> `eventType` | [`EventType`](EventType.md) | Provider event type. |\n| <a id=\"property-isreadonly\"></a> `isReadOnly` | `boolean` | Whether the calendar's access role prohibits editing this copy. |\n| <a id=\"property-location\"></a> `location?` | `string` \\| `null` | Optional physical or virtual location label. |\n| <a id=\"property-reminders\"></a> `reminders` | [`EventReminders`](EventReminders.md) | Reminder configuration of this copy. |\n| <a id=\"property-title\"></a> `title` | `string` | Display title. |\n| <a id=\"property-transparency\"></a> `transparency` | [`EventTransparency`](EventTransparency.md) | Availability behavior. |\n| <a id=\"property-visibility\"></a> `visibility` | [`EventVisibility`](EventVisibility.md) | Event visibility. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarGuestInputBody.md -->\n# Type Alias: CalendarGuestInputBody\n\n> **CalendarGuestInputBody** = \\{ `email`: `string`; `optional?`: `boolean`; \\}\n\nA guest added to an event.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-email\"></a> `email` | `string` | Guest email address. |\n| <a id=\"property-optional\"></a> `optional?` | `boolean` | Whether attendance is optional. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarProvider.md -->\n# Type Alias: CalendarProvider\n\n> **CalendarProvider** = `\"google\"` \\| `\"outlook\"`\n\nProvider selected from the persisted calendar account and email binding.\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarReplacementView.md -->\n# Type Alias: CalendarReplacementView\n\n> **CalendarReplacementView** = \\{ `attendeeCount`: `number`; `completedSteps`: `number`; `event?`: `null` \\| [`CalendarEvent`](CalendarEvent.md); `isSeries`: `boolean`; `operationId`: `string`; `providerUrl?`: `string` \\| `null`; `removeConference`: `boolean`; `replacementUrl?`: `string` \\| `null`; `status`: [`ReplacementStatus`](ReplacementStatus.md); `time`: [`EventTime`](EventTime.md); `title`: `string`; `totalSteps`: `number`; \\}\n\nSafe preview and recovery response; never exposes the opaque provider snapshot.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attendeecount\"></a> `attendeeCount` | `number` | Guest count for cancellation and reinvitation confirmation. |\n| <a id=\"property-completedsteps\"></a> `completedSteps` | `number` | Number of completed provider steps. |\n| <a id=\"property-event\"></a> `event?` | `null` \\| [`CalendarEvent`](CalendarEvent.md) | - |\n| <a id=\"property-isseries\"></a> `isSeries` | `boolean` | Entire recurring series, including exceptions, is replaced. |\n| <a id=\"property-operationid\"></a> `operationId` | `string` | Use this identity when confirming or checking progress. |\n| <a id=\"property-providerurl\"></a> `providerUrl?` | `string` \\| `null` | Original event for manual review. |\n| <a id=\"property-removeconference\"></a> `removeConference` | `boolean` | The provider conference is removed. |\n| <a id=\"property-replacementurl\"></a> `replacementUrl?` | `string` \\| `null` | New provider event, when creation was confirmed. |\n| <a id=\"property-status\"></a> `status` | [`ReplacementStatus`](ReplacementStatus.md) | Current durable state. |\n| <a id=\"property-time\"></a> `time` | [`EventTime`](EventTime.md) | Frozen time. |\n| <a id=\"property-title\"></a> `title` | `string` | Frozen title. |\n| <a id=\"property-totalsteps\"></a> `totalSteps` | `number` | Number of provider steps in this operation. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarRsvpScopeParam.md -->\n# Type Alias: CalendarRsvpScopeParam\n\n> **CalendarRsvpScopeParam** = `\"all\"` \\| `\"this_event\"`\n\nHow much of a recurring series an RSVP applies to.\n\nUnlike deletion there is no this-and-following variant: the provider\ncannot express a forward-scoped response, so offering one would be a\npromise sync could not keep.\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarUpdateScopeParam.md -->\n# Type Alias: CalendarUpdateScopeParam\n\n> **CalendarUpdateScopeParam** = `\"all\"` \\| `\"this_event\"`\n\nHow much of a recurring series an update applies to.\n\nLike RSVPs there is no this-and-following variant: the provider cannot\nexpress a forward-scoped edit as one write, and emulating it (truncate\nthe series, insert an edited clone) is non-atomic and re-invites the\nattendees of the clone. Compose it from a this-and-following deletion\nand a create when that shape is wanted.\n\n\n<!-- generated/calendar/types.gen/type-aliases/ConferenceChange.md -->\n# Type Alias: ConferenceChange\n\n> **ConferenceChange** = `\"provider_default\"` \\| `\"microsoft_teams\"` \\| `\"google_meet\"` \\| `\"none\"`\n\nA requested change to an event's conferencing. Omitting the field leaves\nthe existing conference untouched; only these values change it.\n\n\n<!-- generated/calendar/types.gen/type-aliases/ConferenceProvider.md -->\n# Type Alias: ConferenceProvider\n\n> **ConferenceProvider** = `\"microsoft_teams\"` \\| `\"google_meet\"` \\| `\"other\"`\n\nThe conferencing system backing an event's join URL.\n\nCalendars can create Google Meet or Microsoft Teams according to their\ncapabilities. Imported third-party conferences are labeled separately.\nOmitting a conference change preserves the current conference; explicit\nchanges still require provider and calendar capability validation.\n\n\n<!-- generated/calendar/types.gen/type-aliases/DocumentNoteLink.md -->\n# Type Alias: DocumentNoteLink\n\n> **DocumentNoteLink** = \\{ `documentName`: `string`; `eventId`: `string`; `eventTitle`: `string`; `occurrenceKey`: `string`; `team?`: `null` \\| [`NoteTeam`](NoteTeam.md); \\}\n\nAn owner's durable sharing link, including meetings they can no longer open.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-documentname\"></a> `documentName` | `string` | Current name of the owned markdown document. |\n| <a id=\"property-eventid\"></a> `eventId` | `string` | Linked calendar copy. |\n| <a id=\"property-eventtitle\"></a> `eventTitle` | `string` | Current title, or a safe placeholder when meeting details are unavailable. |\n| <a id=\"property-occurrencekey\"></a> `occurrenceKey` | `string` | Original occurrence start, or `single` for a one-time meeting. |\n| <a id=\"property-team\"></a> `team?` | `null` \\| [`NoteTeam`](NoteTeam.md) | - |\n\n\n<!-- generated/calendar/types.gen/type-aliases/EventReminderOverride.md -->\n# Type Alias: EventReminderOverride\n\n> **EventReminderOverride** = \\{ `method`: `string`; `minutes`: `number`; \\}\n\nOne reminder: how it alerts and how many minutes before the event start\n(before midnight in the calendar's zone for all-day events) it fires.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-method\"></a> `method` | `string` | Provider method, stored verbatim; only `popup` fires Macro notifications. |\n| <a id=\"property-minutes\"></a> `minutes` | `number` | Minutes before the event start. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/EventReminders.md -->\n# Type Alias: EventReminders\n\n> **EventReminders** = \\{ `overrides?`: [`EventReminderOverride`](EventReminderOverride.md)[]; `useDefault`: `boolean`; \\}\n\nPer-user reminder configuration for an event, mirroring Google's model:\neither the calendar's default reminders apply, or the explicit overrides\nreplace them entirely.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-overrides\"></a> `overrides?` | [`EventReminderOverride`](EventReminderOverride.md)[] | Explicit reminders replacing the defaults when `use_default` is off. |\n| <a id=\"property-usedefault\"></a> `useDefault` | `boolean` | Whether the calendar's default reminders apply. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/EventStatus.md -->\n# Type Alias: EventStatus\n\n> **EventStatus** = `\"confirmed\"` \\| `\"tentative\"` \\| `\"cancelled\"`\n\nCanonical event status.\n\n\n<!-- generated/calendar/types.gen/type-aliases/EventTime.md -->\n# Type Alias: EventTime\n\n> **EventTime** = \\{ `endsAt`: `string`; `kind`: `\"timed\"`; `startsAt`: `string`; `timeZone?`: `string` \\| `null`; \\} \\| \\{ `endDate`: `string`; `kind`: `\"allDay\"`; `startDate`: `string`; \\}\n\nThe mutually exclusive time shape of a calendar event.\n\nFields are renamed per variant rather than with `rename_all_fields`\nbecause utoipa only honors variant-level serde renames when it\nderives the OpenAPI schema.\n\n## Union Members\n\n### Type Literal\n\n\\{ `endsAt`: `string`; `kind`: `\"timed\"`; `startsAt`: `string`; `timeZone?`: `string` \\| `null`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `endsAt` | `string` | Exclusive end instant; equal to the start for an imported point event. |\n| `kind` | `\"timed\"` | - |\n| `startsAt` | `string` | Inclusive start instant. |\n| `timeZone?` | `string` \\| `null` | Original IANA time-zone identifier, when supplied. |\n\n***\n\n### Type Literal\n\n\\{ `endDate`: `string`; `kind`: `\"allDay\"`; `startDate`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `endDate` | `string` | Exclusive local end date. |\n| `kind` | `\"allDay\"` | - |\n| `startDate` | `string` | Inclusive local start date. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/EventTransparency.md -->\n# Type Alias: EventTransparency\n\n> **EventTransparency** = `\"opaque\"` \\| `\"transparent\"`\n\nWhether an event blocks availability.\n\n\n<!-- generated/calendar/types.gen/type-aliases/EventType.md -->\n# Type Alias: EventType\n\n> **EventType** = `\"default\"` \\| `\"out_of_office\"` \\| `\"focus_time\"` \\| `\"working_location\"` \\| `\"birthday\"` \\| `\"from_gmail\"`\n\nGoogle's event type: ordinary meetings versus the status-style entries\n(working location, out of office, focus time, birthdays) Google renders\nand notifies differently. Immutable at the provider after creation.\n\n\n<!-- generated/calendar/types.gen/type-aliases/EventVisibility.md -->\n# Type Alias: EventVisibility\n\n> **EventVisibility** = `\"default\"` \\| `\"public\"` \\| `\"private\"` \\| `\"confidential\"`\n\nVisibility of event details.\n\n\n<!-- generated/calendar/types.gen/type-aliases/GuestPolicy.md -->\n# Type Alias: GuestPolicy\n\n> **GuestPolicy** = \\{ `canInviteOthers`: `boolean`; `canModify`: `boolean`; `canSeeOtherGuests`: `boolean`; \\}\n\nThe switches an organizer sets on an event to bound what its guests may\ndo. Google omits a switch from the payload while it holds its default.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-caninviteothers\"></a> `canInviteOthers` | `boolean` | Whether guests may invite others. |\n| <a id=\"property-canmodify\"></a> `canModify` | `boolean` | Whether guests may change the event, including its guest list. |\n| <a id=\"property-canseeotherguests\"></a> `canSeeOtherGuests` | `boolean` | Whether guests may see the guest list. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/MeetingNote.md -->\n# Type Alias: MeetingNote\n\n> **MeetingNote** = \\{ `canManage`: `boolean`; `documentId`: `string`; `name`: `string`; `team?`: `null` \\| [`NoteTeam`](NoteTeam.md); \\}\n\nOne linked document and the extra access this link grants.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-canmanage\"></a> `canManage` | `boolean` | Whether this viewer can change this document's sharing. |\n| <a id=\"property-documentid\"></a> `documentId` | `string` | Markdown document identity. |\n| <a id=\"property-name\"></a> `name` | `string` | Current document name. |\n| <a id=\"property-team\"></a> `team?` | `null` \\| [`NoteTeam`](NoteTeam.md) | - |\n\n\n<!-- generated/calendar/types.gen/type-aliases/NoteTeam.md -->\n# Type Alias: NoteTeam\n\n> **NoteTeam** = \\{ `id`: `string`; `name`: `string`; \\}\n\nAn additional team audience, separate from the meeting's audience.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `string` | Team identity. |\n| <a id=\"property-name\"></a> `name` | `string` | Display name. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/OutOfOfficeAutoDeclineMode.md -->\n# Type Alias: OutOfOfficeAutoDeclineMode\n\n> **OutOfOfficeAutoDeclineMode** = `\"decline_none\"` \\| `\"decline_all_conflicting_invitations\"` \\| `\"decline_only_new_conflicting_invitations\"`\n\nHow an out-of-office event responds to conflicting invitations, mirroring\nGoogle's `autoDeclineMode`.\n\n\n<!-- generated/calendar/types.gen/type-aliases/OutOfOfficeProperties.md -->\n# Type Alias: OutOfOfficeProperties\n\n> **OutOfOfficeProperties** = \\{ `autoDeclineMode?`: [`OutOfOfficeAutoDeclineMode`](OutOfOfficeAutoDeclineMode.md); `declineMessage?`: `string` \\| `null`; \\}\n\nThe extra properties Google requires on an out-of-office event, mirroring\nits `outOfOfficeProperties` block. Their presence on a draft or patch is\nwhat marks the mutation as out-of-office.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-autodeclinemode\"></a> `autoDeclineMode?` | [`OutOfOfficeAutoDeclineMode`](OutOfOfficeAutoDeclineMode.md) | How conflicting invitations are handled while the user is out. |\n| <a id=\"property-declinemessage\"></a> `declineMessage?` | `string` \\| `null` | Message returned to organizers whose invitations are auto-declined. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/ReplacementStatus.md -->\n# Type Alias: ReplacementStatus\n\n> **ReplacementStatus** = `\"needs_confirmation\"` \\| `\"in_progress\"` \\| `\"complete\"`\n\nUser-visible workflow state.\n\n\n<!-- generated/calendar/types.gen/type-aliases/TeamCalendarSharing.md -->\n# Type Alias: TeamCalendarSharing\n\n> **TeamCalendarSharing** = `\"all\"` \\| `\"busy_only\"` \\| `\"none\"`\n\nWhat a user exposes through their team membership.\n\n\n<!-- generated/calendar/types.gen/type-aliases/ViewerCapabilities.md -->\n# Type Alias: ViewerCapabilities\n\n> **ViewerCapabilities** = \\{ `editDetails`: `boolean`; `inviteGuests`: `boolean`; `organize`: `boolean`; `removeGuests`: `boolean`; `rsvp`: `boolean`; `setGuestPolicy`: `boolean`; \\}\n\nWhat the viewing requester may do with an event.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-editdetails\"></a> `editDetails` | `boolean` | Change the event's details (title, time, description, conference). |\n| <a id=\"property-inviteguests\"></a> `inviteGuests` | `boolean` | Add guests. |\n| <a id=\"property-organize\"></a> `organize` | `boolean` | Act as the event's organizer: replace its whole guest list and manage its conferencing. |\n| <a id=\"property-removeguests\"></a> `removeGuests` | `boolean` | Remove guests. |\n| <a id=\"property-rsvp\"></a> `rsvp` | `boolean` | Answer the invitation. |\n| <a id=\"property-setguestpolicy\"></a> `setGuestPolicy` | `boolean` | Change the event's guest policy, which only Google calendars have. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/VisibleCalendar.md -->\n# Type Alias: VisibleCalendar\n\n> **VisibleCalendar** = \\{ `capabilities`: [`CalendarCapabilities`](CalendarCapabilities.md); `color?`: `string` \\| `null`; `defaultReminders`: [`EventReminderOverride`](EventReminderOverride.md)[]; `emailAddress`: `string`; `emailLinkId`: `string`; `id`: `string`; `isPrimary`: `boolean`; `isSubscription`: `boolean`; `isWritable`: `boolean`; `name`: `string`; `provider`: [`CalendarProvider`](CalendarProvider.md); `syncError?`: `string` \\| `null`; \\}\n\nA calendar visible to a requester, listed for pickers and filters.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-capabilities\"></a> `capabilities` | [`CalendarCapabilities`](CalendarCapabilities.md) | Provider features available on this actual calendar. |\n| <a id=\"property-color\"></a> `color?` | `string` \\| `null` | Provider color. |\n| <a id=\"property-defaultreminders\"></a> `defaultReminders` | [`EventReminderOverride`](EventReminderOverride.md)[] | Default reminders applied to events that keep `useDefault`. |\n| <a id=\"property-emailaddress\"></a> `emailAddress` | `string` | Connected inbox address, for grouping in multi-inbox pickers. |\n| <a id=\"property-emaillinkid\"></a> `emailLinkId` | `string` | Connected inbox that syncs this calendar. |\n| <a id=\"property-id\"></a> `id` | `string` | Persisted Macro calendar identifier. |\n| <a id=\"property-isprimary\"></a> `isPrimary` | `boolean` | Whether this is its account's primary calendar. |\n| <a id=\"property-issubscription\"></a> `isSubscription` | `boolean` | Whether this is one of Google's shared system calendars (holidays, birthdays) the account subscribes to rather than one a person maintains. |\n| <a id=\"property-iswritable\"></a> `isWritable` | `boolean` | Whether the grant can create and modify events on this calendar. |\n| <a id=\"property-name\"></a> `name` | `string` | Provider display name. |\n| <a id=\"property-provider\"></a> `provider` | [`CalendarProvider`](CalendarProvider.md) | Calendar provider, for display and reconnect routing. |\n| <a id=\"property-syncerror\"></a> `syncError?` | `string` \\| `null` | A persistent sync failure isolated to this calendar, surfaced so the settings row can badge it. `None` while the calendar is syncing normally or a failure has not yet crossed the persistence threshold. |\n\n\n<!-- generated/storage/types.gen/type-aliases/AttendeeResponseStatus.md -->\n# Type Alias: AttendeeResponseStatus\n\n> **AttendeeResponseStatus** = `\"needs_action\"` \\| `\"accepted\"` \\| `\"declined\"` \\| `\"tentative\"`\n\nRSVP state for an attendee.\n\n\n<!-- generated/storage/types.gen/type-aliases/CalendarAttendee.md -->\n# Type Alias: CalendarAttendee\n\n> **CalendarAttendee** = \\{ `comment?`: `string` \\| `null`; `displayName?`: `string` \\| `null`; `email`: `string`; `isOptional`: `boolean`; `isOrganizer`: `boolean`; `isSelf`: `boolean`; `responseStatus`: [`AttendeeResponseStatus`](AttendeeResponseStatus.md); \\}\n\nAn attendee on a calendar event.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-comment\"></a> `comment?` | `string` \\| `null` | Optional attendee comment. |\n| <a id=\"property-displayname\"></a> `displayName?` | `string` \\| `null` | Provider display name. |\n| <a id=\"property-email\"></a> `email` | `string` | Normalized email address. |\n| <a id=\"property-isoptional\"></a> `isOptional` | `boolean` | Whether attendance is optional. |\n| <a id=\"property-isorganizer\"></a> `isOrganizer` | `boolean` | Whether this attendee is the organizer. |\n| <a id=\"property-isself\"></a> `isSelf` | `boolean` | Whether this attendee is one of the viewing requester's inboxes. |\n| <a id=\"property-responsestatus\"></a> `responseStatus` | [`AttendeeResponseStatus`](AttendeeResponseStatus.md) | RSVP state. |\n\n\n<!-- generated/storage/types.gen/type-aliases/CalendarOccurrence.md -->\n# Type Alias: CalendarOccurrence\n\n> **CalendarOccurrence** = \\{ `eventId`: `string`; `isCancelled`: `boolean`; `occurrenceKey`: `string`; `recurrenceId?`: `string` \\| `null`; `time`: [`EventTime`](EventTime.md); \\}\n\nA materialized recurrence instance optimized for range queries.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-eventid\"></a> `eventId` | `string` | Owning event entity. |\n| <a id=\"property-iscancelled\"></a> `isCancelled` | `boolean` | Whether the instance was cancelled. |\n| <a id=\"property-occurrencekey\"></a> `occurrenceKey` | `string` | Stable key within the event. |\n| <a id=\"property-recurrenceid\"></a> `recurrenceId?` | `string` \\| `null` | Provider recurrence identifier, when applicable. |\n| <a id=\"property-time\"></a> `time` | [`EventTime`](EventTime.md) | Instance time. |\n\n\n<!-- generated/storage/types.gen/type-aliases/EventTime.md -->\n# Type Alias: EventTime\n\n> **EventTime** = \\{ `endsAt`: `string`; `kind`: `\"timed\"`; `startsAt`: `string`; `timeZone?`: `string` \\| `null`; \\} \\| \\{ `endDate`: `string`; `kind`: `\"allDay\"`; `startDate`: `string`; \\}\n\nThe mutually exclusive time shape of a calendar event.\n\nFields are renamed per variant rather than with `rename_all_fields`\nbecause utoipa only honors variant-level serde renames when it\nderives the OpenAPI schema.\n\n## Union Members\n\n### Type Literal\n\n\\{ `endsAt`: `string`; `kind`: `\"timed\"`; `startsAt`: `string`; `timeZone?`: `string` \\| `null`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `endsAt` | `string` | Exclusive end instant; equal to the start for an imported point event. |\n| `kind` | `\"timed\"` | - |\n| `startsAt` | `string` | Inclusive start instant. |\n| `timeZone?` | `string` \\| `null` | Original IANA time-zone identifier, when supplied. |\n\n***\n\n### Type Literal\n\n\\{ `endDate`: `string`; `kind`: `\"allDay\"`; `startDate`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `endDate` | `string` | Exclusive local end date. |\n| `kind` | `\"allDay\"` | - |\n| `startDate` | `string` | Inclusive local start date. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ListOccurrencesData.md -->\n# Type Alias: ListOccurrencesData\n\n> **ListOccurrencesData** = \\{ `body?`: `never`; `path?`: `never`; `query`: \\{ `cursor?`: `string`; `end`: `string`; `endDate?`: `string`; `limit?`: `number`; `start`: `string`; `startDate?`: `string`; \\}; `url`: `\"/calendar-events\"`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-body\"></a> `body?` | `never` | - |\n| <a id=\"property-path\"></a> `path?` | `never` | - |\n| <a id=\"property-query\"></a> `query` | \\{ `cursor?`: `string`; `end`: `string`; `endDate?`: `string`; `limit?`: `number`; `start`: `string`; `startDate?`: `string`; \\} | - |\n| `query.cursor?` | `string` | Opaque continuation cursor returned by the previous page. |\n| `query.end` | `string` | Exclusive UTC viewport end. |\n| `query.endDate?` | `string` | Exclusive local date boundary for all-day events. |\n| `query.limit?` | `number` | Maximum number of occurrences, from 1 through 2,000. |\n| `query.start` | `string` | Inclusive UTC viewport start. |\n| `query.startDate?` | `string` | Inclusive local date boundary for all-day events. |\n| <a id=\"property-url\"></a> `url` | `\"/calendar-events\"` | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/TeamCalendarCoverage.md -->\n# Type Alias: TeamCalendarCoverage\n\n> **TeamCalendarCoverage** = `\"ready\"` \\| `\"unavailable\"` \\| `\"hidden\"`\n\nWhether a member's calendar projection can establish availability.\n\n\n<!-- generated/storage/types.gen/type-aliases/TeamCalendarDetails.md -->\n# Type Alias: TeamCalendarDetails\n\n> **TeamCalendarDetails** = \\{ `attendees`: [`CalendarAttendee`](CalendarAttendee.md)[]; `calendarName`: `string`; `conferenceUrl?`: `string` \\| `null`; `description?`: `string` \\| `null`; `location?`: `string` \\| `null`; `organizerEmail?`: `string` \\| `null`; `organizerName?`: `string` \\| `null`; `title`: `string`; \\}\n\nSafe details from a single authorized source.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attendees\"></a> `attendees` | [`CalendarAttendee`](CalendarAttendee.md)[] | Attendees; self flags are relative to the requesting viewer. |\n| <a id=\"property-calendarname\"></a> `calendarName` | `string` | Source calendar name, shown only with details. |\n| <a id=\"property-conferenceurl\"></a> `conferenceUrl?` | `string` \\| `null` | Join URL, if supplied by this source. |\n| <a id=\"property-description\"></a> `description?` | `string` \\| `null` | Body, if supplied by this source. |\n| <a id=\"property-location\"></a> `location?` | `string` \\| `null` | Location, if supplied by this source. |\n| <a id=\"property-organizeremail\"></a> `organizerEmail?` | `string` \\| `null` | Organizer address from this source. |\n| <a id=\"property-organizername\"></a> `organizerName?` | `string` \\| `null` | Organizer name from this source. |\n| <a id=\"property-title\"></a> `title` | `string` | Display title. |\n\n\n<!-- generated/storage/types.gen/type-aliases/TeamCalendarSharing.md -->\n# Type Alias: TeamCalendarSharing\n\n> **TeamCalendarSharing** = `\"all\"` \\| `\"busy_only\"` \\| `\"none\"`\n\nWhat a user exposes through their team membership.\n\n\n<!-- src/entities/calendar/calendar/classes/Calendar.md -->\n# Class: Calendar\n\nA calendar visible to the requester across their connected inboxes: a\nfree-to-construct handle whose detail resolves from the caller's calendar\nlist. There is no fetch-by-id endpoint, so a bare [Calendar.byId](#byid)\nhandle loads its detail by listing the caller's calendars and matching on id.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`VisibleCalendar`](../../../../../generated/calendar/types.gen/type-aliases/VisibleCalendar.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-color\"></a> `color` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | Provider color, when set. | - |\n| <a id=\"property-emailaddress\"></a> `emailAddress` | `readonly` | () => `Promise`\\<`string`\\> | Connected inbox address that syncs this calendar. | - |\n| <a id=\"property-emaillink\"></a> `emailLink` | `readonly` | () => `Promise`\\<[`Link`](../../../email/link/classes/Link.md)\\> | The connected inbox (email link) that syncs this calendar. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-isprimary\"></a> `isPrimary` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether this is its account's primary calendar. | - |\n| <a id=\"property-issubscription\"></a> `isSubscription` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether this is a subscribed system calendar (holidays, birthdays). | - |\n| <a id=\"property-iswritable\"></a> `isWritable` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether the grant can create and modify events on this calendar. | - |\n| <a id=\"property-name\"></a> `name` | `readonly` | () => `Promise`\\<`string`\\> | Provider display name. | - |\n| <a id=\"property-syncerror\"></a> `syncError` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | A persistent per-calendar sync failure, surfaced for settings badges. | - |\n\n## Methods\n\n### setContributesToAvailability()\n\n> **setContributesToAvailability**(`contributesToAvailability`): `Promise`\\<`void`\\>\n\nSet whether this calendar contributes to the caller's availability.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `contributesToAvailability` | `boolean` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`VisibleCalendar`](../../../../../generated/calendar/types.gen/type-aliases/VisibleCalendar.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`VisibleCalendar`](../../../../../generated/calendar/types.gen/type-aliases/VisibleCalendar.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`VisibleCalendar`](../../../../../generated/calendar/types.gen/type-aliases/VisibleCalendar.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `Calendar`\n\nA handle to a calendar by id. Detail loads on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`Calendar`\n\n***\n\n### list()\n\n> `static` **list**(`client`): `Promise`\\<`Calendar`[]\\>\n\nThe caller's visible calendars, primaries and writable first.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`Promise`\\<`Calendar`[]\\>\n\n\n<!-- src/entities/calendar/event/classes/CalendarEvent.md -->\n# Class: CalendarEvent\n\nA Macro calendar event: a handle exposing the event's synced fields and the\nmutations that act on it ([CalendarEvent.update](#update),\n[CalendarEvent.delete](#delete), [CalendarEvent.rsvp](#rsvp)).\n\nThe calendar service has no fetch-by-id endpoint, so a handle reads its\nfields only when seeded with a record — as returned by\n[CalendarEvent.update](#update), [CalendarEvent.rsvp](#rsvp), or\n`calendar.createEvent`. A bare [CalendarEvent.byId](#byid) handle can drive\nmutations, but reading a field on it throws.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`CalendarEvent`](../../../../../generated/calendar/types.gen/type-aliases/CalendarEvent.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-attendees\"></a> `attendees` | `readonly` | () => `Promise`\\<[`CalendarAttendee`](../../../../../generated/calendar/types.gen/type-aliases/CalendarAttendee.md)[]\\> | Attendees on the canonical copy. | - |\n| <a id=\"property-calendar\"></a> `calendar` | `readonly` | () => `Promise`\\<[`Calendar`](../../calendar/classes/Calendar.md) \\| `undefined`\\> | The calendar the canonical source belongs to, when known. | - |\n| <a id=\"property-description\"></a> `description` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | Optional event body. | - |\n| <a id=\"property-guestpolicy\"></a> `guestPolicy` | `readonly` | () => `Promise`\\<[`GuestPolicy`](../../../../../generated/calendar/types.gen/type-aliases/GuestPolicy.md)\\> | What the organizer lets guests do: modify, invite others, see the guest list. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-isreadonly\"></a> `isReadOnly` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether the canonical source's calendar prohibits editing. | - |\n| <a id=\"property-location\"></a> `location` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | Optional physical or virtual location label. | - |\n| <a id=\"property-recurrencelines\"></a> `recurrenceLines` | `readonly` | () => `Promise`\\<`string`[]\\> | Raw RFC 5545 recurrence properties (`RRULE`, `RDATE`, `EXDATE`). | - |\n| <a id=\"property-status\"></a> `status` | `readonly` | () => `Promise`\\<[`EventStatus`](../../../../../generated/calendar/types.gen/type-aliases/EventStatus.md)\\> | Event status. | - |\n| <a id=\"property-time\"></a> `time` | `readonly` | () => `Promise`\\<[`EventTime`](../../../../../generated/calendar/types.gen/type-aliases/EventTime.md)\\> | Timed or all-day shape. | - |\n| <a id=\"property-title\"></a> `title` | `readonly` | () => `Promise`\\<`string`\\> | Display title. | - |\n| <a id=\"property-transparency\"></a> `transparency` | `readonly` | () => `Promise`\\<[`EventTransparency`](../../../../../generated/calendar/types.gen/type-aliases/EventTransparency.md)\\> | Availability behavior. | - |\n| <a id=\"property-viewercan\"></a> `viewerCan` | `readonly` | () => `Promise`\\<[`ViewerCapabilities`](../../../../../generated/calendar/types.gen/type-aliases/ViewerCapabilities.md)\\> | What the connected account may do with this event under its guest policy. | - |\n\n## Methods\n\n### addToCalendar()\n\n> **addToCalendar**(`options?`): `Promise`\\<`CalendarEvent`\\>\n\nAdd a snapshot of an event shared with one of the requester's\nchannels to one of their Google calendars, and return a handle to the\nsynced snapshot. The snapshot keeps the meeting's iCalendar UID and\norganizer, lists only the requester as a guest, and carries no join link;\nnobody is notified, and answers or guests on it never reach the meeting.\nRefused with `already_on_calendar` when the meeting is already on one of\ntheir calendars, and with `copy_refused` when Google will not import it.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options?` | \\{ `calendar?`: [`Calendar`](../../calendar/classes/Calendar.md); \\} |\n| `options.calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) |\n\n#### Returns\n\n`Promise`\\<`CalendarEvent`\\>\n\n***\n\n### delete()\n\n> **delete**(`options?`): `Promise`\\<`void`\\>\n\nDelete the event (or a scoped part of a recurring series) at its provider.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options?` | [`DeleteEventOptions`](../interfaces/DeleteEventOptions.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### ics()\n\n> **ics**(): `Promise`\\<`string`\\>\n\nThe event as an iCalendar (`.ics`) document: its series, title,\ndescription, location and organizer, never its guests or join link.\nAvailable for the requester's own events and ones shared with a channel\nthey belong to.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### inviteGuests()\n\n> **inviteGuests**(`options`): `Promise`\\<`CalendarEvent`\\>\n\nAdd guests without touching anyone already invited, and return a handle\nto the synced record. The organizer may, and so may a guest the organizer\nlets invite others (see [CalendarEvent.viewerCan](#property-viewercan)); Google emails\nthe new guests.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`InviteGuestsOptions`](../interfaces/InviteGuestsOptions.md) |\n\n#### Returns\n\n`Promise`\\<`CalendarEvent`\\>\n\n***\n\n### linkNote()\n\n> **linkNote**(`document`, `occurrence`, `options?`): `Promise`\\<[`CalendarNote`](../../note/classes/CalendarNote.md)\\>\n\nLink a markdown document you own. Meeting-detail viewers gain read access;\nan optional team gains read access too. Editing and other sharing are preserved.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `document` | [`Document`](../../../documents/document/classes/Document.md) |\n| `occurrence` | [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md) |\n| `options?` | \\{ `team?`: [`Team`](../../../teams/team/classes/Team.md); \\} |\n| `options.team?` | [`Team`](../../../teams/team/classes/Team.md) |\n\n#### Returns\n\n`Promise`\\<[`CalendarNote`](../../note/classes/CalendarNote.md)\\>\n\n***\n\n### notes()\n\n> **notes**(`occurrence`): `Promise`\\<[`CalendarNote`](../../note/classes/CalendarNote.md)[]\\>\n\nNotes linked to a specific occurrence returned by `calendar.occurrences()`.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `occurrence` | [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md) |\n\n#### Returns\n\n`Promise`\\<[`CalendarNote`](../../note/classes/CalendarNote.md)[]\\>\n\n***\n\n### prepareReplacement()\n\n> **prepareReplacement**(`options`): `Promise`\\<[`CalendarReplacement`](../../replacement/classes/CalendarReplacement.md)\\>\n\nPreview an organizer replacement without cancelling or sending invitations.\nReview replacement.status() before explicitly calling replacement.confirm().\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | \\{ `calendar?`: [`Calendar`](../../calendar/classes/Calendar.md); `recurrenceId?`: `string`; `removeConference`: `boolean`; \\} |\n| `options.calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) |\n| `options.recurrenceId?` | `string` |\n| `options.removeConference` | `boolean` |\n\n#### Returns\n\n`Promise`\\<[`CalendarReplacement`](../../replacement/classes/CalendarReplacement.md)\\>\n\n***\n\n### providerUrl()\n\n> **providerUrl**(`options?`): `Promise`\\<`string` \\| `undefined`\\>\n\nOpen this calendar copy in its provider for actions unavailable through its API.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options?` | \\{ `calendar?`: [`Calendar`](../../calendar/classes/Calendar.md); `recurrenceId?`: `string`; \\} |\n| `options.calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) |\n| `options.recurrenceId?` | `string` |\n\n#### Returns\n\n`Promise`\\<`string` \\| `undefined`\\>\n\n***\n\n### record()\n\n> **record**(): `Promise`\\<[`CalendarEvent`](../../../../../generated/calendar/types.gen/type-aliases/CalendarEvent.md)\\>\n\nThe full synced event record. Available on a seeded handle (from create /\nupdate / rsvp); a bare `byId` handle throws (no fetch-by-id endpoint).\n\n#### Returns\n\n`Promise`\\<[`CalendarEvent`](../../../../../generated/calendar/types.gen/type-aliases/CalendarEvent.md)\\>\n\n***\n\n### rsvp()\n\n> **rsvp**(`options`): `Promise`\\<`CalendarEvent`\\>\n\nRecord the requester's RSVP and return a handle to the synced record.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`RsvpEventOptions`](../interfaces/RsvpEventOptions.md) |\n\n#### Returns\n\n`Promise`\\<`CalendarEvent`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`CalendarEvent`](../../../../../generated/calendar/types.gen/type-aliases/CalendarEvent.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`CalendarEvent`](../../../../../generated/calendar/types.gen/type-aliases/CalendarEvent.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`CalendarEvent`](../../../../../generated/calendar/types.gen/type-aliases/CalendarEvent.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### update()\n\n> **update**(`options`): `Promise`\\<`CalendarEvent`\\>\n\nUpdate the event and return a handle to its synced record.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`UpdateEventOptions`](../interfaces/UpdateEventOptions.md) |\n\n#### Returns\n\n`Promise`\\<`CalendarEvent`\\>\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `CalendarEvent`\n\nA handle to a calendar event by id, for driving mutations. Reading a\nfield on it throws (there is no fetch-by-id endpoint).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`CalendarEvent`\n\n***\n\n### fromRecord()\n\n> `static` **fromRecord**(`client`, `record`): `CalendarEvent`\n\nA handle seeded with a synced event record; reads resolve without a fetch.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `record` | [`CalendarEvent`](../../../../../generated/calendar/types.gen/type-aliases/CalendarEvent.md) |\n\n#### Returns\n\n`CalendarEvent`\n\n\n<!-- src/entities/calendar/event/interfaces/DeleteEventOptions.md -->\n# Interface: DeleteEventOptions\n\nHow a deletion is scoped across a recurring series.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-calendar\"></a> `calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) | Calendar whose copy of the event is deleted, for a multi-calendar event. Omit to delete the canonical copy. |\n| <a id=\"property-recurrenceid\"></a> `recurrenceId?` | `string` | Original-start key of the occurrence a scoped deletion targets. |\n| <a id=\"property-scope\"></a> `scope?` | [`CalendarDeletionScopeParam`](../../../../../generated/calendar/types.gen/type-aliases/CalendarDeletionScopeParam.md) | Deletion scope; defaults to the entire event or series. |\n\n\n<!-- src/entities/calendar/event/interfaces/InviteGuestsOptions.md -->\n# Interface: InviteGuestsOptions\n\nGuests to add and how much of a recurring series gains them.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-calendar\"></a> `calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) | Calendar whose copy of the event is written, for a multi-calendar event. Omit to write the canonical copy. |\n| <a id=\"property-guests\"></a> `guests` | [`CalendarGuestInputBody`](../../../../../generated/calendar/types.gen/type-aliases/CalendarGuestInputBody.md)[] | Guests to add; anyone already on the event is skipped. |\n| <a id=\"property-recurrenceid\"></a> `recurrenceId?` | `string` | Original-start key of the occurrence the guests are added to. |\n| <a id=\"property-scope\"></a> `scope?` | [`CalendarUpdateScopeParam`](../../../../../generated/calendar/types.gen/type-aliases/CalendarUpdateScopeParam.md) | How much of a recurring series gains the guests. Omit to let `recurrenceId` decide. |\n\n\n<!-- src/entities/calendar/event/interfaces/RsvpEventOptions.md -->\n# Interface: RsvpEventOptions\n\nThe RSVP to record and how it is scoped across a recurring series.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-calendar\"></a> `calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) | Calendar whose copy of the event is answered, for a multi-calendar event. Omit to answer on the canonical copy. |\n| <a id=\"property-recurrenceid\"></a> `recurrenceId?` | `string` | Original-start key of the occurrence the response targets. |\n| <a id=\"property-response\"></a> `response` | [`AttendeeResponseStatus`](../../../../../generated/calendar/types.gen/type-aliases/AttendeeResponseStatus.md) | The response to record for the connected account. |\n| <a id=\"property-scope\"></a> `scope?` | [`CalendarRsvpScopeParam`](../../../../../generated/calendar/types.gen/type-aliases/CalendarRsvpScopeParam.md) | How much of a recurring series the response covers. Omit to let `recurrenceId` decide. |\n\n\n<!-- src/entities/calendar/event/interfaces/UpdateEventOptions.md -->\n# Interface: UpdateEventOptions\n\nFields to change on an event; omitted fields are left untouched.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attendees\"></a> `attendees?` | [`CalendarAttendeeInputBody`](../../../../../generated/calendar/types.gen/type-aliases/CalendarAttendeeInputBody.md)[] | Replacement attendee list. |\n| <a id=\"property-calendar\"></a> `calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) | Calendar whose copy of the event is patched, for a multi-calendar event. Omit to patch the canonical copy. |\n| <a id=\"property-conference\"></a> `conference?` | [`ConferenceChange`](../../../../../generated/calendar/types.gen/type-aliases/ConferenceChange.md) | Provider conference change; omit to retain it. Outlook removal requires a separately confirmed replacement via prepareReplacement(). |\n| <a id=\"property-description\"></a> `description?` | `string` | Replacement description; an empty string clears it. |\n| <a id=\"property-guestpolicy\"></a> `guestPolicy?` | [`GuestPolicy`](../../../../../generated/calendar/types.gen/type-aliases/GuestPolicy.md) | Replacement guest policy; only the organizer of a Google event may change it (`viewerCan.setGuestPolicy`). It applies to the whole series, so an update scoped to one occurrence (`scope: 'this_event'`, or a `recurrenceId`) that changes it is rejected; use scope `'all'`. |\n| <a id=\"property-location\"></a> `location?` | `string` | Replacement location; an empty string clears it. |\n| <a id=\"property-outofoffice\"></a> `outOfOffice?` | [`OutOfOfficeProperties`](../../../../../generated/calendar/types.gen/type-aliases/OutOfOfficeProperties.md) | Replacement out-of-office properties, applied only to an event that is already out-of-office. |\n| <a id=\"property-recurrenceid\"></a> `recurrenceId?` | `string` | Original-start key of the occurrence the update targets. |\n| <a id=\"property-recurrencelines\"></a> `recurrenceLines?` | `string`[] | Replacement recurrence properties; an empty list clears them. |\n| <a id=\"property-reminders\"></a> `reminders?` | [`EventReminders`](../../../../../generated/calendar/types.gen/type-aliases/EventReminders.md) | Replacement reminder configuration. |\n| <a id=\"property-scope\"></a> `scope?` | [`CalendarUpdateScopeParam`](../../../../../generated/calendar/types.gen/type-aliases/CalendarUpdateScopeParam.md) | How much of a recurring series the update covers. Omit to let `recurrenceId` decide. |\n| <a id=\"property-time\"></a> `time?` | [`EventTime`](../../../../../generated/calendar/types.gen/type-aliases/EventTime.md) | Replacement time. |\n| <a id=\"property-title\"></a> `title?` | `string` | Replacement title; an empty string clears it. |\n| <a id=\"property-transparency\"></a> `transparency?` | [`EventTransparency`](../../../../../generated/calendar/types.gen/type-aliases/EventTransparency.md) | Replacement availability behavior. |\n| <a id=\"property-visibility\"></a> `visibility?` | [`EventVisibility`](../../../../../generated/calendar/types.gen/type-aliases/EventVisibility.md) | Replacement visibility. |\n\n\n<!-- src/entities/calendar/namespace/classes/CalendarNamespace.md -->\n# Class: CalendarNamespace\n\nThe calendar surface: the caller's visible calendars, event creation, and\nhandles to individual events and calendars. Backed by calendar_service (the\nSDK reaches it on the gateway's `/calendar` route).\n\n## Constructors\n\n### Constructor\n\n> **new CalendarNamespace**(`client`): `CalendarNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`CalendarNamespace`\n\n## Methods\n\n### availabilityCalendars()\n\n> **availabilityCalendars**(): `Promise`\\<\\{ `calendar`: [`Calendar`](../../calendar/classes/Calendar.md); `contributesToAvailability`: `boolean`; `isPrimary`: `boolean`; `name`: `string`; \\}[]\\>\n\nCalendar availability settings, each referring to a typed calendar.\n\n#### Returns\n\n`Promise`\\<\\{ `calendar`: [`Calendar`](../../calendar/classes/Calendar.md); `contributesToAvailability`: `boolean`; `isPrimary`: `boolean`; `name`: `string`; \\}[]\\>\n\n***\n\n### calendar()\n\n> **calendar**(`id`): [`Calendar`](../../calendar/classes/Calendar.md)\n\nA handle to a calendar by id. Detail loads on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Calendar`](../../calendar/classes/Calendar.md)\n\n***\n\n### calendars()\n\n> **calendars**(): `Promise`\\<[`Calendar`](../../calendar/classes/Calendar.md)[]\\>\n\nThe caller's visible calendars, primaries and writable first.\n\n#### Returns\n\n`Promise`\\<[`Calendar`](../../calendar/classes/Calendar.md)[]\\>\n\n***\n\n### createEvent()\n\n> **createEvent**(`options`): `Promise`\\<[`CalendarEvent`](../../event/classes/CalendarEvent.md)\\>\n\nCreate a calendar event and return a handle to its synced record.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`CreateEventOptions`](../interfaces/CreateEventOptions.md) |\n\n#### Returns\n\n`Promise`\\<[`CalendarEvent`](../../event/classes/CalendarEvent.md)\\>\n\n***\n\n### event()\n\n> **event**(`id`): [`CalendarEvent`](../../event/classes/CalendarEvent.md)\n\nA handle to a calendar event by id, for driving mutations.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`CalendarEvent`](../../event/classes/CalendarEvent.md)\n\n***\n\n### noteDocuments()\n\n> **noteDocuments**(`query?`): `Promise`\\<\\{ `documents`: \\{ `document`: [`Document`](../../../documents/document/classes/Document.md); `name`: `string`; \\}[]; `teams`: \\{ `name`: `string`; `team`: [`Team`](../../../teams/team/classes/Team.md); \\}[]; \\}\\>\n\nFind up to 30 owned markdown documents for meeting notes, plus available extra team audiences.\n\n#### Parameters\n\n| Parameter | Type | Default value |\n| ------ | ------ | ------ |\n| `query?` | `string` | `''` |\n\n#### Returns\n\n`Promise`\\<\\{ `documents`: \\{ `document`: [`Document`](../../../documents/document/classes/Document.md); `name`: `string`; \\}[]; `teams`: \\{ `name`: `string`; `team`: [`Team`](../../../teams/team/classes/Team.md); \\}[]; \\}\\>\n\n***\n\n### occurrences()\n\n> **occurrences**(`options`): `AsyncGenerator`\\<\\{ `event`: [`CalendarEvent`](../../event/classes/CalendarEvent.md); `occurrence`: [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md); \\}, `any`, `any`\\>\n\nCalendar occurrences in a viewport, automatically paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | `Omit`\\<[`ListOccurrencesData`](../../../../../generated/storage/types.gen/type-aliases/ListOccurrencesData.md)\\[`\"query\"`\\], `\"cursor\"`\\> |\n\n#### Returns\n\n`AsyncGenerator`\\<\\{ `event`: [`CalendarEvent`](../../event/classes/CalendarEvent.md); `occurrence`: [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md); \\}, `any`, `any`\\>\n\n***\n\n### replacement()\n\n> **replacement**(`operationId`): [`CalendarReplacement`](../../replacement/classes/CalendarReplacement.md)\n\nRecover a saved replacement, including after its original event was retired.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `operationId` | `string` |\n\n#### Returns\n\n[`CalendarReplacement`](../../replacement/classes/CalendarReplacement.md)\n\n***\n\n### setTeamSharing()\n\n> **setTeamSharing**(`sharing`): `Promise`\\<[`TeamCalendarSharing`](../../../../../generated/calendar/types.gen/type-aliases/TeamCalendarSharing.md)\\>\n\nReplace the team calendar sharing preference.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `sharing` | [`TeamCalendarSharing`](../../../../../generated/calendar/types.gen/type-aliases/TeamCalendarSharing.md) |\n\n#### Returns\n\n`Promise`\\<[`TeamCalendarSharing`](../../../../../generated/calendar/types.gen/type-aliases/TeamCalendarSharing.md)\\>\n\n***\n\n### teamOutOfOffice()\n\n> **teamOutOfOffice**(`options`): `Promise`\\<\\{ `hasMore`: `boolean`; `items`: \\{ `event`: [`CalendarEvent`](../../event/classes/CalendarEvent.md); `occurrenceKey`: `string`; `owner`: [`User`](../../../users/user/classes/User.md); `time`: [`EventTime`](../../../../../generated/storage/types.gen/type-aliases/EventTime.md); `title`: `string` \\| `undefined`; \\}[]; \\}\\>\n\nTeammates' out-of-office occurrences in a bounded viewport. Check hasMore for truncation.\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `options` | \\{ `end`: `string`; `endDate?`: `string`; `limit?`: `number`; `start`: `string`; `startDate?`: `string`; \\} | - |\n| `options.end` | `string` | Exclusive UTC viewport end. |\n| `options.endDate?` | `string` | Exclusive local date boundary for all-day events. |\n| `options.limit?` | `number` | Maximum number of occurrences, from 1 through 2,000. |\n| `options.start` | `string` | Inclusive UTC viewport start. |\n| `options.startDate?` | `string` | Inclusive local date boundary for all-day events. |\n\n#### Returns\n\n`Promise`\\<\\{ `hasMore`: `boolean`; `items`: \\{ `event`: [`CalendarEvent`](../../event/classes/CalendarEvent.md); `occurrenceKey`: `string`; `owner`: [`User`](../../../users/user/classes/User.md); `time`: [`EventTime`](../../../../../generated/storage/types.gen/type-aliases/EventTime.md); `title`: `string` \\| `undefined`; \\}[]; \\}\\>\n\n***\n\n### teamPage()\n\n> **teamPage**(`options`): `Promise`\\<\\{ `items`: (\\{ `contributesToAvailability`: `boolean`; `id`: `string`; `kind`: `\"busy\"`; `owner`: [`User`](../../../users/user/classes/User.md); `time`: [`EventTime`](../../../../../generated/storage/types.gen/type-aliases/EventTime.md); \\} \\| \\{ `contributesToAvailability`: `boolean`; `details`: [`TeamCalendarDetails`](../../../../../generated/storage/types.gen/type-aliases/TeamCalendarDetails.md); `id`: `string`; `kind`: `\"details\"`; `owner`: [`User`](../../../users/user/classes/User.md); `time`: [`EventTime`](../../../../../generated/storage/types.gen/type-aliases/EventTime.md); \\})[]; `members`: \\{ `coverage`: [`TeamCalendarCoverage`](../../../../../generated/storage/types.gen/type-aliases/TeamCalendarCoverage.md); `sharing`: [`TeamCalendarSharing`](../../../../../generated/storage/types.gen/type-aliases/TeamCalendarSharing.md); `user`: [`User`](../../../users/user/classes/User.md); \\}[]; `nextCursor`: `string` \\| `undefined`; \\}\\>\n\nA page of team availability, including its roster and continuation cursor.\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `options` | \\{ `cursor?`: `string` \\| `null`; `end`: `string`; `limit?`: `number` \\| `null`; `start`: `string`; \\} | - |\n| `options.cursor?` | `string` \\| `null` | Continuation returned by the preceding page. |\n| `options.end` | `string` | Exclusive instant. |\n| `options.limit?` | `number` \\| `null` | Maximum source occurrences, at most 2,000. Zero returns the roster only. |\n| `options.start` | `string` | Inclusive instant. |\n\n#### Returns\n\n`Promise`\\<\\{ `items`: (\\{ `contributesToAvailability`: `boolean`; `id`: `string`; `kind`: `\"busy\"`; `owner`: [`User`](../../../users/user/classes/User.md); `time`: [`EventTime`](../../../../../generated/storage/types.gen/type-aliases/EventTime.md); \\} \\| \\{ `contributesToAvailability`: `boolean`; `details`: [`TeamCalendarDetails`](../../../../../generated/storage/types.gen/type-aliases/TeamCalendarDetails.md); `id`: `string`; `kind`: `\"details\"`; `owner`: [`User`](../../../users/user/classes/User.md); `time`: [`EventTime`](../../../../../generated/storage/types.gen/type-aliases/EventTime.md); \\})[]; `members`: \\{ `coverage`: [`TeamCalendarCoverage`](../../../../../generated/storage/types.gen/type-aliases/TeamCalendarCoverage.md); `sharing`: [`TeamCalendarSharing`](../../../../../generated/storage/types.gen/type-aliases/TeamCalendarSharing.md); `user`: [`User`](../../../users/user/classes/User.md); \\}[]; `nextCursor`: `string` \\| `undefined`; \\}\\>\n\n***\n\n### teamSharing()\n\n> **teamSharing**(): `Promise`\\<[`TeamCalendarSharing`](../../../../../generated/calendar/types.gen/type-aliases/TeamCalendarSharing.md)\\>\n\nCurrent sharing preference for the team calendar.\n\n#### Returns\n\n`Promise`\\<[`TeamCalendarSharing`](../../../../../generated/calendar/types.gen/type-aliases/TeamCalendarSharing.md)\\>\n\n\n<!-- src/entities/calendar/namespace/interfaces/CreateEventOptions.md -->\n# Interface: CreateEventOptions\n\nFields for a new calendar event.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attendees\"></a> `attendees?` | [`CalendarAttendeeInputBody`](../../../../../generated/calendar/types.gen/type-aliases/CalendarAttendeeInputBody.md)[] | Invited attendees. |\n| <a id=\"property-calendar\"></a> `calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) | Exact calendar to create the event on; takes precedence over the inbox default. |\n| <a id=\"property-conference\"></a> `conference?` | [`ConferenceChange`](../../../../../generated/calendar/types.gen/type-aliases/ConferenceChange.md) | Conference to attach; omit to create the event without one. |\n| <a id=\"property-description\"></a> `description?` | `string` | Optional event body. |\n| <a id=\"property-emaillink\"></a> `emailLink?` | [`Link`](../../../email/link/classes/Link.md) | Connected inbox whose primary calendar receives the event; defaults to the requester's primary inbox. |\n| <a id=\"property-guestpolicy\"></a> `guestPolicy?` | [`GuestPolicy`](../../../../../generated/calendar/types.gen/type-aliases/GuestPolicy.md) | What guests may do; omit for Google's defaults. Google calendars only. |\n| <a id=\"property-location\"></a> `location?` | `string` | Optional location label. |\n| <a id=\"property-macrocall\"></a> `macroCall?` | `boolean` | Mint a Macro call with the event; its join link lands in the description and location. Cannot be combined with `conference`. |\n| <a id=\"property-outofoffice\"></a> `outOfOffice?` | [`OutOfOfficeProperties`](../../../../../generated/calendar/types.gen/type-aliases/OutOfOfficeProperties.md) | Out-of-office properties; present to create an out-of-office event. |\n| <a id=\"property-recurrencelines\"></a> `recurrenceLines?` | `string`[] | Raw RFC 5545 recurrence properties (`RRULE`, `RDATE`, `EXDATE`). |\n| <a id=\"property-reminders\"></a> `reminders?` | [`EventReminders`](../../../../../generated/calendar/types.gen/type-aliases/EventReminders.md) | Reminder configuration; omit to keep the calendar defaults. |\n| <a id=\"property-time\"></a> `time` | [`EventTime`](../../../../../generated/calendar/types.gen/type-aliases/EventTime.md) | Timed or all-day shape. |\n| <a id=\"property-title\"></a> `title` | `string` | Display title. |\n| <a id=\"property-transparency\"></a> `transparency?` | [`EventTransparency`](../../../../../generated/calendar/types.gen/type-aliases/EventTransparency.md) | Availability behavior. |\n| <a id=\"property-visibility\"></a> `visibility?` | [`EventVisibility`](../../../../../generated/calendar/types.gen/type-aliases/EventVisibility.md) | Event visibility. |\n\n\n<!-- src/entities/calendar/note/classes/CalendarNote.md -->\n# Class: CalendarNote\n\nA markdown document linked to one meeting occurrence, with view-only access.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`MeetingNote`](../../../../../generated/calendar/types.gen/type-aliases/MeetingNote.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-canmanage\"></a> `canManage` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether the caller may change this link's sharing. | - |\n| <a id=\"property-document\"></a> `document` | `readonly` | () => `Promise`\\<[`Document`](../../../documents/document/classes/Document.md)\\> | The original markdown document; unlinking never deletes it. | - |\n| <a id=\"property-event\"></a> `event` | `readonly` | [`CalendarEvent`](../../event/classes/CalendarEvent.md) | - | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-name\"></a> `name` | `readonly` | () => `Promise`\\<`string`\\> | Current document name. | - |\n| <a id=\"property-occurrence\"></a> `occurrence` | `readonly` | `Pick`\\<[`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md), `\"eventId\"` \\| `\"occurrenceKey\"`\\> | - | - |\n| <a id=\"property-team\"></a> `team` | `readonly` | () => `Promise`\\<[`Team`](../../../teams/team/classes/Team.md) \\| `undefined`\\> | Optional extra team audience. Meeting-detail viewers already have view access. | - |\n\n## Methods\n\n### setTeam()\n\n> **setTeam**(`team?`): `Promise`\\<`void`\\>\n\nChange the extra team view grant; omit the team to remove it. Requires document ownership.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `team?` | [`Team`](../../../teams/team/classes/Team.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`MeetingNote`](../../../../../generated/calendar/types.gen/type-aliases/MeetingNote.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`MeetingNote`](../../../../../generated/calendar/types.gen/type-aliases/MeetingNote.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`MeetingNote`](../../../../../generated/calendar/types.gen/type-aliases/MeetingNote.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### unlink()\n\n> **unlink**(): `Promise`\\<`void`\\>\n\nRemove this occurrence's link and view grants, preserving the document and other sharing.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### forDocument()\n\n> `static` **forDocument**(`client`, `event`, `occurrence`, `document`): `CalendarNote`\n\nConstruct a handle for a document already linked to this occurrence.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `event` | [`CalendarEvent`](../../event/classes/CalendarEvent.md) |\n| `occurrence` | [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md) |\n| `document` | [`Document`](../../../documents/document/classes/Document.md) |\n\n#### Returns\n\n`CalendarNote`\n\n***\n\n### fromDocumentLink()\n\n> `static` **fromDocumentLink**(`client`, `document`, `link`): `CalendarNote`\n\nSeed an owner-visible link that can be revoked even if the meeting is unavailable.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `document` | [`Document`](../../../documents/document/classes/Document.md) |\n| `link` | [`DocumentNoteLink`](../../../../../generated/calendar/types.gen/type-aliases/DocumentNoteLink.md) |\n\n#### Returns\n\n`CalendarNote`\n\n***\n\n### fromRecord()\n\n> `static` **fromRecord**(`client`, `event`, `occurrence`, `record`): `CalendarNote`\n\nSeed a handle with a record returned by the meeting-note API.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `event` | [`CalendarEvent`](../../event/classes/CalendarEvent.md) |\n| `occurrence` | [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md) |\n| `record` | [`MeetingNote`](../../../../../generated/calendar/types.gen/type-aliases/MeetingNote.md) |\n\n#### Returns\n\n`CalendarNote`\n\n\n<!-- src/entities/calendar/replacement/classes/CalendarReplacement.md -->\n# Class: CalendarReplacement\n\nDurable organizer replacement, recoverable even after the original event is retired.\n\n## Constructors\n\n### Constructor\n\n> **new CalendarReplacement**(`client`, `id`): `CalendarReplacement`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`CalendarReplacement`\n\n## Properties\n\n| Property | Modifier | Type |\n| ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `readonly` | `string` |\n\n## Methods\n\n### confirm()\n\n> **confirm**(): `Promise`\\<[`CalendarReplacementView`](../../../../../generated/calendar/types.gen/type-aliases/CalendarReplacementView.md)\\>\n\nConfirm the reviewed cancellation and reinvitation, or resume that same operation.\nPresent the preview and obtain the organizer's confirmation before the first call.\n\n#### Returns\n\n`Promise`\\<[`CalendarReplacementView`](../../../../../generated/calendar/types.gen/type-aliases/CalendarReplacementView.md)\\>\n\n***\n\n### discard()\n\n> **discard**(): `Promise`\\<`void`\\>\n\nDiscard an unconfirmed preview. Confirmed operations must be recovered, not discarded.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### status()\n\n> **status**(): `Promise`\\<[`CalendarReplacementView`](../../../../../generated/calendar/types.gen/type-aliases/CalendarReplacementView.md)\\>\n\nRead progress without initiating provider writes.\n\n#### Returns\n\n`Promise`\\<[`CalendarReplacementView`](../../../../../generated/calendar/types.gen/type-aliases/CalendarReplacementView.md)\\>\n"+ "documentation": "# Macro SDK: calendar\n\nGenerated by TypeDoc. Paths below refer to the canonical Markdown hierarchy. Other entity handles are documented in their named section; request core for shared SDK helpers.\n\n<!-- generated/calendar/types.gen/type-aliases/AttendeeResponseStatus.md -->\n# Type Alias: AttendeeResponseStatus\n\n> **AttendeeResponseStatus** = `\"needs_action\"` \\| `\"accepted\"` \\| `\"declined\"` \\| `\"tentative\"`\n\nRSVP state for an attendee.\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarAttendee.md -->\n# Type Alias: CalendarAttendee\n\n> **CalendarAttendee** = \\{ `comment?`: `string` \\| `null`; `displayName?`: `string` \\| `null`; `email`: `string`; `isOptional`: `boolean`; `isOrganizer`: `boolean`; `isSelf`: `boolean`; `responseStatus`: [`AttendeeResponseStatus`](AttendeeResponseStatus.md); \\}\n\nAn attendee on a calendar event.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-comment\"></a> `comment?` | `string` \\| `null` | Optional attendee comment. |\n| <a id=\"property-displayname\"></a> `displayName?` | `string` \\| `null` | Provider display name. |\n| <a id=\"property-email\"></a> `email` | `string` | Normalized email address. |\n| <a id=\"property-isoptional\"></a> `isOptional` | `boolean` | Whether attendance is optional. |\n| <a id=\"property-isorganizer\"></a> `isOrganizer` | `boolean` | Whether this attendee is the organizer. |\n| <a id=\"property-isself\"></a> `isSelf` | `boolean` | Whether this attendee is one of the viewing requester's inboxes. |\n| <a id=\"property-responsestatus\"></a> `responseStatus` | [`AttendeeResponseStatus`](AttendeeResponseStatus.md) | RSVP state. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarAttendeeInputBody.md -->\n# Type Alias: CalendarAttendeeInputBody\n\n> **CalendarAttendeeInputBody** = \\{ `email`: `string`; `isOptional?`: `boolean`; \\}\n\nAn attendee supplied to a calendar mutation.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-email\"></a> `email` | `string` | Attendee email address. |\n| <a id=\"property-isoptional\"></a> `isOptional?` | `boolean` | Whether attendance is optional. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarCapabilities.md -->\n# Type Alias: CalendarCapabilities\n\n> **CalendarCapabilities** = \\{ `autoDecline`: `boolean`; `conferenceProvider?`: `null` \\| [`ConferenceProvider`](ConferenceProvider.md); `customRecurrence`: `boolean`; `emailReminders`: `boolean`; `guestPolicy`: `boolean`; `removeConference`: `boolean`; `resetRsvp`: `boolean`; \\}\n\nActual provider capabilities used by calendar editors.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-autodecline\"></a> `autoDecline` | `boolean` | Whether event-level automatic invitation declines are supported. |\n| <a id=\"property-conferenceprovider\"></a> `conferenceProvider?` | `null` \\| [`ConferenceProvider`](ConferenceProvider.md) | - |\n| <a id=\"property-customrecurrence\"></a> `customRecurrence` | `boolean` | Whether arbitrary RFC 5545 recurrence properties can be written. |\n| <a id=\"property-emailreminders\"></a> `emailReminders` | `boolean` | Whether email reminders are delivered by the provider or Macro. |\n| <a id=\"property-guestpolicy\"></a> `guestPolicy` | `boolean` | Whether the organizer can set what guests may do. |\n| <a id=\"property-removeconference\"></a> `removeConference` | `boolean` | Whether an existing conference can be detached. |\n| <a id=\"property-resetrsvp\"></a> `resetRsvp` | `boolean` | Whether an attendee can reset their RSVP to unanswered. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarDeletionScopeParam.md -->\n# Type Alias: CalendarDeletionScopeParam\n\n> **CalendarDeletionScopeParam** = `\"all\"` \\| `\"this_event\"` \\| `\"this_and_following\"`\n\nHow much of a recurring series a deletion removes.\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarEvent.md -->\n# Type Alias: CalendarEvent\n\n> **CalendarEvent** = \\{ `attendees`: [`CalendarAttendee`](CalendarAttendee.md)[]; `calendarId?`: `string` \\| `null`; `conferenceProvider?`: `null` \\| [`ConferenceProvider`](ConferenceProvider.md); `conferenceUrl?`: `string` \\| `null`; `createdAt`: `string`; `creatorEmail?`: `string` \\| `null`; `creatorName?`: `string` \\| `null`; `description?`: `string` \\| `null`; `eventType?`: [`EventType`](EventType.md); `guestPolicy`: [`GuestPolicy`](GuestPolicy.md); `icalUid`: `string`; `id`: `string`; `isReadOnly`: `boolean`; `isSnapshot`: `boolean`; `location?`: `string` \\| `null`; `organizerEmail?`: `string` \\| `null`; `organizerName?`: `string` \\| `null`; `ownerId`: `string`; `recurrenceLines`: `string`[]; `reminders?`: [`EventReminders`](EventReminders.md); `sequence`: `number`; `sources?`: [`CalendarEventSourceContent`](CalendarEventSourceContent.md)[]; `status`: [`EventStatus`](EventStatus.md); `time`: [`EventTime`](EventTime.md); `title`: `string`; `transparency`: [`EventTransparency`](EventTransparency.md); `updatedAt`: `string`; `viewerCan`: [`ViewerCapabilities`](ViewerCapabilities.md); `visibility`: [`EventVisibility`](EventVisibility.md); \\}\n\nA stable, first-class Macro calendar event entity.\n\nContent fields hold the canonical source's values: the account's primary\ncalendar copy when one is synced, else the freshest remaining copy.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attendees\"></a> `attendees` | [`CalendarAttendee`](CalendarAttendee.md)[] | Attendees, keyed by email during persistence. |\n| <a id=\"property-calendarid\"></a> `calendarId?` | `string` \\| `null` | Calendar the canonical source belongs to, when known. Absent only in projections stored before calendars were attributed. |\n| <a id=\"property-conferenceprovider\"></a> `conferenceProvider?` | `null` \\| [`ConferenceProvider`](ConferenceProvider.md) | - |\n| <a id=\"property-conferenceurl\"></a> `conferenceUrl?` | `string` \\| `null` | Direct join URL when known. |\n| <a id=\"property-createdat\"></a> `createdAt` | `string` | Entity creation time. |\n| <a id=\"property-creatoremail\"></a> `creatorEmail?` | `string` \\| `null` | Provider-reported creator email. Distinct from the organizer when someone writes onto a calendar they do not own. Omitted from stored projections when unknown so events ingested before this field still compare equal. |\n| <a id=\"property-creatorname\"></a> `creatorName?` | `string` \\| `null` | Provider-reported creator display name. |\n| <a id=\"property-description\"></a> `description?` | `string` \\| `null` | Optional event body. |\n| <a id=\"property-eventtype\"></a> `eventType?` | [`EventType`](EventType.md) | Provider event type. Skipped when it is the regular type so projections stored before event types were modeled still compare equal. |\n| <a id=\"property-guestpolicy\"></a> `guestPolicy` | [`GuestPolicy`](GuestPolicy.md) | What the organizer lets guests do: the canonical copy's values, or Google's defaults for an event synced before the policy was modeled. |\n| <a id=\"property-icaluid\"></a> `icalUid` | `string` | RFC 5545 UID used to reconcile provider and email sources. |\n| <a id=\"property-id\"></a> `id` | `string` | Macro entity identifier. |\n| <a id=\"property-isreadonly\"></a> `isReadOnly` | `boolean` | Whether the canonical source's calendar prohibits editing it. |\n| <a id=\"property-issnapshot\"></a> `isSnapshot` | `boolean` | Whether this is a snapshot of a meeting shared with the owner, which Macro added to their calendar as a private copy: the meeting's changes never reach it, and nothing done to it reaches the meeting. |\n| <a id=\"property-location\"></a> `location?` | `string` \\| `null` | Optional physical or virtual location label. |\n| <a id=\"property-organizeremail\"></a> `organizerEmail?` | `string` \\| `null` | Organizer email. |\n| <a id=\"property-organizername\"></a> `organizerName?` | `string` \\| `null` | Organizer display name. |\n| <a id=\"property-ownerid\"></a> `ownerId` | `string` | Macro user who owns this event entity. |\n| <a id=\"property-recurrencelines\"></a> `recurrenceLines` | `string`[] | Raw RFC 5545 recurrence properties (`RRULE`, `RDATE`, `EXDATE`). |\n| <a id=\"property-reminders\"></a> `reminders?` | [`EventReminders`](EventReminders.md) | Per-user reminder configuration. Skipped when it is the provider default so projections stored before reminders were modeled still compare equal. |\n| <a id=\"property-sequence\"></a> `sequence` | `number` | Provider/iCalendar sequence number. |\n| <a id=\"property-sources\"></a> `sources?` | [`CalendarEventSourceContent`](CalendarEventSourceContent.md)[] | Content of every active copy of this event, canonical first: the primary calendar's copy, then the freshest. A client picks the copy whose calendar it is showing and falls back to the first. Populated only on the read path, so stored projections omit it. |\n| <a id=\"property-status\"></a> `status` | [`EventStatus`](EventStatus.md) | Event status. |\n| <a id=\"property-time\"></a> `time` | [`EventTime`](EventTime.md) | Timed or all-day shape. |\n| <a id=\"property-title\"></a> `title` | `string` | Display title. |\n| <a id=\"property-transparency\"></a> `transparency` | [`EventTransparency`](EventTransparency.md) | Availability behavior. |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `string` | Entity update time. |\n| <a id=\"property-viewercan\"></a> `viewerCan` | [`ViewerCapabilities`](ViewerCapabilities.md) | What the viewing requester may do with the event. Resolved only on the read path, alongside each attendee's `is_self`; nothing when no viewer is known. Source projections never store it. |\n| <a id=\"property-visibility\"></a> `visibility` | [`EventVisibility`](EventVisibility.md) | Event visibility. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarEventSourceContent.md -->\n# Type Alias: CalendarEventSourceContent\n\n> **CalendarEventSourceContent** = \\{ `calendarId`: `string`; `creatorEmail?`: `string` \\| `null`; `creatorName?`: `string` \\| `null`; `description?`: `string` \\| `null`; `eventType`: [`EventType`](EventType.md); `isReadOnly`: `boolean`; `location?`: `string` \\| `null`; `reminders`: [`EventReminders`](EventReminders.md); `title`: `string`; `transparency`: [`EventTransparency`](EventTransparency.md); `visibility`: [`EventVisibility`](EventVisibility.md); \\}\n\nThe content one provider copy of an event carries.\n\nGoogle keeps these fields per calendar copy: a shared calendar's copy of a\nmember's event can have its own title, type, reminders, and access role.\nThe entity holds its canonical source's values. Every other copy's values\nare read from here so a client can show the copy that belongs to the\ncalendar being viewed.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-calendarid\"></a> `calendarId` | `string` | Calendar this copy lives on. |\n| <a id=\"property-creatoremail\"></a> `creatorEmail?` | `string` \\| `null` | Provider-reported creator email. |\n| <a id=\"property-creatorname\"></a> `creatorName?` | `string` \\| `null` | Provider-reported creator display name. |\n| <a id=\"property-description\"></a> `description?` | `string` \\| `null` | Optional event body. |\n| <a id=\"property-eventtype\"></a> `eventType` | [`EventType`](EventType.md) | Provider event type. |\n| <a id=\"property-isreadonly\"></a> `isReadOnly` | `boolean` | Whether the calendar's access role prohibits editing this copy. |\n| <a id=\"property-location\"></a> `location?` | `string` \\| `null` | Optional physical or virtual location label. |\n| <a id=\"property-reminders\"></a> `reminders` | [`EventReminders`](EventReminders.md) | Reminder configuration of this copy. |\n| <a id=\"property-title\"></a> `title` | `string` | Display title. |\n| <a id=\"property-transparency\"></a> `transparency` | [`EventTransparency`](EventTransparency.md) | Availability behavior. |\n| <a id=\"property-visibility\"></a> `visibility` | [`EventVisibility`](EventVisibility.md) | Event visibility. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarGuestInputBody.md -->\n# Type Alias: CalendarGuestInputBody\n\n> **CalendarGuestInputBody** = \\{ `email`: `string`; `optional?`: `boolean`; \\}\n\nA guest added to an event.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-email\"></a> `email` | `string` | Guest email address. |\n| <a id=\"property-optional\"></a> `optional?` | `boolean` | Whether attendance is optional. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarProvider.md -->\n# Type Alias: CalendarProvider\n\n> **CalendarProvider** = `\"google\"` \\| `\"outlook\"`\n\nProvider selected from the persisted calendar account and email binding.\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarReplacementView.md -->\n# Type Alias: CalendarReplacementView\n\n> **CalendarReplacementView** = \\{ `attendeeCount`: `number`; `completedSteps`: `number`; `event?`: `null` \\| [`CalendarEvent`](CalendarEvent.md); `isSeries`: `boolean`; `operationId`: `string`; `providerUrl?`: `string` \\| `null`; `removeConference`: `boolean`; `replacementUrl?`: `string` \\| `null`; `status`: [`ReplacementStatus`](ReplacementStatus.md); `time`: [`EventTime`](EventTime.md); `title`: `string`; `totalSteps`: `number`; \\}\n\nSafe preview and recovery response; never exposes the opaque provider snapshot.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attendeecount\"></a> `attendeeCount` | `number` | Guest count for cancellation and reinvitation confirmation. |\n| <a id=\"property-completedsteps\"></a> `completedSteps` | `number` | Number of completed provider steps. |\n| <a id=\"property-event\"></a> `event?` | `null` \\| [`CalendarEvent`](CalendarEvent.md) | - |\n| <a id=\"property-isseries\"></a> `isSeries` | `boolean` | Entire recurring series, including exceptions, is replaced. |\n| <a id=\"property-operationid\"></a> `operationId` | `string` | Use this identity when confirming or checking progress. |\n| <a id=\"property-providerurl\"></a> `providerUrl?` | `string` \\| `null` | Original event for manual review. |\n| <a id=\"property-removeconference\"></a> `removeConference` | `boolean` | The provider conference is removed. |\n| <a id=\"property-replacementurl\"></a> `replacementUrl?` | `string` \\| `null` | New provider event, when creation was confirmed. |\n| <a id=\"property-status\"></a> `status` | [`ReplacementStatus`](ReplacementStatus.md) | Current durable state. |\n| <a id=\"property-time\"></a> `time` | [`EventTime`](EventTime.md) | Frozen time. |\n| <a id=\"property-title\"></a> `title` | `string` | Frozen title. |\n| <a id=\"property-totalsteps\"></a> `totalSteps` | `number` | Number of provider steps in this operation. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarRsvpScopeParam.md -->\n# Type Alias: CalendarRsvpScopeParam\n\n> **CalendarRsvpScopeParam** = `\"all\"` \\| `\"this_event\"`\n\nHow much of a recurring series an RSVP applies to.\n\nUnlike deletion there is no this-and-following variant: the provider\ncannot express a forward-scoped response, so offering one would be a\npromise sync could not keep.\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarUpdateScopeParam.md -->\n# Type Alias: CalendarUpdateScopeParam\n\n> **CalendarUpdateScopeParam** = `\"all\"` \\| `\"this_event\"`\n\nHow much of a recurring series an update applies to.\n\nLike RSVPs there is no this-and-following variant: the provider cannot\nexpress a forward-scoped edit as one write, and emulating it (truncate\nthe series, insert an edited clone) is non-atomic and re-invites the\nattendees of the clone. Compose it from a this-and-following deletion\nand a create when that shape is wanted.\n\n\n<!-- generated/calendar/types.gen/type-aliases/ConferenceChange.md -->\n# Type Alias: ConferenceChange\n\n> **ConferenceChange** = `\"provider_default\"` \\| `\"microsoft_teams\"` \\| `\"google_meet\"` \\| `\"none\"`\n\nA requested change to an event's conferencing. Omitting the field leaves\nthe existing conference untouched; only these values change it.\n\n\n<!-- generated/calendar/types.gen/type-aliases/ConferenceProvider.md -->\n# Type Alias: ConferenceProvider\n\n> **ConferenceProvider** = `\"microsoft_teams\"` \\| `\"google_meet\"` \\| `\"other\"`\n\nThe conferencing system backing an event's join URL.\n\nCalendars can create Google Meet or Microsoft Teams according to their\ncapabilities. Imported third-party conferences are labeled separately.\nOmitting a conference change preserves the current conference; explicit\nchanges still require provider and calendar capability validation.\n\n\n<!-- generated/calendar/types.gen/type-aliases/DocumentNoteLink.md -->\n# Type Alias: DocumentNoteLink\n\n> **DocumentNoteLink** = \\{ `documentName`: `string`; `eventId`: `string`; `eventTitle`: `string`; `occurrenceKey`: `string`; `team?`: `null` \\| [`NoteTeam`](NoteTeam.md); \\}\n\nAn owner's durable sharing link, including meetings they can no longer open.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-documentname\"></a> `documentName` | `string` | Current name of the owned markdown document. |\n| <a id=\"property-eventid\"></a> `eventId` | `string` | Linked calendar copy. |\n| <a id=\"property-eventtitle\"></a> `eventTitle` | `string` | Current title, or a safe placeholder when meeting details are unavailable. |\n| <a id=\"property-occurrencekey\"></a> `occurrenceKey` | `string` | Original occurrence start, or `single` for a one-time meeting. |\n| <a id=\"property-team\"></a> `team?` | `null` \\| [`NoteTeam`](NoteTeam.md) | - |\n\n\n<!-- generated/calendar/types.gen/type-aliases/EventReminderOverride.md -->\n# Type Alias: EventReminderOverride\n\n> **EventReminderOverride** = \\{ `method`: `string`; `minutes`: `number`; \\}\n\nOne reminder: how it alerts and how many minutes before the event start\n(before midnight in the calendar's zone for all-day events) it fires.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-method\"></a> `method` | `string` | Provider method, stored verbatim; only `popup` fires Macro notifications. |\n| <a id=\"property-minutes\"></a> `minutes` | `number` | Minutes before the event start. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/EventReminders.md -->\n# Type Alias: EventReminders\n\n> **EventReminders** = \\{ `overrides?`: [`EventReminderOverride`](EventReminderOverride.md)[]; `useDefault`: `boolean`; \\}\n\nPer-user reminder configuration for an event, mirroring Google's model:\neither the calendar's default reminders apply, or the explicit overrides\nreplace them entirely.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-overrides\"></a> `overrides?` | [`EventReminderOverride`](EventReminderOverride.md)[] | Explicit reminders replacing the defaults when `use_default` is off. |\n| <a id=\"property-usedefault\"></a> `useDefault` | `boolean` | Whether the calendar's default reminders apply. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/EventStatus.md -->\n# Type Alias: EventStatus\n\n> **EventStatus** = `\"confirmed\"` \\| `\"tentative\"` \\| `\"cancelled\"`\n\nCanonical event status.\n\n\n<!-- generated/calendar/types.gen/type-aliases/EventTime.md -->\n# Type Alias: EventTime\n\n> **EventTime** = \\{ `endsAt`: `string`; `kind`: `\"timed\"`; `startsAt`: `string`; `timeZone?`: `string` \\| `null`; \\} \\| \\{ `endDate`: `string`; `kind`: `\"allDay\"`; `startDate`: `string`; \\}\n\nThe mutually exclusive time shape of a calendar event.\n\nFields are renamed per variant rather than with `rename_all_fields`\nbecause utoipa only honors variant-level serde renames when it\nderives the OpenAPI schema.\n\n## Union Members\n\n### Type Literal\n\n\\{ `endsAt`: `string`; `kind`: `\"timed\"`; `startsAt`: `string`; `timeZone?`: `string` \\| `null`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `endsAt` | `string` | Exclusive end instant; equal to the start for an imported point event. |\n| `kind` | `\"timed\"` | - |\n| `startsAt` | `string` | Inclusive start instant. |\n| `timeZone?` | `string` \\| `null` | Original IANA time-zone identifier, when supplied. |\n\n***\n\n### Type Literal\n\n\\{ `endDate`: `string`; `kind`: `\"allDay\"`; `startDate`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `endDate` | `string` | Exclusive local end date. |\n| `kind` | `\"allDay\"` | - |\n| `startDate` | `string` | Inclusive local start date. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/EventTransparency.md -->\n# Type Alias: EventTransparency\n\n> **EventTransparency** = `\"opaque\"` \\| `\"transparent\"`\n\nWhether an event blocks availability.\n\n\n<!-- generated/calendar/types.gen/type-aliases/EventType.md -->\n# Type Alias: EventType\n\n> **EventType** = `\"default\"` \\| `\"out_of_office\"` \\| `\"focus_time\"` \\| `\"working_location\"` \\| `\"birthday\"` \\| `\"from_gmail\"`\n\nGoogle's event type: ordinary meetings versus the status-style entries\n(working location, out of office, focus time, birthdays) Google renders\nand notifies differently. Immutable at the provider after creation.\n\n\n<!-- generated/calendar/types.gen/type-aliases/EventVisibility.md -->\n# Type Alias: EventVisibility\n\n> **EventVisibility** = `\"default\"` \\| `\"public\"` \\| `\"private\"` \\| `\"confidential\"`\n\nVisibility of event details.\n\n\n<!-- generated/calendar/types.gen/type-aliases/GuestPolicy.md -->\n# Type Alias: GuestPolicy\n\n> **GuestPolicy** = \\{ `canInviteOthers`: `boolean`; `canModify`: `boolean`; `canSeeOtherGuests`: `boolean`; \\}\n\nThe switches an organizer sets on an event to bound what its guests may\ndo. Google omits a switch from the payload while it holds its default.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-caninviteothers\"></a> `canInviteOthers` | `boolean` | Whether guests may invite others. |\n| <a id=\"property-canmodify\"></a> `canModify` | `boolean` | Whether guests may change the event, including its guest list. |\n| <a id=\"property-canseeotherguests\"></a> `canSeeOtherGuests` | `boolean` | Whether guests may see the guest list. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/MeetingNote.md -->\n# Type Alias: MeetingNote\n\n> **MeetingNote** = \\{ `canManage`: `boolean`; `documentId`: `string`; `name`: `string`; `team?`: `null` \\| [`NoteTeam`](NoteTeam.md); \\}\n\nOne linked document and the extra access this link grants.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-canmanage\"></a> `canManage` | `boolean` | Whether this viewer can change this document's sharing. |\n| <a id=\"property-documentid\"></a> `documentId` | `string` | Markdown document identity. |\n| <a id=\"property-name\"></a> `name` | `string` | Current document name. |\n| <a id=\"property-team\"></a> `team?` | `null` \\| [`NoteTeam`](NoteTeam.md) | - |\n\n\n<!-- generated/calendar/types.gen/type-aliases/NoteTeam.md -->\n# Type Alias: NoteTeam\n\n> **NoteTeam** = \\{ `id`: `string`; `name`: `string`; \\}\n\nAn additional team audience, separate from the meeting's audience.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `string` | Team identity. |\n| <a id=\"property-name\"></a> `name` | `string` | Display name. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/OutOfOfficeAutoDeclineMode.md -->\n# Type Alias: OutOfOfficeAutoDeclineMode\n\n> **OutOfOfficeAutoDeclineMode** = `\"decline_none\"` \\| `\"decline_all_conflicting_invitations\"` \\| `\"decline_only_new_conflicting_invitations\"`\n\nHow an out-of-office event responds to conflicting invitations, mirroring\nGoogle's `autoDeclineMode`.\n\n\n<!-- generated/calendar/types.gen/type-aliases/OutOfOfficeProperties.md -->\n# Type Alias: OutOfOfficeProperties\n\n> **OutOfOfficeProperties** = \\{ `autoDeclineMode?`: [`OutOfOfficeAutoDeclineMode`](OutOfOfficeAutoDeclineMode.md); `declineMessage?`: `string` \\| `null`; \\}\n\nThe extra properties Google requires on an out-of-office event, mirroring\nits `outOfOfficeProperties` block. Their presence on a draft or patch is\nwhat marks the mutation as out-of-office.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-autodeclinemode\"></a> `autoDeclineMode?` | [`OutOfOfficeAutoDeclineMode`](OutOfOfficeAutoDeclineMode.md) | How conflicting invitations are handled while the user is out. |\n| <a id=\"property-declinemessage\"></a> `declineMessage?` | `string` \\| `null` | Message returned to organizers whose invitations are auto-declined. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/ReplacementStatus.md -->\n# Type Alias: ReplacementStatus\n\n> **ReplacementStatus** = `\"needs_confirmation\"` \\| `\"in_progress\"` \\| `\"complete\"`\n\nUser-visible workflow state.\n\n\n<!-- generated/calendar/types.gen/type-aliases/TeamCalendarSharing.md -->\n# Type Alias: TeamCalendarSharing\n\n> **TeamCalendarSharing** = `\"all\"` \\| `\"busy_only\"` \\| `\"none\"`\n\nWhat a user exposes through their team membership.\n\n\n<!-- generated/calendar/types.gen/type-aliases/ViewerCapabilities.md -->\n# Type Alias: ViewerCapabilities\n\n> **ViewerCapabilities** = \\{ `editDetails`: `boolean`; `inviteGuests`: `boolean`; `organize`: `boolean`; `removeGuests`: `boolean`; `rsvp`: `boolean`; `setGuestPolicy`: `boolean`; \\}\n\nWhat the viewing requester may do with an event.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-editdetails\"></a> `editDetails` | `boolean` | Change the event's details (title, time, description, conference). |\n| <a id=\"property-inviteguests\"></a> `inviteGuests` | `boolean` | Add guests. |\n| <a id=\"property-organize\"></a> `organize` | `boolean` | Act as the event's organizer: replace its whole guest list and manage its conferencing. |\n| <a id=\"property-removeguests\"></a> `removeGuests` | `boolean` | Remove guests. |\n| <a id=\"property-rsvp\"></a> `rsvp` | `boolean` | Answer the invitation. |\n| <a id=\"property-setguestpolicy\"></a> `setGuestPolicy` | `boolean` | Change the event's guest policy, which only Google calendars have. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/VisibleCalendar.md -->\n# Type Alias: VisibleCalendar\n\n> **VisibleCalendar** = \\{ `capabilities`: [`CalendarCapabilities`](CalendarCapabilities.md); `color?`: `string` \\| `null`; `defaultReminders`: [`EventReminderOverride`](EventReminderOverride.md)[]; `emailAddress`: `string`; `emailLinkId`: `string`; `id`: `string`; `isPrimary`: `boolean`; `isSubscription`: `boolean`; `isWritable`: `boolean`; `name`: `string`; `provider`: [`CalendarProvider`](CalendarProvider.md); `syncError?`: `string` \\| `null`; \\}\n\nA calendar visible to a requester, listed for pickers and filters.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-capabilities\"></a> `capabilities` | [`CalendarCapabilities`](CalendarCapabilities.md) | Provider features available on this actual calendar. |\n| <a id=\"property-color\"></a> `color?` | `string` \\| `null` | Provider color. |\n| <a id=\"property-defaultreminders\"></a> `defaultReminders` | [`EventReminderOverride`](EventReminderOverride.md)[] | Default reminders applied to events that keep `useDefault`. |\n| <a id=\"property-emailaddress\"></a> `emailAddress` | `string` | Connected inbox address, for grouping in multi-inbox pickers. |\n| <a id=\"property-emaillinkid\"></a> `emailLinkId` | `string` | Connected inbox that syncs this calendar. |\n| <a id=\"property-id\"></a> `id` | `string` | Persisted Macro calendar identifier. |\n| <a id=\"property-isprimary\"></a> `isPrimary` | `boolean` | Whether this is its account's primary calendar. |\n| <a id=\"property-issubscription\"></a> `isSubscription` | `boolean` | Whether this is one of Google's shared system calendars (holidays, birthdays) the account subscribes to rather than one a person maintains. |\n| <a id=\"property-iswritable\"></a> `isWritable` | `boolean` | Whether the grant can create and modify events on this calendar. |\n| <a id=\"property-name\"></a> `name` | `string` | Provider display name. |\n| <a id=\"property-provider\"></a> `provider` | [`CalendarProvider`](CalendarProvider.md) | Calendar provider, for display and reconnect routing. |\n| <a id=\"property-syncerror\"></a> `syncError?` | `string` \\| `null` | A persistent sync failure isolated to this calendar, surfaced so the settings row can badge it. `None` while the calendar is syncing normally or a failure has not yet crossed the persistence threshold. |\n\n\n<!-- generated/storage/types.gen/type-aliases/AttendeeResponseStatus.md -->\n# Type Alias: AttendeeResponseStatus\n\n> **AttendeeResponseStatus** = `\"needs_action\"` \\| `\"accepted\"` \\| `\"declined\"` \\| `\"tentative\"`\n\nRSVP state for an attendee.\n\n\n<!-- generated/storage/types.gen/type-aliases/CalendarAttendee.md -->\n# Type Alias: CalendarAttendee\n\n> **CalendarAttendee** = \\{ `comment?`: `string` \\| `null`; `displayName?`: `string` \\| `null`; `email`: `string`; `isOptional`: `boolean`; `isOrganizer`: `boolean`; `isSelf`: `boolean`; `responseStatus`: [`AttendeeResponseStatus`](AttendeeResponseStatus.md); \\}\n\nAn attendee on a calendar event.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-comment\"></a> `comment?` | `string` \\| `null` | Optional attendee comment. |\n| <a id=\"property-displayname\"></a> `displayName?` | `string` \\| `null` | Provider display name. |\n| <a id=\"property-email\"></a> `email` | `string` | Normalized email address. |\n| <a id=\"property-isoptional\"></a> `isOptional` | `boolean` | Whether attendance is optional. |\n| <a id=\"property-isorganizer\"></a> `isOrganizer` | `boolean` | Whether this attendee is the organizer. |\n| <a id=\"property-isself\"></a> `isSelf` | `boolean` | Whether this attendee is one of the viewing requester's inboxes. |\n| <a id=\"property-responsestatus\"></a> `responseStatus` | [`AttendeeResponseStatus`](AttendeeResponseStatus.md) | RSVP state. |\n\n\n<!-- generated/storage/types.gen/type-aliases/CalendarOccurrence.md -->\n# Type Alias: CalendarOccurrence\n\n> **CalendarOccurrence** = \\{ `eventId`: `string`; `isCancelled`: `boolean`; `occurrenceKey`: `string`; `recurrenceId?`: `string` \\| `null`; `time`: [`EventTime`](EventTime.md); \\}\n\nA materialized recurrence instance optimized for range queries.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-eventid\"></a> `eventId` | `string` | Owning event entity. |\n| <a id=\"property-iscancelled\"></a> `isCancelled` | `boolean` | Whether the instance was cancelled. |\n| <a id=\"property-occurrencekey\"></a> `occurrenceKey` | `string` | Stable key within the event. |\n| <a id=\"property-recurrenceid\"></a> `recurrenceId?` | `string` \\| `null` | Provider recurrence identifier, when applicable. |\n| <a id=\"property-time\"></a> `time` | [`EventTime`](EventTime.md) | Instance time. |\n\n\n<!-- generated/storage/types.gen/type-aliases/EventTime.md -->\n# Type Alias: EventTime\n\n> **EventTime** = \\{ `endsAt`: `string`; `kind`: `\"timed\"`; `startsAt`: `string`; `timeZone?`: `string` \\| `null`; \\} \\| \\{ `endDate`: `string`; `kind`: `\"allDay\"`; `startDate`: `string`; \\}\n\nThe mutually exclusive time shape of a calendar event.\n\nFields are renamed per variant rather than with `rename_all_fields`\nbecause utoipa only honors variant-level serde renames when it\nderives the OpenAPI schema.\n\n## Union Members\n\n### Type Literal\n\n\\{ `endsAt`: `string`; `kind`: `\"timed\"`; `startsAt`: `string`; `timeZone?`: `string` \\| `null`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `endsAt` | `string` | Exclusive end instant; equal to the start for an imported point event. |\n| `kind` | `\"timed\"` | - |\n| `startsAt` | `string` | Inclusive start instant. |\n| `timeZone?` | `string` \\| `null` | Original IANA time-zone identifier, when supplied. |\n\n***\n\n### Type Literal\n\n\\{ `endDate`: `string`; `kind`: `\"allDay\"`; `startDate`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `endDate` | `string` | Exclusive local end date. |\n| `kind` | `\"allDay\"` | - |\n| `startDate` | `string` | Inclusive local start date. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ListOccurrencesData.md -->\n# Type Alias: ListOccurrencesData\n\n> **ListOccurrencesData** = \\{ `body?`: `never`; `path?`: `never`; `query`: \\{ `cursor?`: `string`; `end`: `string`; `endDate?`: `string`; `limit?`: `number`; `start`: `string`; `startDate?`: `string`; \\}; `url`: `\"/calendar-events\"`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-body\"></a> `body?` | `never` | - |\n| <a id=\"property-path\"></a> `path?` | `never` | - |\n| <a id=\"property-query\"></a> `query` | \\{ `cursor?`: `string`; `end`: `string`; `endDate?`: `string`; `limit?`: `number`; `start`: `string`; `startDate?`: `string`; \\} | - |\n| `query.cursor?` | `string` | Opaque continuation cursor returned by the previous page. |\n| `query.end` | `string` | Exclusive UTC viewport end. |\n| `query.endDate?` | `string` | Exclusive local date boundary for all-day events. |\n| `query.limit?` | `number` | Maximum number of occurrences, from 1 through 2,000. |\n| `query.start` | `string` | Inclusive UTC viewport start. |\n| `query.startDate?` | `string` | Inclusive local date boundary for all-day events. |\n| <a id=\"property-url\"></a> `url` | `\"/calendar-events\"` | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/TeamCalendarCoverage.md -->\n# Type Alias: TeamCalendarCoverage\n\n> **TeamCalendarCoverage** = `\"ready\"` \\| `\"unavailable\"` \\| `\"hidden\"`\n\nWhether a member's calendar projection can establish availability.\n\n\n<!-- generated/storage/types.gen/type-aliases/TeamCalendarDetails.md -->\n# Type Alias: TeamCalendarDetails\n\n> **TeamCalendarDetails** = \\{ `attendees`: [`CalendarAttendee`](CalendarAttendee.md)[]; `calendarName`: `string`; `conferenceUrl?`: `string` \\| `null`; `description?`: `string` \\| `null`; `location?`: `string` \\| `null`; `organizerEmail?`: `string` \\| `null`; `organizerName?`: `string` \\| `null`; `title`: `string`; \\}\n\nSafe details from a single authorized source.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attendees\"></a> `attendees` | [`CalendarAttendee`](CalendarAttendee.md)[] | Attendees; self flags are relative to the requesting viewer. |\n| <a id=\"property-calendarname\"></a> `calendarName` | `string` | Source calendar name, shown only with details. |\n| <a id=\"property-conferenceurl\"></a> `conferenceUrl?` | `string` \\| `null` | Join URL, if supplied by this source. |\n| <a id=\"property-description\"></a> `description?` | `string` \\| `null` | Body, if supplied by this source. |\n| <a id=\"property-location\"></a> `location?` | `string` \\| `null` | Location, if supplied by this source. |\n| <a id=\"property-organizeremail\"></a> `organizerEmail?` | `string` \\| `null` | Organizer address from this source. |\n| <a id=\"property-organizername\"></a> `organizerName?` | `string` \\| `null` | Organizer name from this source. |\n| <a id=\"property-title\"></a> `title` | `string` | Display title. |\n\n\n<!-- generated/storage/types.gen/type-aliases/TeamCalendarSharing.md -->\n# Type Alias: TeamCalendarSharing\n\n> **TeamCalendarSharing** = `\"all\"` \\| `\"busy_only\"` \\| `\"none\"`\n\nWhat a user exposes through their team membership.\n\n\n<!-- src/entities/calendar/calendar/classes/Calendar.md -->\n# Class: Calendar\n\nA calendar visible to the requester across their connected inboxes: a\nfree-to-construct handle whose detail resolves from the caller's calendar\nlist. There is no fetch-by-id endpoint, so a bare [Calendar.byId](#byid)\nhandle loads its detail by listing the caller's calendars and matching on id.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`VisibleCalendar`](../../../../../generated/calendar/types.gen/type-aliases/VisibleCalendar.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-color\"></a> `color` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | Provider color, when set. | - |\n| <a id=\"property-emailaddress\"></a> `emailAddress` | `readonly` | () => `Promise`\\<`string`\\> | Connected inbox address that syncs this calendar. | - |\n| <a id=\"property-emaillink\"></a> `emailLink` | `readonly` | () => `Promise`\\<[`Link`](../../../email/link/classes/Link.md)\\> | The connected inbox (email link) that syncs this calendar. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-isprimary\"></a> `isPrimary` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether this is its account's primary calendar. | - |\n| <a id=\"property-issubscription\"></a> `isSubscription` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether this is a subscribed system calendar (holidays, birthdays). | - |\n| <a id=\"property-iswritable\"></a> `isWritable` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether the grant can create and modify events on this calendar. | - |\n| <a id=\"property-name\"></a> `name` | `readonly` | () => `Promise`\\<`string`\\> | Provider display name. | - |\n| <a id=\"property-syncerror\"></a> `syncError` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | A persistent per-calendar sync failure, surfaced for settings badges. | - |\n\n## Methods\n\n### setContributesToAvailability()\n\n> **setContributesToAvailability**(`contributesToAvailability`): `Promise`\\<`void`\\>\n\nSet whether this calendar contributes to the caller's availability.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `contributesToAvailability` | `boolean` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`VisibleCalendar`](../../../../../generated/calendar/types.gen/type-aliases/VisibleCalendar.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`VisibleCalendar`](../../../../../generated/calendar/types.gen/type-aliases/VisibleCalendar.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`VisibleCalendar`](../../../../../generated/calendar/types.gen/type-aliases/VisibleCalendar.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `Calendar`\n\nA handle to a calendar by id. Detail loads on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`Calendar`\n\n***\n\n### list()\n\n> `static` **list**(`client`): `Promise`\\<`Calendar`[]\\>\n\nThe caller's visible calendars, primaries and writable first.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`Promise`\\<`Calendar`[]\\>\n\n\n<!-- src/entities/calendar/event/classes/CalendarEvent.md -->\n# Class: CalendarEvent\n\nA Macro calendar event: a handle exposing the event's synced fields and the\nmutations that act on it ([CalendarEvent.update](#update),\n[CalendarEvent.delete](#delete), [CalendarEvent.rsvp](#rsvp)).\n\nThe calendar service has no fetch-by-id endpoint, so a handle reads its\nfields only when seeded with a record — as returned by\n[CalendarEvent.update](#update), [CalendarEvent.rsvp](#rsvp), or\n`calendar.createEvent`. A bare [CalendarEvent.byId](#byid) handle can drive\nmutations, but reading a field on it throws.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`CalendarEvent`](../../../../../generated/calendar/types.gen/type-aliases/CalendarEvent.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-attendees\"></a> `attendees` | `readonly` | () => `Promise`\\<[`CalendarAttendee`](../../../../../generated/calendar/types.gen/type-aliases/CalendarAttendee.md)[]\\> | Attendees on the canonical copy. | - |\n| <a id=\"property-calendar\"></a> `calendar` | `readonly` | () => `Promise`\\<[`Calendar`](../../calendar/classes/Calendar.md) \\| `undefined`\\> | The calendar the canonical source belongs to, when known. | - |\n| <a id=\"property-description\"></a> `description` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | Optional event body. | - |\n| <a id=\"property-guestpolicy\"></a> `guestPolicy` | `readonly` | () => `Promise`\\<[`GuestPolicy`](../../../../../generated/calendar/types.gen/type-aliases/GuestPolicy.md)\\> | What the organizer lets guests do: modify, invite others, see the guest list. | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-isreadonly\"></a> `isReadOnly` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether the canonical source's calendar prohibits editing. | - |\n| <a id=\"property-location\"></a> `location` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | Optional physical or virtual location label. | - |\n| <a id=\"property-recurrencelines\"></a> `recurrenceLines` | `readonly` | () => `Promise`\\<`string`[]\\> | Raw RFC 5545 recurrence properties (`RRULE`, `RDATE`, `EXDATE`). | - |\n| <a id=\"property-status\"></a> `status` | `readonly` | () => `Promise`\\<[`EventStatus`](../../../../../generated/calendar/types.gen/type-aliases/EventStatus.md)\\> | Event status. | - |\n| <a id=\"property-time\"></a> `time` | `readonly` | () => `Promise`\\<[`EventTime`](../../../../../generated/calendar/types.gen/type-aliases/EventTime.md)\\> | Timed or all-day shape. | - |\n| <a id=\"property-title\"></a> `title` | `readonly` | () => `Promise`\\<`string`\\> | Display title. | - |\n| <a id=\"property-transparency\"></a> `transparency` | `readonly` | () => `Promise`\\<[`EventTransparency`](../../../../../generated/calendar/types.gen/type-aliases/EventTransparency.md)\\> | Availability behavior. | - |\n| <a id=\"property-viewercan\"></a> `viewerCan` | `readonly` | () => `Promise`\\<[`ViewerCapabilities`](../../../../../generated/calendar/types.gen/type-aliases/ViewerCapabilities.md)\\> | What the connected account may do with this event under its guest policy. | - |\n\n## Methods\n\n### addToCalendar()\n\n> **addToCalendar**(`options?`): `Promise`\\<`CalendarEvent`\\>\n\nAdd a snapshot of an event shared with one of the requester's\nchannels to one of their Google calendars, and return a handle to the\nsynced snapshot. The snapshot keeps the meeting's iCalendar UID and\norganizer, lists only the requester as a guest, and carries no join link;\nnobody is notified, and answers or guests on it never reach the meeting.\nRefused with `already_on_calendar` when the meeting is already on one of\ntheir calendars, with `join_request_open` while their request to join it\nis pending or accepted (the meeting then arrives as an invitation), and\nwith `copy_refused` when Google will not import it.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options?` | \\{ `calendar?`: [`Calendar`](../../calendar/classes/Calendar.md); \\} |\n| `options.calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) |\n\n#### Returns\n\n`Promise`\\<`CalendarEvent`\\>\n\n***\n\n### delete()\n\n> **delete**(`options?`): `Promise`\\<`void`\\>\n\nDelete the event (or a scoped part of a recurring series) at its provider.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options?` | [`DeleteEventOptions`](../interfaces/DeleteEventOptions.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### ics()\n\n> **ics**(): `Promise`\\<`string`\\>\n\nThe event as an iCalendar (`.ics`) document: its series, title,\ndescription, location and organizer, never its guests or join link.\nAvailable for the requester's own events and ones shared with a channel\nthey belong to.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### inviteGuests()\n\n> **inviteGuests**(`options`): `Promise`\\<`CalendarEvent`\\>\n\nAdd guests without touching anyone already invited, and return a handle\nto the synced record. The organizer may, and so may a guest the organizer\nlets invite others (see [CalendarEvent.viewerCan](#property-viewercan)); Google emails\nthe new guests.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`InviteGuestsOptions`](../interfaces/InviteGuestsOptions.md) |\n\n#### Returns\n\n`Promise`\\<`CalendarEvent`\\>\n\n***\n\n### linkNote()\n\n> **linkNote**(`document`, `occurrence`, `options?`): `Promise`\\<[`CalendarNote`](../../note/classes/CalendarNote.md)\\>\n\nLink a markdown document you own. Meeting-detail viewers gain read access;\nan optional team gains read access too. Editing and other sharing are preserved.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `document` | [`Document`](../../../documents/document/classes/Document.md) |\n| `occurrence` | [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md) |\n| `options?` | \\{ `team?`: [`Team`](../../../teams/team/classes/Team.md); \\} |\n| `options.team?` | [`Team`](../../../teams/team/classes/Team.md) |\n\n#### Returns\n\n`Promise`\\<[`CalendarNote`](../../note/classes/CalendarNote.md)\\>\n\n***\n\n### notes()\n\n> **notes**(`occurrence`): `Promise`\\<[`CalendarNote`](../../note/classes/CalendarNote.md)[]\\>\n\nNotes linked to a specific occurrence returned by `calendar.occurrences()`.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `occurrence` | [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md) |\n\n#### Returns\n\n`Promise`\\<[`CalendarNote`](../../note/classes/CalendarNote.md)[]\\>\n\n***\n\n### prepareReplacement()\n\n> **prepareReplacement**(`options`): `Promise`\\<[`CalendarReplacement`](../../replacement/classes/CalendarReplacement.md)\\>\n\nPreview an organizer replacement without cancelling or sending invitations.\nReview replacement.status() before explicitly calling replacement.confirm().\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | \\{ `calendar?`: [`Calendar`](../../calendar/classes/Calendar.md); `recurrenceId?`: `string`; `removeConference`: `boolean`; \\} |\n| `options.calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) |\n| `options.recurrenceId?` | `string` |\n| `options.removeConference` | `boolean` |\n\n#### Returns\n\n`Promise`\\<[`CalendarReplacement`](../../replacement/classes/CalendarReplacement.md)\\>\n\n***\n\n### providerUrl()\n\n> **providerUrl**(`options?`): `Promise`\\<`string` \\| `undefined`\\>\n\nOpen this calendar copy in its provider for actions unavailable through its API.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options?` | \\{ `calendar?`: [`Calendar`](../../calendar/classes/Calendar.md); `recurrenceId?`: `string`; \\} |\n| `options.calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) |\n| `options.recurrenceId?` | `string` |\n\n#### Returns\n\n`Promise`\\<`string` \\| `undefined`\\>\n\n***\n\n### record()\n\n> **record**(): `Promise`\\<[`CalendarEvent`](../../../../../generated/calendar/types.gen/type-aliases/CalendarEvent.md)\\>\n\nThe full synced event record. Available on a seeded handle (from create /\nupdate / rsvp); a bare `byId` handle throws (no fetch-by-id endpoint).\n\n#### Returns\n\n`Promise`\\<[`CalendarEvent`](../../../../../generated/calendar/types.gen/type-aliases/CalendarEvent.md)\\>\n\n***\n\n### rsvp()\n\n> **rsvp**(`options`): `Promise`\\<`CalendarEvent`\\>\n\nRecord the requester's RSVP and return a handle to the synced record.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`RsvpEventOptions`](../interfaces/RsvpEventOptions.md) |\n\n#### Returns\n\n`Promise`\\<`CalendarEvent`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`CalendarEvent`](../../../../../generated/calendar/types.gen/type-aliases/CalendarEvent.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`CalendarEvent`](../../../../../generated/calendar/types.gen/type-aliases/CalendarEvent.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`CalendarEvent`](../../../../../generated/calendar/types.gen/type-aliases/CalendarEvent.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### update()\n\n> **update**(`options`): `Promise`\\<`CalendarEvent`\\>\n\nUpdate the event and return a handle to its synced record.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`UpdateEventOptions`](../interfaces/UpdateEventOptions.md) |\n\n#### Returns\n\n`Promise`\\<`CalendarEvent`\\>\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `CalendarEvent`\n\nA handle to a calendar event by id, for driving mutations. Reading a\nfield on it throws (there is no fetch-by-id endpoint).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`CalendarEvent`\n\n***\n\n### fromRecord()\n\n> `static` **fromRecord**(`client`, `record`): `CalendarEvent`\n\nA handle seeded with a synced event record; reads resolve without a fetch.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `record` | [`CalendarEvent`](../../../../../generated/calendar/types.gen/type-aliases/CalendarEvent.md) |\n\n#### Returns\n\n`CalendarEvent`\n\n\n<!-- src/entities/calendar/event/interfaces/DeleteEventOptions.md -->\n# Interface: DeleteEventOptions\n\nHow a deletion is scoped across a recurring series.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-calendar\"></a> `calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) | Calendar whose copy of the event is deleted, for a multi-calendar event. Omit to delete the canonical copy. |\n| <a id=\"property-recurrenceid\"></a> `recurrenceId?` | `string` | Original-start key of the occurrence a scoped deletion targets. |\n| <a id=\"property-scope\"></a> `scope?` | [`CalendarDeletionScopeParam`](../../../../../generated/calendar/types.gen/type-aliases/CalendarDeletionScopeParam.md) | Deletion scope; defaults to the entire event or series. |\n\n\n<!-- src/entities/calendar/event/interfaces/InviteGuestsOptions.md -->\n# Interface: InviteGuestsOptions\n\nGuests to add and how much of a recurring series gains them.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-calendar\"></a> `calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) | Calendar whose copy of the event is written, for a multi-calendar event. Omit to write the canonical copy. |\n| <a id=\"property-guests\"></a> `guests` | [`CalendarGuestInputBody`](../../../../../generated/calendar/types.gen/type-aliases/CalendarGuestInputBody.md)[] | Guests to add; anyone already on the event is skipped. |\n| <a id=\"property-recurrenceid\"></a> `recurrenceId?` | `string` | Original-start key of the occurrence the guests are added to. |\n| <a id=\"property-scope\"></a> `scope?` | [`CalendarUpdateScopeParam`](../../../../../generated/calendar/types.gen/type-aliases/CalendarUpdateScopeParam.md) | How much of a recurring series gains the guests. Omit to let `recurrenceId` decide. |\n\n\n<!-- src/entities/calendar/event/interfaces/RsvpEventOptions.md -->\n# Interface: RsvpEventOptions\n\nThe RSVP to record and how it is scoped across a recurring series.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-calendar\"></a> `calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) | Calendar whose copy of the event is answered, for a multi-calendar event. Omit to answer on the canonical copy. |\n| <a id=\"property-recurrenceid\"></a> `recurrenceId?` | `string` | Original-start key of the occurrence the response targets. |\n| <a id=\"property-response\"></a> `response` | [`AttendeeResponseStatus`](../../../../../generated/calendar/types.gen/type-aliases/AttendeeResponseStatus.md) | The response to record for the connected account. |\n| <a id=\"property-scope\"></a> `scope?` | [`CalendarRsvpScopeParam`](../../../../../generated/calendar/types.gen/type-aliases/CalendarRsvpScopeParam.md) | How much of a recurring series the response covers. Omit to let `recurrenceId` decide. |\n\n\n<!-- src/entities/calendar/event/interfaces/UpdateEventOptions.md -->\n# Interface: UpdateEventOptions\n\nFields to change on an event; omitted fields are left untouched.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attendees\"></a> `attendees?` | [`CalendarAttendeeInputBody`](../../../../../generated/calendar/types.gen/type-aliases/CalendarAttendeeInputBody.md)[] | Replacement attendee list. |\n| <a id=\"property-calendar\"></a> `calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) | Calendar whose copy of the event is patched, for a multi-calendar event. Omit to patch the canonical copy. |\n| <a id=\"property-conference\"></a> `conference?` | [`ConferenceChange`](../../../../../generated/calendar/types.gen/type-aliases/ConferenceChange.md) | Provider conference change; omit to retain it. Outlook removal requires a separately confirmed replacement via prepareReplacement(). |\n| <a id=\"property-description\"></a> `description?` | `string` | Replacement description; an empty string clears it. |\n| <a id=\"property-guestpolicy\"></a> `guestPolicy?` | [`GuestPolicy`](../../../../../generated/calendar/types.gen/type-aliases/GuestPolicy.md) | Replacement guest policy; only the organizer of a Google event may change it (`viewerCan.setGuestPolicy`). It applies to the whole series, so an update scoped to one occurrence (`scope: 'this_event'`, or a `recurrenceId`) that changes it is rejected; use scope `'all'`. |\n| <a id=\"property-location\"></a> `location?` | `string` | Replacement location; an empty string clears it. |\n| <a id=\"property-outofoffice\"></a> `outOfOffice?` | [`OutOfOfficeProperties`](../../../../../generated/calendar/types.gen/type-aliases/OutOfOfficeProperties.md) | Replacement out-of-office properties, applied only to an event that is already out-of-office. |\n| <a id=\"property-recurrenceid\"></a> `recurrenceId?` | `string` | Original-start key of the occurrence the update targets. |\n| <a id=\"property-recurrencelines\"></a> `recurrenceLines?` | `string`[] | Replacement recurrence properties; an empty list clears them. |\n| <a id=\"property-reminders\"></a> `reminders?` | [`EventReminders`](../../../../../generated/calendar/types.gen/type-aliases/EventReminders.md) | Replacement reminder configuration. |\n| <a id=\"property-scope\"></a> `scope?` | [`CalendarUpdateScopeParam`](../../../../../generated/calendar/types.gen/type-aliases/CalendarUpdateScopeParam.md) | How much of a recurring series the update covers. Omit to let `recurrenceId` decide. |\n| <a id=\"property-time\"></a> `time?` | [`EventTime`](../../../../../generated/calendar/types.gen/type-aliases/EventTime.md) | Replacement time. |\n| <a id=\"property-title\"></a> `title?` | `string` | Replacement title; an empty string clears it. |\n| <a id=\"property-transparency\"></a> `transparency?` | [`EventTransparency`](../../../../../generated/calendar/types.gen/type-aliases/EventTransparency.md) | Replacement availability behavior. |\n| <a id=\"property-visibility\"></a> `visibility?` | [`EventVisibility`](../../../../../generated/calendar/types.gen/type-aliases/EventVisibility.md) | Replacement visibility. |\n\n\n<!-- src/entities/calendar/namespace/classes/CalendarNamespace.md -->\n# Class: CalendarNamespace\n\nThe calendar surface: the caller's visible calendars, event creation, and\nhandles to individual events and calendars. Backed by calendar_service (the\nSDK reaches it on the gateway's `/calendar` route).\n\n## Constructors\n\n### Constructor\n\n> **new CalendarNamespace**(`client`): `CalendarNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`CalendarNamespace`\n\n## Methods\n\n### availabilityCalendars()\n\n> **availabilityCalendars**(): `Promise`\\<\\{ `calendar`: [`Calendar`](../../calendar/classes/Calendar.md); `contributesToAvailability`: `boolean`; `isPrimary`: `boolean`; `name`: `string`; \\}[]\\>\n\nCalendar availability settings, each referring to a typed calendar.\n\n#### Returns\n\n`Promise`\\<\\{ `calendar`: [`Calendar`](../../calendar/classes/Calendar.md); `contributesToAvailability`: `boolean`; `isPrimary`: `boolean`; `name`: `string`; \\}[]\\>\n\n***\n\n### calendar()\n\n> **calendar**(`id`): [`Calendar`](../../calendar/classes/Calendar.md)\n\nA handle to a calendar by id. Detail loads on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Calendar`](../../calendar/classes/Calendar.md)\n\n***\n\n### calendars()\n\n> **calendars**(): `Promise`\\<[`Calendar`](../../calendar/classes/Calendar.md)[]\\>\n\nThe caller's visible calendars, primaries and writable first.\n\n#### Returns\n\n`Promise`\\<[`Calendar`](../../calendar/classes/Calendar.md)[]\\>\n\n***\n\n### createEvent()\n\n> **createEvent**(`options`): `Promise`\\<[`CalendarEvent`](../../event/classes/CalendarEvent.md)\\>\n\nCreate a calendar event and return a handle to its synced record.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`CreateEventOptions`](../interfaces/CreateEventOptions.md) |\n\n#### Returns\n\n`Promise`\\<[`CalendarEvent`](../../event/classes/CalendarEvent.md)\\>\n\n***\n\n### event()\n\n> **event**(`id`): [`CalendarEvent`](../../event/classes/CalendarEvent.md)\n\nA handle to a calendar event by id, for driving mutations.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`CalendarEvent`](../../event/classes/CalendarEvent.md)\n\n***\n\n### noteDocuments()\n\n> **noteDocuments**(`query?`): `Promise`\\<\\{ `documents`: \\{ `document`: [`Document`](../../../documents/document/classes/Document.md); `name`: `string`; \\}[]; `teams`: \\{ `name`: `string`; `team`: [`Team`](../../../teams/team/classes/Team.md); \\}[]; \\}\\>\n\nFind up to 30 owned markdown documents for meeting notes, plus available extra team audiences.\n\n#### Parameters\n\n| Parameter | Type | Default value |\n| ------ | ------ | ------ |\n| `query?` | `string` | `''` |\n\n#### Returns\n\n`Promise`\\<\\{ `documents`: \\{ `document`: [`Document`](../../../documents/document/classes/Document.md); `name`: `string`; \\}[]; `teams`: \\{ `name`: `string`; `team`: [`Team`](../../../teams/team/classes/Team.md); \\}[]; \\}\\>\n\n***\n\n### occurrences()\n\n> **occurrences**(`options`): `AsyncGenerator`\\<\\{ `event`: [`CalendarEvent`](../../event/classes/CalendarEvent.md); `occurrence`: [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md); \\}, `any`, `any`\\>\n\nCalendar occurrences in a viewport, automatically paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | `Omit`\\<[`ListOccurrencesData`](../../../../../generated/storage/types.gen/type-aliases/ListOccurrencesData.md)\\[`\"query\"`\\], `\"cursor\"`\\> |\n\n#### Returns\n\n`AsyncGenerator`\\<\\{ `event`: [`CalendarEvent`](../../event/classes/CalendarEvent.md); `occurrence`: [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md); \\}, `any`, `any`\\>\n\n***\n\n### replacement()\n\n> **replacement**(`operationId`): [`CalendarReplacement`](../../replacement/classes/CalendarReplacement.md)\n\nRecover a saved replacement, including after its original event was retired.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `operationId` | `string` |\n\n#### Returns\n\n[`CalendarReplacement`](../../replacement/classes/CalendarReplacement.md)\n\n***\n\n### setTeamSharing()\n\n> **setTeamSharing**(`sharing`): `Promise`\\<[`TeamCalendarSharing`](../../../../../generated/calendar/types.gen/type-aliases/TeamCalendarSharing.md)\\>\n\nReplace the team calendar sharing preference.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `sharing` | [`TeamCalendarSharing`](../../../../../generated/calendar/types.gen/type-aliases/TeamCalendarSharing.md) |\n\n#### Returns\n\n`Promise`\\<[`TeamCalendarSharing`](../../../../../generated/calendar/types.gen/type-aliases/TeamCalendarSharing.md)\\>\n\n***\n\n### teamOutOfOffice()\n\n> **teamOutOfOffice**(`options`): `Promise`\\<\\{ `hasMore`: `boolean`; `items`: \\{ `event`: [`CalendarEvent`](../../event/classes/CalendarEvent.md); `occurrenceKey`: `string`; `owner`: [`User`](../../../users/user/classes/User.md); `time`: [`EventTime`](../../../../../generated/storage/types.gen/type-aliases/EventTime.md); `title`: `string` \\| `undefined`; \\}[]; \\}\\>\n\nTeammates' out-of-office occurrences in a bounded viewport. Check hasMore for truncation.\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `options` | \\{ `end`: `string`; `endDate?`: `string`; `limit?`: `number`; `start`: `string`; `startDate?`: `string`; \\} | - |\n| `options.end` | `string` | Exclusive UTC viewport end. |\n| `options.endDate?` | `string` | Exclusive local date boundary for all-day events. |\n| `options.limit?` | `number` | Maximum number of occurrences, from 1 through 2,000. |\n| `options.start` | `string` | Inclusive UTC viewport start. |\n| `options.startDate?` | `string` | Inclusive local date boundary for all-day events. |\n\n#### Returns\n\n`Promise`\\<\\{ `hasMore`: `boolean`; `items`: \\{ `event`: [`CalendarEvent`](../../event/classes/CalendarEvent.md); `occurrenceKey`: `string`; `owner`: [`User`](../../../users/user/classes/User.md); `time`: [`EventTime`](../../../../../generated/storage/types.gen/type-aliases/EventTime.md); `title`: `string` \\| `undefined`; \\}[]; \\}\\>\n\n***\n\n### teamPage()\n\n> **teamPage**(`options`): `Promise`\\<\\{ `items`: (\\{ `contributesToAvailability`: `boolean`; `id`: `string`; `kind`: `\"busy\"`; `owner`: [`User`](../../../users/user/classes/User.md); `time`: [`EventTime`](../../../../../generated/storage/types.gen/type-aliases/EventTime.md); \\} \\| \\{ `contributesToAvailability`: `boolean`; `details`: [`TeamCalendarDetails`](../../../../../generated/storage/types.gen/type-aliases/TeamCalendarDetails.md); `id`: `string`; `kind`: `\"details\"`; `owner`: [`User`](../../../users/user/classes/User.md); `time`: [`EventTime`](../../../../../generated/storage/types.gen/type-aliases/EventTime.md); \\})[]; `members`: \\{ `coverage`: [`TeamCalendarCoverage`](../../../../../generated/storage/types.gen/type-aliases/TeamCalendarCoverage.md); `sharing`: [`TeamCalendarSharing`](../../../../../generated/storage/types.gen/type-aliases/TeamCalendarSharing.md); `user`: [`User`](../../../users/user/classes/User.md); \\}[]; `nextCursor`: `string` \\| `undefined`; \\}\\>\n\nA page of team availability, including its roster and continuation cursor.\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `options` | \\{ `cursor?`: `string` \\| `null`; `end`: `string`; `limit?`: `number` \\| `null`; `start`: `string`; \\} | - |\n| `options.cursor?` | `string` \\| `null` | Continuation returned by the preceding page. |\n| `options.end` | `string` | Exclusive instant. |\n| `options.limit?` | `number` \\| `null` | Maximum source occurrences, at most 2,000. Zero returns the roster only. |\n| `options.start` | `string` | Inclusive instant. |\n\n#### Returns\n\n`Promise`\\<\\{ `items`: (\\{ `contributesToAvailability`: `boolean`; `id`: `string`; `kind`: `\"busy\"`; `owner`: [`User`](../../../users/user/classes/User.md); `time`: [`EventTime`](../../../../../generated/storage/types.gen/type-aliases/EventTime.md); \\} \\| \\{ `contributesToAvailability`: `boolean`; `details`: [`TeamCalendarDetails`](../../../../../generated/storage/types.gen/type-aliases/TeamCalendarDetails.md); `id`: `string`; `kind`: `\"details\"`; `owner`: [`User`](../../../users/user/classes/User.md); `time`: [`EventTime`](../../../../../generated/storage/types.gen/type-aliases/EventTime.md); \\})[]; `members`: \\{ `coverage`: [`TeamCalendarCoverage`](../../../../../generated/storage/types.gen/type-aliases/TeamCalendarCoverage.md); `sharing`: [`TeamCalendarSharing`](../../../../../generated/storage/types.gen/type-aliases/TeamCalendarSharing.md); `user`: [`User`](../../../users/user/classes/User.md); \\}[]; `nextCursor`: `string` \\| `undefined`; \\}\\>\n\n***\n\n### teamSharing()\n\n> **teamSharing**(): `Promise`\\<[`TeamCalendarSharing`](../../../../../generated/calendar/types.gen/type-aliases/TeamCalendarSharing.md)\\>\n\nCurrent sharing preference for the team calendar.\n\n#### Returns\n\n`Promise`\\<[`TeamCalendarSharing`](../../../../../generated/calendar/types.gen/type-aliases/TeamCalendarSharing.md)\\>\n\n\n<!-- src/entities/calendar/namespace/interfaces/CreateEventOptions.md -->\n# Interface: CreateEventOptions\n\nFields for a new calendar event.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attendees\"></a> `attendees?` | [`CalendarAttendeeInputBody`](../../../../../generated/calendar/types.gen/type-aliases/CalendarAttendeeInputBody.md)[] | Invited attendees. |\n| <a id=\"property-calendar\"></a> `calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) | Exact calendar to create the event on; takes precedence over the inbox default. |\n| <a id=\"property-conference\"></a> `conference?` | [`ConferenceChange`](../../../../../generated/calendar/types.gen/type-aliases/ConferenceChange.md) | Conference to attach; omit to create the event without one. |\n| <a id=\"property-description\"></a> `description?` | `string` | Optional event body. |\n| <a id=\"property-emaillink\"></a> `emailLink?` | [`Link`](../../../email/link/classes/Link.md) | Connected inbox whose primary calendar receives the event; defaults to the requester's primary inbox. |\n| <a id=\"property-guestpolicy\"></a> `guestPolicy?` | [`GuestPolicy`](../../../../../generated/calendar/types.gen/type-aliases/GuestPolicy.md) | What guests may do; omit for Google's defaults. Google calendars only. |\n| <a id=\"property-location\"></a> `location?` | `string` | Optional location label. |\n| <a id=\"property-macrocall\"></a> `macroCall?` | `boolean` | Mint a Macro call with the event; its join link lands in the description and location. Cannot be combined with `conference`. |\n| <a id=\"property-outofoffice\"></a> `outOfOffice?` | [`OutOfOfficeProperties`](../../../../../generated/calendar/types.gen/type-aliases/OutOfOfficeProperties.md) | Out-of-office properties; present to create an out-of-office event. |\n| <a id=\"property-recurrencelines\"></a> `recurrenceLines?` | `string`[] | Raw RFC 5545 recurrence properties (`RRULE`, `RDATE`, `EXDATE`). |\n| <a id=\"property-reminders\"></a> `reminders?` | [`EventReminders`](../../../../../generated/calendar/types.gen/type-aliases/EventReminders.md) | Reminder configuration; omit to keep the calendar defaults. |\n| <a id=\"property-time\"></a> `time` | [`EventTime`](../../../../../generated/calendar/types.gen/type-aliases/EventTime.md) | Timed or all-day shape. |\n| <a id=\"property-title\"></a> `title` | `string` | Display title. |\n| <a id=\"property-transparency\"></a> `transparency?` | [`EventTransparency`](../../../../../generated/calendar/types.gen/type-aliases/EventTransparency.md) | Availability behavior. |\n| <a id=\"property-visibility\"></a> `visibility?` | [`EventVisibility`](../../../../../generated/calendar/types.gen/type-aliases/EventVisibility.md) | Event visibility. |\n\n\n<!-- src/entities/calendar/note/classes/CalendarNote.md -->\n# Class: CalendarNote\n\nA markdown document linked to one meeting occurrence, with view-only access.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`MeetingNote`](../../../../../generated/calendar/types.gen/type-aliases/MeetingNote.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-canmanage\"></a> `canManage` | `readonly` | () => `Promise`\\<`boolean`\\> | Whether the caller may change this link's sharing. | - |\n| <a id=\"property-document\"></a> `document` | `readonly` | () => `Promise`\\<[`Document`](../../../documents/document/classes/Document.md)\\> | The original markdown document; unlinking never deletes it. | - |\n| <a id=\"property-event\"></a> `event` | `readonly` | [`CalendarEvent`](../../event/classes/CalendarEvent.md) | - | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | - | [`MacroEntity`](../../../entity/classes/MacroEntity.md).[`id`](../../../entity/classes/MacroEntity.md#property-id) |\n| <a id=\"property-name\"></a> `name` | `readonly` | () => `Promise`\\<`string`\\> | Current document name. | - |\n| <a id=\"property-occurrence\"></a> `occurrence` | `readonly` | `Pick`\\<[`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md), `\"eventId\"` \\| `\"occurrenceKey\"`\\> | - | - |\n| <a id=\"property-team\"></a> `team` | `readonly` | () => `Promise`\\<[`Team`](../../../teams/team/classes/Team.md) \\| `undefined`\\> | Optional extra team audience. Meeting-detail viewers already have view access. | - |\n\n## Methods\n\n### setTeam()\n\n> **setTeam**(`team?`): `Promise`\\<`void`\\>\n\nChange the extra team view grant; omit the team to remove it. Requires document ownership.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `team?` | [`Team`](../../../teams/team/classes/Team.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`MeetingNote`](../../../../../generated/calendar/types.gen/type-aliases/MeetingNote.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`MeetingNote`](../../../../../generated/calendar/types.gen/type-aliases/MeetingNote.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`MeetingNote`](../../../../../generated/calendar/types.gen/type-aliases/MeetingNote.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### unlink()\n\n> **unlink**(): `Promise`\\<`void`\\>\n\nRemove this occurrence's link and view grants, preserving the document and other sharing.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### forDocument()\n\n> `static` **forDocument**(`client`, `event`, `occurrence`, `document`): `CalendarNote`\n\nConstruct a handle for a document already linked to this occurrence.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `event` | [`CalendarEvent`](../../event/classes/CalendarEvent.md) |\n| `occurrence` | [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md) |\n| `document` | [`Document`](../../../documents/document/classes/Document.md) |\n\n#### Returns\n\n`CalendarNote`\n\n***\n\n### fromDocumentLink()\n\n> `static` **fromDocumentLink**(`client`, `document`, `link`): `CalendarNote`\n\nSeed an owner-visible link that can be revoked even if the meeting is unavailable.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `document` | [`Document`](../../../documents/document/classes/Document.md) |\n| `link` | [`DocumentNoteLink`](../../../../../generated/calendar/types.gen/type-aliases/DocumentNoteLink.md) |\n\n#### Returns\n\n`CalendarNote`\n\n***\n\n### fromRecord()\n\n> `static` **fromRecord**(`client`, `event`, `occurrence`, `record`): `CalendarNote`\n\nSeed a handle with a record returned by the meeting-note API.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `event` | [`CalendarEvent`](../../event/classes/CalendarEvent.md) |\n| `occurrence` | [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md) |\n| `record` | [`MeetingNote`](../../../../../generated/calendar/types.gen/type-aliases/MeetingNote.md) |\n\n#### Returns\n\n`CalendarNote`\n\n\n<!-- src/entities/calendar/replacement/classes/CalendarReplacement.md -->\n# Class: CalendarReplacement\n\nDurable organizer replacement, recoverable even after the original event is retired.\n\n## Constructors\n\n### Constructor\n\n> **new CalendarReplacement**(`client`, `id`): `CalendarReplacement`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`CalendarReplacement`\n\n## Properties\n\n| Property | Modifier | Type |\n| ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `readonly` | `string` |\n\n## Methods\n\n### confirm()\n\n> **confirm**(): `Promise`\\<[`CalendarReplacementView`](../../../../../generated/calendar/types.gen/type-aliases/CalendarReplacementView.md)\\>\n\nConfirm the reviewed cancellation and reinvitation, or resume that same operation.\nPresent the preview and obtain the organizer's confirmation before the first call.\n\n#### Returns\n\n`Promise`\\<[`CalendarReplacementView`](../../../../../generated/calendar/types.gen/type-aliases/CalendarReplacementView.md)\\>\n\n***\n\n### discard()\n\n> **discard**(): `Promise`\\<`void`\\>\n\nDiscard an unconfirmed preview. Confirmed operations must be recovered, not discarded.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### status()\n\n> **status**(): `Promise`\\<[`CalendarReplacementView`](../../../../../generated/calendar/types.gen/type-aliases/CalendarReplacementView.md)\\>\n\nRead progress without initiating provider writes.\n\n#### Returns\n\n`Promise`\\<[`CalendarReplacementView`](../../../../../generated/calendar/types.gen/type-aliases/CalendarReplacementView.md)\\>\n"},{"name": "calls",diff --git a/crates/calendar_events/AGENTS.md b/crates/calendar_events/AGENTS.mdindex 8e5082b250..f2ed141911 100644--- a/crates/calendar_events/AGENTS.md+++ b/crates/calendar_events/AGENTS.md@@ -123,7 +123,10 @@ reminder dispatch, team availability, and provider/Postgres persistence.and accepting calls `invite_guests` as the sharer(`src/domain/mutations/join.rs`). A declined request stands: asking againis refused with `Declined` (409 `request_declined`) and never notifies the- sharer twice.+ sharer twice. While the requester's request is pending or accepted,+ `copy_shared_event` refuses with `JoinRequestOpen`: the answer is an+ invitation under the meeting's UID, which a snapshot imported meanwhile+ would take in. A declined requester may still add a copy.- `viewer_can` is viewer-relative, like an attendee's `is_self`: resolve it with`ActorInboxes::mark_event` and the copy's source link wherever a read pathmarks the viewer, and never store it. Each connected inbox gets its own copydiff --git a/crates/calendar_events/src/domain/mutations/copy.rs b/crates/calendar_events/src/domain/mutations/copy.rsindex 3937b84e82..3e10bd8f06 100644--- a/crates/calendar_events/src/domain/mutations/copy.rs+++ b/crates/calendar_events/src/domain/mutations/copy.rs@@ -3,6 +3,7 @@use super::*;use crate::domain::{ics::{CalendarEventExport, CalendarEventExportAccess},+ join_requests::CalendarJoinRequestStatus,models::{CalendarProvider, EventType},};@@ -31,6 +32,18 @@ whereif source.access == CalendarEventExportAccess::OwnCopy {return Err(CalendarMutationError::AlreadyOnCalendar);}+ // The sharer's answer to a join request is an invitation to the+ // meeting under its own UID, which a snapshot added meanwhile would+ // take in, so a copy waits until the request is declined.+ let join_request = self+ .repository+ .find_join_request(event_id, requester_id)+ .await+ .map_err(internal)?;+ if join_request.is_some_and(|request| request.status != CalendarJoinRequestStatus::Declined)+ {+ return Err(CalendarMutationError::JoinRequestOpen);+ }// Google imports only regular events; status events such as// out-of-office belong to their owner's calendar alone.if source.event_type != EventType::Default {@@ -108,6 +121,7 @@ pub(super) fn copy_outcome(result: &Result<CalendarEvent, CalendarMutationError>match result {Ok(_) => "copied",Err(CalendarMutationError::AlreadyOnCalendar) => "already_on_calendar",+ Err(CalendarMutationError::JoinRequestOpen) => "join_request_open",Err(CalendarMutationError::NotFound) => "not_found",Err(CalendarMutationError::NoWritableCalendar) => "no_writable_calendar",Err(CalendarMutationError::ReadOnly) => "read_only",diff --git a/crates/calendar_events/src/domain/mutations/test/copy.rs b/crates/calendar_events/src/domain/mutations/test/copy.rsindex 743d1c1a66..63f14ddab1 100644--- a/crates/calendar_events/src/domain/mutations/test/copy.rs+++ b/crates/calendar_events/src/domain/mutations/test/copy.rs@@ -158,6 +158,78 @@ async fn copy_refuses_before_the_provider_when_the_event_cannot_be_copied() {}}+#[tokio::test]+async fn copy_waits_for_the_requesters_join_request_unless_it_was_declined() {+ use crate::domain::join_requests::{CalendarJoinRequest, CalendarJoinRequestStatus};+ let event_id = Uuid::now_v7();+ let cases = [+ (CalendarJoinRequestStatus::Pending, "join_request_open"),+ (CalendarJoinRequestStatus::Accepted, "join_request_open"),+ (CalendarJoinRequestStatus::Declined, "copied"),+ ];+ for (status, expected) in cases {+ let repo = shared_repo();+ repo.join_requests+ .lock()+ .unwrap()+ .push(CalendarJoinRequest {+ id: Uuid::now_v7(),+ event_id,+ requester_id: "macro|user".to_string(),+ requester_email: "[email protected]".to_string(),+ status,+ created_at: Utc::now(),+ });+ let provider = FakeProvider::new(FakeProviderBehavior::Echo);+ let imported = provider.imported.clone();++ let result = service(repo, provider, FakeTokens::ok())+ .copy_shared_event("macro|user", event_id, None)+ .await;++ assert_eq!(super::super::copy::copy_outcome(&result), expected);+ assert_eq!(+ imported.lock().unwrap().len(),+ usize::from(expected == "copied"),+ "{status:?}"+ );+ }+}++#[tokio::test]+async fn copy_ignores_join_requests_for_other_events_and_people() {+ use crate::domain::join_requests::{CalendarJoinRequest, CalendarJoinRequestStatus};+ let repo = shared_repo();+ let event_id = Uuid::now_v7();+ repo.join_requests.lock().unwrap().extend([+ CalendarJoinRequest {+ id: Uuid::now_v7(),+ event_id,+ requester_id: "macro|someone-else".to_string(),+ requester_email: "[email protected]".to_string(),+ status: CalendarJoinRequestStatus::Pending,+ created_at: Utc::now(),+ },+ CalendarJoinRequest {+ id: Uuid::now_v7(),+ event_id: Uuid::now_v7(),+ requester_id: "macro|user".to_string(),+ requester_email: "[email protected]".to_string(),+ status: CalendarJoinRequestStatus::Pending,+ created_at: Utc::now(),+ },+ ]);++ service(+ repo,+ FakeProvider::new(FakeProviderBehavior::Echo),+ FakeTokens::ok(),+ )+ .copy_shared_event("macro|user", event_id, None)+ .await+ .unwrap();+}+#[tokio::test]async fn copy_leaves_an_event_the_calendar_already_holds_and_syncs_it_in() {let target = creation_target(false);diff --git a/crates/calendar_events/src/domain/ports.rs b/crates/calendar_events/src/domain/ports.rsindex 34bea2b4b3..3f95654519 100644--- a/crates/calendar_events/src/domain/ports.rs+++ b/crates/calendar_events/src/domain/ports.rs@@ -1106,6 +1106,11 @@ pub enum CalendarMutationError {/// The meeting is already on one of the requester's calendars.#[error("the event is already on one of the requester's calendars")]AlreadyOnCalendar,+ /// The requester asked to join the shared event and the request is+ /// pending or accepted, so the meeting reaches their calendar as an+ /// invitation; a snapshot added meanwhile would take that invitation in.+ #[error("the requester has asked to join this event")]+ JoinRequestOpen,/// The provider refused to add a copy of the event to the calendar.#[error("the calendar provider refused to add a copy of the event: {0}")]CopyRefused(String),diff --git a/crates/calendar_events/src/inbound/mutation_router.rs b/crates/calendar_events/src/inbound/mutation_router.rsindex 556353fd8d..49009dfd5a 100644--- a/crates/calendar_events/src/inbound/mutation_router.rs+++ b/crates/calendar_events/src/inbound/mutation_router.rs@@ -382,6 +382,9 @@ pub enum CalendarMutationErrorCode {GuestsCannotModify,/// The meeting is already on one of the requester's calendars.AlreadyOnCalendar,+ /// The requester asked to join the event and the request is pending or+ /// accepted, so the meeting reaches their calendar as an invitation.+ JoinRequestOpen,/// The provider refused to add a copy of the event to the calendar.CopyRefused,/// The event is a snapshot of a shared meeting, so an answer or a new@@ -481,6 +484,13 @@ impl From<CalendarMutationError> for CalendarMutationApiError {CalendarMutationErrorCode::AlreadyOnCalendar,"this event is already on one of your calendars".to_string(),),+ CalendarMutationError::JoinRequestOpen => (+ StatusCode::CONFLICT,+ CalendarMutationErrorCode::JoinRequestOpen,+ "You've asked to join this event, so it reaches your calendar as an invitation \+ once you're added as a guest."+ .to_string(),+ ),CalendarMutationError::CopyRefused(_) => (StatusCode::CONFLICT,CalendarMutationErrorCode::CopyRefused,@@ -924,6 +934,9 @@ pub struct CopyCalendarEventRequest {/// one of their Google calendars and return the synced snapshot. The/// snapshot keeps the meeting's iCalendar UID and organizer, lists only the/// requester as a guest, and carries no join link; nobody is notified.+/// While the requester's request to join the event is pending or accepted,+/// the copy is refused with `join_request_open`: the meeting reaches their+/// calendar as the invitation, which a copy would otherwise take in.#[tracing::instrument(skip_all, fields(event_id = %event_id), err)]#[utoipa::path(post,@@ -937,7 +950,7 @@ pub struct CopyCalendarEventRequest {(status = 401, description = "Authentication required"),(status = 403, description = "Calendar is read-only or needs reauthorization", body = CalendarMutationApiError),(status = 404, description = "Event not found or not shared with the requester", body = CalendarMutationApiError),- (status = 409, description = "Already on the requester's calendar, no writable calendar, or the provider refused the copy", body = CalendarMutationApiError),+ (status = 409, description = "Already on the requester's calendar, a request to join it is pending or accepted, no writable calendar, or the provider refused the copy", body = CalendarMutationApiError),(status = 503, description = "Transient provider failure", body = CalendarMutationApiError),))]diff --git a/crates/calendar_events/src/inbound/toolset.rs b/crates/calendar_events/src/inbound/toolset.rsindex c39ecb265c..9e16c9160c 100644--- a/crates/calendar_events/src/inbound/toolset.rs+++ b/crates/calendar_events/src/inbound/toolset.rs@@ -589,6 +589,14 @@ fn mutation_tool_error(action: &str, error: CalendarMutationError) -> ToolCallErCalendarMutationError::AlreadyOnCalendar => {"This event is already on one of the user's calendars.".to_string()}+ CalendarMutationError::JoinRequestOpen => {+ "The user has asked the person who shared this event to add them as a guest, and \+ that request is pending or already accepted. Either way the event reaches their \+ calendar as the organizer's invitation, and a copy added meanwhile would take that \+ invitation in, so nothing was added. Tell the user they asked to join this event; a \+ copy can be added only if the request is declined."+ .to_string()+ }CalendarMutationError::CopyRefused(_) => {"Google Calendar refused to add a copy of this event to that calendar. Suggest \downloading the event's .ics file instead."diff --git a/crates/calendar_events/src/outbound/calendar_service_mutations.rs b/crates/calendar_events/src/outbound/calendar_service_mutations.rsindex 008756730b..1d20d0fc58 100644--- a/crates/calendar_events/src/outbound/calendar_service_mutations.rs+++ b/crates/calendar_events/src/outbound/calendar_service_mutations.rs@@ -162,6 +162,7 @@ fn error_from_response(status: StatusCode, body: Option<String>) -> CalendarMuta"guest_list_hidden" => CalendarMutationError::GuestListHidden,"guests_cannot_modify" => CalendarMutationError::GuestsCannotModify,"already_on_calendar" => CalendarMutationError::AlreadyOnCalendar,+ "join_request_open" => CalendarMutationError::JoinRequestOpen,"copy_refused" => CalendarMutationError::CopyRefused(error.message),"snapshot" => CalendarMutationError::Snapshot,"invalid_input" => CalendarMutationError::InvalidInput(error.message),diff --git a/crates/calendar_events/src/outbound/calendar_service_mutations/test.rs b/crates/calendar_events/src/outbound/calendar_service_mutations/test.rsindex 95594c5992..521a801010 100644--- a/crates/calendar_events/src/outbound/calendar_service_mutations/test.rs+++ b/crates/calendar_events/src/outbound/calendar_service_mutations/test.rs@@ -246,6 +246,7 @@ fn router_error_bodies_round_trip_to_their_domain_failures() {CalendarMutationError::GuestListHidden,CalendarMutationError::GuestsCannotModify,CalendarMutationError::AlreadyOnCalendar,+ CalendarMutationError::JoinRequestOpen,CalendarMutationError::InvalidInput("bad".to_string()),CalendarMutationError::ReauthRequired("expired".to_string()),CalendarMutationError::ProviderRejected("no".to_string()),diff --git a/crates/graphql_calendar/src/mutation.rs b/crates/graphql_calendar/src/mutation.rsindex 0e7b47a091..bcf472b4ae 100644--- a/crates/graphql_calendar/src/mutation.rs+++ b/crates/graphql_calendar/src/mutation.rs@@ -243,6 +243,12 @@ pub(crate) fn mutation_error(error: CalendarMutationError) -> async_graphql::Err"already_on_calendar","this event is already on one of your calendars".into(),),+ CalendarMutationError::JoinRequestOpen => (+ "join_request_open",+ "You've asked to join this event, so it reaches your calendar as an invitation once \+ you're added as a guest."+ .into(),+ ),CalendarMutationError::CopyRefused(_) => ("copy_refused","Google Calendar won't add a copy of this event to that calendar.".into(),diff --git a/crates/graphql_calendar/src/mutation/test.rs b/crates/graphql_calendar/src/mutation/test.rsindex b3eb48d712..1c6db6f9af 100644--- a/crates/graphql_calendar/src/mutation/test.rs+++ b/crates/graphql_calendar/src/mutation/test.rs@@ -818,6 +818,11 @@ async fn every_failure_carries_its_rest_code_and_hides_provider_details() {"already_on_calendar",false,),+ (+ CalendarMutationError::JoinRequestOpen,+ "join_request_open",+ false,+ ),(CalendarMutationError::InvalidInput("end before start".to_owned()),"invalid_input",diff --git a/docs/agent-guide/calendar.md b/docs/agent-guide/calendar.mdindex dee2f72f0f..3e942ad648 100644--- a/docs/agent-guide/calendar.md+++ b/docs/agent-guide/calendar.md@@ -686,7 +686,9 @@ copy whose organizer lets guests invite others and shows the guest list), and otreads `The person who shared this event can't add guests to it.` The card then shows`Requested`, and `Invited` once accepted, and stops offering `Add to calendar` until the requestis declined: the sharer's answer is an invitation to the meeting, and a snapshot added meanwhile-would take that invitation in and stay a snapshot. The sharer gets a `calendar_event_join_request`+would take that invitation in and stay a snapshot. The server refuses the copy in the same cases+(`join_request_open`, from the API, the SDK and the agent alike); a card that had not caught up+says `You've asked to join this event` and refreshes to `Requested` or `Invited`. The sharer gets a `calendar_event_join_request`notification (Settings → Notifications → Calendar → Requests to join), which Home lists as`<requester> asked to join <event>` with a person-plus glyph, like a comment row. It opens the event,whose details list each request with `Add as guest` and `Decline` on desktop and in the phonediff --git a/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/CalendarMutationErrorCode.md b/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/CalendarMutationErrorCode.mdindex e70d4d84eb..309bfdfed2 100644--- a/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/CalendarMutationErrorCode.md+++ b/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/CalendarMutationErrorCode.md@@ -1,5 +1,5 @@# Type Alias: CalendarMutationErrorCode-> **CalendarMutationErrorCode** = `"not_found"` \| `"occurrence_not_found"` \| `"read_only"` \| `"no_writable_calendar"` \| `"not_attendee"` \| `"not_organizer"` \| `"guests_cannot_invite"` \| `"guest_list_hidden"` \| `"guests_cannot_modify"` \| `"already_on_calendar"` \| `"copy_refused"` \| `"snapshot"` \| `"invalid_input"` \| `"reauth_required"` \| `"provider_rejected"` \| `"retryable"` \| `"persist_failed"` \| `"macro_call_failed"`+> **CalendarMutationErrorCode** = `"not_found"` \| `"occurrence_not_found"` \| `"read_only"` \| `"no_writable_calendar"` \| `"not_attendee"` \| `"not_organizer"` \| `"guests_cannot_invite"` \| `"guest_list_hidden"` \| `"guests_cannot_modify"` \| `"already_on_calendar"` \| `"join_request_open"` \| `"copy_refused"` \| `"snapshot"` \| `"invalid_input"` \| `"reauth_required"` \| `"provider_rejected"` \| `"retryable"` \| `"persist_failed"` \| `"macro_call_failed"`Machine-readable failure category for calendar mutations.diff --git a/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/CopyCalendarEventErrors.md b/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/CopyCalendarEventErrors.mdindex 5fda9ca324..58ceceb8a8 100644--- a/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/CopyCalendarEventErrors.md+++ b/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/CopyCalendarEventErrors.md@@ -10,5 +10,5 @@| <a id="property-401"></a> `401` | `unknown` | Authentication required || <a id="property-403"></a> `403` | [`CalendarMutationApiError`](CalendarMutationApiError.md) | Calendar is read-only or needs reauthorization || <a id="property-404"></a> `404` | [`CalendarMutationApiError`](CalendarMutationApiError.md) | Event not found or not shared with the requester |-| <a id="property-409"></a> `409` | [`CalendarMutationApiError`](CalendarMutationApiError.md) | Already on the requester's calendar, no writable calendar, or the provider refused the copy |+| <a id="property-409"></a> `409` | [`CalendarMutationApiError`](CalendarMutationApiError.md) | Already on the requester's calendar, a request to join it is pending or accepted, no writable calendar, or the provider refused the copy || <a id="property-503"></a> `503` | [`CalendarMutationApiError`](CalendarMutationApiError.md) | Transient provider failure |diff --git a/packages/sdk-docs/reference/src/entities/calendar/event/classes/CalendarEvent.md b/packages/sdk-docs/reference/src/entities/calendar/event/classes/CalendarEvent.mdindex d24b3afe88..365c8e1887 100644--- a/packages/sdk-docs/reference/src/entities/calendar/event/classes/CalendarEvent.md+++ b/packages/sdk-docs/reference/src/entities/calendar/event/classes/CalendarEvent.md@@ -44,7 +44,9 @@ synced snapshot. The snapshot keeps the meeting's iCalendar UID andorganizer, lists only the requester as a guest, and carries no join link;nobody is notified, and answers or guests on it never reach the meeting.Refused with `already_on_calendar` when the meeting is already on one of-their calendars, and with `copy_refused` when Google will not import it.+their calendars, with `join_request_open` while their request to join it+is pending or accepted (the meeting then arrives as an invitation), and+with `copy_refused` when Google will not import it.#### Parametersdiff --git a/packages/sdk/generated/calendar/sdk.gen.ts b/packages/sdk/generated/calendar/sdk.gen.tsindex 3b3a3deb5b..a2d98fa499 100644--- a/packages/sdk/generated/calendar/sdk.gen.ts+++ b/packages/sdk/generated/calendar/sdk.gen.ts@@ -125,6 +125,9 @@ export class Sdk extends HeyApiClient {* one of their Google calendars and return the synced snapshot. The* snapshot keeps the meeting's iCalendar UID and organizer, lists only the* requester as a guest, and carries no join link; nobody is notified.+ * While the requester's request to join the event is pending or accepted,+ * the copy is refused with `join_request_open`: the meeting reaches their+ * calendar as the invitation, which a copy would otherwise take in.*/public copyCalendarEvent<ThrowOnError extends boolean = false>(options: Options<CopyCalendarEventData, ThrowOnError>): RequestResult<CopyCalendarEventResponses, CopyCalendarEventErrors, ThrowOnError> {return (options.client ?? this.client).post<CopyCalendarEventResponses, CopyCalendarEventErrors, ThrowOnError>({diff --git a/packages/sdk/generated/calendar/types.gen.ts b/packages/sdk/generated/calendar/types.gen.tsindex 2b9f9a4675..90316dbe17 100644--- a/packages/sdk/generated/calendar/types.gen.ts+++ b/packages/sdk/generated/calendar/types.gen.ts@@ -411,7 +411,7 @@ export type CalendarMutationApiError = {/*** Machine-readable failure category for calendar mutations.*/-export type CalendarMutationErrorCode = 'not_found' | 'occurrence_not_found' | 'read_only' | 'no_writable_calendar' | 'not_attendee' | 'not_organizer' | 'guests_cannot_invite' | 'guest_list_hidden' | 'guests_cannot_modify' | 'already_on_calendar' | 'copy_refused' | 'snapshot' | 'invalid_input' | 'reauth_required' | 'provider_rejected' | 'retryable' | 'persist_failed' | 'macro_call_failed';+export type CalendarMutationErrorCode = 'not_found' | 'occurrence_not_found' | 'read_only' | 'no_writable_calendar' | 'not_attendee' | 'not_organizer' | 'guests_cannot_invite' | 'guest_list_hidden' | 'guests_cannot_modify' | 'already_on_calendar' | 'join_request_open' | 'copy_refused' | 'snapshot' | 'invalid_input' | 'reauth_required' | 'provider_rejected' | 'retryable' | 'persist_failed' | 'macro_call_failed';/*** Provider selected from the persisted calendar account and email binding.@@ -1288,7 +1288,7 @@ export type CopyCalendarEventErrors = {*/404: CalendarMutationApiError;/**- * Already on the requester's calendar, no writable calendar, or the provider refused the copy+ * Already on the requester's calendar, a request to join it is pending or accepted, no writable calendar, or the provider refused the copy*/409: CalendarMutationApiError;/**diff --git a/packages/sdk/specs/calendar.json b/packages/sdk/specs/calendar.jsonindex f6fe893dee..6f32e7f503 100644--- a/packages/sdk/specs/calendar.json+++ b/packages/sdk/specs/calendar.json@@ -355,7 +355,7 @@"/events/{event_id}/copy": {"post": {"tags": ["calendar_events"],- "summary": "Add a snapshot of an event shared with one of the requester's channels to\none of their Google calendars and return the synced snapshot. The\nsnapshot keeps the meeting's iCalendar UID and organizer, lists only the\nrequester as a guest, and carries no join link; nobody is notified.",+ "summary": "Add a snapshot of an event shared with one of the requester's channels to\none of their Google calendars and return the synced snapshot. The\nsnapshot keeps the meeting's iCalendar UID and organizer, lists only the\nrequester as a guest, and carries no join link; nobody is notified.\nWhile the requester's request to join the event is pending or accepted,\nthe copy is refused with `join_request_open`: the meeting reaches their\ncalendar as the invitation, which a copy would otherwise take in.","operationId": "copy_calendar_event","parameters": [{@@ -424,7 +424,7 @@}},"409": {- "description": "Already on the requester's calendar, no writable calendar, or the provider refused the copy",+ "description": "Already on the requester's calendar, a request to join it is pending or accepted, no writable calendar, or the provider refused the copy","content": {"application/json": {"schema": {@@ -1685,6 +1685,7 @@"guest_list_hidden","guests_cannot_modify","already_on_calendar",+ "join_request_open","copy_refused","snapshot","invalid_input",diff --git a/packages/sdk/src/entities/calendar/event.ts b/packages/sdk/src/entities/calendar/event.tsindex b226fc9c4c..a7ea76eea5 100644--- a/packages/sdk/src/entities/calendar/event.ts+++ b/packages/sdk/src/entities/calendar/event.ts@@ -305,7 +305,9 @@ export class CalendarEvent extends MacroEntity<CalendarEventRecord> {* organizer, lists only the requester as a guest, and carries no join link;* nobody is notified, and answers or guests on it never reach the meeting.* Refused with `already_on_calendar` when the meeting is already on one of- * their calendars, and with `copy_refused` when Google will not import it. */+ * their calendars, with `join_request_open` while their request to join it+ * is pending or accepted (the meeting then arrives as an invitation), and+ * with `copy_refused` when Google will not import it. */async addToCalendar(options: { calendar?: Calendar } = {},): Promise<CalendarEvent> {