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): make agents ask which inbox's copy before changing it (#8765)
gbirman04865ec0df60
diff --git a/apps/docs/AI/mcp/tools/delete-calendar-event.mdx b/apps/docs/AI/mcp/tools/delete-calendar-event.mdxindex 5f3d5d4aa3..68f30586f1 100644--- a/apps/docs/AI/mcp/tools/delete-calendar-event.mdx+++ b/apps/docs/AI/mcp/tools/delete-calendar-event.mdx@@ -6,11 +6,13 @@ description: >-# DeleteCalendarEvent-Delete an event from the user's calendar. The deletion is written to the calendar provider immediately and attendees are notified, so confirm with the user before deleting — it cannot be undone. Get the `eventId` from ListCalendarEvents.+Delete an event from the user's calendar.-For recurring events, `scope` controls how much is removed: "all" (default) removes the whole series, "this_event" removes one occurrence, and "this_and_following" ends the series from an occurrence onward. The scoped variants require `recurrenceId` from the targeted occurrence's ListCalendarEvents entry.+A meeting on more than one of the user's inboxes is one ListCalendarEvents entry per inbox. Before deleting any of them, ask the user which inbox's copy to delete, then pass that copy's `inbox`. Never choose between the user's inboxes yourself, whatever they look like: a test, secondary or unfamiliar address is still the user's own inbox. Skip the question only when the user already named the inbox, or when only one copy can be deleted (`isReadOnly` false); then delete that copy and say why. Without `inbox` the tool refuses, lists each copy and gives the question to ask. Deleting the copy the user organizes cancels the meeting for every guest. Deleting a copy where they are a guest takes the meeting off that inbox's calendar: on Google it also declines the invitation and tells the organizer, while on Outlook the organizer is not told and still sees the invitation unanswered.++The deletion is written to the calendar provider immediately and attendees are notified, so confirm with the user before deleting — it cannot be undone. Get the `eventId` from ListCalendarEvents.-When the meeting is on several of the user's inboxes (one ListCalendarEvents entry per inbox), the tool refuses until `inbox` names the inbox of the copy to delete, and lists each copy. Ask which inbox's copy to delete unless the user named one or only one copy is writable (`isReadOnly` false), in which case delete that one, pass its `inbox` and say why. Deleting the copy the user organizes cancels the meeting for every guest. Deleting a copy where they are a guest takes the meeting off that inbox's calendar: on Google it also declines the invitation and tells the organizer, while on Outlook the organizer is not told and still sees the invitation unanswered.+For recurring events, `scope` controls how much is removed: "all" (default) removes the whole series, "this_event" removes one occurrence, and "this_and_following" ends the series from an occurrence onward. The scoped variants require `recurrenceId` from the targeted occurrence's ListCalendarEvents entry.## Parametersdiff --git a/apps/docs/AI/mcp/tools/list-calendar-events.mdx b/apps/docs/AI/mcp/tools/list-calendar-events.mdxindex 0b57111377..62bda20184 100644--- a/apps/docs/AI/mcp/tools/list-calendar-events.mdx+++ b/apps/docs/AI/mcp/tools/list-calendar-events.mdx@@ -13,7 +13,7 @@ Use this to answer questions about the user's schedule ("what's on my calendar tEach entry names the calendar (`calendarName`) and connected inbox (`inbox`) holding that copy of the event, and `myRole` says whether the user organizes it or is a guest there. A meeting on several of the user's inboxes appears once per inbox, each with its own `eventId`, and what the user may do can differ between them. When asking which one the user means, describe each by its inbox and role, never by id; when the user names an inbox, act on the entry whose `inbox` matches.-When the user does not name an inbox, choose the copy by what the change does. Reminders belong to one copy only, so set them on one copy without asking and say which inbox you used. Answer an invitation on the copy where the user is a guest; when they are a guest through more than one inbox, ask which inbox answers, since each answers only for itself. Any other change reaches the meeting differently from each copy: the title, time, description, location, recurrence or conference, adding or removing guests, guest permissions, and deleting. UpdateCalendarEvent and DeleteCalendarEvent refuse such a change on a meeting held by several of the user's inboxes until `inbox` names the inbox of the copy being changed, and the refusal lists each copy. If only one copy allows the change (`viewerCan`, or for deleting, `isReadOnly` false), use that copy with its `inbox` and say why (for example, only the copy the user organizes can move the meeting). If more than one can, ask which inbox, saying what the change would do from each. Add guests from the copy the user organizes when there is one: it invites them directly, while a guest's copy invites only as far as the organizer allows. Deleting the organizer's copy cancels the meeting for everyone, while deleting a guest's copy takes the meeting off that inbox's calendar and, on Google, also declines the invitation and tells the organizer.+When the user does not name an inbox, choose the copy by what the change does. Reminders belong to one copy only, so set them on one copy without asking and say which inbox you used. Answer an invitation on the copy where the user is a guest; when they are a guest through more than one inbox, ask which inbox answers, since each answers only for itself. Any other change reaches the meeting differently from each copy: the title, time, description, location, recurrence or conference, adding or removing guests, guest permissions, and deleting. UpdateCalendarEvent and DeleteCalendarEvent refuse such a change on a meeting held by several of the user's inboxes until `inbox` names the inbox of the copy being changed, and the refusal lists each copy. If only one copy allows the change (`viewerCan`, or for deleting, `isReadOnly` false), use that copy with its `inbox` and say why (for example, only the copy the user organizes can move the meeting). If more than one can, ask which inbox, saying what the change would do from each, and never choose between the user's inboxes yourself, whatever they look like. Add guests from the copy the user organizes when there is one: it invites them directly, while a guest's copy invites only as far as the organizer allows. Deleting the organizer's copy cancels the meeting for everyone, while deleting a guest's copy takes the meeting off that inbox's calendar and, on Google, also declines the invitation and tells the organizer.## Parametersdiff --git a/apps/docs/AI/mcp/tools/update-calendar-event.mdx b/apps/docs/AI/mcp/tools/update-calendar-event.mdxindex 00d61a3e19..2bb838275c 100644--- a/apps/docs/AI/mcp/tools/update-calendar-event.mdx+++ b/apps/docs/AI/mcp/tools/update-calendar-event.mdx@@ -6,7 +6,11 @@ description: >-# UpdateCalendarEvent-Update an existing calendar event. Only the supplied fields change; omitted fields keep their current values. The change is written to the calendar provider immediately and attendees are notified of it, so confirm details with the user first. Get the `eventId` from ListCalendarEvents.+Update an existing calendar event.++A meeting on more than one of the user's inboxes is one ListCalendarEvents entry per inbox. Before changing its details, guests or guest permissions, ask the user which inbox's copy to change, then pass that copy's `inbox`. Never choose between the user's inboxes yourself, whatever they look like: a test, secondary or unfamiliar address is still the user's own inbox. Skip the question only when the user already named the inbox, when only one copy's `viewerCan` allows the change (use it and say why), or when adding guests to a meeting the user organizes from one of the inboxes (add them from that copy and say why). Reminders may go to one copy and an `rsvp` to the copy where the user is a guest, naming the inbox in your reply. Without `inbox` the tool refuses, lists each copy and gives the question to ask. One call changes one copy, so an edit on one copy and an `rsvp` on another take two calls.++Only the supplied fields change; omitted fields keep their current values. The change is written to the calendar provider immediately and attendees are notified of it, so confirm details with the user first. Get the `eventId` from ListCalendarEvents.`scope` picks how much of a recurring series changes and is always required: "this_event" edits one occurrence (pass the occurrence's `recurrenceId` from ListCalendarEvents) and leaves the rest of the series alone; "all" edits the series itself — with `time` that MOVES EVERY OCCURRENCE, so never use "all" to reschedule a single occurrence. Non-recurring events use "all". There is no this-and-following update: end the series with DeleteCalendarEvent's "this_and_following" and create a new event instead.@@ -16,8 +20,6 @@ A guest without modify rights (`viewerCan.editDetails` false while `viewerCan.rs`rsvp` sets the user's own response to an invitation and is independent of the field edits — it can be the only thing this call changes. It applies at the same `scope` as the rest of the call and answers as the connected inbox the event's copy belongs to, so it only works when that inbox is an attendee.-When the meeting is on several of the user's inboxes, ListCalendarEvents lists one entry per inbox; pick the copy by its rule. Reminders may go to one copy and an `rsvp` to the copy where the user is a guest, naming the inbox in your reply. Any other change needs `inbox`, the inbox of the copy it changes; without it the tool refuses and lists each copy. Use the only copy whose `viewerCan` allows the change, with the reason, or the copy the user chooses when more than one could make it, and add guests from the copy the user organizes when there is one. One call changes one copy, so an edit on one copy and an `rsvp` on another take two calls.-## Parameters| Parameter | Type | Required | Description |diff --git a/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts b/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.tsindex cf9c50eafb..d16e1857d2 100644--- a/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts+++ b/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts@@ -8339,11 +8339,13 @@ export interface DeleteBotResponse {summary: string;}/**- * Delete an event from the user's calendar. The deletion is written to the calendar provider immediately and attendees are notified, so confirm with the user before deleting — it cannot be undone. Get the `eventId` from ListCalendarEvents.+ * Delete an event from the user's calendar.*- * For recurring events, `scope` controls how much is removed: "all" (default) removes the whole series, "this_event" removes one occurrence, and "this_and_following" ends the series from an occurrence onward. The scoped variants require `recurrenceId` from the targeted occurrence's ListCalendarEvents entry.+ * A meeting on more than one of the user's inboxes is one ListCalendarEvents entry per inbox. Before deleting any of them, ask the user which inbox's copy to delete, then pass that copy's `inbox`. Never choose between the user's inboxes yourself, whatever they look like: a test, secondary or unfamiliar address is still the user's own inbox. Skip the question only when the user already named the inbox, or when only one copy can be deleted (`isReadOnly` false); then delete that copy and say why. Without `inbox` the tool refuses, lists each copy and gives the question to ask. Deleting the copy the user organizes cancels the meeting for every guest. Deleting a copy where they are a guest takes the meeting off that inbox's calendar: on Google it also declines the invitation and tells the organizer, while on Outlook the organizer is not told and still sees the invitation unanswered.+ *+ * The deletion is written to the calendar provider immediately and attendees are notified, so confirm with the user before deleting — it cannot be undone. Get the `eventId` from ListCalendarEvents.*- * When the meeting is on several of the user's inboxes (one ListCalendarEvents entry per inbox), the tool refuses until `inbox` names the inbox of the copy to delete, and lists each copy. Ask which inbox's copy to delete unless the user named one or only one copy is writable (`isReadOnly` false), in which case delete that one, pass its `inbox` and say why. Deleting the copy the user organizes cancels the meeting for every guest. Deleting a copy where they are a guest takes the meeting off that inbox's calendar: on Google it also declines the invitation and tells the organizer, while on Outlook the organizer is not told and still sees the invitation unanswered.+ * For recurring events, `scope` controls how much is removed: "all" (default) removes the whole series, "this_event" removes one occurrence, and "this_and_following" ends the series from an occurrence onward. The scoped variants require `recurrenceId` from the targeted occurrence's ListCalendarEvents entry.*/export interface DeleteCalendarEvent {/**@@ -11239,7 +11241,7 @@ export interface ListBotsResponse {** Each entry names the calendar (`calendarName`) and connected inbox (`inbox`) holding that copy of the event, and `myRole` says whether the user organizes it or is a guest there. A meeting on several of the user's inboxes appears once per inbox, each with its own `eventId`, and what the user may do can differ between them. When asking which one the user means, describe each by its inbox and role, never by id; when the user names an inbox, act on the entry whose `inbox` matches.*- * When the user does not name an inbox, choose the copy by what the change does. Reminders belong to one copy only, so set them on one copy without asking and say which inbox you used. Answer an invitation on the copy where the user is a guest; when they are a guest through more than one inbox, ask which inbox answers, since each answers only for itself. Any other change reaches the meeting differently from each copy: the title, time, description, location, recurrence or conference, adding or removing guests, guest permissions, and deleting. UpdateCalendarEvent and DeleteCalendarEvent refuse such a change on a meeting held by several of the user's inboxes until `inbox` names the inbox of the copy being changed, and the refusal lists each copy. If only one copy allows the change (`viewerCan`, or for deleting, `isReadOnly` false), use that copy with its `inbox` and say why (for example, only the copy the user organizes can move the meeting). If more than one can, ask which inbox, saying what the change would do from each. Add guests from the copy the user organizes when there is one: it invites them directly, while a guest's copy invites only as far as the organizer allows. Deleting the organizer's copy cancels the meeting for everyone, while deleting a guest's copy takes the meeting off that inbox's calendar and, on Google, also declines the invitation and tells the organizer.+ * When the user does not name an inbox, choose the copy by what the change does. Reminders belong to one copy only, so set them on one copy without asking and say which inbox you used. Answer an invitation on the copy where the user is a guest; when they are a guest through more than one inbox, ask which inbox answers, since each answers only for itself. Any other change reaches the meeting differently from each copy: the title, time, description, location, recurrence or conference, adding or removing guests, guest permissions, and deleting. UpdateCalendarEvent and DeleteCalendarEvent refuse such a change on a meeting held by several of the user's inboxes until `inbox` names the inbox of the copy being changed, and the refusal lists each copy. If only one copy allows the change (`viewerCan`, or for deleting, `isReadOnly` false), use that copy with its `inbox` and say why (for example, only the copy the user organizes can move the meeting). If more than one can, ask which inbox, saying what the change would do from each, and never choose between the user's inboxes yourself, whatever they look like. Add guests from the copy the user organizes when there is one: it invites them directly, while a guest's copy invites only as far as the organizer allows. Deleting the organizer's copy cancels the meeting for everyone, while deleting a guest's copy takes the meeting off that inbox's calendar and, on Google, also declines the invitation and tells the organizer.*/export interface ListCalendarEvents {/**@@ -15477,7 +15479,11 @@ export interface UpdateBookingSettings {userConfirmation: string;}/**- * Update an existing calendar event. Only the supplied fields change; omitted fields keep their current values. The change is written to the calendar provider immediately and attendees are notified of it, so confirm details with the user first. Get the `eventId` from ListCalendarEvents.+ * Update an existing calendar event.+ *+ * A meeting on more than one of the user's inboxes is one ListCalendarEvents entry per inbox. Before changing its details, guests or guest permissions, ask the user which inbox's copy to change, then pass that copy's `inbox`. Never choose between the user's inboxes yourself, whatever they look like: a test, secondary or unfamiliar address is still the user's own inbox. Skip the question only when the user already named the inbox, when only one copy's `viewerCan` allows the change (use it and say why), or when adding guests to a meeting the user organizes from one of the inboxes (add them from that copy and say why). Reminders may go to one copy and an `rsvp` to the copy where the user is a guest, naming the inbox in your reply. Without `inbox` the tool refuses, lists each copy and gives the question to ask. One call changes one copy, so an edit on one copy and an `rsvp` on another take two calls.+ *+ * Only the supplied fields change; omitted fields keep their current values. The change is written to the calendar provider immediately and attendees are notified of it, so confirm details with the user first. Get the `eventId` from ListCalendarEvents.** `scope` picks how much of a recurring series changes and is always required: "this_event" edits one occurrence (pass the occurrence's `recurrenceId` from ListCalendarEvents) and leaves the rest of the series alone; "all" edits the series itself — with `time` that MOVES EVERY OCCURRENCE, so never use "all" to reschedule a single occurrence. Non-recurring events use "all". There is no this-and-following update: end the series with DeleteCalendarEvent's "this_and_following" and create a new event instead.*@@ -15486,8 +15492,6 @@ export interface UpdateBookingSettings {* A guest without modify rights (`viewerCan.editDetails` false while `viewerCan.rsvp` is true) may only change their own `reminders`, add guests where `viewerCan.inviteGuests` allows it, and answer with `rsvp`; changing the title, time, description, location, recurrence or conference fails because the organizer doesn't let guests change the event.** `rsvp` sets the user's own response to an invitation and is independent of the field edits — it can be the only thing this call changes. It applies at the same `scope` as the rest of the call and answers as the connected inbox the event's copy belongs to, so it only works when that inbox is an attendee.- *- * When the meeting is on several of the user's inboxes, ListCalendarEvents lists one entry per inbox; pick the copy by its rule. Reminders may go to one copy and an `rsvp` to the copy where the user is a guest, naming the inbox in your reply. Any other change needs `inbox`, the inbox of the copy it changes; without it the tool refuses and lists each copy. Use the only copy whose `viewerCan` allows the change, with the reason, or the copy the user chooses when more than one could make it, and add guests from the copy the user organizes when there is one. One call changes one copy, so an edit on one copy and an `rsvp` on another take two calls.*/export interface UpdateCalendarEvent {/**diff --git a/crates/agent_code_mode/src/domain/documentation.json b/crates/agent_code_mode/src/domain/documentation.jsonindex 925597fdee..00daf6b36b 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); `inbox`: `string` \\| `undefined`; `occurrence`: [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md); `role`: [`CalendarEventRole`](../type-aliases/CalendarEventRole.md) \\| `undefined`; \\}, `any`, `any`\\>\n\nCalendar occurrences in a viewport, automatically paginated. Each names\nthe address of the connected inbox holding that copy of the event\n(`inbox`) and whether the user organizes it or is a guest there (`role`,\nabsent when neither). A meeting on several of the user's inboxes appears\nonce per inbox, each with its own event; describe them by inbox and role,\nnever by id, and pass the chosen copy's `inbox` to its `update`,\n`inviteGuests` or `delete`.\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); `inbox`: `string` \\| `undefined`; `occurrence`: [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md); `role`: [`CalendarEventRole`](../type-aliases/CalendarEventRole.md) \\| `undefined`; \\}, `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/namespace/type-aliases/CalendarEventRole.md -->\n# Type Alias: CalendarEventRole\n\n> **CalendarEventRole** = `\"organizer\"` \\| `\"guest\"`\n\nWhat the user is on one copy of an event, through the inbox holding it:\nits organizer (or the owner of an event without guests), or a guest.\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\nDeleting the copy the user organizes cancels the meeting for every guest.\nDeleting a copy where they are a guest takes the meeting off that inbox's\ncalendar: on Google it also declines the invitation and tells the\norganizer, while on Outlook the organizer is not told and still sees the\ninvitation unanswered. When the meeting is on several of the user's\ninboxes, ask which inbox's copy to delete unless the user named one or\nonly one copy is writable, and pass that copy's `inbox`; without it the\ncall is refused with `copy_choice_required`, listing each copy.\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. When the meeting is on several of the user's inboxes,\nadd from the copy the user organizes when there is one (it invites\ndirectly, while a guest's copy invites only as far as the organizer\nallows), else ask which inbox, and pass that copy's `inbox`; without it\nthe call is refused with `copy_choice_required`, listing each copy.\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\nA meeting on several of the user's inboxes is one event per inbox, each\nwith its own id (see the occurrence listing's `inbox` and `role`).\nReminders belong to one copy, so set them on one copy and say which inbox\nyou used; any other change reaches the meeting differently from each copy.\nUse the only copy whose `viewerCan` allows the change and say why, or ask\nthe user which inbox's copy to change when more than one could make it,\nand add guests from the copy the user organizes when there is one. Pass\nthe chosen copy's `inbox`; without it the call is refused with\n`copy_choice_required`, listing each copy.\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-inbox\"></a> `inbox?` | `string` | Address of the inbox holding the copy this call deletes (an occurrence listing's `inbox`). When the meeting is on more than one of the user's inboxes, an agent must name it: the call is refused with `copy_choice_required`, listing each copy's inbox, role and event, until it does. It must be the inbox holding this 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-inbox\"></a> `inbox?` | `string` | Address of the inbox holding the copy this call changes (an occurrence listing's `inbox`). When the meeting is on more than one of the user's inboxes, an agent must name it: the call is refused with `copy_choice_required`, listing each copy's inbox, role and event, until it does. It must be the inbox holding this copy. |\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-inbox\"></a> `inbox?` | `string` | Address of the inbox holding the copy this call changes (an occurrence listing's `inbox`). When the meeting is on more than one of the user's inboxes, an agent must name it: the call is refused with `copy_choice_required`, listing each copy's inbox, role and event, until it does. It must be the inbox holding this copy. |\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); `inbox`: `string` \\| `undefined`; `occurrence`: [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md); `role`: [`CalendarEventRole`](../type-aliases/CalendarEventRole.md) \\| `undefined`; \\}, `any`, `any`\\>\n\nCalendar occurrences in a viewport, automatically paginated. Each names\nthe address of the connected inbox holding that copy of the event\n(`inbox`) and whether the user organizes it or is a guest there (`role`,\nabsent when neither). A meeting on several of the user's inboxes appears\nonce per inbox, each with its own event; describe them by inbox and role,\nnever by id, and pass the chosen copy's `inbox` to its `update`,\n`inviteGuests` or `delete`.\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); `inbox`: `string` \\| `undefined`; `occurrence`: [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md); `role`: [`CalendarEventRole`](../type-aliases/CalendarEventRole.md) \\| `undefined`; \\}, `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/namespace/type-aliases/CalendarEventRole.md -->\n# Type Alias: CalendarEventRole\n\n> **CalendarEventRole** = `\"organizer\"` \\| `\"guest\"`\n\nWhat the user is on one copy of an event, through the inbox holding it:\nits organizer (or the owner of an event without guests), or a guest.\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\nA meeting on more than one of the user's inboxes is one event per inbox.\nBefore deleting any of them, ask the user which inbox's copy to delete,\nthen pass that copy's `inbox`. Never choose between the user's inboxes\nyourself, whatever they look like: a test, secondary or unfamiliar address\nis still the user's own inbox. Skip the question only when the user\nalready named the inbox, or when only one copy can be deleted; then delete\nthat copy and say why. Without `inbox` the call is refused with\n`copy_choice_required`, listing each copy and the question to ask.\n\nDeleting the copy the user organizes cancels the meeting for every guest.\nDeleting a copy where they are a guest takes the meeting off that inbox's\ncalendar: on Google it also declines the invitation and tells the\norganizer, while on Outlook the organizer is not told and still sees the\ninvitation unanswered.\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.\n\nWhen the meeting is on more than one of the user's inboxes, add from the\ncopy the user organizes when there is one (it invites directly, while a\nguest's copy invites only as far as the organizer allows) and say why;\notherwise ask the user which inbox's copy to add them from. Never choose\nbetween the user's inboxes any other way, whatever they look like. Pass\nthat copy's `inbox`; without it the call is refused with\n`copy_choice_required`, listing each copy and the question to ask.\n\nThe organizer may add guests, and so may a guest the organizer lets\ninvite others (see [CalendarEvent.viewerCan](#property-viewercan)); Google emails the\nnew 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\nA meeting on more than one of the user's inboxes is one event per inbox,\neach with its own id (see the occurrence listing's `inbox` and `role`).\nBefore changing its details, guests or guest permissions, ask the user\nwhich inbox's copy to change, then pass that copy's `inbox`. Never choose\nbetween the user's inboxes yourself, whatever they look like: a test,\nsecondary or unfamiliar address is still the user's own inbox. Skip the\nquestion only when the user already named the inbox, when only one copy's\n`viewerCan` allows the change (use it and say why), or when adding guests\nto a meeting the user organizes from one of the inboxes (add them from\nthat copy and say why). Reminders belong to one copy, so set them on one\ncopy and say which inbox you used. Without `inbox` the call is refused\nwith `copy_choice_required`, listing each copy and the question to ask.\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-inbox\"></a> `inbox?` | `string` | Address of the inbox holding the copy this call deletes (an occurrence listing's `inbox`). When the meeting is on more than one of the user's inboxes, an agent must name it: the call is refused with `copy_choice_required`, listing each copy's inbox, role and event, until it does. It must be the inbox holding this 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-inbox\"></a> `inbox?` | `string` | Address of the inbox holding the copy this call changes (an occurrence listing's `inbox`). When the meeting is on more than one of the user's inboxes, an agent must name it: the call is refused with `copy_choice_required`, listing each copy's inbox, role and event, until it does. It must be the inbox holding this copy. |\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-inbox\"></a> `inbox?` | `string` | Address of the inbox holding the copy this call changes (an occurrence listing's `inbox`). When the meeting is on more than one of the user's inboxes, an agent must name it: the call is refused with `copy_choice_required`, listing each copy's inbox, role and event, until it does. It must be the inbox holding this copy. |\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); `inbox`: `string` \\| `undefined`; `occurrence`: [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md); `role`: [`CalendarEventRole`](../type-aliases/CalendarEventRole.md) \\| `undefined`; \\}, `any`, `any`\\>\n\nCalendar occurrences in a viewport, automatically paginated. Each names\nthe address of the connected inbox holding that copy of the event\n(`inbox`) and whether the user organizes it or is a guest there (`role`,\nabsent when neither). A meeting on several of the user's inboxes appears\nonce per inbox, each with its own event; describe them by inbox and role,\nnever by id, and pass the chosen copy's `inbox` to its `update`,\n`inviteGuests` or `delete`.\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); `inbox`: `string` \\| `undefined`; `occurrence`: [`CalendarOccurrence`](../../../../../generated/storage/types.gen/type-aliases/CalendarOccurrence.md); `role`: [`CalendarEventRole`](../type-aliases/CalendarEventRole.md) \\| `undefined`; \\}, `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/namespace/type-aliases/CalendarEventRole.md -->\n# Type Alias: CalendarEventRole\n\n> **CalendarEventRole** = `\"organizer\"` \\| `\"guest\"`\n\nWhat the user is on one copy of an event, through the inbox holding it:\nits organizer (or the owner of an event without guests), or a guest.\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 f565bbd64a..2e20421f8b 100644--- a/crates/calendar_events/AGENTS.md+++ b/crates/calendar_events/AGENTS.md@@ -163,10 +163,15 @@ reminder dispatch, team availability, and provider/Postgres persistence.through several inboxes); a change whose effect differs by copy (details,guests, permissions, deleting) goes to the only copy allowed to make it, withthe reason, or the agent asks, and guests are added from the copy the user- organizes. `domain::copies::check_copy` enforces it: such a change on a- meeting the user holds through several of their own inboxes- (`meeting_copies`) is refused, listing each copy, until `inbox` names the- addressed copy's inbox. UpdateCalendarEvent and DeleteCalendarEvent check+ organizes. The agent must never choose between the user's inboxes itself,+ whatever they look like: the SDK delete and update docs and the+ DeleteCalendarEvent and UpdateCalendarEvent descriptions state the ask rule+ first. `domain::copies::check_copy` enforces it: such a change on a meeting+ the user holds through several of their own inboxes (`meeting_copies`) is+ refused, listing each copy and ending with the question to ask word for+ word, until `inbox` names the addressed copy's inbox. The route cannot tell+ an inbox the user chose from one the agent picked, so the wording is the+ only guard against a guess. UpdateCalendarEvent and DeleteCalendarEvent checkevery call; the update, invite-guests and delete routes check agent runs andany request naming `inbox` through `CalendarCopyConfirmation`, answering 409`copy_choice_required`. An agent run is a token with `agent_id` (in-app codediff --git a/crates/calendar_events/src/domain/copies.rs b/crates/calendar_events/src/domain/copies.rsindex 4a8480f9df..1c5daa5101 100644--- a/crates/calendar_events/src/domain/copies.rs+++ b/crates/calendar_events/src/domain/copies.rs@@ -13,12 +13,14 @@ use super::models::MeetingCopy;/// user's copies makes it.#[derive(Clone, Copy, Debug, PartialEq, Eq)]pub enum CopyChange {- /// Details, guests or guest permissions; `adds_guests` when the change- /// carries guests to add.+ /// Details, guest permissions or the guest list; `changes_guests` when+ /// the change carries a guest list, which may invite or remove guests.Update {- /// Whether the change adds guests.- adds_guests: bool,+ /// Whether the change carries a guest list.+ changes_guests: bool,},+ /// Adding guests without touching anyone already invited.+ InviteGuests,/// Deleting the copy.Delete,}@@ -80,7 +82,8 @@ pub fn check_copy(}/// What the caller needs to ask which copy to change: each copy's inbox,-/// role and id, and what the change would do from each.+/// role and id, what the change would do from each, and the question to put+/// to the user word for word.fn copy_question(copies: &[MeetingCopy], inboxes: usize, change: CopyChange) -> String {let listed = copies.iter()@@ -96,34 +99,92 @@ fn copy_question(copies: &[MeetingCopy], inboxes: usize, change: CopyChange) ->}).collect::<Vec<_>>().join("; ");- let effect = match change {- CopyChange::Delete => {+ let (effect, verb) = match change {+ CopyChange::Delete => ("Deleting the copy an inbox organizes cancels the meeting for every guest, while \deleting a guest's copy takes it off that inbox's calendar and, on Google, also \declines the invitation and tells the organizer."- .to_string()- }- CopyChange::Update { adds_guests } => {- let organizer = copies.iter().find(|copy| copy.organizes);- match organizer {- Some(organizer) if adds_guests => format!(+ .to_string(),+ "delete",+ ),+ CopyChange::InviteGuests => match copies.iter().find(|copy| copy.organizes) {+ Some(organizer) => (+ format!("To add guests, suggest {}: it organizes the meeting, so they are invited \directly, while a guest's copy can invite only where the organizer allows \it.",organizer.inbox),- _ => "The change reaches the meeting differently from each copy, and a guest's \- copy can only make it where the organizer allows it."+ "add the guests from",+ ),+ None => (+ "A guest's copy can invite only where the organizer allows it.".to_string(),+ "add the guests from",+ ),+ },+ CopyChange::Update { changes_guests } => match copies.iter().find(|copy| copy.organizes) {+ Some(organizer) if changes_guests => (+ format!(+ "To change the guest list, suggest {}: it organizes the meeting, so it \+ can invite and remove guests, while a guest's copy can only invite, \+ and only where the organizer allows it.",+ organizer.inbox+ ),+ "change the guests on",+ ),+ _ => (+ "The change reaches the meeting differently from each copy, and a guest's \+ copy can only make it where the organizer allows it.".to_string(),- }- }+ "change",+ ),+ },};+ let organizer_first = matches!(+ change,+ CopyChange::InviteGuests+ | CopyChange::Update {+ changes_guests: true+ }+ );+ let question = format!(+ "Which inbox's copy should I {verb}: {}?",+ choices(copies, organizer_first)+ );format!(- "This meeting is on {inboxes} of the user's inboxes: {listed}. {effect} Ask the user \- which inbox's copy to change, then call again with that copy's `eventId` and its inbox \- as `inbox`."+ "This meeting is on {inboxes} of the user's inboxes: {listed}. {effect} Never choose \+ between the user's inboxes yourself, whatever they look like. Once the user answers, \+ call again with the chosen copy's `eventId` and its inbox as `inbox`. Ask the user \+ exactly this and wait for the answer: \"{question}\"")}+/// Each inbox once, with its role, as "a (organizer), b (guest) or c+/// (guest)"; the organizing inbox leads when it is the one to suggest.+fn choices(copies: &[MeetingCopy], organizer_first: bool) -> String {+ let mut ordered = copies.iter().collect::<Vec<_>>();+ if organizer_first {+ ordered.sort_by_key(|copy| !copy.organizes);+ }+ let mut seen = HashSet::new();+ let options = ordered+ .into_iter()+ .filter(|copy| seen.insert(copy.inbox.to_lowercase()))+ .map(|copy| {+ if copy.organizes {+ format!("{} (organizer)", copy.inbox)+ } else if copy.attends {+ format!("{} (guest)", copy.inbox)+ } else {+ copy.inbox.clone()+ }+ })+ .collect::<Vec<_>>();+ match options.split_last() {+ Some((last, rest)) if !rest.is_empty() => format!("{} or {last}", rest.join(", ")),+ _ => options.join(""),+ }+}+#[cfg(test)]mod test;diff --git a/crates/calendar_events/src/domain/copies/test.rs b/crates/calendar_events/src/domain/copies/test.rsindex dc16cd8ac9..be3ccd115c 100644--- a/crates/calendar_events/src/domain/copies/test.rs+++ b/crates/calendar_events/src/domain/copies/test.rs@@ -36,6 +36,66 @@ fn a_copy_of_several_inboxes_needs_its_inbox() {"{message}");assert!(message.contains("cancels the meeting"), "{message}");+ assert!(+ message.contains("Never choose between the user's inboxes yourself"),+ "{message}"+ );+ assert!(+ message.ends_with(+ "Ask the user exactly this and wait for the answer: \"Which inbox's copy should I \+ delete: [email protected] (guest) or [email protected] (organizer)?\""+ ),+ "{message}"+ );+}++#[test]+fn a_guest_list_change_is_asked_as_a_change_not_an_addition() {+ let refusal = check_copy(+ &two_inboxes(),+ INVITED,+ None,+ CopyChange::Update {+ changes_guests: true,+ },+ )+ .expect("two inboxes hold the meeting");+ let message = refusal.message();+ assert!(+ message.contains("To change the guest list, suggest [email protected]"),+ "{message}"+ );+ assert!(+ message.ends_with(+ "\"Which inbox's copy should I change the guests on: [email protected] (organizer) \+ or [email protected] (guest)?\""+ ),+ "{message}"+ );+}++#[test]+fn the_question_names_each_inbox_once() {+ let mut copies = two_inboxes();+ copies.push(copy(Uuid::from_u128(9), "[email protected]", false));+ copies.push(copy(Uuid::from_u128(10), "[email protected]", false));+ let refusal = check_copy(+ &copies,+ ORGANIZED,+ None,+ CopyChange::Update {+ changes_guests: false,+ },+ )+ .expect("three inboxes hold the meeting");+ assert!(+ refusal.message().contains(+ "\"Which inbox's copy should I change: [email protected] (guest), [email protected] \+ (organizer) or [email protected] (guest)?\""+ ),+ "{}",+ refusal.message()+ );}#[test]@@ -57,7 +117,9 @@ fn another_copys_inbox_is_refused_with_that_copys_id() {&two_inboxes(),ORGANIZED,Some("[email protected]"),- CopyChange::Update { adds_guests: false },+ CopyChange::Update {+ changes_guests: false,+ },).expect("the inbox holds a different copy");assert!(@@ -71,13 +133,8 @@ fn another_copys_inbox_is_refused_with_that_copys_id() {#[test]fn adding_guests_suggests_the_copy_the_user_organizes() {- let refusal = check_copy(- &two_inboxes(),- INVITED,- None,- CopyChange::Update { adds_guests: true },- )- .expect("two inboxes hold the meeting");+ let refusal = check_copy(&two_inboxes(), INVITED, None, CopyChange::InviteGuests)+ .expect("two inboxes hold the meeting");assert!(refusal.message()@@ -85,6 +142,14 @@ fn adding_guests_suggests_the_copy_the_user_organizes() {"{}",refusal.message());+ assert!(+ refusal.message().contains(+ "\"Which inbox's copy should I add the guests from: [email protected] (organizer) \+ or [email protected] (guest)?\""+ ),+ "{}",+ refusal.message()+ );}#[test]diff --git a/crates/calendar_events/src/inbound/mutation_router.rs b/crates/calendar_events/src/inbound/mutation_router.rsindex 0c74574b74..e67e6de036 100644--- a/crates/calendar_events/src/inbound/mutation_router.rs+++ b/crates/calendar_events/src/inbound/mutation_router.rs@@ -817,7 +817,7 @@ whereevent_id,request.inbox.as_deref(),CopyChange::Update {- adds_guests: patch.attendees.is_some(),+ changes_guests: patch.attendees.is_some(),},).await?;@@ -998,7 +998,7 @@ whereis_agent_run(user.authorization.user.agent_id.is_some(), &headers),event_id,request.inbox.as_deref(),- CopyChange::Update { adds_guests: true },+ CopyChange::InviteGuests,).await?;let event = statediff --git a/crates/calendar_events/src/inbound/toolset/delete_calendar_event.rs b/crates/calendar_events/src/inbound/toolset/delete_calendar_event.rsindex f06ed5791e..3f89e6b665 100644--- a/crates/calendar_events/src/inbound/toolset/delete_calendar_event.rs+++ b/crates/calendar_events/src/inbound/toolset/delete_calendar_event.rs@@ -42,23 +42,27 @@ pub struct DeleteCalendarEventResponse {#[schemars(title = "DeleteCalendarEvent",description = "\-Delete an event from the user's calendar. The deletion is written to the calendar provider immediately and \-attendees are notified, so confirm with the user before deleting — it cannot be undone. Get \-the `eventId` from ListCalendarEvents.\n\+Delete an event from the user's calendar.\n\+\n\+A meeting on more than one of the user's inboxes is one ListCalendarEvents entry per inbox. \+Before deleting any of them, ask the user which inbox's copy to delete, then pass that \+copy's `inbox`. Never choose between the user's inboxes yourself, whatever they look like: \+a test, secondary or unfamiliar address is still the user's own inbox. Skip the question \+only when the user already named the inbox, or when only one copy can be deleted \+(`isReadOnly` false); then delete that copy and say why. Without `inbox` the tool refuses, \+lists each copy and gives the question to ask. Deleting the copy the user organizes cancels \+the meeting for every guest. Deleting a copy where they are a guest takes the meeting off \+that inbox's calendar: on Google it also declines the invitation and tells the organizer, \+while on Outlook the organizer is not told and still sees the invitation unanswered.\n\+\n\+The deletion is written to the calendar provider immediately and attendees are notified, so \+confirm with the user before deleting — it cannot be undone. Get the `eventId` from \+ListCalendarEvents.\n\\n\For recurring events, `scope` controls how much is removed: \"all\" (default) removes the \whole series, \"this_event\" removes one occurrence, and \"this_and_following\" ends the \series from an occurrence onward. The scoped variants require `recurrenceId` from the \-targeted occurrence's ListCalendarEvents entry.\n\-\n\-When the meeting is on several of the user's inboxes (one ListCalendarEvents entry per \-inbox), the tool refuses until `inbox` names the inbox of the copy to delete, and lists each \-copy. Ask which inbox's copy to delete unless the user named one or only one copy is writable \-(`isReadOnly` false), in which case delete that one, pass its `inbox` and say why. Deleting \-the copy the user organizes cancels the meeting for every guest. Deleting a copy where they \-are a guest takes the meeting off that inbox's calendar: on Google it also declines the \-invitation and tells the organizer, while on Outlook the organizer is not told and still sees \-the invitation unanswered."+targeted occurrence's ListCalendarEvents entry.")]pub struct DeleteCalendarEvent {/// Event to delete.diff --git a/crates/calendar_events/src/inbound/toolset/list_calendar_events.rs b/crates/calendar_events/src/inbound/toolset/list_calendar_events.rsindex b9b35e333a..aabd8c9dcb 100644--- a/crates/calendar_events/src/inbound/toolset/list_calendar_events.rs+++ b/crates/calendar_events/src/inbound/toolset/list_calendar_events.rs@@ -170,7 +170,8 @@ by several of the user's inboxes until `inbox` names the inbox of the copy beingthe refusal lists each copy. If only one copy allows the change (`viewerCan`, or for deleting, \`isReadOnly` false), use that copy with its `inbox` and say why (for example, only the copy \the user organizes can move the meeting). If more than one can, ask which inbox, saying what \-the change would do from each. Add guests from the copy the user organizes when there is one: \+the change would do from each, and never choose between the user's inboxes yourself, whatever \+they look like. Add guests from the copy the user organizes when there is one: \it invites them directly, while a guest's copy invites only as far as the organizer allows. \Deleting the organizer's copy cancels the meeting for everyone, while deleting a guest's copy \takes the meeting off that inbox's calendar and, on Google, also declines the invitation and \diff --git a/crates/calendar_events/src/inbound/toolset/test/copies.rs b/crates/calendar_events/src/inbound/toolset/test/copies.rsindex a74e8c58ba..ca19dc622c 100644--- a/crates/calendar_events/src/inbound/toolset/test/copies.rs+++ b/crates/calendar_events/src/inbound/toolset/test/copies.rs@@ -134,7 +134,7 @@ async fn a_copy_outside_the_users_own_inboxes_is_not_checked() {}#[tokio::test]-async fn adding_guests_suggests_the_copy_the_user_organizes() {+async fn a_guest_list_change_suggests_the_copy_the_user_organizes() {let (mutations, context) = context(MockMutations::default(), occurrences_with(two_inboxes()));let error = update(serde_json::json!({@@ -149,7 +149,7 @@ async fn adding_guests_suggests_the_copy_the_user_organizes() {assert!(error.description- .contains("To add guests, suggest [email protected]"),+ .contains("To change the guest list, suggest [email protected]"),"{}",error.description);@@ -168,7 +168,7 @@ async fn a_detail_change_asks_which_copy() {assert!(error.description- .contains("Ask the user which inbox's copy"),+ .contains("\"Which inbox's copy should I change: "),"{}",error.description);diff --git a/crates/calendar_events/src/inbound/toolset/update_calendar_event.rs b/crates/calendar_events/src/inbound/toolset/update_calendar_event.rsindex e545df296a..ef1aebe1a2 100644--- a/crates/calendar_events/src/inbound/toolset/update_calendar_event.rs+++ b/crates/calendar_events/src/inbound/toolset/update_calendar_event.rs@@ -84,8 +84,20 @@ pub enum UpdateScopeInput {#[schemars(title = "UpdateCalendarEvent",description = "\-Update an existing calendar event. Only the supplied fields change; omitted fields keep \-their current values. The change is written to the calendar provider immediately and attendees are \+Update an existing calendar event.\n\+\n\+A meeting on more than one of the user's inboxes is one ListCalendarEvents entry per inbox. \+Before changing its details, guests or guest permissions, ask the user which inbox's copy to \+change, then pass that copy's `inbox`. Never choose between the user's inboxes yourself, \+whatever they look like: a test, secondary or unfamiliar address is still the user's own \+inbox. Skip the question only when the user already named the inbox, when only one copy's \+`viewerCan` allows the change (use it and say why), or when adding guests to a meeting the \+user organizes from one of the inboxes (add them from that copy and say why). Reminders may \+go to one copy and an `rsvp` to the copy where the user is a guest, naming the inbox in your \+reply. Without `inbox` the tool refuses, lists each copy and gives the question to ask. One \+call changes one copy, so an edit on one copy and an `rsvp` on another take two calls.\n\+\n\+Only the supplied fields change; omitted fields keep their current values. The change is written to the calendar provider immediately and attendees are \notified of it, so confirm details with the user first. Get the `eventId` from \ListCalendarEvents.\n\\n\@@ -116,16 +128,7 @@ event.\n\`rsvp` sets the user's own response to an invitation and is independent of the field \edits — it can be the only thing this call changes. It applies at the same `scope` as \the rest of the call and answers as the connected inbox the event's copy belongs to, so \-it only works when that inbox is an attendee.\n\-\n\-When the meeting is on several of the user's inboxes, ListCalendarEvents lists one entry per \-inbox; pick the copy by its rule. Reminders may go to one copy and an `rsvp` to the copy \-where the user is a guest, naming the inbox in your reply. Any other change needs `inbox`, \-the inbox of the copy it changes; without it the tool refuses and lists each copy. Use the \-only copy whose `viewerCan` allows the change, with the reason, or the copy the user chooses \-when more than one could make it, and add guests from the copy the user organizes when there \-is one. One call changes one copy, so an edit on one copy and an `rsvp` on another take two \-calls."+it only works when that inbox is an attendee.")]pub struct UpdateCalendarEvent {/// Event to update.@@ -356,7 +359,7 @@ whereself.event_id,self.inbox.as_deref(),CopyChange::Update {- adds_guests: patch.attendees.is_some(),+ changes_guests: patch.attendees.is_some(),},).await?;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 bd43d50dd6..ad41c00569 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@@ -67,14 +67,20 @@ with `copy_refused` when Google will not import it.Delete the event (or a scoped part of a recurring series) at its provider.+A meeting on more than one of the user's inboxes is one event per inbox.+Before deleting any of them, ask the user which inbox's copy to delete,+then pass that copy's `inbox`. Never choose between the user's inboxes+yourself, whatever they look like: a test, secondary or unfamiliar address+is still the user's own inbox. Skip the question only when the user+already named the inbox, or when only one copy can be deleted; then delete+that copy and say why. Without `inbox` the call is refused with+`copy_choice_required`, listing each copy and the question to ask.+Deleting the copy the user organizes cancels the meeting for every guest.Deleting a copy where they are a guest takes the meeting off that inbox'scalendar: on Google it also declines the invitation and tells theorganizer, while on Outlook the organizer is not told and still sees the-invitation unanswered. When the meeting is on several of the user's-inboxes, ask which inbox's copy to delete unless the user named one or-only one copy is writable, and pass that copy's `inbox`; without it the-call is refused with `copy_choice_required`, listing each copy.+invitation unanswered.#### Parameters@@ -108,13 +114,19 @@ they belong to.> **inviteGuests**(`options`): `Promise`\<`CalendarEvent`\>Add guests without touching anyone already invited, and return a handle-to the synced record. The organizer may, and so may a guest the organizer-lets invite others (see [CalendarEvent.viewerCan](#property-viewercan)); Google emails-the new guests. When the meeting is on several of the user's inboxes,-add from the copy the user organizes when there is one (it invites-directly, while a guest's copy invites only as far as the organizer-allows), else ask which inbox, and pass that copy's `inbox`; without it-the call is refused with `copy_choice_required`, listing each copy.+to the synced record.++When the meeting is on more than one of the user's inboxes, add from the+copy the user organizes when there is one (it invites directly, while a+guest's copy invites only as far as the organizer allows) and say why;+otherwise ask the user which inbox's copy to add them from. Never choose+between the user's inboxes any other way, whatever they look like. Pass+that copy's `inbox`; without it the call is refused with+`copy_choice_required`, listing each copy and the question to ask.++The organizer may add guests, and so may a guest the organizer lets+invite others (see [CalendarEvent.viewerCan](#property-viewercan)); Google emails the+new guests.#### Parameters@@ -266,15 +278,18 @@ Record the requester's RSVP and return a handle to the synced record.Update the event and return a handle to its synced record.-A meeting on several of the user's inboxes is one event per inbox, each-with its own id (see the occurrence listing's `inbox` and `role`).-Reminders belong to one copy, so set them on one copy and say which inbox-you used; any other change reaches the meeting differently from each copy.-Use the only copy whose `viewerCan` allows the change and say why, or ask-the user which inbox's copy to change when more than one could make it,-and add guests from the copy the user organizes when there is one. Pass-the chosen copy's `inbox`; without it the call is refused with-`copy_choice_required`, listing each copy.+A meeting on more than one of the user's inboxes is one event per inbox,+each with its own id (see the occurrence listing's `inbox` and `role`).+Before changing its details, guests or guest permissions, ask the user+which inbox's copy to change, then pass that copy's `inbox`. Never choose+between the user's inboxes yourself, whatever they look like: a test,+secondary or unfamiliar address is still the user's own inbox. Skip the+question only when the user already named the inbox, when only one copy's+`viewerCan` allows the change (use it and say why), or when adding guests+to a meeting the user organizes from one of the inboxes (add them from+that copy and say why). Reminders belong to one copy, so set them on one+copy and say which inbox you used. Without `inbox` the call is refused+with `copy_choice_required`, listing each copy and the question to ask.#### Parametersdiff --git a/packages/sdk/src/entities/calendar/event.ts b/packages/sdk/src/entities/calendar/event.tsindex a5c4be2124..567c69ccba 100644--- a/packages/sdk/src/entities/calendar/event.ts+++ b/packages/sdk/src/entities/calendar/event.ts@@ -239,15 +239,18 @@ export class CalendarEvent extends MacroEntity<CalendarEventRecord> {/** Update the event and return a handle to its synced record.*- * A meeting on several of the user's inboxes is one event per inbox, each- * with its own id (see the occurrence listing's `inbox` and `role`).- * Reminders belong to one copy, so set them on one copy and say which inbox- * you used; any other change reaches the meeting differently from each copy.- * Use the only copy whose `viewerCan` allows the change and say why, or ask- * the user which inbox's copy to change when more than one could make it,- * and add guests from the copy the user organizes when there is one. Pass- * the chosen copy's `inbox`; without it the call is refused with- * `copy_choice_required`, listing each copy. */+ * A meeting on more than one of the user's inboxes is one event per inbox,+ * each with its own id (see the occurrence listing's `inbox` and `role`).+ * Before changing its details, guests or guest permissions, ask the user+ * which inbox's copy to change, then pass that copy's `inbox`. Never choose+ * between the user's inboxes yourself, whatever they look like: a test,+ * secondary or unfamiliar address is still the user's own inbox. Skip the+ * question only when the user already named the inbox, when only one copy's+ * `viewerCan` allows the change (use it and say why), or when adding guests+ * to a meeting the user organizes from one of the inboxes (add them from+ * that copy and say why). Reminders belong to one copy, so set them on one+ * copy and say which inbox you used. Without `inbox` the call is refused+ * with `copy_choice_required`, listing each copy and the question to ask. */async update(options: UpdateEventOptions): Promise<CalendarEvent> {const record = await this.mutate((client) =>client.calendar.updateCalendarEvent({@@ -259,15 +262,21 @@ export class CalendarEvent extends MacroEntity<CalendarEventRecord> {}/** Delete the event (or a scoped part of a recurring series) at its provider.+ *+ * A meeting on more than one of the user's inboxes is one event per inbox.+ * Before deleting any of them, ask the user which inbox's copy to delete,+ * then pass that copy's `inbox`. Never choose between the user's inboxes+ * yourself, whatever they look like: a test, secondary or unfamiliar address+ * is still the user's own inbox. Skip the question only when the user+ * already named the inbox, or when only one copy can be deleted; then delete+ * that copy and say why. Without `inbox` the call is refused with+ * `copy_choice_required`, listing each copy and the question to ask.** Deleting the copy the user organizes cancels the meeting for every guest.* Deleting a copy where they are a guest takes the meeting off that inbox's* calendar: on Google it also declines the invitation and tells the* organizer, while on Outlook the organizer is not told and still sees the- * invitation unanswered. When the meeting is on several of the user's- * inboxes, ask which inbox's copy to delete unless the user named one or- * only one copy is writable, and pass that copy's `inbox`; without it the- * call is refused with `copy_choice_required`, listing each copy. */+ * invitation unanswered. */async delete(options: DeleteEventOptions = {}): Promise<void> {await this.mutate((client) =>client.calendar.deleteCalendarEvent({@@ -319,13 +328,19 @@ export class CalendarEvent extends MacroEntity<CalendarEventRecord> {}/** Add guests without touching anyone already invited, and return a handle- * to the synced record. The organizer may, and so may a guest the organizer- * lets invite others (see {@link CalendarEvent.viewerCan}); Google emails- * the new guests. When the meeting is on several of the user's inboxes,- * add from the copy the user organizes when there is one (it invites- * directly, while a guest's copy invites only as far as the organizer- * allows), else ask which inbox, and pass that copy's `inbox`; without it- * the call is refused with `copy_choice_required`, listing each copy. */+ * to the synced record.+ *+ * When the meeting is on more than one of the user's inboxes, add from the+ * copy the user organizes when there is one (it invites directly, while a+ * guest's copy invites only as far as the organizer allows) and say why;+ * otherwise ask the user which inbox's copy to add them from. Never choose+ * between the user's inboxes any other way, whatever they look like. Pass+ * that copy's `inbox`; without it the call is refused with+ * `copy_choice_required`, listing each copy and the question to ask.+ *+ * The organizer may add guests, and so may a guest the organizer lets+ * invite others (see {@link CalendarEvent.viewerCan}); Google emails the+ * new guests. */async inviteGuests(options: InviteGuestsOptions): Promise<CalendarEvent> {const record = await this.mutate((client) =>client.calendar.inviteCalendarEventGuests({