Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

feat(calendar): show linked meetings in document references (#8870)

gbirmana72667ef7f8b
diff --git a/.sqlx/query-3f0661915621c25f5bf5d3e5eb78c9e0a854c45a3b724820be55853a0eee4740.json b/.sqlx/query-3f0661915621c25f5bf5d3e5eb78c9e0a854c45a3b724820be55853a0eee4740.json
new file mode 100644
index 0000000000..625b55f8d3
--- /dev/null
+++ b/.sqlx/query-3f0661915621c25f5bf5d3e5eb78c9e0a854c45a3b724820be55853a0eee4740.json
@@ -0,0 +1,59 @@
+{
+ "db_name": "PostgreSQL",
+ "query": "\n SELECT note.event_id, note.occurrence_key, document.name AS document_name,\n calendar_note_event_visible($1, note.event_id, note.occurrence_key) AS \"can_view_meeting!\",\n CASE WHEN calendar_note_event_visible($1, note.event_id, note.occurrence_key)\n THEN CASE WHEN event.owner_id = $1 OR EXISTS (\n SELECT 1 FROM macro_user_links delegate\n WHERE delegate.link_id = event.source_link_id AND delegate.primary_macro_id = $1\n ) THEN event.title ELSE 'Shared meeting' END\n ELSE 'Unavailable meeting' END AS \"event_title!\",\n team.id AS \"team_id?\", team.name AS \"team_name?\"\n FROM calendar_event_notes note\n JOIN \"Document\" document ON document.id = note.document_id AND document.\"deletedAt\" IS NULL\n JOIN calendar_events event ON event.id = note.event_id\n LEFT JOIN team ON team.id = note.team_id\n WHERE note.document_id = $2\n AND (document.owner = $1 OR calendar_note_event_visible($1, note.event_id, note.occurrence_key))\n ORDER BY note.created_at, note.event_id, note.occurrence_key\n ",
+ "describe": {
+ "columns": [
+ {
+ "ordinal": 0,
+ "name": "event_id",
+ "type_info": "Uuid"
+ },
+ {
+ "ordinal": 1,
+ "name": "occurrence_key",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 2,
+ "name": "document_name",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 3,
+ "name": "can_view_meeting!",
+ "type_info": "Bool"
+ },
+ {
+ "ordinal": 4,
+ "name": "event_title!",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 5,
+ "name": "team_id?",
+ "type_info": "Uuid"
+ },
+ {
+ "ordinal": 6,
+ "name": "team_name?",
+ "type_info": "Text"
+ }
+ ],
+ "parameters": {
+ "Left": [
+ "Text",
+ "Text"
+ ]
+ },
+ "nullable": [
+ false,
+ false,
+ false,
+ null,
+ null,
+ false,
+ false
+ ]
+ },
+ "hash": "3f0661915621c25f5bf5d3e5eb78c9e0a854c45a3b724820be55853a0eee4740"
+}
diff --git a/.sqlx/query-7bb507dd28fef3044b651c51295532001b6f9dac01144191c41577752ba2cbf3.json b/.sqlx/query-7bb507dd28fef3044b651c51295532001b6f9dac01144191c41577752ba2cbf3.json
new file mode 100644
index 0000000000..9bf822df59
--- /dev/null
+++ b/.sqlx/query-7bb507dd28fef3044b651c51295532001b6f9dac01144191c41577752ba2cbf3.json
@@ -0,0 +1,92 @@
+{
+ "db_name": "PostgreSQL",
+ "query": "\n WITH reference_targets AS MATERIALIZED (\n SELECT candidate.id AS event_id, note.event_id AS reference_event_id,\n note.occurrence_key AS reference_occurrence_key\n FROM calendar_event_notes note\n JOIN calendar_events linked ON linked.id = note.event_id\n JOIN calendar_events candidate ON candidate.ical_uid = linked.ical_uid\n AND lower(candidate.organizer_email) IS NOT DISTINCT FROM lower(linked.organizer_email)\n WHERE note.document_id = $11\n AND calendar_note_copies_match(note.event_id, candidate.id, note.occurrence_key)\n ), eligible AS (\n SELECT teammate.user_id, COALESCE(policy.sharing, 'busy_only') AS sharing FROM team_user viewer\n JOIN team_user teammate ON teammate.team_id = viewer.team_id\n LEFT JOIN calendar_team_sharing policy ON policy.user_id = teammate.user_id\n WHERE viewer.user_id = $1 AND teammate.user_id <> $1\n AND COALESCE(policy.sharing, 'busy_only') <> 'none'\n UNION SELECT $1::text, 'all'\n ), visible_accounts AS MATERIALIZED (\n SELECT eligible.user_id, eligible.sharing, account.id AS account_id\n FROM eligible JOIN calendar_accounts account ON account.owner_id = eligible.user_id\n WHERE ($11::text IS NOT NULL OR eligible.user_id = ANY($2::text[]))\n UNION\n SELECT eligible.user_id, eligible.sharing, account.id AS account_id\n FROM eligible\n JOIN macro_user_links link ON link.primary_macro_id = eligible.user_id\n JOIN calendar_accounts account ON account.email_link_id = link.link_id\n WHERE ($11::text IS NOT NULL OR eligible.user_id = ANY($2::text[]))\n ), authorized_sources AS MATERIALIZED (\n SELECT eligible.user_id AS shared_by, source.id AS source_id,\n calendar.id AS calendar_id, calendar.name AS calendar_name, calendar.time_zone,\n COALESCE(preference.contributes_to_availability,\n account.owner_id = eligible.user_id AND calendar.is_primary) AS contributes,\n source.normalized_payload, reference.reference_event_id,\n reference.reference_occurrence_key\n FROM visible_accounts eligible\n JOIN calendar_accounts account ON account.id = eligible.account_id\n AND account.sync_status IN ('ready', 'syncing')\n AND account.last_sync_error IS NULL\n AND account.last_synced_at > now() - interval '15 minutes'\n JOIN calendars calendar ON calendar.account_id = account.id AND NOT calendar.is_deleted\n AND calendar.synced_at IS NOT NULL AND calendar.last_sync_error IS NULL\n AND calendar.snapshot_normalization_version >= 1\n JOIN calendar_event_sources source ON source.calendar_id = calendar.id AND source.account_id = account.id\n AND source.provider_access_role IS NOT NULL\n AND source.provider_access_role IS NOT DISTINCT FROM calendar.access_role\n LEFT JOIN calendar_availability_preferences preference ON preference.user_id = eligible.user_id AND preference.calendar_id = calendar.id\n LEFT JOIN reference_targets reference ON reference.event_id = source.event_id\n WHERE ($11::text IS NULL OR (eligible.sharing = 'all' AND reference.event_id IS NOT NULL))\n AND ($7::text IS NULL OR (eligible.user_id, source.id) >= ($7,$8))\n )\n SELECT shared_by AS \"shared_by!\", source_id AS \"source_id!\",\n calendar_id AS \"calendar_id!\", calendar_name AS \"calendar_name!\", time_zone,\n contributes AS \"contributes!\", reference_event_id AS \"reference_event_id?\",\n reference_occurrence_key AS \"reference_occurrence_key?\",\n ARRAY(SELECT owned.email_address::text FROM email_links owned WHERE owned.macro_id = shared_by) AS \"owner_emails!\",\n (normalized_payload - 'occurrences') AS \"snapshot!\", occurrence.value AS \"occurrence!\"\n FROM authorized_sources\n CROSS JOIN LATERAL jsonb_array_elements(normalized_payload->'occurrences') occurrence(value)\n WHERE (normalized_payload->'event'->>'status') <> 'cancelled'\n AND NOT COALESCE((occurrence.value->>'isCancelled')::boolean, false)\n AND ($11::text IS NOT NULL OR (\n ((occurrence.value->'time'->>'kind') = 'timed'\n AND (occurrence.value->'time'->>'startsAt')::timestamptz < $4\n AND ((occurrence.value->'time'->>'endsAt')::timestamptz > $3\n OR ((occurrence.value->'time'->>'startsAt')::timestamptz = (occurrence.value->'time'->>'endsAt')::timestamptz\n AND (occurrence.value->'time'->>'startsAt')::timestamptz >= $3)))\n OR ((occurrence.value->'time'->>'kind') = 'allDay'\n AND (occurrence.value->'time'->>'startDate')::date < $6\n AND (occurrence.value->'time'->>'endDate')::date > $5)\n ))\n AND ($11::text IS NULL OR occurrence.value->>'occurrenceKey' = reference_occurrence_key\n OR (reference_occurrence_key = 'single' AND jsonb_array_length(normalized_payload->'event'->'recurrenceLines') = 0))\n AND ($7::text IS NULL OR (shared_by, source_id, occurrence.value->>'occurrenceKey') > ($7,$8,$9))\n ORDER BY shared_by, source_id, occurrence.value->>'occurrenceKey'\n LIMIT $10\n ",
+ "describe": {
+ "columns": [
+ {
+ "ordinal": 0,
+ "name": "shared_by!",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 1,
+ "name": "source_id!",
+ "type_info": "Uuid"
+ },
+ {
+ "ordinal": 2,
+ "name": "calendar_id!",
+ "type_info": "Uuid"
+ },
+ {
+ "ordinal": 3,
+ "name": "calendar_name!",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 4,
+ "name": "time_zone",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 5,
+ "name": "contributes!",
+ "type_info": "Bool"
+ },
+ {
+ "ordinal": 6,
+ "name": "reference_event_id?",
+ "type_info": "Uuid"
+ },
+ {
+ "ordinal": 7,
+ "name": "reference_occurrence_key?",
+ "type_info": "Text"
+ },
+ {
+ "ordinal": 8,
+ "name": "owner_emails!",
+ "type_info": "TextArray"
+ },
+ {
+ "ordinal": 9,
+ "name": "snapshot!",
+ "type_info": "Jsonb"
+ },
+ {
+ "ordinal": 10,
+ "name": "occurrence!",
+ "type_info": "Jsonb"
+ }
+ ],
+ "parameters": {
+ "Left": [
+ "Text",
+ "TextArray",
+ "Timestamptz",
+ "Timestamptz",
+ "Date",
+ "Date",
+ "Text",
+ "Uuid",
+ "Text",
+ "Int8",
+ "Text"
+ ]
+ },
+ "nullable": [
+ null,
+ false,
+ false,
+ false,
+ true,
+ null,
+ false,
+ false,
+ null,
+ null,
+ null
+ ]
+ },
+ "hash": "7bb507dd28fef3044b651c51295532001b6f9dac01144191c41577752ba2cbf3"
+}
diff --git a/.sqlx/query-dfae0eee308e6c895ea971b451866bae98e3b75a336c1cd2dcae15ea0b63de0d.json b/.sqlx/query-dfae0eee308e6c895ea971b451866bae98e3b75a336c1cd2dcae15ea0b63de0d.json
deleted file mode 100644
index 2b4276a72e..0000000000
--- a/.sqlx/query-dfae0eee308e6c895ea971b451866bae98e3b75a336c1cd2dcae15ea0b63de0d.json
+++ /dev/null
@@ -1,53 +0,0 @@
-{
- "db_name": "PostgreSQL",
- "query": "\n SELECT note.event_id, note.occurrence_key, document.name AS document_name,\n CASE WHEN calendar_note_event_visible($1, note.event_id, note.occurrence_key)\n THEN CASE WHEN event.owner_id = $1 OR EXISTS (\n SELECT 1 FROM macro_user_links delegate\n WHERE delegate.link_id = event.source_link_id AND delegate.primary_macro_id = $1\n ) THEN event.title ELSE 'Shared meeting' END\n ELSE 'Unavailable meeting' END AS \"event_title!\",\n team.id AS \"team_id?\", team.name AS \"team_name?\"\n FROM calendar_event_notes note\n JOIN \"Document\" document ON document.id = note.document_id AND document.owner = $1 AND document.\"deletedAt\" IS NULL\n JOIN calendar_events event ON event.id = note.event_id\n LEFT JOIN team ON team.id = note.team_id\n WHERE note.document_id = $2\n ORDER BY note.created_at, note.event_id, note.occurrence_key\n ",
- "describe": {
- "columns": [
- {
- "ordinal": 0,
- "name": "event_id",
- "type_info": "Uuid"
- },
- {
- "ordinal": 1,
- "name": "occurrence_key",
- "type_info": "Text"
- },
- {
- "ordinal": 2,
- "name": "document_name",
- "type_info": "Text"
- },
- {
- "ordinal": 3,
- "name": "event_title!",
- "type_info": "Text"
- },
- {
- "ordinal": 4,
- "name": "team_id?",
- "type_info": "Uuid"
- },
- {
- "ordinal": 5,
- "name": "team_name?",
- "type_info": "Text"
- }
- ],
- "parameters": {
- "Left": [
- "Text",
- "Text"
- ]
- },
- "nullable": [
- false,
- false,
- false,
- null,
- false,
- false
- ]
- },
- "hash": "dfae0eee308e6c895ea971b451866bae98e3b75a336c1cd2dcae15ea0b63de0d"
-}
diff --git a/.sqlx/query-fedcb133dd9ba625014a0aee5129c3e3cfd470cc4f0c008cb1a670e6333535b7.json b/.sqlx/query-fedcb133dd9ba625014a0aee5129c3e3cfd470cc4f0c008cb1a670e6333535b7.json
deleted file mode 100644
index 96663c8fb2..0000000000
--- a/.sqlx/query-fedcb133dd9ba625014a0aee5129c3e3cfd470cc4f0c008cb1a670e6333535b7.json
+++ /dev/null
@@ -1,79 +0,0 @@
-{
- "db_name": "PostgreSQL",
- "query": "\n WITH eligible AS (\n SELECT teammate.user_id FROM team_user viewer\n JOIN team_user teammate ON teammate.team_id = viewer.team_id\n LEFT JOIN calendar_team_sharing policy ON policy.user_id = teammate.user_id\n WHERE viewer.user_id = $1 AND COALESCE(policy.sharing, 'busy_only') <> 'none'\n UNION SELECT $1::text\n ), visible_accounts AS MATERIALIZED (\n SELECT eligible.user_id, account.id AS account_id\n FROM eligible JOIN calendar_accounts account ON account.owner_id = eligible.user_id\n WHERE eligible.user_id = ANY($2::text[])\n UNION\n SELECT eligible.user_id, account.id AS account_id\n FROM eligible\n JOIN macro_user_links link ON link.primary_macro_id = eligible.user_id\n JOIN calendar_accounts account ON account.email_link_id = link.link_id\n WHERE eligible.user_id = ANY($2::text[])\n ), authorized_sources AS MATERIALIZED (\n SELECT eligible.user_id AS shared_by, source.id AS source_id,\n calendar.id AS calendar_id, calendar.name AS calendar_name, calendar.time_zone,\n COALESCE(preference.contributes_to_availability,\n account.owner_id = eligible.user_id AND calendar.is_primary) AS contributes,\n source.normalized_payload\n FROM visible_accounts eligible\n JOIN calendar_accounts account ON account.id = eligible.account_id\n AND account.sync_status IN ('ready', 'syncing')\n AND account.last_sync_error IS NULL\n AND account.last_synced_at > now() - interval '15 minutes'\n JOIN calendars calendar ON calendar.account_id = account.id AND NOT calendar.is_deleted\n AND calendar.synced_at IS NOT NULL AND calendar.last_sync_error IS NULL\n AND calendar.snapshot_normalization_version >= 1\n JOIN calendar_event_sources source ON source.calendar_id = calendar.id AND source.account_id = account.id\n AND source.provider_access_role IS NOT NULL\n AND source.provider_access_role IS NOT DISTINCT FROM calendar.access_role\n LEFT JOIN calendar_availability_preferences preference ON preference.user_id = eligible.user_id AND preference.calendar_id = calendar.id\n WHERE ($7::text IS NULL OR (eligible.user_id, source.id) >= ($7,$8))\n )\n SELECT shared_by AS \"shared_by!\", source_id AS \"source_id!\",\n calendar_id AS \"calendar_id!\", calendar_name AS \"calendar_name!\", time_zone,\n contributes AS \"contributes!\",\n ARRAY(SELECT owned.email_address::text FROM email_links owned WHERE owned.macro_id = shared_by) AS \"owner_emails!\",\n (normalized_payload - 'occurrences') AS \"snapshot!\", occurrence.value AS \"occurrence!\"\n FROM authorized_sources\n CROSS JOIN LATERAL jsonb_array_elements(normalized_payload->'occurrences') occurrence(value)\n WHERE (normalized_payload->'event'->>'status') <> 'cancelled'\n AND NOT COALESCE((occurrence.value->>'isCancelled')::boolean, false)\n AND (\n ((occurrence.value->'time'->>'kind') = 'timed'\n AND (occurrence.value->'time'->>'startsAt')::timestamptz < $4\n AND ((occurrence.value->'time'->>'endsAt')::timestamptz > $3\n OR ((occurrence.value->'time'->>'startsAt')::timestamptz = (occurrence.value->'time'->>'endsAt')::timestamptz\n AND (occurrence.value->'time'->>'startsAt')::timestamptz >= $3)))\n OR ((occurrence.value->'time'->>'kind') = 'allDay'\n AND (occurrence.value->'time'->>'startDate')::date < $6\n AND (occurrence.value->'time'->>'endDate')::date > $5)\n )\n AND ($7::text IS NULL OR (shared_by, source_id, occurrence.value->>'occurrenceKey') > ($7,$8,$9))\n ORDER BY shared_by, source_id, occurrence.value->>'occurrenceKey'\n LIMIT $10\n ",
- "describe": {
- "columns": [
- {
- "ordinal": 0,
- "name": "shared_by!",
- "type_info": "Text"
- },
- {
- "ordinal": 1,
- "name": "source_id!",
- "type_info": "Uuid"
- },
- {
- "ordinal": 2,
- "name": "calendar_id!",
- "type_info": "Uuid"
- },
- {
- "ordinal": 3,
- "name": "calendar_name!",
- "type_info": "Text"
- },
- {
- "ordinal": 4,
- "name": "time_zone",
- "type_info": "Text"
- },
- {
- "ordinal": 5,
- "name": "contributes!",
- "type_info": "Bool"
- },
- {
- "ordinal": 6,
- "name": "owner_emails!",
- "type_info": "TextArray"
- },
- {
- "ordinal": 7,
- "name": "snapshot!",
- "type_info": "Jsonb"
- },
- {
- "ordinal": 8,
- "name": "occurrence!",
- "type_info": "Jsonb"
- }
- ],
- "parameters": {
- "Left": [
- "Text",
- "TextArray",
- "Timestamptz",
- "Timestamptz",
- "Date",
- "Date",
- "Text",
- "Uuid",
- "Text",
- "Int8"
- ]
- },
- "nullable": [
- null,
- false,
- false,
- false,
- true,
- null,
- null,
- null,
- null
- ]
- },
- "hash": "fedcb133dd9ba625014a0aee5129c3e3cfd470cc4f0c008cb1a670e6333535b7"
-}
diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.md
index 0affa4f38d..a93b5a2216 100644
--- a/apps/web/AGENTS.md
+++ b/apps/web/AGENTS.md
@@ -45,6 +45,9 @@ sample data; keep notes aligned with those existing surfaces and preserve their
dialog open guards. Open the existing document Share dialog for note access,
keep labeled Options controls visible beside truncated titles without redundant
hover tooltips, and use existing team memberships for optional note sharing.
+Include linked meetings in Markdown side-panel References, behind the same flag;
+reuse the shared single-line ReferenceRow with the title and date inline, and
+resolve meeting details and opening targets through authorized calendar previews.
Gate event notes and document Share meeting-link controls with
`enable-calendar-meeting-notes` before mounting their query sources; it defaults
on in dev and uses PostHog in production.
diff --git a/apps/web/src/features/block-md/component/sidepanel/MarkdownReferencesSection.tsx b/apps/web/src/features/block-md/component/sidepanel/MarkdownReferencesSection.tsx
new file mode 100644
index 0000000000..408fcc9420
--- /dev/null
+++ b/apps/web/src/features/block-md/component/sidepanel/MarkdownReferencesSection.tsx
@@ -0,0 +1,101 @@
+import { MeetingReference } from '@app/features/calendar-notes/meeting-reference';
+import type { DocumentReference } from '@app/features/calendar-notes/queries/notes-source';
+import { documentLinksOptions } from '@app/features/calendar-notes/queries/notes-source';
+import { useFeatureFlag } from '@app/lib/analytics/posthog';
+import { SidePanel, useSidePanel } from '@components/app/side-panel';
+import { References } from '@core/component/References';
+import { enableCalendarMeetingNotes } from '@core/constant/featureFlags';
+import { useUserId } from '@core/context/user';
+import { isMobile } from '@core/mobile/isMobile';
+import { fireAndForget } from '@core/util/fireAndForget';
+import { queryReadyGate } from '@queries/gate';
+import { useAttachmentReferencesQuery } from '@queries/storage/attachment-references';
+import { useQuery } from '@tanstack/solid-query';
+import { Button } from '@ui';
+import { For, Show, Suspense } from 'solid-js';
+
+/** Keep the meeting source unmounted while its rollout flag is off. */
+export function MarkdownReferencesSection(props: { documentId: string }) {
+ const flag = useFeatureFlag(enableCalendarMeetingNotes);
+ const userId = useUserId();
+ return (
+ <Show
+ when={flag().enabled && userId()}
+ fallback={<ReferencesSection documentId={props.documentId} />}
+ >
+ <Suspense fallback={<ReferencesSection documentId={props.documentId} />}>
+ <ReferencesWithMeetings documentId={props.documentId} />
+ </Suspense>
+ </Show>
+ );
+}
+
+function ReferencesWithMeetings(props: { documentId: string }) {
+ const userId = useUserId();
+ const links = useQuery(() =>
+ documentLinksOptions(userId(), props.documentId)
+ );
+ return (
+ <ReferencesSection
+ documentId={props.documentId}
+ meetings={queryReadyGate(links) ? links.data : []}
+ meetingError={links.isError}
+ onRetry={() =>
+ fireAndForget(links.refetch(), 'calendar.notes.references.retry')
+ }
+ />
+ );
+}
+
+function ReferencesSection(props: {
+ documentId: string;
+ meetings?: DocumentReference[];
+ meetingError?: boolean;
+ onRetry?: () => void;
+}) {
+ const sidePanel = useSidePanel();
+ const references = useAttachmentReferencesQuery(
+ () => props.documentId,
+ () => 'document'
+ );
+ const attachmentCount = () =>
+ queryReadyGate(references) ? references.data.length : 0;
+ const count = () => attachmentCount() + (props.meetings?.length ?? 0);
+ return (
+ <Show when={count() > 0 || props.meetingError}>
+ <SidePanel.Section
+ id="references"
+ title={<SidePanel.CountTitle label="References" count={count()} />}
+ order={33}
+ >
+ <div class="text-xs">
+ <Show when={props.meetingError}>
+ <div
+ role="alert"
+ class="flex items-center justify-between gap-2 py-2 text-ink-muted"
+ >
+ Couldn’t load meeting references.
+ <Button variant="ghost" size="sm" onClick={props.onRetry}>
+ Retry
+ </Button>
+ </div>
+ </Show>
+ <For each={props.meetings}>
+ {(link) => (
+ <MeetingReference
+ documentId={props.documentId}
+ link={link}
+ onOpenCalendar={() => {
+ if (isMobile()) sidePanel?.setIsOpen(false);
+ }}
+ />
+ )}
+ </For>
+ <Show when={attachmentCount() > 0}>
+ <References documentId={props.documentId} />
+ </Show>
+ </div>
+ </SidePanel.Section>
+ </Show>
+ );
+}
diff --git a/apps/web/src/features/block-md/component/sidepanel/MarkdownSidePanelSections.tsx b/apps/web/src/features/block-md/component/sidepanel/MarkdownSidePanelSections.tsx
index 5d32df60f3..060445c22b 100644
--- a/apps/web/src/features/block-md/component/sidepanel/MarkdownSidePanelSections.tsx
+++ b/apps/web/src/features/block-md/component/sidepanel/MarkdownSidePanelSections.tsx
@@ -17,7 +17,6 @@ import { EntityIcon } from '@core/component/EntityIcon';
import { openDocument } from '@core/component/LexicalMarkdown/component/core/BlockLink';
import { Wordcount } from '@core/component/LexicalMarkdown/component/status/Wordcount';
import { Notifications } from '@core/component/Notifications';
-import { References } from '@core/component/References';
import {
enableProjects,
USE_MACRO_PR_SUMMARY_BLOCK,
@@ -34,8 +33,6 @@ import {
getDefaultPinnedProperties,
SYSTEM_PROPERTY_IDS,
} from '@property/constants';
-import { queryReadyGate } from '@queries/gate';
-import { useAttachmentReferencesQuery } from '@queries/storage/attachment-references';
import { useDocumentMetadataQuery } from '@queries/storage/document-metadata';
import {
type GithubPullRequestWithDetails,
@@ -50,6 +47,7 @@ import { createPinnedProperties } from '../../primitives/create-pinned-propertie
import { DispatchAgentButton } from '../DispatchAgentMenu';
import { useMarkdownName } from '../MarkdownNameProvider';
import { TaskDuplicateMatchesSidePanelSection } from '../TaskDuplicateMatches';
+import { MarkdownReferencesSection } from './MarkdownReferencesSection';
/** Registers markdown header actions, panel sections, and metadata footer. */
export function MarkdownSidePanelSections() {
@@ -115,7 +113,7 @@ export function MarkdownSidePanelSections() {
/>
<GithubSectionConditional documentId={documentId()} isTask={isTask()} />
<NotificationsSectionConditional entity={entity()} />
- <ReferencesSectionConditional documentId={documentId()} />
+ <MarkdownReferencesSection documentId={documentId()} />
<Show when={isTask()}>
<TaskDuplicateMatchesSidePanelSection />
</Show>
@@ -311,33 +309,6 @@ function NotificationsSectionConditional(props: { entity: Entity }) {
);
}
-// ─────────────────────────────────────────────────────────────────────────────
-// References Section (conditional)
-// ─────────────────────────────────────────────────────────────────────────────
-
-function ReferencesSectionConditional(props: { documentId: string }) {
- const references = useAttachmentReferencesQuery(
- () => props.documentId,
- () => 'document'
- );
-
- const count = () => (queryReadyGate(references) ? references.data.length : 0);
-
- return (
- <Show when={count() > 0}>
- <SidePanel.Section
- id="references"
- title={<SidePanel.CountTitle label="References" count={count()} />}
- order={33}
- >
- <div class="text-xs">
- <References documentId={props.documentId} />
- </div>
- </SidePanel.Section>
- </Show>
- );
-}
-
// ─────────────────────────────────────────────────────────────────────────────
// GitHub Section (conditional)
// ─────────────────────────────────────────────────────────────────────────────
diff --git a/apps/web/src/features/calendar-notes/meeting-reference.tsx b/apps/web/src/features/calendar-notes/meeting-reference.tsx
new file mode 100644
index 0000000000..efa855278c
--- /dev/null
+++ b/apps/web/src/features/calendar-notes/meeting-reference.tsx
@@ -0,0 +1,134 @@
+import { parseLocalDate } from '@app/features/calendar/utils/calendar-date';
+import { openCalendarEventSplit } from '@app/features/calendar-view/open-calendar-event';
+import { CalendarEventPreviewDetails } from '@core/component/DocumentPreview';
+import { ReferenceRow } from '@core/component/References';
+import { fireAndForget } from '@core/util/fireAndForget';
+import { Telemetry } from '@macro-inc/observability';
+import CalendarIcon from '@phosphor/calendar-blank.svg';
+import { Button, Dialog } from '@ui';
+import { createSignal, onCleanup, Show } from 'solid-js';
+import type { DocumentReference } from './queries/notes-source';
+import { resolveReferencePreview } from './queries/reference-preview';
+
+/** A linked occurrence, resolved through the document-link access checks. */
+export function MeetingReference(props: {
+ link: DocumentReference;
+ documentId: string;
+ onOpenCalendar?: () => void;
+}) {
+ const occurrenceKey = () =>
+ props.link.occurrenceKey === 'single'
+ ? undefined
+ : props.link.occurrenceKey;
+ const resolved = () => resolveReferencePreview(props.link);
+ const event = () => resolved()?.event;
+ const [detailsOpen, setDetailsOpen] = createSignal(false);
+ const title = () => event()?.title || props.link.eventTitle;
+ const date = () => {
+ const time = event()?.time;
+ if (!time) return undefined;
+ const start =
+ time.kind === 'allDay'
+ ? parseLocalDate(time.startDate)
+ : new Date(time.startsAt);
+ if (!start || !Number.isFinite(start.getTime())) return undefined;
+ return start.toLocaleDateString(undefined, {
+ month: 'short',
+ day: 'numeric',
+ year:
+ start.getFullYear() === new Date().getFullYear()
+ ? undefined
+ : 'numeric',
+ });
+ };
+ let active = true;
+ onCleanup(() => {
+ active = false;
+ });
+ function open() {
+ fireAndForget(
+ Telemetry.span('calendar.notes.reference.open', async (span) => {
+ span.setAttr('event.id', props.link.eventId);
+ span.setAttr('document.id', props.documentId);
+ const current = event();
+ if (!current?.viewerEventId) {
+ span.setAttr(
+ 'calendar.notes.reference.outcome',
+ current ? 'shared_preview' : 'unavailable'
+ );
+ setDetailsOpen(true);
+ return;
+ }
+ setDetailsOpen(false);
+ const opened = await openCalendarEventSplit({
+ eventId: current.viewerEventId,
+ occurrenceKey: current.occurrenceKey ?? occurrenceKey(),
+ time: current.time,
+ openInNewSplit: true,
+ });
+ span.setAttr(
+ 'calendar.notes.reference.outcome',
+ opened ? 'calendar' : 'preview'
+ );
+ if (!active) return;
+ if (opened) props.onOpenCalendar?.();
+ else setDetailsOpen(true);
+ }),
+ 'calendar.notes.reference'
+ );
+ }
+
+ return (
+ <>
+ <ReferenceRow
+ source={
+ <span class="inline-flex min-w-0 max-w-full items-baseline gap-1 align-baseline">
+ <CalendarIcon class="relative top-[0.125em] size-[1em] shrink-0" />
+ <span class="min-w-0 truncate underline decoration-current/20 decoration-[max(1px,0.1em)] underline-offset-2">
+ {title()}
+ </span>
+ </span>
+ }
+ timestampLabel={date()}
+ onClick={open}
+ ariaLabel={`Open meeting ${title()}`}
+ />
+ <Show when={detailsOpen()}>
+ <Dialog
+ open
+ onOpenChange={setDetailsOpen}
+ position="center"
+ class="w-[400px]"
+ >
+ <Dialog.Title class="px-4 pt-4 text-sm font-medium">
+ {title()}
+ </Dialog.Title>
+ <Dialog.Description class="sr-only">
+ Details of the meeting linked to this note.
+ </Dialog.Description>
+ <Show
+ when={event()}
+ fallback={
+ <p class="p-4 text-sm text-ink-muted">
+ This meeting is no longer available to you.
+ </p>
+ }
+ >
+ {(current) => (
+ <CalendarEventPreviewDetails
+ event={current()}
+ mentionedEventId={props.link.eventId}
+ sharedActions={resolved()?.sharedActions}
+ />
+ )}
+ </Show>
+ <div class="flex justify-end p-3">
+ <Button variant="ghost" onClick={() => setDetailsOpen(false)}>
+ Close
+ </Button>
+ </div>
+ </Dialog>
+ </Show>
+ </>
+ );
+}
diff --git a/apps/web/src/features/calendar-notes/queries/notes-source.ts b/apps/web/src/features/calendar-notes/queries/notes-source.ts
index a19de28fbe..3115a70451 100644
--- a/apps/web/src/features/calendar-notes/queries/notes-source.ts
+++ b/apps/web/src/features/calendar-notes/queries/notes-source.ts
@@ -4,6 +4,7 @@ import { Telemetry } from '@macro-inc/observability';
import { queryClient } from '@queries/client';
import { queryReadyGate } from '@queries/gate';
import { useCurrentTeamQuery } from '@queries/team/teams';
+import type { DocumentNoteLink as CalendarDocumentLink } from '@service-calendar/generated/schemas/documentNoteLink';
import { calendarNotesClient } from '@service-calendar/notes';
import { createDebouncedMemo } from '@solid-primitives/memo';
import { useMutation, useQuery } from '@tanstack/solid-query';
@@ -11,6 +12,7 @@ import { err, ok } from 'neverthrow';
import type { Accessor } from 'solid-js';
import type { DocumentNotesSource, NotesSource } from '../context/notes-source';
import type {
+ DocumentNoteLink,
MeetingNote,
NoteCreateFailure,
NoteFailure,
@@ -198,7 +200,14 @@ export function createNotesSource(
};
}
-function documentLinksOptions(userId: string | undefined, documentId: string) {
+/** Reference previews are adapted at the calendar API boundary. */
+export type DocumentReference = DocumentNoteLink &
+ Pick<CalendarDocumentLink, 'teamEvent' | 'event' | 'canViewMeeting'>;
+
+export function documentLinksOptions(
+ userId: string | undefined,
+ documentId: string
+) {
return {
queryKey: notesKeys.documentLinks(userId, documentId).queryKey,
queryFn: async ({ signal }: { signal: AbortSignal }) => {
@@ -210,6 +219,8 @@ function documentLinksOptions(userId: string | undefined, documentId: string) {
enabled: !!userId,
staleTime: 0,
gcTime: 0,
+ refetchInterval: 30_000,
+ refetchOnWindowFocus: true,
};
}
diff --git a/apps/web/src/features/calendar-notes/queries/reference-preview.test.ts b/apps/web/src/features/calendar-notes/queries/reference-preview.test.ts
new file mode 100644
index 0000000000..e56129a177
--- /dev/null
+++ b/apps/web/src/features/calendar-notes/queries/reference-preview.test.ts
@@ -0,0 +1,109 @@
+import type { CalendarMentionEvent } from '@service-calendar/generated/schemas/calendarMentionEvent';
+import { describe, expect, it } from 'vitest';
+import type { DocumentReference } from './notes-source';
+import { resolveReferencePreview } from './reference-preview';
+
+const link: DocumentReference = {
+ eventId: 'linked-copy',
+ canViewMeeting: true,
+ eventTitle: 'Planning',
+ occurrenceKey: '2026-10-26T14:00:00+00:00',
+};
+const preview: CalendarMentionEvent = {
+ title: 'Planning',
+ viewerEventId: 'viewer-copy',
+ time: {
+ kind: 'timed',
+ startsAt: '2026-10-26T14:00:00Z',
+ endsAt: '2026-10-26T15:00:00Z',
+ },
+ occurrenceKey: link.occurrenceKey,
+ isRecurring: true,
+ description: null,
+ location: null,
+ organizerEmail: null,
+ organizerName: null,
+ attendeeCount: 2,
+ updatedAt: '2026-10-25T12:00:00Z',
+ canRequestToJoin: false,
+};
+
+describe('meeting reference resolution', () => {
+ it('never recovers details for an unavailable owner link from a retained preview', () => {
+ expect(
+ resolveReferencePreview({
+ ...link,
+ canViewMeeting: false,
+ event: preview,
+ })
+ ).toBeUndefined();
+ });
+ it('never substitutes another instance for a cancelled linked occurrence', () => {
+ expect(
+ resolveReferencePreview({ ...link, event: preview })?.event.viewerEventId
+ ).toBe('viewer-copy');
+ expect(
+ resolveReferencePreview({
+ ...link,
+ event: {
+ ...preview,
+ occurrenceKey: '2026-10-27T14:00:00+00:00',
+ },
+ })
+ ).toBeUndefined();
+ expect(
+ resolveReferencePreview({
+ ...link,
+ event: { ...preview, occurrenceKey: null },
+ })
+ ).toBeUndefined();
+ });
+
+ it('follows a rescheduled one-time meeting but not a conversion into a series', () => {
+ const moved = {
+ ...preview,
+ isRecurring: false,
+ occurrenceKey: '2026-10-28T16:00:00+00:00',
+ };
+ expect(
+ resolveReferencePreview({
+ ...link,
+ occurrenceKey: 'single',
+ event: moved,
+ })?.event
+ ).toBe(moved);
+ expect(
+ resolveReferencePreview({
+ ...link,
+ occurrenceKey: 'single',
+ event: { ...moved, isRecurring: true },
+ })
+ ).toBeUndefined();
+ });
+
+ it('uses authorized team details without channel-sharing actions or a calendar copy', () => {
+ const result = resolveReferencePreview({
+ ...link,
+ teamEvent: {
+ id: 'opaque-team-projection',
+ ownerId: 'macro|[email protected]',
+ time: preview.time,
+ contributesToAvailability: true,
+ kind: 'details',
+ details: {
+ title: 'Source-scoped planning',
+ description: null,
+ location: null,
+ conferenceUrl: null,
+ organizerEmail: null,
+ organizerName: null,
+ attendees: [],
+ calendarName: 'Work',
+ },
+ },
+ });
+ expect(result?.event.title).toBe('Source-scoped planning');
+ expect(result?.event.viewerEventId).toBeNull();
+ expect(result?.sharedActions).toBe(false);
+ });
+});
diff --git a/apps/web/src/features/calendar-notes/queries/reference-preview.ts b/apps/web/src/features/calendar-notes/queries/reference-preview.ts
new file mode 100644
index 0000000000..aeaf835ea2
--- /dev/null
+++ b/apps/web/src/features/calendar-notes/queries/reference-preview.ts
@@ -0,0 +1,28 @@
+import type { CalendarMentionEvent } from '@service-calendar/generated/schemas/calendarMentionEvent';
+import type { DocumentReference } from './notes-source';
+
+/** Mentions may fall forward to another instance; durable note links never do. */
+export function resolveReferencePreview(link: DocumentReference) {
+ if (!link.canViewMeeting) return undefined;
+ const preview = link.event;
+ const exact =
+ preview &&
+ (link.occurrenceKey === 'single'
+ ? !preview.isRecurring
+ : preview.occurrenceKey === link.occurrenceKey);
+ if (exact) return { event: preview, sharedActions: false };
+ const team = link.teamEvent;
+ if (team?.kind !== 'details') return undefined;
+ return {
+ event: {
+ ...team.details,
+ time: team.time,
+ viewerEventId: null,
+ occurrenceKey:
+ link.occurrenceKey === 'single' ? undefined : link.occurrenceKey,
+ isRecurring: link.occurrenceKey !== 'single',
+ attendeeCount: team.details.attendees.length,
+ } satisfies Omit<CalendarMentionEvent, 'updatedAt'>,
+ sharedActions: false,
+ };
+}
diff --git a/apps/web/src/lib/core/component/DocumentPreview.tsx b/apps/web/src/lib/core/component/DocumentPreview.tsx
index 1104d20e03..0d6785fb13 100644
--- a/apps/web/src/lib/core/component/DocumentPreview.tsx
+++ b/apps/web/src/lib/core/component/DocumentPreview.tsx
@@ -329,7 +329,7 @@ const calendarTimeFormat = new Intl.DateTimeFormat(undefined, {
/** One compact local-time schedule line for a calendar mention preview. */
export function calendarPreviewSchedule(
- event: PreviewCalendarEventAccess['event']
+ event: Pick<PreviewCalendarEventAccess['event'], 'time'>
): string | undefined {
if (event.time.kind === 'allDay') {
const start = parseLocalDate(event.time.startDate);
@@ -364,12 +364,14 @@ function heldOnCalendarLabel(
}
/** Meeting-level rows of the calendar mention hover card. */
-function CalendarEventPreviewDetails(props: {
- event: PreviewCalendarEventAccess['event'];
+export function CalendarEventPreviewDetails(props: {
+ event: Omit<PreviewCalendarEventAccess['event'], 'updatedAt'>;
/** The mentioned event, which a read-only share copies from. */
mentionedEventId: string;
/** Opens the viewer's own copy; absent where the card cannot open it. */
onOpen?: (event: MouseEvent) => void;
+ /** Team-calendar projections have no channel-share mutation capabilities. */
+ sharedActions?: boolean;
}) {
const organizer = () =>
props.event.organizerName ?? props.event.organizerEmail;
@@ -455,7 +457,9 @@ function CalendarEventPreviewDetails(props: {
</MetadataInfo>
</Show>
<Switch>
- <Match when={!props.event.viewerEventId}>
+ <Match
+ when={!props.event.viewerEventId && props.sharedActions !== false}
+ >
<SharedEventActions
eventId={props.mentionedEventId}
title={props.event.title}
diff --git a/apps/web/src/lib/core/component/References.tsx b/apps/web/src/lib/core/component/References.tsx
index a8440ca9ba..2649448ffe 100644
--- a/apps/web/src/lib/core/component/References.tsx
+++ b/apps/web/src/lib/core/component/References.tsx
@@ -97,19 +97,25 @@ interface ReferenceRowProps {
source: JSX.Element;
senderAvatar?: JSX.Element;
senderName?: string;
- timestamp: DateValue;
+ timestamp?: DateValue;
+ timestampLabel?: string;
+ ariaLabel?: string;
body?: JSX.Element;
onClick?: (e: KeyboardEvent | MouseEvent) => void;
}
-function ReferenceRow(props: ReferenceRowProps) {
+export function ReferenceRow(props: ReferenceRowProps) {
const navHandlers = useSplitNavigationHandler<HTMLDivElement>((e) => {
props.onClick?.(e);
});
+ const timestamp = () =>
+ props.timestampLabel ??
+ (props.timestamp ? formatRelativeTimestamp(props.timestamp) : undefined);
return (
<div
role="button"
+ aria-label={props.ariaLabel}
tabIndex={0}
class="group/ref-row flex min-w-0 flex-col overflow-hidden rounded-lg py-1 hover:bg-hover/30 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
onMouseDown={navHandlers.onMouseDown}
@@ -134,12 +140,18 @@ function ReferenceRow(props: ReferenceRowProps) {
{props.source}
</div>
</div>
- <span aria-hidden class="shrink-0 text-ink-extra-muted">
- ·
- </span>
- <span class="shrink-0 text-ink-extra-muted tabular-nums">
- {formatRelativeTimestamp(props.timestamp)}
- </span>
+ <Show when={timestamp()}>
+ {(label) => (
+ <>
+ <span aria-hidden class="shrink-0 text-ink-extra-muted">
+ ·
+ </span>
+ <span class="shrink-0 text-ink-extra-muted tabular-nums">
+ {label()}
+ </span>
+ </>
+ )}
+ </Show>
</div>
<Show when={props.body}>
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/client.ts b/apps/web/src/lib/service-clients/service-calendar/generated/client.ts
index fc3e33fcef..46582ed843 100644
--- a/apps/web/src/lib/service-clients/service-calendar/generated/client.ts
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/client.ts
@@ -1128,7 +1128,7 @@ export const noteDocuments = async (
};
/**
- * @summary List an owned document's meeting grants, including unavailable meetings.
+ * @summary List a document's visible meeting links; owners also see unavailable grants.
*/
export type documentNoteLinksResponse200 = {
data: DocumentNoteLink[];
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEvent.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEvent.ts
new file mode 100644
index 0000000000..b72774a831
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEvent.ts
@@ -0,0 +1,62 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { CalendarMentionEventDescription } from './calendarMentionEventDescription';
+import type { CalendarMentionEventJoinRequestStatus } from './calendarMentionEventJoinRequestStatus';
+import type { CalendarMentionEventLocation } from './calendarMentionEventLocation';
+import type { CalendarMentionEventOccurrenceKey } from './calendarMentionEventOccurrenceKey';
+import type { CalendarMentionEventOrganizerEmail } from './calendarMentionEventOrganizerEmail';
+import type { CalendarMentionEventOrganizerName } from './calendarMentionEventOrganizerName';
+import type { CalendarMentionEventViewerCopy } from './calendarMentionEventViewerCopy';
+import type { CalendarMentionEventViewerEventId } from './calendarMentionEventViewerEventId';
+import type { EventTime } from './eventTime';
+
+/**
+ * Meeting-level fields shown in a calendar event mention preview, taken from
+the requester's own projection of the meeting, or — when the requester has
+none — from the mentioned projection a channel they belong to was given.
+ */
+export interface CalendarMentionEvent {
+ /**
+ * Number of attendees on the previewed copy.
+ * @minimum 0
+ */
+ attendeeCount: number;
+ /** For a channel-shared preview, whether the person who shared it can
+add the requester as a guest. Always false for the requester's own
+copy. */
+ canRequestToJoin?: boolean;
+ /** Provider description, plain text or HTML, truncated for the preview.
+Clients must sanitize it before rendering. */
+ description?: CalendarMentionEventDescription;
+ /** Whether the event repeats. */
+ isRecurring: boolean;
+ joinRequestStatus?: CalendarMentionEventJoinRequestStatus;
+ /** Location label, when set. */
+ location?: CalendarMentionEventLocation;
+ /** Key of the previewed instance, absent when no occurrence is
+materialized. */
+ occurrenceKey?: CalendarMentionEventOccurrenceKey;
+ /** Organizer email. */
+ organizerEmail?: CalendarMentionEventOrganizerEmail;
+ /** Organizer display name. */
+ organizerName?: CalendarMentionEventOrganizerName;
+ /** Time of the previewed instance: the requested occurrence when it
+exists, else the next upcoming one, else the latest past one, else the
+series start. */
+ time: EventTime;
+ /** Display title. */
+ title: string;
+ /** Entity update time of the previewed copy. */
+ updatedAt: string;
+ viewerCopy?: CalendarMentionEventViewerCopy;
+ /** The requester's own event entity for the mentioned meeting. Differs
+from the mentioned id when the mention came from another attendee.
+Absent when the meeting is on none of the requester's calendars and
+they see it only because it was shared with one of their channels:
+that preview is read-only and there is no event of theirs to open. */
+ viewerEventId?: CalendarMentionEventViewerEventId;
+}
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventDescription.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventDescription.ts
new file mode 100644
index 0000000000..9a1c557eb9
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventDescription.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * Provider description, plain text or HTML, truncated for the preview.
+Clients must sanitize it before rendering.
+ */
+export type CalendarMentionEventDescription = string | null;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventJoinRequestStatus.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventJoinRequestStatus.ts
new file mode 100644
index 0000000000..27b82d8f2e
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventJoinRequestStatus.ts
@@ -0,0 +1,10 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { CalendarJoinRequestStatus } from './calendarJoinRequestStatus';
+
+export type CalendarMentionEventJoinRequestStatus =
+ null | CalendarJoinRequestStatus;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventLocation.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventLocation.ts
new file mode 100644
index 0000000000..505e0e0073
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventLocation.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * Location label, when set.
+ */
+export type CalendarMentionEventLocation = string | null;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventOccurrenceKey.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventOccurrenceKey.ts
new file mode 100644
index 0000000000..46c50a8fb6
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventOccurrenceKey.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * Key of the previewed instance, absent when no occurrence is
+materialized.
+ */
+export type CalendarMentionEventOccurrenceKey = string | null;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventOrganizerEmail.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventOrganizerEmail.ts
new file mode 100644
index 0000000000..815fb1f57b
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventOrganizerEmail.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * Organizer email.
+ */
+export type CalendarMentionEventOrganizerEmail = string | null;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventOrganizerName.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventOrganizerName.ts
new file mode 100644
index 0000000000..051a6f9091
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventOrganizerName.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * Organizer display name.
+ */
+export type CalendarMentionEventOrganizerName = string | null;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventViewerCopy.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventViewerCopy.ts
new file mode 100644
index 0000000000..8b9cddde1a
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventViewerCopy.ts
@@ -0,0 +1,9 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { CalendarMentionViewerCopy } from './calendarMentionViewerCopy';
+
+export type CalendarMentionEventViewerCopy = null | CalendarMentionViewerCopy;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventViewerEventId.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventViewerEventId.ts
new file mode 100644
index 0000000000..5ad1f4d7cc
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionEventViewerEventId.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * The requester's own event entity for the mentioned meeting. Differs
+from the mentioned id when the mention came from another attendee.
+Absent when the meeting is on none of the requester's calendars and
+they see it only because it was shared with one of their channels:
+that preview is read-only and there is no event of theirs to open.
+ */
+export type CalendarMentionEventViewerEventId = string | null;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionViewerCopy.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionViewerCopy.ts
new file mode 100644
index 0000000000..cea91a4ec8
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/calendarMentionViewerCopy.ts
@@ -0,0 +1,21 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * How a requester holds a mentioned meeting on their own calendar, decided
+by the copy's own inbox, the way viewer capabilities decide organizer and
+guest.
+ */
+export type CalendarMentionViewerCopy =
+ (typeof CalendarMentionViewerCopy)[keyof typeof CalendarMentionViewerCopy];
+
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export const CalendarMentionViewerCopy = {
+ snapshot: 'snapshot',
+ invitation: 'invitation',
+ event: 'event',
+} as const;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/documentNoteLink.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/documentNoteLink.ts
index 7ae0e2f6be..f408ec9987 100644
--- a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/documentNoteLink.ts
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/documentNoteLink.ts
@@ -4,14 +4,19 @@
* calendar_service
* OpenAPI spec version: 0.1.0
*/
+import type { DocumentNoteLinkEvent } from './documentNoteLinkEvent';
import type { DocumentNoteLinkTeam } from './documentNoteLinkTeam';
+import type { DocumentNoteLinkTeamEvent } from './documentNoteLinkTeamEvent';
/**
- * An owner's durable sharing link, including meetings they can no longer open.
+ * A visible meeting link, or an owner's durable grant they can no longer open.
*/
export interface DocumentNoteLink {
- /** Current name of the owned markdown document. */
+ /** Whether the reader may resolve this exact meeting's details right now. */
+ canViewMeeting: boolean;
+ /** Current name of the markdown document. */
documentName: string;
+ event?: DocumentNoteLinkEvent;
/** Linked calendar copy. */
eventId: string;
/** Current title, or a safe placeholder when meeting details are unavailable. */
@@ -19,4 +24,5 @@ export interface DocumentNoteLink {
/** Original occurrence start, or `single` for a one-time meeting. */
occurrenceKey: string;
team?: DocumentNoteLinkTeam;
+ teamEvent?: DocumentNoteLinkTeamEvent;
}
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/documentNoteLinkEvent.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/documentNoteLinkEvent.ts
new file mode 100644
index 0000000000..4a8996e2f7
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/documentNoteLinkEvent.ts
@@ -0,0 +1,9 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { CalendarMentionEvent } from './calendarMentionEvent';
+
+export type DocumentNoteLinkEvent = null | CalendarMentionEvent;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/documentNoteLinkTeamEvent.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/documentNoteLinkTeamEvent.ts
new file mode 100644
index 0000000000..756ad2d5e8
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/documentNoteLinkTeamEvent.ts
@@ -0,0 +1,9 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { TeamCalendarItem } from './teamCalendarItem';
+
+export type DocumentNoteLinkTeamEvent = null | TeamCalendarItem;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/index.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/index.ts
index 933cdf7475..25117eaef5 100644
--- a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/index.ts
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/index.ts
@@ -38,6 +38,16 @@ export * from './calendarGuestInputBody';
export * from './calendarJoinRequest';
export * from './calendarJoinRequestDecision';
export * from './calendarJoinRequestStatus';
+export * from './calendarMentionEvent';
+export * from './calendarMentionEventDescription';
+export * from './calendarMentionEventJoinRequestStatus';
+export * from './calendarMentionEventLocation';
+export * from './calendarMentionEventOccurrenceKey';
+export * from './calendarMentionEventOrganizerEmail';
+export * from './calendarMentionEventOrganizerName';
+export * from './calendarMentionEventViewerCopy';
+export * from './calendarMentionEventViewerEventId';
+export * from './calendarMentionViewerCopy';
export * from './calendarMutationApiError';
export * from './calendarMutationErrorCode';
export * from './calendarProvider';
@@ -65,7 +75,9 @@ export * from './createCalendarEventRequestTransparency';
export * from './createCalendarEventRequestVisibility';
export * from './deleteCalendarEventParams';
export * from './documentNoteLink';
+export * from './documentNoteLinkEvent';
export * from './documentNoteLinkTeam';
+export * from './documentNoteLinkTeamEvent';
export * from './eventNotesParams';
export * from './eventReminderOverride';
export * from './eventReminders';
@@ -113,6 +125,19 @@ export * from './rsvpCalendarEventRequestCalendarId';
export * from './rsvpCalendarEventRequestRecurrenceId';
export * from './rsvpCalendarEventRequestRespondingEmail';
export * from './rsvpCalendarEventRequestScope';
+export * from './teamCalendarContent';
+export * from './teamCalendarContentOneOf';
+export * from './teamCalendarContentOneOfKind';
+export * from './teamCalendarContentOneOfThree';
+export * from './teamCalendarContentOneOfThreeKind';
+export * from './teamCalendarDetails';
+export * from './teamCalendarDetailsConferenceUrl';
+export * from './teamCalendarDetailsDescription';
+export * from './teamCalendarDetailsLocation';
+export * from './teamCalendarDetailsOrganizerEmail';
+export * from './teamCalendarDetailsOrganizerName';
+export * from './teamCalendarItem';
+export * from './teamCalendarItemAllOf';
export * from './teamCalendarSharing';
export * from './teamCalendarSharingBody';
export * from './unlinkEventNoteParams';
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarContent.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarContent.ts
new file mode 100644
index 0000000000..9a168034d4
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarContent.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { TeamCalendarContentOneOf } from './teamCalendarContentOneOf';
+import type { TeamCalendarContentOneOfThree } from './teamCalendarContentOneOfThree';
+
+/**
+ * Disjoint busy/detail shapes prevent new event fields leaking by default.
+ */
+export type TeamCalendarContent =
+ | TeamCalendarContentOneOf
+ | TeamCalendarContentOneOfThree;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarContentOneOf.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarContentOneOf.ts
new file mode 100644
index 0000000000..8b004d25b5
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarContentOneOf.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { TeamCalendarContentOneOfKind } from './teamCalendarContentOneOfKind';
+
+/**
+ * No provider or event metadata.
+ */
+export type TeamCalendarContentOneOf = {
+ kind: TeamCalendarContentOneOfKind;
+};
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarContentOneOfKind.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarContentOneOfKind.ts
new file mode 100644
index 0000000000..4b88ffe980
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarContentOneOfKind.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+export type TeamCalendarContentOneOfKind =
+ (typeof TeamCalendarContentOneOfKind)[keyof typeof TeamCalendarContentOneOfKind];
+
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export const TeamCalendarContentOneOfKind = {
+ busy: 'busy',
+} as const;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarContentOneOfThree.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarContentOneOfThree.ts
new file mode 100644
index 0000000000..b5b41491c3
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarContentOneOfThree.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+import type { TeamCalendarContentOneOfThreeKind } from './teamCalendarContentOneOfThreeKind';
+import type { TeamCalendarDetails } from './teamCalendarDetails';
+
+/**
+ * Explicitly authorized source content.
+ */
+export type TeamCalendarContentOneOfThree = {
+ /** Detail projection. */
+ details: TeamCalendarDetails;
+ kind: TeamCalendarContentOneOfThreeKind;
+};
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarContentOneOfThreeKind.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarContentOneOfThreeKind.ts
new file mode 100644
index 0000000000..88187f095b
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarContentOneOfThreeKind.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+export type TeamCalendarContentOneOfThreeKind =
+ (typeof TeamCalendarContentOneOfThreeKind)[keyof typeof TeamCalendarContentOneOfThreeKind];
+
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export const TeamCalendarContentOneOfThreeKind = {
+ details: 'details',
+} as const;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarDetails.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarDetails.ts
new file mode 100644
index 0000000000..b5012306a8
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarDetails.ts
@@ -0,0 +1,34 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { CalendarAttendee } from './calendarAttendee';
+import type { TeamCalendarDetailsConferenceUrl } from './teamCalendarDetailsConferenceUrl';
+import type { TeamCalendarDetailsDescription } from './teamCalendarDetailsDescription';
+import type { TeamCalendarDetailsLocation } from './teamCalendarDetailsLocation';
+import type { TeamCalendarDetailsOrganizerEmail } from './teamCalendarDetailsOrganizerEmail';
+import type { TeamCalendarDetailsOrganizerName } from './teamCalendarDetailsOrganizerName';
+
+/**
+ * Safe details from a single authorized source.
+ */
+export interface TeamCalendarDetails {
+ /** Attendees; self flags are relative to the requesting viewer. */
+ attendees: CalendarAttendee[];
+ /** Source calendar name, shown only with details. */
+ calendarName: string;
+ /** Join URL, if supplied by this source. */
+ conferenceUrl?: TeamCalendarDetailsConferenceUrl;
+ /** Body, if supplied by this source. */
+ description?: TeamCalendarDetailsDescription;
+ /** Location, if supplied by this source. */
+ location?: TeamCalendarDetailsLocation;
+ /** Organizer address from this source. */
+ organizerEmail?: TeamCalendarDetailsOrganizerEmail;
+ /** Organizer name from this source. */
+ organizerName?: TeamCalendarDetailsOrganizerName;
+ /** Display title. */
+ title: string;
+}
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarDetailsConferenceUrl.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarDetailsConferenceUrl.ts
new file mode 100644
index 0000000000..59d3891b3c
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarDetailsConferenceUrl.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * Join URL, if supplied by this source.
+ */
+export type TeamCalendarDetailsConferenceUrl = string | null;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarDetailsDescription.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarDetailsDescription.ts
new file mode 100644
index 0000000000..74465a13c6
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarDetailsDescription.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * Body, if supplied by this source.
+ */
+export type TeamCalendarDetailsDescription = string | null;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarDetailsLocation.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarDetailsLocation.ts
new file mode 100644
index 0000000000..c5fc6f8b99
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarDetailsLocation.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * Location, if supplied by this source.
+ */
+export type TeamCalendarDetailsLocation = string | null;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarDetailsOrganizerEmail.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarDetailsOrganizerEmail.ts
new file mode 100644
index 0000000000..debd5b0a08
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarDetailsOrganizerEmail.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * Organizer address from this source.
+ */
+export type TeamCalendarDetailsOrganizerEmail = string | null;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarDetailsOrganizerName.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarDetailsOrganizerName.ts
new file mode 100644
index 0000000000..8053194907
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarDetailsOrganizerName.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * Organizer name from this source.
+ */
+export type TeamCalendarDetailsOrganizerName = string | null;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarItem.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarItem.ts
new file mode 100644
index 0000000000..bbb14fba76
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarItem.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { TeamCalendarContent } from './teamCalendarContent';
+import type { TeamCalendarItemAllOf } from './teamCalendarItemAllOf';
+
+/**
+ * A read-only team calendar occurrence.
+ */
+export type TeamCalendarItem = TeamCalendarContent & TeamCalendarItemAllOf;
diff --git a/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarItemAllOf.ts b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarItemAllOf.ts
new file mode 100644
index 0000000000..533689e4c1
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-calendar/generated/schemas/teamCalendarItemAllOf.ts
@@ -0,0 +1,19 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * calendar_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { EventTime } from './eventTime';
+
+export type TeamCalendarItemAllOf = {
+ /** Whether this occurrence blocks the sharer's personal availability.
+A subscribed calendar's block can be shared without occupying the sharer. */
+ contributesToAvailability: boolean;
+ /** Stable opaque projection identity, never an event entity id. */
+ id: string;
+ /** The person sharing access to the source. */
+ ownerId: string;
+ /** Occurrence interval. */
+ time: EventTime;
+};
diff --git a/apps/web/src/lib/service-clients/service-calendar/openapi.json b/apps/web/src/lib/service-clients/service-calendar/openapi.json
index 7afaad6b95..fafd7f2792 100644
--- a/apps/web/src/lib/service-clients/service-calendar/openapi.json
+++ b/apps/web/src/lib/service-clients/service-calendar/openapi.json
@@ -1008,7 +1008,7 @@
"/meeting-notes/documents/{document_id}/links": {
"get": {
"tags": ["calendar_events"],
- "summary": "List an owned document's meeting grants, including unavailable meetings.",
+ "summary": "List a document's visible meeting links; owners also see unavailable grants.",
"operationId": "document_note_links",
"parameters": [
{
@@ -1665,6 +1665,97 @@
"description": "Lifecycle of a request to be added as a guest of a shared event.",
"enum": ["pending", "accepted", "declined"]
},
+ "CalendarMentionEvent": {
+ "type": "object",
+ "description": "Meeting-level fields shown in a calendar event mention preview, taken from\nthe requester's own projection of the meeting, or — when the requester has\nnone — from the mentioned projection a channel they belong to was given.",
+ "required": [
+ "title",
+ "time",
+ "isRecurring",
+ "attendeeCount",
+ "updatedAt"
+ ],
+ "properties": {
+ "attendeeCount": {
+ "type": "integer",
+ "description": "Number of attendees on the previewed copy.",
+ "minimum": 0
+ },
+ "canRequestToJoin": {
+ "type": "boolean",
+ "description": "For a channel-shared preview, whether the person who shared it can\nadd the requester as a guest. Always false for the requester's own\ncopy."
+ },
+ "description": {
+ "type": ["string", "null"],
+ "description": "Provider description, plain text or HTML, truncated for the preview.\nClients must sanitize it before rendering."
+ },
+ "isRecurring": {
+ "type": "boolean",
+ "description": "Whether the event repeats."
+ },
+ "joinRequestStatus": {
+ "oneOf": [
+ {
+ "type": "null"
+ },
+ {
+ "$ref": "#/components/schemas/CalendarJoinRequestStatus",
+ "description": "For a channel-shared preview, the requester's request to join, if any."
+ }
+ ]
+ },
+ "location": {
+ "type": ["string", "null"],
+ "description": "Location label, when set."
+ },
+ "occurrenceKey": {
+ "type": ["string", "null"],
+ "description": "Key of the previewed instance, absent when no occurrence is\nmaterialized."
+ },
+ "organizerEmail": {
+ "type": ["string", "null"],
+ "description": "Organizer email."
+ },
+ "organizerName": {
+ "type": ["string", "null"],
+ "description": "Organizer display name."
+ },
+ "time": {
+ "$ref": "#/components/schemas/EventTime",
+ "description": "Time of the previewed instance: the requested occurrence when it\nexists, else the next upcoming one, else the latest past one, else the\nseries start."
+ },
+ "title": {
+ "type": "string",
+ "description": "Display title."
+ },
+ "updatedAt": {
+ "type": "string",
+ "format": "date-time",
+ "description": "Entity update time of the previewed copy."
+ },
+ "viewerCopy": {
+ "oneOf": [
+ {
+ "type": "null"
+ },
+ {
+ "$ref": "#/components/schemas/CalendarMentionViewerCopy",
+ "description": "How the requester holds the meeting through `viewer_event_id`; absent\nexactly when that is."
+ }
+ ]
+ },
+ "viewerEventId": {
+ "type": ["string", "null"],
+ "format": "uuid",
+ "description": "The requester's own event entity for the mentioned meeting. Differs\nfrom the mentioned id when the mention came from another attendee.\nAbsent when the meeting is on none of the requester's calendars and\nthey see it only because it was shared with one of their channels:\nthat preview is read-only and there is no event of theirs to open."
+ }
+ }
+ },
+ "CalendarMentionViewerCopy": {
+ "type": "string",
+ "description": "How a requester holds a mentioned meeting on their own calendar, decided\nby the copy's own inbox, the way viewer capabilities decide organizer and\nguest.",
+ "enum": ["snapshot", "invitation", "event"]
+ },
"CalendarMutationApiError": {
"type": "object",
"description": "HTTP error body returned by calendar mutation endpoints.",
@@ -1942,12 +2033,33 @@
},
"DocumentNoteLink": {
"type": "object",
- "description": "An owner's durable sharing link, including meetings they can no longer open.",
- "required": ["documentName", "eventId", "occurrenceKey", "eventTitle"],
+ "description": "A visible meeting link, or an owner's durable grant they can no longer open.",
+ "required": [
+ "documentName",
+ "eventId",
+ "occurrenceKey",
+ "eventTitle",
+ "canViewMeeting"
+ ],
"properties": {
+ "canViewMeeting": {
+ "type": "boolean",
+ "description": "Whether the reader may resolve this exact meeting's details right now."
+ },
"documentName": {
"type": "string",
- "description": "Current name of the owned markdown document."
+ "description": "Current name of the markdown document."
+ },
+ "event": {
+ "oneOf": [
+ {
+ "type": "null"
+ },
+ {
+ "$ref": "#/components/schemas/CalendarMentionEvent",
+ "description": "Exact accessible calendar preview, resolved with this link's authorization snapshot."
+ }
+ ]
},
"eventId": {
"type": "string",
@@ -1972,6 +2084,17 @@
"description": "Independent optional team audience."
}
]
+ },
+ "teamEvent": {
+ "oneOf": [
+ {
+ "type": "null"
+ },
+ {
+ "$ref": "#/components/schemas/TeamCalendarItem",
+ "description": "Exact, sanitized team-calendar details when the meeting is shared through a team."
+ }
+ ]
}
}
},
@@ -2386,6 +2509,110 @@
}
}
},
+ "TeamCalendarContent": {
+ "oneOf": [
+ {
+ "type": "object",
+ "description": "No provider or event metadata.",
+ "required": ["kind"],
+ "properties": {
+ "kind": {
+ "type": "string",
+ "enum": ["busy"]
+ }
+ }
+ },
+ {
+ "type": "object",
+ "description": "Explicitly authorized source content.",
+ "required": ["details", "kind"],
+ "properties": {
+ "details": {
+ "$ref": "#/components/schemas/TeamCalendarDetails",
+ "description": "Detail projection."
+ },
+ "kind": {
+ "type": "string",
+ "enum": ["details"]
+ }
+ }
+ }
+ ],
+ "description": "Disjoint busy/detail shapes prevent new event fields leaking by default."
+ },
+ "TeamCalendarDetails": {
+ "type": "object",
+ "description": "Safe details from a single authorized source.",
+ "required": ["title", "attendees", "calendarName"],
+ "properties": {
+ "attendees": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/CalendarAttendee"
+ },
+ "description": "Attendees; self flags are relative to the requesting viewer."
+ },
+ "calendarName": {
+ "type": "string",
+ "description": "Source calendar name, shown only with details."
+ },
+ "conferenceUrl": {
+ "type": ["string", "null"],
+ "description": "Join URL, if supplied by this source."
+ },
+ "description": {
+ "type": ["string", "null"],
+ "description": "Body, if supplied by this source."
+ },
+ "location": {
+ "type": ["string", "null"],
+ "description": "Location, if supplied by this source."
+ },
+ "organizerEmail": {
+ "type": ["string", "null"],
+ "description": "Organizer address from this source."
+ },
+ "organizerName": {
+ "type": ["string", "null"],
+ "description": "Organizer name from this source."
+ },
+ "title": {
+ "type": "string",
+ "description": "Display title."
+ }
+ }
+ },
+ "TeamCalendarItem": {
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/TeamCalendarContent",
+ "description": "Authorized content variant."
+ },
+ {
+ "type": "object",
+ "required": ["id", "ownerId", "time", "contributesToAvailability"],
+ "properties": {
+ "contributesToAvailability": {
+ "type": "boolean",
+ "description": "Whether this occurrence blocks the sharer's personal availability.\nA subscribed calendar's block can be shared without occupying the sharer."
+ },
+ "id": {
+ "type": "string",
+ "description": "Stable opaque projection identity, never an event entity id."
+ },
+ "ownerId": {
+ "type": "string",
+ "description": "The person sharing access to the source."
+ },
+ "time": {
+ "$ref": "#/components/schemas/EventTime",
+ "description": "Occurrence interval."
+ }
+ }
+ }
+ ],
+ "description": "A read-only team calendar occurrence."
+ },
"TeamCalendarSharing": {
"type": "string",
"description": "What a user exposes through their team membership.",
diff --git a/crates/agent_code_mode/src/domain/documentation.json b/crates/agent_code_mode/src/domain/documentation.json
index b842192587..28b64141aa 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\nA meeting on more than one of the user's inboxes is one event per inbox;\n[CalendarNamespace.occurrences](#occurrences) lists each copy with its `inbox` and\n`role`. Before changing such a meeting's details, guests or guest\npermissions, or deleting it, ask the user which inbox's copy to change, then\npass that copy's `inbox` to [CalendarEvent.update](../../event/classes/CalendarEvent.md#update),\n[CalendarEvent.inviteGuests](../../event/classes/CalendarEvent.md#inviteguests) or [CalendarEvent.delete](../../event/classes/CalendarEvent.md#delete). Never\nchoose between the user's inboxes yourself, whatever they look like: a\ntest, secondary or unfamiliar address is still the user's own inbox. Skip\nthe question only when the user already named the inbox, when only one copy\ncan make the change, or when adding guests from the copy the user\norganizes, and say why. Reminders may go to one copy; name its inbox. Read\nthose three methods' documentation before changing a meeting held through\nseveral inboxes: it says what each change does from each copy.\n\n[CalendarEvent.addToCalendar](../../event/classes/CalendarEvent.md#addtocalendar) adds a shared meeting only while none\nof the user's calendars holds it. Refused with `already_on_calendar`, it is\nrefused on every calendar, so tell the user the meeting is already on their\ncalendar and never offer to add it to another one.\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.\n\nBefore changing or deleting such a meeting, ask the user which inbox's\ncopy to change, unless they named it, only one copy can make the change,\nor you add guests from the copy they organize. Never choose between the\nuser's inboxes yourself, whatever they look like. Pass the chosen copy's\n`inbox` to its `update`, `inviteGuests` or `delete`; without it the call\nis refused with `copy_choice_required`, which names each copy's inbox and\nevent and gives the question to ask. An occurrence whose calendar is no\nlonger listed has no `inbox`; take it from that refusal.\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, whichever calendar is named, so it cannot be added to\nanother of their calendars either; with `join_request_open` while their\nrequest to join it is pending or accepted (the meeting then arrives as an\ninvitation); and with `copy_refused` when Google will not import it.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options?` | \\{ `calendar?`: [`Calendar`](../../calendar/classes/Calendar.md); \\} |\n| `options.calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) |\n\n#### Returns\n\n`Promise`\\<`CalendarEvent`\\>\n\n***\n\n### delete()\n\n> **delete**(`options?`): `Promise`\\<`void`\\>\n\nDelete the event (or a scoped part of a recurring series) at its provider.\n\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\nA meeting on more than one of the user's inboxes is one event per inbox;\n[CalendarNamespace.occurrences](#occurrences) lists each copy with its `inbox` and\n`role`. Before changing such a meeting's details, guests or guest\npermissions, or deleting it, ask the user which inbox's copy to change, then\npass that copy's `inbox` to [CalendarEvent.update](../../event/classes/CalendarEvent.md#update),\n[CalendarEvent.inviteGuests](../../event/classes/CalendarEvent.md#inviteguests) or [CalendarEvent.delete](../../event/classes/CalendarEvent.md#delete). Never\nchoose between the user's inboxes yourself, whatever they look like: a\ntest, secondary or unfamiliar address is still the user's own inbox. Skip\nthe question only when the user already named the inbox, when only one copy\ncan make the change, or when adding guests from the copy the user\norganizes, and say why. Reminders may go to one copy; name its inbox. Read\nthose three methods' documentation before changing a meeting held through\nseveral inboxes: it says what each change does from each copy.\n\n[CalendarEvent.addToCalendar](../../event/classes/CalendarEvent.md#addtocalendar) adds a shared meeting only while none\nof the user's calendars holds it. Refused with `already_on_calendar`, it is\nrefused on every calendar, so tell the user the meeting is already on their\ncalendar and never offer to add it to another one.\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.\n\nBefore changing or deleting such a meeting, ask the user which inbox's\ncopy to change, unless they named it, only one copy can make the change,\nor you add guests from the copy they organize. Never choose between the\nuser's inboxes yourself, whatever they look like. Pass the chosen copy's\n`inbox` to its `update`, `inviteGuests` or `delete`; without it the call\nis refused with `copy_choice_required`, which names each copy's inbox and\nevent and gives the question to ask. An occurrence whose calendar is no\nlonger listed has no `inbox`; take it from that refusal.\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/CalendarJoinRequestStatus.md -->\n# Type Alias: CalendarJoinRequestStatus\n\n> **CalendarJoinRequestStatus** = `\"pending\"` \\| `\"accepted\"` \\| `\"declined\"`\n\nLifecycle of a request to be added as a guest of a shared event.\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarMentionEvent.md -->\n# Type Alias: CalendarMentionEvent\n\n> **CalendarMentionEvent** = \\{ `attendeeCount`: `number`; `canRequestToJoin?`: `boolean`; `description?`: `string` \\| `null`; `isRecurring`: `boolean`; `joinRequestStatus?`: `null` \\| [`CalendarJoinRequestStatus`](CalendarJoinRequestStatus.md); `location?`: `string` \\| `null`; `occurrenceKey?`: `string` \\| `null`; `organizerEmail?`: `string` \\| `null`; `organizerName?`: `string` \\| `null`; `time`: [`EventTime`](EventTime.md); `title`: `string`; `updatedAt`: `string`; `viewerCopy?`: `null` \\| [`CalendarMentionViewerCopy`](CalendarMentionViewerCopy.md); `viewerEventId?`: `string` \\| `null`; \\}\n\nMeeting-level fields shown in a calendar event mention preview, taken from\nthe requester's own projection of the meeting, or — when the requester has\nnone — from the mentioned projection a channel they belong to was given.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attendeecount\"></a> `attendeeCount` | `number` | Number of attendees on the previewed copy. |\n| <a id=\"property-canrequesttojoin\"></a> `canRequestToJoin?` | `boolean` | For a channel-shared preview, whether the person who shared it can add the requester as a guest. Always false for the requester's own copy. |\n| <a id=\"property-description\"></a> `description?` | `string` \\| `null` | Provider description, plain text or HTML, truncated for the preview. Clients must sanitize it before rendering. |\n| <a id=\"property-isrecurring\"></a> `isRecurring` | `boolean` | Whether the event repeats. |\n| <a id=\"property-joinrequeststatus\"></a> `joinRequestStatus?` | `null` \\| [`CalendarJoinRequestStatus`](CalendarJoinRequestStatus.md) | - |\n| <a id=\"property-location\"></a> `location?` | `string` \\| `null` | Location label, when set. |\n| <a id=\"property-occurrencekey\"></a> `occurrenceKey?` | `string` \\| `null` | Key of the previewed instance, absent when no occurrence is materialized. |\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-time\"></a> `time` | [`EventTime`](EventTime.md) | Time of the previewed instance: the requested occurrence when it exists, else the next upcoming one, else the latest past one, else the series start. |\n| <a id=\"property-title\"></a> `title` | `string` | Display title. |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `string` | Entity update time of the previewed copy. |\n| <a id=\"property-viewercopy\"></a> `viewerCopy?` | `null` \\| [`CalendarMentionViewerCopy`](CalendarMentionViewerCopy.md) | - |\n| <a id=\"property-viewereventid\"></a> `viewerEventId?` | `string` \\| `null` | The requester's own event entity for the mentioned meeting. Differs from the mentioned id when the mention came from another attendee. Absent when the meeting is on none of the requester's calendars and they see it only because it was shared with one of their channels: that preview is read-only and there is no event of theirs to open. |\n\n\n<!-- generated/calendar/types.gen/type-aliases/CalendarMentionViewerCopy.md -->\n# Type Alias: CalendarMentionViewerCopy\n\n> **CalendarMentionViewerCopy** = `\"snapshot\"` \\| `\"invitation\"` \\| `\"event\"`\n\nHow a requester holds a mentioned meeting on their own calendar, decided\nby the copy's own inbox, the way viewer capabilities decide organizer and\nguest.\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** = \\{ `canViewMeeting`: `boolean`; `documentName`: `string`; `event?`: `null` \\| [`CalendarMentionEvent`](CalendarMentionEvent.md); `eventId`: `string`; `eventTitle`: `string`; `occurrenceKey`: `string`; `team?`: `null` \\| [`NoteTeam`](NoteTeam.md); `teamEvent?`: `null` \\| [`TeamCalendarItem`](TeamCalendarItem.md); \\}\n\nA visible meeting link, or an owner's durable grant they can no longer open.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-canviewmeeting\"></a> `canViewMeeting` | `boolean` | Whether the reader may resolve this exact meeting's details right now. |\n| <a id=\"property-documentname\"></a> `documentName` | `string` | Current name of the markdown document. |\n| <a id=\"property-event\"></a> `event?` | `null` \\| [`CalendarMentionEvent`](CalendarMentionEvent.md) | - |\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| <a id=\"property-teamevent\"></a> `teamEvent?` | `null` \\| [`TeamCalendarItem`](TeamCalendarItem.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/TeamCalendarContent.md -->\n# Type Alias: TeamCalendarContent\n\n> **TeamCalendarContent** = \\{ `kind`: `\"busy\"`; \\} \\| \\{ `details`: [`TeamCalendarDetails`](TeamCalendarDetails.md); `kind`: `\"details\"`; \\}\n\nDisjoint busy/detail shapes prevent new event fields leaking by default.\n\n## Union Members\n\n### Type Literal\n\n\\{ `kind`: `\"busy\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `details`: [`TeamCalendarDetails`](TeamCalendarDetails.md); `kind`: `\"details\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `details` | [`TeamCalendarDetails`](TeamCalendarDetails.md) | Detail projection. |\n| `kind` | `\"details\"` | - |\n\n\n<!-- generated/calendar/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/calendar/types.gen/type-aliases/TeamCalendarItem.md -->\n# Type Alias: TeamCalendarItem\n\n> **TeamCalendarItem** = [`TeamCalendarContent`](TeamCalendarContent.md) & \\{ `contributesToAvailability`: `boolean`; `id`: `string`; `ownerId`: `string`; `time`: [`EventTime`](EventTime.md); \\}\n\nA read-only team calendar occurrence.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `contributesToAvailability` | `boolean` | Whether this occurrence blocks the sharer's personal availability. A subscribed calendar's block can be shared without occupying the sharer. |\n| `id` | `string` | Stable opaque projection identity, never an event entity id. |\n| `ownerId` | `string` | The person sharing access to the source. |\n| `time` | [`EventTime`](EventTime.md) | Occurrence interval. |\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, whichever calendar is named, so it cannot be added to\nanother of their calendars either; with `join_request_open` while their\nrequest to join it is pending or accepted (the meeting then arrives as an\ninvitation); and with `copy_refused` when Google will not import it.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options?` | \\{ `calendar?`: [`Calendar`](../../calendar/classes/Calendar.md); \\} |\n| `options.calendar?` | [`Calendar`](../../calendar/classes/Calendar.md) |\n\n#### Returns\n\n`Promise`\\<`CalendarEvent`\\>\n\n***\n\n### delete()\n\n> **delete**(`options?`): `Promise`\\<`void`\\>\n\nDelete the event (or a scoped part of a recurring series) at its provider.\n\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\nA meeting on more than one of the user's inboxes is one event per inbox;\n[CalendarNamespace.occurrences](#occurrences) lists each copy with its `inbox` and\n`role`. Before changing such a meeting's details, guests or guest\npermissions, or deleting it, ask the user which inbox's copy to change, then\npass that copy's `inbox` to [CalendarEvent.update](../../event/classes/CalendarEvent.md#update),\n[CalendarEvent.inviteGuests](../../event/classes/CalendarEvent.md#inviteguests) or [CalendarEvent.delete](../../event/classes/CalendarEvent.md#delete). Never\nchoose between the user's inboxes yourself, whatever they look like: a\ntest, secondary or unfamiliar address is still the user's own inbox. Skip\nthe question only when the user already named the inbox, when only one copy\ncan make the change, or when adding guests from the copy the user\norganizes, and say why. Reminders may go to one copy; name its inbox. Read\nthose three methods' documentation before changing a meeting held through\nseveral inboxes: it says what each change does from each copy.\n\n[CalendarEvent.addToCalendar](../../event/classes/CalendarEvent.md#addtocalendar) adds a shared meeting only while none\nof the user's calendars holds it. Refused with `already_on_calendar`, it is\nrefused on every calendar, so tell the user the meeting is already on their\ncalendar and never offer to add it to another one.\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.\n\nBefore changing or deleting such a meeting, ask the user which inbox's\ncopy to change, unless they named it, only one copy can make the change,\nor you add guests from the copy they organize. Never choose between the\nuser's inboxes yourself, whatever they look like. Pass the chosen copy's\n`inbox` to its `update`, `inviteGuests` or `delete`; without it the call\nis refused with `copy_choice_required`, which names each copy's inbox and\nevent and gives the question to ask. An occurrence whose calendar is no\nlonger listed has no `inbox`; take it from that refusal.\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",
@@ -99,7 +99,7 @@
"name": "documents",
"description": "Search, read, create, and manage documents and tasks.",
"overview": "<!-- src/entities/documents/namespace/classes/DocumentNamespace.md -->\n# Class: DocumentNamespace\n\n## Constructors\n\n### Constructor\n\n> **new DocumentNamespace**(`client`): `DocumentNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`DocumentNamespace`\n\n## Methods\n\n### byId()\n\n> **byId**(`id`): [`Document`](../../document/classes/Document.md)\n\nA handle to a document by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Document`](../../document/classes/Document.md)\n\n***\n\n### byTeamSlug()\n\n> **byTeamSlug**(`slug`): `Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\nResolve a team task reference such as ENG-42.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `slug` | `string` |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### create()\n\n> **create**(`opts`): `Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\nCreate a markdown document.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### createCanvas()\n\n> **createCanvas**(`opts`): `Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\nCreate a native Canvas with shared content ready for reading and editing.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### createSkill()\n\n> **createSkill**(`opts`): `Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\nCreate a skill: markdown instructions that AI reads and follows.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### createSnippet()\n\n> **createSnippet**(`opts`): `Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\nCreate a snippet: a reusable markdown document.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### createUpload()\n\n> **createUpload**(`options`): `Promise`\\<\\{ `content`: [`DocumentContent`](../../../../../generated/storage/types.gen/type-aliases/DocumentContent.md); `contentType`: `string`; `document`: [`Document`](../../document/classes/Document.md); `uploadUrl`: `string` \\| `undefined`; \\}\\>\n\nReserve a binary document and return upload instructions. Upload content before saving.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | \\{ `attachment?`: [`EmailAttachment`](../../../email/attachment/classes/EmailAttachment.md); `branchedFrom?`: [`Document`](../../document/classes/Document.md); `fileType?`: `string`; `isTask?`: `boolean`; `mimeType?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); `sha`: `string`; `team?`: [`Team`](../../../teams/team/classes/Team.md); \\} |\n| `options.attachment?` | [`EmailAttachment`](../../../email/attachment/classes/EmailAttachment.md) |\n| `options.branchedFrom?` | [`Document`](../../document/classes/Document.md) |\n| `options.fileType?` | `string` |\n| `options.isTask?` | `boolean` |\n| `options.mimeType?` | `string` |\n| `options.name` | `string` |\n| `options.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n| `options.sha` | `string` |\n| `options.team?` | [`Team`](../../../teams/team/classes/Team.md) |\n\n#### Returns\n\n`Promise`\\<\\{ `content`: [`DocumentContent`](../../../../../generated/storage/types.gen/type-aliases/DocumentContent.md); `contentType`: `string`; `document`: [`Document`](../../document/classes/Document.md); `uploadUrl`: `string` \\| `undefined`; \\}\\>\n\n***\n\n### recent()\n\n> **recent**(`opts?`): `AsyncGenerator`\\<[`Document`](../../document/classes/Document.md)\\>\n\nThe user's recent documents, most recent first, auto-paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `fileType?`: `string`; `pageSize?`: `number`; \\} |\n| `opts.fileType?` | `string` |\n| `opts.pageSize?` | `number` |\n\n#### Returns\n\n`AsyncGenerator`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### recentlyDeleted()\n\n> **recentlyDeleted**(): `Promise`\\<[`Document`](../../document/classes/Document.md)[]\\>\n\nThe user's recently soft-deleted documents.\n\n#### Returns\n\n`Promise`\\<[`Document`](../../document/classes/Document.md)[]\\>\n\n***\n\n### search()\n\n> **search**(`query`, `opts?`): `AsyncGenerator`\\<[`Document`](../../document/classes/Document.md)\\>\n\nSearch documents by name and content, most relevant first, auto-paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `query` | `string` |\n| `opts?` | [`SearchOpts`](../../../search/interfaces/SearchOpts.md) |\n\n#### Returns\n\n`AsyncGenerator`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### systemSkills()\n\n> **systemSkills**(): `Promise`\\<[`SystemSkill`](../../system-skill/classes/SystemSkill.md)[]\\>\n\nThe built-in system skills: static AI instructions with no document\nbehind them. Unlike user skills they cannot be opened or edited.\n\n#### Returns\n\n`Promise`\\<[`SystemSkill`](../../system-skill/classes/SystemSkill.md)[]\\>\n\n***\n\n### validatePermissionsToken()\n\n> **validatePermissionsToken**(`token`): `Promise`\\<\\{ `accessLevel`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md); `document`: [`Document`](../../document/classes/Document.md); `expiresAt`: `number`; `issuer`: `string`; `user`: [`User`](../../../users/user/classes/User.md) \\| `undefined`; \\}\\>\n\nValidate a permissions token, returning its document and optional user handles.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `token` | `string` |\n\n#### Returns\n\n`Promise`\\<\\{ `accessLevel`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md); `document`: [`Document`](../../document/classes/Document.md); `expiresAt`: `number`; `issuer`: `string`; `user`: [`User`](../../../users/user/classes/User.md) \\| `undefined`; \\}\\>\n",
- "documentation": "# Macro SDK: documents\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/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md -->\n# Type Alias: BulkUpdateEntityPropertyOptionsResponse\n\n> **BulkUpdateEntityPropertyOptionsResponse** = \\{ `properties`: [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[]; \\}\n\nResponse for a bulk option update: each property's reconciled final ids.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-properties\"></a> `properties` | [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[] | The final option ids per updated property. |\n\n\n<!-- generated/properties/types.gen/type-aliases/DataType.md -->\n# Type Alias: DataType\n\n> **DataType** = `\"BOOLEAN\"` \\| `\"DATE\"` \\| `\"NUMBER\"` \\| `\"STRING\"` \\| `\"SELECT_NUMBER\"` \\| `\"SELECT_STRING\"` \\| `\"TAG\"` \\| `\"ENTITY\"` \\| `\"LINK\"`\n\nData type for property values, determining storage and validation.\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityProperty.md -->\n# Type Alias: EntityProperty\n\n> **EntityProperty** = \\{ `created_at`: `string`; `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; \\}\n\nAssignment of a property definition to a specific entity (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyOptionSelectionResponse.md -->\n# Type Alias: EntityPropertyOptionSelectionResponse\n\n> **EntityPropertyOptionSelectionResponse** = \\{ `option_ids`: `string`[]; `property_id`: `string`; \\}\n\nThe reconciled final option ids stored for one property after a bulk update.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-option_ids\"></a> `option_ids` | `string`[] | The final option ids the server persisted, in stored order. |\n| <a id=\"property-property_id\"></a> `property_id` | `string` | The property definition the options belong to. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md -->\n# Type Alias: EntityPropertyWithDefinition\n\n> **EntityPropertyWithDefinition** = \\{ `definition`: [`PropertyDefinition`](PropertyDefinition.md); `options?`: [`PropertyOption`](PropertyOption.md)[] \\| `null`; `property`: [`EntityProperty`](EntityProperty.md); `value?`: `null` \\| [`PropertyValue`](PropertyValue.md); \\}\n\nEntity property with its definition, value, and options (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-definition\"></a> `definition` | [`PropertyDefinition`](PropertyDefinition.md) |\n| <a id=\"property-options\"></a> `options?` | [`PropertyOption`](PropertyOption.md)[] \\| `null` |\n| <a id=\"property-property\"></a> `property` | [`EntityProperty`](EntityProperty.md) |\n| <a id=\"property-value\"></a> `value?` | `null` \\| [`PropertyValue`](PropertyValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityReference.md -->\n# Type Alias: EntityReference\n\n> **EntityReference** = \\{ `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `specific_message_id?`: `string` \\| `null`; \\}\n\nEntity reference for entity-type property values.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | - |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) | - |\n| <a id=\"property-specific_message_id\"></a> `specific_message_id?` | `string` \\| `null` | For CHANNEL, CHAT, THREAD entity types - optional specific message ID. This allows referencing a specific message within a thread/channel/chat. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityType.md -->\n# Type Alias: EntityType\n\n> **EntityType** = `\"CALENDAR_EVENT\"` \\| `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"CONTACT\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"TASK\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nType of entity that can be referenced by entity properties.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyDefinition.md -->\n# Type Alias: PropertyDefinition\n\n> **PropertyDefinition** = \\{ `created_at`: `string`; `data_type`: [`DataType`](DataType.md); `display_name`: `string`; `id`: `string`; `is_metadata`: `boolean`; `is_multi_select`: `boolean`; `is_system`: `boolean`; `owner`: [`PropertyOwner`](PropertyOwner.md); `specific_entity_type`: `null` \\| [`EntityType`](EntityType.md); `updated_at`: `string`; \\}\n\nProperty definition model (service representation).\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | - |\n| <a id=\"property-data_type\"></a> `data_type` | [`DataType`](DataType.md) | - |\n| <a id=\"property-display_name\"></a> `display_name` | `string` | - |\n| <a id=\"property-id\"></a> `id` | `string` | - |\n| <a id=\"property-is_metadata\"></a> `is_metadata` | `boolean` | Flag to indicate if this is a system-generated metadata property. Not stored in database - computed at service layer. |\n| <a id=\"property-is_multi_select\"></a> `is_multi_select` | `boolean` | - |\n| <a id=\"property-is_system\"></a> `is_system` | `boolean` | Flag to indicate if this is a system property (stored in DB). |\n| <a id=\"property-owner\"></a> `owner` | [`PropertyOwner`](PropertyOwner.md) | - |\n| <a id=\"property-specific_entity_type\"></a> `specific_entity_type` | `null` \\| [`EntityType`](EntityType.md) | - |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | - |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOption.md -->\n# Type Alias: PropertyOption\n\n> **PropertyOption** = \\{ `color`: `string` \\| `null`; `created_at`: `string`; `display_order`: `number`; `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; `value`: [`PropertyOptionValue`](PropertyOptionValue.md); \\}\n\nA selectable option for select-type properties (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-color\"></a> `color` | `string` \\| `null` |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-display_order\"></a> `display_order` | `number` |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n| <a id=\"property-value\"></a> `value` | [`PropertyOptionValue`](PropertyOptionValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOptionValue.md -->\n# Type Alias: PropertyOptionValue\n\n> **PropertyOptionValue** = \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\}\n\nThe value of a property option - either a string or a number.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"string\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"string\"` | - |\n| `value` | `string` | String value for SelectString properties |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"number\"` | - |\n| `value` | `number` | Number value for SelectNumber properties |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOwner.md -->\n# Type Alias: PropertyOwner\n\n> **PropertyOwner** = \\{ `scope`: `\"user\"`; `user_id`: `string`; \\} \\| \\{ `scope`: `\"team\"`; `team_id`: `string`; \\} \\| \\{ `database_id`: `string`; `scope`: `\"database\"`; \\} \\| \\{ `scope`: `\"system\"`; \\}\n\nDefines who owns a property - user-scoped, team-scoped, database-scoped, or system.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetEntityType.md -->\n# Type Alias: PropertyTargetEntityType\n\n> **PropertyTargetEntityType** = `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nCanonical type of an entity receiving properties.\n\nTasks are documents at API boundaries. `Task` intentionally does not exist\nhere; task classification is resolved by the properties domain from the\ndocument subtype.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetReference.md -->\n# Type Alias: PropertyTargetReference\n\n> **PropertyTargetReference** = \\{ `entity_id`: `string`; `entity_type`: [`PropertyTargetEntityType`](PropertyTargetEntityType.md); \\}\n\nCanonical reference to an entity receiving properties.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Entity identifier. |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`PropertyTargetEntityType`](PropertyTargetEntityType.md) | Canonical entity type. |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyValue.md -->\n# Type Alias: PropertyValue\n\n> **PropertyValue** = \\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"Number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"String\"`; `value`: `string`; \\} \\| \\{ `type`: `\"Date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\} \\| \\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\} \\| \\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\nProperty value (service representation).\n\nRepresents the actual value stored for an entity property.\nThis is serialized to/from JSONB in the database.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Boolean\"` | - |\n| `value` | `boolean` | Boolean value Serializes as: {\"type\": \"Boolean\", \"value\": true} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Number\"` | - |\n| `value` | `number` | Numeric value Serializes as: {\"type\": \"Number\", \"value\": 42.5} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"String\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"String\"` | - |\n| `value` | `string` | String value Serializes as: {\"type\": \"String\", \"value\": \"text\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Date\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Date\"` | - |\n| `value` | `string` | Date/timestamp value Serializes as: {\"type\": \"Date\", \"value\": \"2025-01-01T00:00:00Z\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"SelectOption\"` | - |\n| `value` | `string`[] | Select option(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"SelectOption\", \"value\": [\"uuid\"]} (length 0 or 1) Multi-select: {\"type\": \"SelectOption\", \"value\": [\"uuid1\", \"uuid2\", ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"EntityReference\"` | - |\n| `value` | [`EntityReference`](EntityReference.md)[] | Entity reference(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"EntityReference\", \"value\": [{...}]} (length 0 or 1) Multi-select: {\"type\": \"EntityReference\", \"value\": [{...}, {...}, ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Link\"` | - |\n| `value` | `string`[] | Link value(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"Link\", \"value\": [\"https://example.com\"]} (length 0 or 1) Multi-select: {\"type\": \"Link\", \"value\": [\"https://example.com\", \"https://other.com\"]} (length 0+) |\n\n\n<!-- generated/properties/types.gen/type-aliases/SetPropertyValue.md -->\n# Type Alias: SetPropertyValue\n\n> **SetPropertyValue** = \\{ `type`: `\"boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `option_id`: `string`; `type`: `\"select_option\"`; \\} \\| \\{ `option_ids`: `string`[]; `type`: `\"multi_select_option\"`; \\} \\| \\{ `reference`: [`EntityReference`](EntityReference.md); `type`: `\"entity_reference\"`; \\} \\| \\{ `references`: [`EntityReference`](EntityReference.md)[]; `type`: `\"multi_entity_reference\"`; \\} \\| \\{ `type`: `\"link\"`; `url`: `string`; \\} \\| \\{ `type`: `\"multi_link\"`; `urls`: `string`[]; \\}\n\nType-safe enum for setting entity property values - provides compile-time validation.\n\n\n<!-- generated/storage/types.gen/type-aliases/AccessLevel.md -->\n# Type Alias: AccessLevel\n\n> **AccessLevel** = `\"view\"` \\| `\"comment\"` \\| `\"edit\"` \\| `\"owner\"`\n\nOrdered from least to most access top -> bottom\n\n\n<!-- generated/storage/types.gen/type-aliases/Anchor.md -->\n# Type Alias: Anchor\n\n> **Anchor** = [`PdfAnchor`](PdfAnchor.md)\n\n\n<!-- generated/storage/types.gen/type-aliases/BomPart.md -->\n# Type Alias: BomPart\n\n> **BomPart** = \\{ `id`: `string`; `path`: `string`; `sha`: `string`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `string` | The uuid of the bom part |\n| <a id=\"property-path\"></a> `path` | `string` | The file path of the bom part content |\n| <a id=\"property-sha\"></a> `sha` | `string` | The sha of the bom part content There is an index on sha for more performant queries based on it. |\n\n\n<!-- generated/storage/types.gen/type-aliases/BotSenderProfile.md -->\n# Type Alias: BotSenderProfile\n\n> **BotSenderProfile** = \\{ `avatar_url?`: `string` \\| `null`; `name`: `string`; \\}\n\nPublic bot profile attached to bot-authored messages.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-avatar_url\"></a> `avatar_url?` | `string` \\| `null` | Bot avatar URL. |\n| <a id=\"property-name\"></a> `name` | `string` | Bot display name. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ChannelSharePermission.md -->\n# Type Alias: ChannelSharePermission\n\n> **ChannelSharePermission** = \\{ `access_level`: [`AccessLevel`](AccessLevel.md); `channel_id`: `string`; \\}\n\nThe channel share permission\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-access_level\"></a> `access_level` | [`AccessLevel`](AccessLevel.md) | The access level for the channel |\n| <a id=\"property-channel_id\"></a> `channel_id` | `string` | The channel id |\n\n\n<!-- generated/storage/types.gen/type-aliases/CountedReaction.md -->\n# Type Alias: CountedReaction\n\n> **CountedReaction** = \\{ `emoji`: `string`; `users`: `string`[]; \\}\n\nReaction emoji and the users who added it.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-emoji\"></a> `emoji` | `string` | Emoji being reacted with. |\n| <a id=\"property-users\"></a> `users` | `string`[] | User identifiers. |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentContent.md -->\n# Type Alias: DocumentContent\n\n> **DocumentContent** = \\{ `location?`: `null` \\| [`DocumentContentLocation`](DocumentContentLocation.md); `state`: [`DocumentContentState`](DocumentContentState.md); \\}\n\nAPI-visible content lifecycle and location metadata.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-location\"></a> `location?` | `null` \\| [`DocumentContentLocation`](DocumentContentLocation.md) | - |\n| <a id=\"property-state\"></a> `state` | [`DocumentContentState`](DocumentContentState.md) | The current lifecycle state of the content. |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentContentLocation.md -->\n# Type Alias: DocumentContentLocation\n\n> **DocumentContentLocation** = `\"object_storage\"` \\| `\"sync_service\"` \\| `\"docx_bom_parts\"` \\| `\"converted_pdf\"` \\| `\"unknown\"`\n\nWhere document content is, or is expected to be, read from.\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentContentState.md -->\n# Type Alias: DocumentContentState\n\n> **DocumentContentState** = `\"unknown\"` \\| `\"pending\"` \\| `\"ready\"`\n\nAPI-visible content lifecycle state derived from current document metadata.\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentId.md -->\n# Type Alias: DocumentId\n\n> **DocumentId** = `string`\n\nA validated document identifier. Historical document ids need not be UUIDs.\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentMetadata.md -->\n# Type Alias: DocumentMetadata\n\n> **DocumentMetadata** = \\{ `branchedFromId?`: `string` \\| `null`; `branchedFromVersionId?`: `number` \\| `null`; `createdAt?`: `string` \\| `null`; `deletedAt?`: `string` \\| `null`; `documentBom?`: [`BomPart`](BomPart.md)[] \\| `null`; `documentFamilyId?`: `number` \\| `null`; `documentId`: `string`; `documentName`: `string`; `documentVersionId`: `number`; `fileType?`: `string` \\| `null`; `modificationData?`: `unknown`; `owner`: `string`; `projectId?`: `string` \\| `null`; `projectName?`: `string` \\| `null`; `sha?`: `string` \\| `null`; `subType?`: `null` \\| [`DocumentSubType`](DocumentSubType.md); `updatedAt?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-branchedfromid\"></a> `branchedFromId?` | `string` \\| `null` | The id of the document this document branched from |\n| <a id=\"property-branchedfromversionid\"></a> `branchedFromVersionId?` | `number` \\| `null` | The id of the version this document branched from This could be either DocumentInstance or DocumentBom id depending on the file type |\n| <a id=\"property-createdat\"></a> `createdAt?` | `string` \\| `null` | The time the document was created |\n| <a id=\"property-deletedat\"></a> `deletedAt?` | `string` \\| `null` | The time the document was deleted |\n| <a id=\"property-documentbom\"></a> `documentBom?` | [`BomPart`](BomPart.md)[] \\| `null` | If the document is a DOCX document and unzipped, the document_bom will be present |\n| <a id=\"property-documentfamilyid\"></a> `documentFamilyId?` | `number` \\| `null` | The id of the document family this document belongs to |\n| <a id=\"property-documentid\"></a> `documentId` | `string` | The document id |\n| <a id=\"property-documentname\"></a> `documentName` | `string` | The name of the document |\n| <a id=\"property-documentversionid\"></a> `documentVersionId` | `number` | The version of the document This could be the document_instance_id or document_bom_id depending on the file type |\n| <a id=\"property-filetype\"></a> `fileType?` | `string` \\| `null` | The file type of the document (file extension) |\n| <a id=\"property-modificationdata\"></a> `modificationData?` | `unknown` | The modification data for the document instance. This is only used for PDF documents. |\n| <a id=\"property-owner\"></a> `owner` | `string` | The owner of the document |\n| <a id=\"property-projectid\"></a> `projectId?` | `string` \\| `null` | The id of the project that this document belongs to |\n| <a id=\"property-projectname\"></a> `projectName?` | `string` \\| `null` | The name of the project that this document belongs to |\n| <a id=\"property-sha\"></a> `sha?` | `string` \\| `null` | If the document is a PDF, this is the SHA of the pdf If the document is a DOCX, this will not be present |\n| <a id=\"property-subtype\"></a> `subType?` | `null` \\| [`DocumentSubType`](DocumentSubType.md) | - |\n| <a id=\"property-updatedat\"></a> `updatedAt?` | `string` \\| `null` | The time the document instance / document BOM was updated |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentMetadataWithContent.md -->\n# Type Alias: DocumentMetadataWithContent\n\n> **DocumentMetadataWithContent** = [`DocumentMetadata`](DocumentMetadata.md) & \\{ `content`: [`DocumentContent`](DocumentContent.md); `teamId?`: `string` \\| `null`; `teamTaskId?`: `number` \\| `null`; \\}\n\nFull document metadata plus content lifecycle metadata.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `content` | [`DocumentContent`](DocumentContent.md) | Content lifecycle and location metadata. |\n| `teamId?` | `string` \\| `null` | The team this task number is scoped to, for task documents. |\n| `teamTaskId?` | `number` \\| `null` | The task number assigned within the team, for task documents. |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentResponseMetadata.md -->\n# Type Alias: DocumentResponseMetadata\n\n> **DocumentResponseMetadata** = \\{ `branchedFromId?`: `string` \\| `null`; `branchedFromVersionId?`: `number` \\| `null`; `createdAt?`: `string` \\| `null`; `documentBom?`: [`BomPart`](BomPart.md)[] \\| `null`; `documentFamilyId?`: `number` \\| `null`; `documentId`: `string`; `documentName`: `string`; `documentVersionId`: `number`; `fileType?`: `string` \\| `null`; `modificationData?`: `unknown`; `owner`: `string`; `sha?`: `string` \\| `null`; `subType?`: `null` \\| [`DocumentSubType`](DocumentSubType.md); `updatedAt?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-branchedfromid\"></a> `branchedFromId?` | `string` \\| `null` | The id of the document this document branched from |\n| <a id=\"property-branchedfromversionid\"></a> `branchedFromVersionId?` | `number` \\| `null` | The id of the version this document branched from This could be either DocumentInstance or DocumentBom id depending on the file type |\n| <a id=\"property-createdat\"></a> `createdAt?` | `string` \\| `null` | The time the document was created |\n| <a id=\"property-documentbom\"></a> `documentBom?` | [`BomPart`](BomPart.md)[] \\| `null` | If the document is a DOCX document, the document_bom will be present |\n| <a id=\"property-documentfamilyid\"></a> `documentFamilyId?` | `number` \\| `null` | The id of the document family this document belongs to |\n| <a id=\"property-documentid\"></a> `documentId` | `string` | The document id |\n| <a id=\"property-documentname\"></a> `documentName` | `string` | The name of the document |\n| <a id=\"property-documentversionid\"></a> `documentVersionId` | `number` | The version of the document This could be the document_instance_id or document_bom_id depending on the file type |\n| <a id=\"property-filetype\"></a> `fileType?` | `string` \\| `null` | The file type of the document |\n| <a id=\"property-modificationdata\"></a> `modificationData?` | `unknown` | The modification data for the document instance. This is only used for PDF documents. |\n| <a id=\"property-owner\"></a> `owner` | `string` | The owner of the document |\n| <a id=\"property-sha\"></a> `sha?` | `string` \\| `null` | If the document is a PDF, this is the SHA of the pdf If the document is a DOCX, this will not be present |\n| <a id=\"property-subtype\"></a> `subType?` | `null` \\| [`DocumentSubType`](DocumentSubType.md) | - |\n| <a id=\"property-updatedat\"></a> `updatedAt?` | `string` \\| `null` | The time the document instance / document BOM was updated |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentSubType.md -->\n# Type Alias: DocumentSubType\n\n> **DocumentSubType** = `\"task\"` \\| `\"snippet\"` \\| `\"skill\"` \\| `\"initiative_description\"`\n\nThe document sub type enum represents all values of document sub types.\nThese values should match the `document_sub_type_value` table in macrodb.\n\nWire, database, and `Display` spellings are all `snake_case` so a\nmulti-word variant serializes identically in every system.\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentTeamShareResponse.md -->\n# Type Alias: DocumentTeamShareResponse\n\n> **DocumentTeamShareResponse** = \\{ `sharedWithTeam`: `boolean`; `teamId?`: `string` \\| `null`; \\}\n\nThe team-share state of a document. The team is resolved from the document\nowner's team membership.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-sharedwithteam\"></a> `sharedWithTeam` | `boolean` | Whether explicit team sharing is enabled; inherited team access does not count. |\n| <a id=\"property-teamid\"></a> `teamId?` | `string` \\| `null` | The owner's team the document is (or would be) shared with. `None` when the owner does not belong to a team. |\n\n\n<!-- generated/storage/types.gen/type-aliases/EditPdfPlaceableCommentAnchorRequest.md -->\n# Type Alias: EditPdfPlaceableCommentAnchorRequest\n\n> **EditPdfPlaceableCommentAnchorRequest** = \\{ `allowableEdits?`: `unknown`; `heightPct?`: `number` \\| `null`; `originalIndex?`: `number` \\| `null`; `originalPage?`: `number` \\| `null`; `page?`: `number` \\| `null`; `rotation?`: `number` \\| `null`; `shouldLockOnSave?`: `boolean` \\| `null`; `uuid`: `string`; `wasDeleted?`: `boolean` \\| `null`; `wasEdited?`: `boolean` \\| `null`; `widthPct?`: `number` \\| `null`; `xPct?`: `number` \\| `null`; `yPct?`: `number` \\| `null`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-allowableedits\"></a> `allowableEdits?` | `unknown` |\n| <a id=\"property-heightpct\"></a> `heightPct?` | `number` \\| `null` |\n| <a id=\"property-originalindex\"></a> `originalIndex?` | `number` \\| `null` |\n| <a id=\"property-originalpage\"></a> `originalPage?` | `number` \\| `null` |\n| <a id=\"property-page\"></a> `page?` | `number` \\| `null` |\n| <a id=\"property-rotation\"></a> `rotation?` | `number` \\| `null` |\n| <a id=\"property-shouldlockonsave\"></a> `shouldLockOnSave?` | `boolean` \\| `null` |\n| <a id=\"property-uuid\"></a> `uuid` | `string` |\n| <a id=\"property-wasdeleted\"></a> `wasDeleted?` | `boolean` \\| `null` |\n| <a id=\"property-wasedited\"></a> `wasEdited?` | `boolean` \\| `null` |\n| <a id=\"property-widthpct\"></a> `widthPct?` | `number` \\| `null` |\n| <a id=\"property-xpct\"></a> `xPct?` | `number` \\| `null` |\n| <a id=\"property-ypct\"></a> `yPct?` | `number` \\| `null` |\n\n\n<!-- generated/storage/types.gen/type-aliases/EntityPermission.md -->\n# Type Alias: EntityPermission\n\n> **EntityPermission** = \\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\} \\| \\{ `type`: `\"channel_view_only\"`; \\} \\| \\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\} \\| \\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\nA user's permission for an entity, discriminated by entity kind.\n\nItems (documents, chats, projects, threads) use access levels.\nChannels use view-only permission or participant roles.\n\n## Union Members\n\n### Type Literal\n\n\\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `access_level` | [`AccessLevel`](AccessLevel.md) | The access level the user has. |\n| `type` | `\"access_level\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"channel_view_only\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`ParticipantRole`](ParticipantRole.md) | The role the user has in the channel. |\n| `type` | `\"channel_role\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`TeamRole`](TeamRole.md) | The role the user has in the team. |\n| `type` | `\"team_role\"` | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/GetDocumentResponseData.md -->\n# Type Alias: GetDocumentResponseData\n\n> **GetDocumentResponseData** = \\{ `documentMetadata`: [`DocumentMetadata`](DocumentMetadata.md); `userAccessLevel`: [`AccessLevel`](AccessLevel.md); `viewLocation?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-documentmetadata\"></a> `documentMetadata` | [`DocumentMetadata`](DocumentMetadata.md) | The metadata of the document |\n| <a id=\"property-useraccesslevel\"></a> `userAccessLevel` | [`AccessLevel`](AccessLevel.md) | The users level of access to the document |\n| <a id=\"property-viewlocation\"></a> `viewLocation?` | `string` \\| `null` | The users view location if there is one |\n\n\n<!-- generated/storage/types.gen/type-aliases/GithubPullRequest.md -->\n# Type Alias: GithubPullRequest\n\n> **GithubPullRequest** = \\{ `additions?`: `number` \\| `null`; `checks?`: [`GithubPullRequestCheckRun`](GithubPullRequestCheckRun.md)[] \\| `null`; `comments?`: [`GithubPullRequestComment`](GithubPullRequestComment.md)[] \\| `null`; `deletions?`: `number` \\| `null`; `displayName`: `string`; `foreignEntityId?`: `string` \\| `null`; `githubKey`: `string`; `name?`: `string` \\| `null`; `number`: `number`; `owner`: `string`; `repo`: `string`; `status?`: `string` \\| `null`; `url`: `string`; \\}\n\nDisplay-ready data for a GitHub pull request associated with a task.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-additions\"></a> `additions?` | `number` \\| `null` | The number of added lines in the pull request, when enrichment data is available. |\n| <a id=\"property-checks\"></a> `checks?` | [`GithubPullRequestCheckRun`](GithubPullRequestCheckRun.md)[] \\| `null` | Check runs collected from the pull request head commit, when enrichment data is available. |\n| <a id=\"property-comments\"></a> `comments?` | [`GithubPullRequestComment`](GithubPullRequestComment.md)[] \\| `null` | Comments collected from the pull request, when enrichment data is available. |\n| <a id=\"property-deletions\"></a> `deletions?` | `number` \\| `null` | The number of deleted lines in the pull request, when enrichment data is available. |\n| <a id=\"property-displayname\"></a> `displayName` | `string` | A compact label suitable for display in the UI. |\n| <a id=\"property-foreignentityid\"></a> `foreignEntityId?` | `string` \\| `null` | The internal `foreign_entity.id` UUID for the GitHub pull request row. |\n| <a id=\"property-githubkey\"></a> `githubKey` | `string` | The stored GitHub association key, in `owner/repo/pull/number` format. |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | The GitHub pull request title, when enrichment data is available. |\n| <a id=\"property-number\"></a> `number` | `number` | The GitHub pull request number. |\n| <a id=\"property-owner\"></a> `owner` | `string` | The GitHub repository owner or organization. |\n| <a id=\"property-repo\"></a> `repo` | `string` | The GitHub repository name. |\n| <a id=\"property-status\"></a> `status?` | `string` \\| `null` | The GitHub pull request status, when enrichment data is available. |\n| <a id=\"property-url\"></a> `url` | `string` | The public GitHub URL for the pull request. |\n\n\n<!-- generated/storage/types.gen/type-aliases/GithubPullRequestCheckRun.md -->\n# Type Alias: GithubPullRequestCheckRun\n\n> **GithubPullRequestCheckRun** = \\{ `completedAt?`: `string` \\| `null`; `conclusion?`: `string` \\| `null`; `id`: `number`; `name`: `string`; `startedAt?`: `string` \\| `null`; `status`: `string`; `url?`: `string` \\| `null`; \\}\n\nA check run associated with a GitHub pull request.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-completedat\"></a> `completedAt?` | `string` \\| `null` | When the check run completed, when available. |\n| <a id=\"property-conclusion\"></a> `conclusion?` | `string` \\| `null` | The raw GitHub check run conclusion, when the run has completed. |\n| <a id=\"property-id\"></a> `id` | `number` | The unique GitHub identifier for the check run. |\n| <a id=\"property-name\"></a> `name` | `string` | The check run name. |\n| <a id=\"property-startedat\"></a> `startedAt?` | `string` \\| `null` | When the check run started, when available. |\n| <a id=\"property-status\"></a> `status` | `string` | The raw GitHub check run status. |\n| <a id=\"property-url\"></a> `url?` | `string` \\| `null` | The public GitHub URL for the check run, when available. |\n\n\n<!-- generated/storage/types.gen/type-aliases/GithubPullRequestComment.md -->\n# Type Alias: GithubPullRequestComment\n\n> **GithubPullRequestComment** = \\{ `authorAssociation?`: `string` \\| `null`; `authorId?`: `number` \\| `null`; `authorLogin?`: `string` \\| `null`; `body`: `string`; `createdAt?`: `string` \\| `null`; `id`: `number`; `inReplyToId?`: `number` \\| `null`; `line?`: `number` \\| `null`; `originalLine?`: `number` \\| `null`; `path?`: `string` \\| `null`; `pullRequestReviewId?`: `number` \\| `null`; `source`: `string`; `updatedAt?`: `string` \\| `null`; `url?`: `string` \\| `null`; \\}\n\nA comment associated with a GitHub pull request.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-authorassociation\"></a> `authorAssociation?` | `string` \\| `null` | GitHub's relationship label for the author, when available. |\n| <a id=\"property-authorid\"></a> `authorId?` | `number` \\| `null` | The stable numeric GitHub user id for the comment author, when available. |\n| <a id=\"property-authorlogin\"></a> `authorLogin?` | `string` \\| `null` | The GitHub login for the comment author, when available. |\n| <a id=\"property-body\"></a> `body` | `string` | The comment or review body text. |\n| <a id=\"property-createdat\"></a> `createdAt?` | `string` \\| `null` | When the comment was created or the review was submitted. |\n| <a id=\"property-id\"></a> `id` | `number` | The unique GitHub identifier for the comment or review. |\n| <a id=\"property-inreplytoid\"></a> `inReplyToId?` | `number` \\| `null` | The id of the comment this one replies to, when it is part of a review thread. Only ever present on `review_comment` sources. |\n| <a id=\"property-line\"></a> `line?` | `number` \\| `null` | The line in the current diff the comment is anchored to. Cleared by GitHub when later commits outdate the comment's diff. |\n| <a id=\"property-originalline\"></a> `originalLine?` | `number` \\| `null` | The line the comment was originally anchored to, kept even when the diff has since changed. |\n| <a id=\"property-path\"></a> `path?` | `string` \\| `null` | The repository-relative file path the review comment is anchored to. Only ever present on `review_comment` sources. |\n| <a id=\"property-pullrequestreviewid\"></a> `pullRequestReviewId?` | `number` \\| `null` | The id of the pull request review this comment was submitted with. Only ever present on `review_comment` sources. |\n| <a id=\"property-source\"></a> `source` | `string` | The GitHub source for the comment, such as `issue_comment` or `review_comment`. |\n| <a id=\"property-updatedat\"></a> `updatedAt?` | `string` \\| `null` | When the comment or review was last updated. |\n| <a id=\"property-url\"></a> `url?` | `string` \\| `null` | The public GitHub URL for the comment or review, when available. |\n\n\n<!-- generated/storage/types.gen/type-aliases/HighlightType.md -->\n# Type Alias: HighlightType\n\n> **HighlightType** = `1` \\| `2` \\| `3`\n\n\n<!-- generated/storage/types.gen/type-aliases/ImportedAuthor.md -->\n# Type Alias: ImportedAuthor\n\n> **ImportedAuthor** = \\{ `name`: `string`; \\}\n\nDisplay attribution for a comment imported from an external document.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-name\"></a> `name` | `string` | Original author text; never interpreted as an authenticated principal. |\n\n\n<!-- generated/storage/types.gen/type-aliases/LinkShare.md -->\n# Type Alias: LinkShare\n\n> **LinkShare** = `\"PUBLIC\"` \\| `\"TEAM\"`\n\nDefines who can access an item through its share link.\n\n\n<!-- generated/storage/types.gen/type-aliases/Message.md -->\n# Type Alias: Message\n\n> **Message** = \\{ `attachments`: [`MessageAttachment`](MessageAttachment.md)[]; `bot_profile?`: `null` \\| [`BotSenderProfile`](BotSenderProfile.md); `content`: `string`; `created_at`: `string`; `deleted_at?`: `string` \\| `null`; `edited_at?`: `string` \\| `null`; `guest_name?`: `string` \\| `null`; `id`: `string`; `imported_author?`: `null` \\| [`ImportedAuthor`](ImportedAuthor.md); `mentions`: [`SimpleMention`](SimpleMention.md)[]; `parent`: [`MessageParent`](MessageParent.md); `reactions`: [`CountedReaction`](CountedReaction.md)[]; `sender_id`: `string`; `thread_id?`: `string` \\| `null`; `triggered_by?`: `string` \\| `null`; `updated_at`: `string`; \\}\n\nShared message representation for channel timelines and entity discussions.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attachments\"></a> `attachments` | [`MessageAttachment`](MessageAttachment.md)[] | Attached entities. |\n| <a id=\"property-bot_profile\"></a> `bot_profile?` | `null` \\| [`BotSenderProfile`](BotSenderProfile.md) | - |\n| <a id=\"property-content\"></a> `content` | `string` | Macro Markdown body. |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Creation time. |\n| <a id=\"property-deleted_at\"></a> `deleted_at?` | `string` \\| `null` | Message tombstone, independent of thread deletion. |\n| <a id=\"property-edited_at\"></a> `edited_at?` | `string` \\| `null` | Last content edit, if any. |\n| <a id=\"property-guest_name\"></a> `guest_name?` | `string` \\| `null` | Display name of a verified call guest, retained after the call ends. |\n| <a id=\"property-id\"></a> `id` | `string` | Message UUID. |\n| <a id=\"property-imported_author\"></a> `imported_author?` | `null` \\| [`ImportedAuthor`](ImportedAuthor.md) | - |\n| <a id=\"property-mentions\"></a> `mentions` | [`SimpleMention`](SimpleMention.md)[] | Tracked mentions, retained when a caller changes attachments only. |\n| <a id=\"property-parent\"></a> `parent` | [`MessageParent`](MessageParent.md) | Entity that owns this conversation. |\n| <a id=\"property-reactions\"></a> `reactions` | [`CountedReaction`](CountedReaction.md)[] | Aggregated reactions. |\n| <a id=\"property-sender_id\"></a> `sender_id` | `string` | Authenticated actor or owner of imported content. |\n| <a id=\"property-thread_id\"></a> `thread_id?` | `string` \\| `null` | Root message UUID for replies; absent on roots. |\n| <a id=\"property-triggered_by\"></a> `triggered_by?` | `string` \\| `null` | User who triggered a bot-authored message. |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | Last persisted update. |\n\n\n<!-- generated/storage/types.gen/type-aliases/MessageAttachment.md -->\n# Type Alias: MessageAttachment\n\n> **MessageAttachment** = \\{ `created_at`: `string`; `entity_id`: `string`; `entity_type`: `string`; `height?`: `number` \\| `null`; `id`: `string`; `width?`: `number` \\| `null`; \\}\n\nAn entity attached to a message.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | When the attachment was added. |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Attached entity identifier. |\n| <a id=\"property-entity_type\"></a> `entity_type` | `string` | Attached entity type. |\n| <a id=\"property-height\"></a> `height?` | `number` \\| `null` | Optional media height. |\n| <a id=\"property-id\"></a> `id` | `string` | Attachment UUID. |\n| <a id=\"property-width\"></a> `width?` | `number` \\| `null` | Optional media width. |\n\n\n<!-- generated/storage/types.gen/type-aliases/MessageCursor.md -->\n# Type Alias: MessageCursor\n\n> **MessageCursor** = \\{ `created_at`: `string`; `id`: `string`; \\}\n\nCursor for a chronological parent timeline.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Last message creation time or activity occurrence time. |\n| <a id=\"property-id\"></a> `id` | `string` | Last entry UUID, used to break timestamp ties across both sources. |\n\n\n<!-- generated/storage/types.gen/type-aliases/MessageParent.md -->\n# Type Alias: MessageParent\n\n> **MessageParent** = \\{ `id`: `string`; `type`: `\"channel\"`; \\} \\| \\{ `id`: [`DocumentId`](DocumentId.md); `type`: `\"document\"`; \\} \\| \\{ `id`: `string`; `type`: `\"initiative\"`; \\} \\| \\{ `id`: `string`; `type`: `\"crm_company\"`; \\} \\| \\{ `id`: `string`; `type`: `\"crm_contact\"`; \\} \\| \\{ `id`: `string`; `type`: `\"call\"`; \\}\n\nThe entity whose permissions and lifecycle govern a message.\n\n## Union Members\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"channel\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A channel, including direct messages. |\n| `type` | `\"channel\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: [`DocumentId`](DocumentId.md); `type`: `\"document\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | [`DocumentId`](DocumentId.md) | A document, including tasks and PDFs. |\n| `type` | `\"document\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"initiative\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | An initiative, presented as a project in the application. |\n| `type` | `\"initiative\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"crm_company\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A CRM company. |\n| `type` | `\"crm_company\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"crm_contact\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A CRM contact. |\n| `type` | `\"crm_contact\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"call\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A video call and its persistent chat thread. |\n| `type` | `\"call\"` | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/ParticipantRole.md -->\n# Type Alias: ParticipantRole\n\n> **ParticipantRole** = `\"owner\"` \\| `\"admin\"` \\| `\"member\"`\n\nThe role a user has within a channel.\n\n\n<!-- generated/storage/types.gen/type-aliases/PdfAnchor.md -->\n# Type Alias: PdfAnchor\n\n> **PdfAnchor** = [`PdfPlaceableCommentAnchor`](PdfPlaceableCommentAnchor.md) & \\{ `anchorType`: `\"placeable\"`; \\} \\| [`PdfHighlightAnchor`](PdfHighlightAnchor.md) & \\{ `anchorType`: `\"highlight\"`; \\}\n\n\n<!-- generated/storage/types.gen/type-aliases/PdfHighlightAnchor.md -->\n# Type Alias: PdfHighlightAnchor\n\n> **PdfHighlightAnchor** = \\{ `alpha`: `number`; `blue`: `number`; `createdAt?`: `string` \\| `null`; `deletedAt?`: `string` \\| `null`; `documentId`: `string`; `green`: `number`; `highlightRects`: [`PdfHighlightRect`](PdfHighlightRect.md)[]; `highlightType`: [`HighlightType`](HighlightType.md); `owner`: `string`; `page`: `number`; `pageViewportHeight`: `number`; `pageViewportWidth`: `number`; `red`: `number`; `rootId?`: `string` \\| `null`; `text`: `string`; `updatedAt?`: `string` \\| `null`; `uuid`: `string`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-alpha\"></a> `alpha` | `number` |\n| <a id=\"property-blue\"></a> `blue` | `number` |\n| <a id=\"property-createdat\"></a> `createdAt?` | `string` \\| `null` |\n| <a id=\"property-deletedat\"></a> `deletedAt?` | `string` \\| `null` |\n| <a id=\"property-documentid\"></a> `documentId` | `string` |\n| <a id=\"property-green\"></a> `green` | `number` |\n| <a id=\"property-highlightrects\"></a> `highlightRects` | [`PdfHighlightRect`](PdfHighlightRect.md)[] |\n| <a id=\"property-highlighttype\"></a> `highlightType` | [`HighlightType`](HighlightType.md) |\n| <a id=\"property-owner\"></a> `owner` | `string` |\n| <a id=\"property-page\"></a> `page` | `number` |\n| <a id=\"property-pageviewportheight\"></a> `pageViewportHeight` | `number` |\n| <a id=\"property-pageviewportwidth\"></a> `pageViewportWidth` | `number` |\n| <a id=\"property-red\"></a> `red` | `number` |\n| <a id=\"property-rootid\"></a> `rootId?` | `string` \\| `null` |\n| <a id=\"property-text\"></a> `text` | `string` |\n| <a id=\"property-updatedat\"></a> `updatedAt?` | `string` \\| `null` |\n| <a id=\"property-uuid\"></a> `uuid` | `string` |\n\n\n<!-- generated/storage/types.gen/type-aliases/PdfHighlightAnchorRequest.md -->\n# Type Alias: PdfHighlightAnchorRequest\n\n> **PdfHighlightAnchorRequest** = \\{ `alpha`: `number`; `blue`: `number`; `green`: `number`; `highlightRects`: [`PdfHighlightRectAnchorRequest`](PdfHighlightRectAnchorRequest.md)[]; `highlightType`: [`HighlightType`](HighlightType.md); `page`: `number`; `pageViewportHeight`: `number`; `pageViewportWidth`: `number`; `red`: `number`; `text`: `string`; `uuid?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-alpha\"></a> `alpha` | `number` |\n| <a id=\"property-blue\"></a> `blue` | `number` |\n| <a id=\"property-green\"></a> `green` | `number` |\n| <a id=\"property-highlightrects\"></a> `highlightRects` | [`PdfHighlightRectAnchorRequest`](PdfHighlightRectAnchorRequest.md)[] |\n| <a id=\"property-highlighttype\"></a> `highlightType` | [`HighlightType`](HighlightType.md) |\n| <a id=\"property-page\"></a> `page` | `number` |\n| <a id=\"property-pageviewportheight\"></a> `pageViewportHeight` | `number` |\n| <a id=\"property-pageviewportwidth\"></a> `pageViewportWidth` | `number` |\n| <a id=\"property-red\"></a> `red` | `number` |\n| <a id=\"property-text\"></a> `text` | `string` |\n| <a id=\"property-uuid\"></a> `uuid?` | `string` \\| `null` |\n\n\n<!-- generated/storage/types.gen/type-aliases/PdfHighlightRect.md -->\n# Type Alias: PdfHighlightRect\n\n> **PdfHighlightRect** = \\{ `height`: `number`; `id`: `number`; `left`: `number`; `top`: `number`; `width`: `number`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-height\"></a> `height` | `number` |\n| <a id=\"property-id\"></a> `id` | `number` |\n| <a id=\"property-left\"></a> `left` | `number` |\n| <a id=\"property-top\"></a> `top` | `number` |\n| <a id=\"property-width\"></a> `width` | `number` |\n\n\n<!-- generated/storage/types.gen/type-aliases/PdfHighlightRectAnchorRequest.md -->\n# Type Alias: PdfHighlightRectAnchorRequest\n\n> **PdfHighlightRectAnchorRequest** = \\{ `height`: `number`; `left`: `number`; `top`: `number`; `width`: `number`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-height\"></a> `height` | `number` |\n| <a id=\"property-left\"></a> `left` | `number` |\n| <a id=\"property-top\"></a> `top` | `number` |\n| <a id=\"property-width\"></a> `width` | `number` |\n\n\n<!-- generated/storage/types.gen/type-aliases/PdfPlaceableCommentAnchor.md -->\n# Type Alias: PdfPlaceableCommentAnchor\n\n> **PdfPlaceableCommentAnchor** = \\{ `allowableEdits?`: `unknown`; `documentId`: `string`; `heightPct`: `number`; `originalIndex`: `number`; `originalPage`: `number`; `owner`: `string`; `page`: `number`; `rootId?`: `string` \\| `null`; `rotation`: `number`; `shouldLockOnSave`: `boolean`; `uuid`: `string`; `wasDeleted`: `boolean`; `wasEdited`: `boolean`; `widthPct`: `number`; `xPct`: `number`; `yPct`: `number`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-allowableedits\"></a> `allowableEdits?` | `unknown` |\n| <a id=\"property-documentid\"></a> `documentId` | `string` |\n| <a id=\"property-heightpct\"></a> `heightPct` | `number` |\n| <a id=\"property-originalindex\"></a> `originalIndex` | `number` |\n| <a id=\"property-originalpage\"></a> `originalPage` | `number` |\n| <a id=\"property-owner\"></a> `owner` | `string` |\n| <a id=\"property-page\"></a> `page` | `number` |\n| <a id=\"property-rootid\"></a> `rootId?` | `string` \\| `null` |\n| <a id=\"property-rotation\"></a> `rotation` | `number` |\n| <a id=\"property-shouldlockonsave\"></a> `shouldLockOnSave` | `boolean` |\n| <a id=\"property-uuid\"></a> `uuid` | `string` |\n| <a id=\"property-wasdeleted\"></a> `wasDeleted` | `boolean` |\n| <a id=\"property-wasedited\"></a> `wasEdited` | `boolean` |\n| <a id=\"property-widthpct\"></a> `widthPct` | `number` |\n| <a id=\"property-xpct\"></a> `xPct` | `number` |\n| <a id=\"property-ypct\"></a> `yPct` | `number` |\n\n\n<!-- generated/storage/types.gen/type-aliases/PreSaveDocumentResponseData.md -->\n# Type Alias: PreSaveDocumentResponseData\n\n> **PreSaveDocumentResponseData** = \\{ `presignedUrls`: [`PresignedUrl`](PresignedUrl.md)[]; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-presignedurls\"></a> `presignedUrls` | [`PresignedUrl`](PresignedUrl.md)[] | Contains any presigned urls you need to upload specific bom parts with. |\n\n\n<!-- generated/storage/types.gen/type-aliases/PresignedUrl.md -->\n# Type Alias: PresignedUrl\n\n> **PresignedUrl** = \\{ `presignedUrl`: `string`; `sha`: `string`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-presignedurl\"></a> `presignedUrl` | `string` | The presigned url used to upload the sha |\n| <a id=\"property-sha\"></a> `sha` | `string` | The sha of the item |\n\n\n<!-- generated/storage/types.gen/type-aliases/SaveBomPart.md -->\n# Type Alias: SaveBomPart\n\n> **SaveBomPart** = \\{ `path`: `string`; `sha`: `string`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-path\"></a> `path` | `string` | The file path of the bom part content |\n| <a id=\"property-sha\"></a> `sha` | `string` | The sha of the bom part content There is an index on sha for more performant queries based on it. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SaveDocumentRequest.md -->\n# Type Alias: SaveDocumentRequest\n\n> **SaveDocumentRequest** = \\{ `modificationData?`: `unknown`; `newBom?`: [`SaveBomPart`](SaveBomPart.md)[] \\| `null`; `sha?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-modificationdata\"></a> `modificationData?` | `unknown` | The modification data for the document instance. Used to store highlights and other overlays onto a static file |\n| <a id=\"property-newbom\"></a> `newBom?` | [`SaveBomPart`](SaveBomPart.md)[] \\| `null` | **DOCX ONLY** The updated BOM for the document. Containing the file path and the sha. |\n| <a id=\"property-sha\"></a> `sha?` | `string` \\| `null` | The sha of the new document. This is used to generate a presigned url to upload the new document content to s3. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md -->\n# Type Alias: SaveDocumentResponseData\n\n> **SaveDocumentResponseData** = \\{ `documentMetadata`: [`DocumentResponseMetadata`](DocumentResponseMetadata.md); `presignedUrl?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-documentmetadata\"></a> `documentMetadata` | [`DocumentResponseMetadata`](DocumentResponseMetadata.md) | The updated document metadata |\n| <a id=\"property-presignedurl\"></a> `presignedUrl?` | `string` \\| `null` | If the document is an editable file, we provide a presigned url to save the updated file to. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SharePermissionV2.md -->\n# Type Alias: SharePermissionV2\n\n> **SharePermissionV2** = \\{ `channelSharePermissions?`: [`ChannelSharePermission`](ChannelSharePermission.md)[] \\| `null`; `id`: `string`; `linkShare?`: `null` \\| [`LinkShare`](LinkShare.md); `linkShareAccessLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); `owner`: `string`; `teamShareAccessLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channelsharepermissions\"></a> `channelSharePermissions?` | [`ChannelSharePermission`](ChannelSharePermission.md)[] \\| `null` | The channel share permissions for the item |\n| <a id=\"property-id\"></a> `id` | `string` | The share permission id |\n| <a id=\"property-linkshare\"></a> `linkShare?` | `null` \\| [`LinkShare`](LinkShare.md) | - |\n| <a id=\"property-linkshareaccesslevel\"></a> `linkShareAccessLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n| <a id=\"property-owner\"></a> `owner` | `string` | The owner of the item |\n| <a id=\"property-teamshareaccesslevel\"></a> `teamShareAccessLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/SimpleMention.md -->\n# Type Alias: SimpleMention\n\n> **SimpleMention** = \\{ `entity_id`: `string`; `entity_type`: `string`; \\}\n\nA mention tracked in a message body.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Mentioned entity identifier. |\n| <a id=\"property-entity_type\"></a> `entity_type` | `string` | Mentioned entity type. |\n\n\n<!-- generated/storage/types.gen/type-aliases/TeamRole.md -->\n# Type Alias: TeamRole\n\n> **TeamRole** = `\"member\"` \\| `\"admin\"` \\| `\"owner\"`\n\nThe role a user has within a team.\n\nOrdered least to most privileged so comparisons reflect access strength.\n\n\n<!-- generated/storage/types.gen/type-aliases/ThreadAnchor.md -->\n# Type Alias: ThreadAnchor\n\n> **ThreadAnchor** = \\{ `mark_id`: `string`; `marked_text?`: `string` \\| `null`; `type`: `\"markdown\"`; \\} \\| \\{ `anchor_id`: `string`; `marked_text?`: `string` \\| `null`; `type`: `\"pdf_highlight\"`; \\} \\| \\{ `anchor_id`: `string`; `type`: `\"pdf_placeable\"`; \\} \\| \\{ `range`: `string`; `sheetId`: `string`; `sheetName`: `string`; `type`: `\"spreadsheet\"`; \\} \\| \\{ `nodeId?`: `string` \\| `null`; `pageId`: `string`; `type`: `\"fig\"`; `x`: `number`; `y`: `number`; \\}\n\nA thread's location within its document. PDF geometry remains annotation-owned.\n\n## Union Members\n\n### Type Literal\n\n\\{ `mark_id`: `string`; `marked_text?`: `string` \\| `null`; `type`: `\"markdown\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `mark_id` | `string` | Mark UUID serialized in the document. |\n| `marked_text?` | `string` \\| `null` | The marked text as it read when the discussion was created, already trimmed and bounded. Absent on threads created or imported before snapshots were captured: the text a mark covers cannot be recovered from the mark id alone. |\n| `type` | `\"markdown\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `anchor_id`: `string`; `marked_text?`: `string` \\| `null`; `type`: `\"pdf_highlight\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `anchor_id` | `string` | Highlight annotation UUID. |\n| `marked_text?` | `string` \\| `null` | The text the highlight covers, trimmed and bounded like a markdown snapshot. The highlight owns it and it can be edited there, so it is read from the highlight whenever the thread is, never stored on the thread. Absent when the highlight carries no text. |\n| `type` | `\"pdf_highlight\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `anchor_id`: `string`; `type`: `\"pdf_placeable\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `anchor_id` | `string` | Placeable annotation UUID. |\n| `type` | `\"pdf_placeable\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `range`: `string`; `sheetId`: `string`; `sheetName`: `string`; `type`: `\"spreadsheet\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `range` | `string` | A1 cell or range, such as B4 or B4:C9. |\n| `sheetId` | `string` | Stable sheet identity within the workbook. |\n| `sheetName` | `string` | Sheet name when the discussion was created. |\n| `type` | `\"spreadsheet\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `nodeId?`: `string` \\| `null`; `pageId`: `string`; `type`: `\"fig\"`; `x`: `number`; `y`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `nodeId?` | `string` \\| `null` | Layer the pin follows; absent for a pin on the bare canvas. |\n| `pageId` | `string` | Page (canvas) the pin is on. |\n| `type` | `\"fig\"` | - |\n| `x` | `number` | Horizontal offset from the layer's origin, or the page's when the pin is on no layer, in design units. |\n| `y` | `number` | Vertical offset, measured like `x`. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ThreadState.md -->\n# Type Alias: ThreadState\n\n> **ThreadState** = \\{ `anchor?`: `null` \\| [`ThreadAnchor`](ThreadAnchor.md); `created_at`: `string`; `deleted_at?`: `string` \\| `null`; `resolved`: `boolean`; `root_id`: `string`; `updated_at`: `string`; `user_id`: `string`; \\}\n\nState belonging to a whole thread, keyed by its root message.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-anchor\"></a> `anchor?` | `null` \\| [`ThreadAnchor`](ThreadAnchor.md) | - |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Creation time of the discussion. |\n| <a id=\"property-deleted_at\"></a> `deleted_at?` | `string` \\| `null` | Explicit deletion of the entire thread, distinct from root deletion. |\n| <a id=\"property-resolved\"></a> `resolved` | `boolean` | Whether this discussion has been resolved. |\n| <a id=\"property-root_id\"></a> `root_id` | `string` | Root message UUID; there is no separate thread identity. |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | Last state change. |\n| <a id=\"property-user_id\"></a> `user_id` | `string` | User who owns this discussion, including imported discussions. |\n\n\n<!-- src/entities/documents/anchor/classes/DocumentAnchor.md -->\n# Class: DocumentAnchor\n\nA PDF annotation scoped to its document.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`Anchor`](../../../../../generated/storage/types.gen/type-aliases/Anchor.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-document\"></a> `document` | `readonly` | [`Document`](../../document/classes/Document.md) | Owning document. | - |\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-kind\"></a> `kind` | `readonly` | () => `Promise`\\<`\"highlight\"` \\| `\"placeable\"`\\> | Annotation kind. | - |\n| <a id=\"property-page\"></a> `page` | `readonly` | () => `Promise`\\<`number`\\> | Page containing the annotation. | - |\n\n## Methods\n\n### delete()\n\n> **delete**(): `Promise`\\<`void`\\>\n\nDelete a standalone highlight annotation.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### edit()\n\n> **edit**(`options`): `Promise`\\<`void`\\>\n\nEdit a placeable comment's position and display settings.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | `Omit`\\<[`EditPdfPlaceableCommentAnchorRequest`](../../../../../generated/storage/types.gen/type-aliases/EditPdfPlaceableCommentAnchorRequest.md), `\"uuid\"`\\> |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`PdfAnchor`](../../../../../generated/storage/types.gen/type-aliases/PdfAnchor.md); `documentId`: `string`; `id`: `string`; \\}\n\nSerialize identity with its owning resource.\n\n#### Returns\n\n\\{ `detail?`: [`PdfAnchor`](../../../../../generated/storage/types.gen/type-aliases/PdfAnchor.md); `documentId`: `string`; `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`PdfAnchor`](../../../../../generated/storage/types.gen/type-aliases/PdfAnchor.md) |\n| `documentId` | `string` |\n| `id` | `string` |\n\n#### Overrides\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `document`, `id`): `DocumentAnchor`\n\nConstruct a document scoped annotation handle.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `document` | [`Document`](../../document/classes/Document.md) |\n| `id` | `string` |\n\n#### Returns\n\n`DocumentAnchor`\n\n***\n\n### from()\n\n> `static` **from**(`client`, `document`, `record`): `DocumentAnchor`\n\nSeed an annotation from a document annotation listing.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `document` | [`Document`](../../document/classes/Document.md) |\n| `record` | [`PdfAnchor`](../../../../../generated/storage/types.gen/type-aliases/PdfAnchor.md) |\n\n#### Returns\n\n`DocumentAnchor`\n\n\n<!-- src/entities/documents/comment/classes/Comment.md -->\n# Class: Comment\n\nA comment on a document: a document-parent message, addressed by its\ndocument and message UUID. Its record and mutations are the ones channel\nmessages use.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`Message`](../../../../../generated/storage/types.gen/type-aliases/Message.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-createdat\"></a> `createdAt` | `readonly` | () => `Promise`\\<`string`\\> | When the comment was created. | - |\n| <a id=\"property-documentid\"></a> `documentId` | `readonly` | `string` | The document this comment belongs to. | - |\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-text\"></a> `text` | `readonly` | () => `Promise`\\<`string`\\> | The comment's text. | - |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `readonly` | () => `Promise`\\<`string`\\> | When the comment was last updated. | - |\n\n## Methods\n\n### author()\n\n> **author**(): `Promise`\\<[`User`](../../../users/user/classes/User.md)\\>\n\nThe user who wrote this comment.\n\n#### Returns\n\n`Promise`\\<[`User`](../../../users/user/classes/User.md)\\>\n\n***\n\n### delete()\n\n> **delete**(): `Promise`\\<`void`\\>\n\nDelete this comment.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### document()\n\n> **document**(): [`Document`](../../document/classes/Document.md)\n\nThe document this comment is on.\n\n#### Returns\n\n[`Document`](../../document/classes/Document.md)\n\n***\n\n### edit()\n\n> **edit**(`body`): `Promise`\\<`Comment`\\>\n\nReplace the comment's text.\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `body` | `string` \\| [`RichMessage`](../../../../mentions/interfaces/RichMessage.md) | Plain text, or a rich body composed with msg. |\n\n#### Returns\n\n`Promise`\\<`Comment`\\>\n\n***\n\n### reply()\n\n> **reply**(`body`): `Promise`\\<`Comment`\\>\n\nReply in this comment's thread.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `body` | `string` \\| [`RichMessage`](../../../../mentions/interfaces/RichMessage.md) |\n\n#### Returns\n\n`Promise`\\<`Comment`\\>\n\n***\n\n### threadId()\n\n> **threadId**(): `Promise`\\<`string`\\>\n\nThe id of the thread this comment belongs to: its root, or itself for a root.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`Message`](../../../../../generated/storage/types.gen/type-aliases/Message.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`Message`](../../../../../generated/storage/types.gen/type-aliases/Message.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`Message`](../../../../../generated/storage/types.gen/type-aliases/Message.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`, `documentId`, `id`): `Comment`\n\nA handle to a comment by id. Fields load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `documentId` | `string` |\n| `id` | `string` |\n\n#### Returns\n\n`Comment`\n\n***\n\n### from()\n\n> `static` **from**(`client`, `documentId`, `record`): `Comment`\n\nBuild a comment from a message record (pre-seeded, no fetch).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `documentId` | `string` |\n| `record` | [`Message`](../../../../../generated/storage/types.gen/type-aliases/Message.md) |\n\n#### Returns\n\n`Comment`\n\n\n<!-- src/entities/documents/document/classes/Document.md -->\n# Class: Document\n\nA Macro document. Can be dropped into a msg template to render an\ninline link to the document.\n\n## Extends\n\n- [`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md)\\<`DocumentDetail`\\>\n\n## Extended by\n\n- [`Task`](../../../tasks/task/classes/Task.md)\n\n## Implements\n\n- [`Mentionable`](../../../../mentions/interfaces/Mentionable.md)\n\n## Properties\n\n| Property | Modifier | Type | Default value | Description | Overrides | Inherited from |\n| ------ | ------ | ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-access\"></a> `access` | `readonly` | [`EntityAccess`](../../../sharing/access/classes/EntityAccess.md) | `...` | Access requests and direct user grants. | - | - |\n| <a id=\"property-branchedfrom\"></a> `branchedFrom` | `readonly` | () => `Promise`\\<`Document` \\| `undefined`\\> | `...` | The document this one was branched from, if any. | - | - |\n| <a id=\"property-createdat\"></a> `createdAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | When the document was created. | - | - |\n| <a id=\"property-deletedat\"></a> `deletedAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | When the document was deleted, if it has been. | - | - |\n| <a id=\"property-entitytype\"></a> `entityType` | `readonly` | `\"document\"` | `'document'` | Favorites identify documents as `document`. | [`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`entityType`](../../../entity/classes/PropertiedEntity.md#property-entitytype) | - |\n| <a id=\"property-filetype\"></a> `fileType` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | The document's file type (e.g. `md`, `pdf`, `docx`). | - | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | `undefined` | - | - | [`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`id`](../../../entity/classes/PropertiedEntity.md#property-id) |\n| <a id=\"property-name\"></a> `name` | `readonly` | () => `Promise`\\<`string`\\> | `...` | The document's display name. | - | - |\n| <a id=\"property-owner\"></a> `owner` | `readonly` | () => `Promise`\\<[`User`](../../../users/user/classes/User.md)\\> | `...` | The user who owns the document. | - | - |\n| <a id=\"property-project\"></a> `project` | `readonly` | () => `Promise`\\<[`Project`](../../../projects/project/classes/Project.md) \\| `undefined`\\> | `...` | The project this document belongs to, if any. | - | - |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | When the document was last updated. | - | - |\n| <a id=\"property-search\"></a> `search` | `static` | (`client`, `query`, `searchOpts?`) => `AsyncGenerator`\\<`Document`\\> | `...` | Search documents by name and content, most relevant first, auto-paginated. | - | - |\n\n## Methods\n\n### anchors()\n\n> **anchors**(): `Promise`\\<[`DocumentAnchor`](../../anchor/classes/DocumentAnchor.md)[]\\>\n\nPDF annotations in this document.\n\n#### Returns\n\n`Promise`\\<[`DocumentAnchor`](../../anchor/classes/DocumentAnchor.md)[]\\>\n\n***\n\n### branchName()\n\n> **branchName**(): `Promise`\\<`string`\\>\n\nThe git branch name derived for the document (task documents).\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### comment()\n\n> **comment**(`body`, `opts?`): `Promise`\\<[`Comment`](../../comment/classes/Comment.md)\\>\n\nAdd a comment. Starts a new unanchored thread, or replies to an existing\none when `threadId` (the thread's root comment id) is given.\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `body` | `string` \\| [`RichMessage`](../../../../mentions/interfaces/RichMessage.md) | Plain text, or a rich body composed with msg. |\n| `opts?` | \\{ `threadId?`: `string`; \\} | - |\n| `opts.threadId?` | `string` | - |\n\n#### Returns\n\n`Promise`\\<[`Comment`](../../comment/classes/Comment.md)\\>\n\nThe created comment.\n\n***\n\n### comments()\n\n> **comments**(): `Promise`\\<[`CommentThread`](../interfaces/CommentThread.md)[]\\>\n\nThe document's live comment threads, each with its comments, newest thread first.\n\n#### Returns\n\n`Promise`\\<[`CommentThread`](../interfaces/CommentThread.md)[]\\>\n\n***\n\n### content()\n\n> **content**(): `Promise`\\<`string`\\>\n\nCurrent Markdown for native documents, extracted text for PDF/Word,\nor raw file content for other formats. Native reads include live edits.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### copy()\n\n> **copy**(`opts`): `Promise`\\<`Document`\\>\n\nCopy the document under a new name, optionally from a specific version.\nReturns a handle to the new document.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `name`: `string`; `versionId?`: `number`; \\} |\n| `opts.name` | `string` |\n| `opts.versionId?` | `number` |\n\n#### Returns\n\n`Promise`\\<`Document`\\>\n\n***\n\n### createHighlight()\n\n> **createHighlight**(`options`): `Promise`\\<[`DocumentAnchor`](../../anchor/classes/DocumentAnchor.md)\\>\n\nCreate a standalone PDF highlight.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | `Omit`\\<[`PdfHighlightAnchorRequest`](../../../../../generated/storage/types.gen/type-aliases/PdfHighlightAnchorRequest.md), `\"uuid\"`\\> |\n\n#### Returns\n\n`Promise`\\<[`DocumentAnchor`](../../anchor/classes/DocumentAnchor.md)\\>\n\n***\n\n### delete()\n\n> **delete**(`opts?`): `Promise`\\<`void`\\>\n\nDelete the document. Soft by default (reversible with [restore](#restore));\npass `permanent: true` to delete irreversibly.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `permanent?`: `boolean`; \\} |\n| `opts.permanent?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### deleteProperty()\n\n> **deleteProperty**(`assignment`): `Promise`\\<`void`\\>\n\nRemove a property from this entity, given its [properties](#properties) entry.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `assignment` | [`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`deleteProperty`](../../../entity/classes/PropertiedEntity.md#deleteproperty)\n\n***\n\n### favorite()\n\n> **favorite**(): `Promise`\\<`Document`\\>\n\nAdd this entity to the user's favorites. Returns this handle for chaining.\nPlain unwrap: favoriting alters the user's favorites collection, not this\nentity's own detail, so there's nothing cached to invalidate.\n\n#### Returns\n\n`Promise`\\<`Document`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`favorite`](../../../entity/classes/PropertiedEntity.md#favorite)\n\n***\n\n### githubPullRequests()\n\n> **githubPullRequests**(): `Promise`\\<[`GithubPullRequest`](../../../../../generated/storage/types.gen/type-aliases/GithubPullRequest.md)[]\\>\n\nGitHub pull requests associated with the document.\n\n#### Returns\n\n`Promise`\\<[`GithubPullRequest`](../../../../../generated/storage/types.gen/type-aliases/GithubPullRequest.md)[]\\>\n\n***\n\n### meetingNotes()\n\n> **meetingNotes**(): `Promise`\\<\\{ `eventTitle`: `string`; `note`: [`CalendarNote`](../../../calendar/note/classes/CalendarNote.md); \\}[]\\>\n\nOwner-only meeting grants, including unavailable meetings. Unlink a returned note to revoke its meeting/team access.\n\n#### Returns\n\n`Promise`\\<\\{ `eventTitle`: `string`; `note`: [`CalendarNote`](../../../calendar/note/classes/CalendarNote.md); \\}[]\\>\n\n***\n\n### messageThreadById()\n\n> **messageThreadById**(`id`): [`MessageThread`](../../../messages/thread/classes/MessageThread.md)\n\nA shared message thread scoped to this resource.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`MessageThread`](../../../messages/thread/classes/MessageThread.md)\n\n***\n\n### move()\n\n> **move**(`project`): `Promise`\\<`void`\\>\n\nMove the document into a project (or out of one, with `null`).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `project` | [`Project`](../../../projects/project/classes/Project.md) \\| `null` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### permission()\n\n> **permission**(): `Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\nRead the caller's effective permission on this entity.\n\n#### Returns\n\n`Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`permission`](../../../entity/classes/PropertiedEntity.md#permission)\n\n***\n\n### permissionsToken()\n\n> **permissionsToken**(): `Promise`\\<`string`\\>\n\nMint a scoped permissions token.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### prepareSave()\n\n> **prepareSave**(`parts`): `Promise`\\<[`PreSaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/PreSaveDocumentResponseData.md)\\>\n\nPrepare multipart content saving and return the service's upload instructions.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `parts` | [`SaveBomPart`](../../../../../generated/storage/types.gen/type-aliases/SaveBomPart.md)[] |\n\n#### Returns\n\n`Promise`\\<[`PreSaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/PreSaveDocumentResponseData.md)\\>\n\n***\n\n### properties()\n\n> **properties**(`opts?`): `Promise`\\<[`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\nThe properties set on this entity, each with its definition, value, and options.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `includeMetadata?`: `boolean`; \\} |\n| `opts.includeMetadata?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<[`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`properties`](../../../entity/classes/PropertiedEntity.md#properties)\n\n***\n\n### propertyReference()\n\n> **propertyReference**(): [`PropertyTargetReference`](../../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\nThis entity's reference for bulk property operations.\n\n#### Returns\n\n[`PropertyTargetReference`](../../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`propertyReference`](../../../entity/classes/PropertiedEntity.md#propertyreference)\n\n***\n\n### rename()\n\n> **rename**(`name`): `Promise`\\<`void`\\>\n\nRename the document.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `name` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### restore()\n\n> **restore**(): `Promise`\\<`void`\\>\n\nRestore a soft-deleted document.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### save()\n\n> **save**(`options`): `Promise`\\<[`SaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md)\\>\n\nCommit uploaded content. Does not retry uncertain writes.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`SaveDocumentRequest`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentRequest.md) |\n\n#### Returns\n\n`Promise`\\<[`SaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md)\\>\n\n***\n\n### setProperty()\n\n> **setProperty**(`property`, `value?`): `Promise`\\<`void`\\>\n\nSet a property value on this entity, or attach the property without a\nvalue when `value` is omitted.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `property` | [`PropertyDefinition`](../../../properties/property-definition/classes/PropertyDefinition.md) |\n| `value?` | [`SetPropertyValue`](../../../../../generated/properties/types.gen/type-aliases/SetPropertyValue.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`setProperty`](../../../entity/classes/PropertiedEntity.md#setproperty)\n\n***\n\n### setTeamShare()\n\n> **setTeamShare**(`shared`): `Promise`\\<`void`\\>\n\nShare the document with the owner's team, or unshare it.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `shared` | `boolean` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### sharePermissions()\n\n> **sharePermissions**(): `Promise`\\<[`SharePermissionV2`](../../../../../generated/storage/types.gen/type-aliases/SharePermissionV2.md)\\>\n\nSharing configuration.\n\n#### Returns\n\n`Promise`\\<[`SharePermissionV2`](../../../../../generated/storage/types.gen/type-aliases/SharePermissionV2.md)\\>\n\n***\n\n### shortId()\n\n> **shortId**(): `Promise`\\<`string`\\>\n\nThe document's short id (used in compact links and branch names).\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### simpleSave()\n\n> **simpleSave**(): `Promise`\\<[`SaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md)\\>\n\nCommit a simple document save.\n\n#### Returns\n\n`Promise`\\<[`SaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md)\\>\n\n***\n\n### teamShare()\n\n> **teamShare**(): `Promise`\\<[`DocumentTeamShareResponse`](../../../../../generated/storage/types.gen/type-aliases/DocumentTeamShareResponse.md)\\>\n\nWhether the document is shared with the owner's team, and which team.\n\n#### Returns\n\n`Promise`\\<[`DocumentTeamShareResponse`](../../../../../generated/storage/types.gen/type-aliases/DocumentTeamShareResponse.md)\\>\n\n***\n\n### timelinePage()\n\n> **timelinePage**(`selection?`): `Promise`\\<\\{ `entries`: (\\{ `activity`: \\{ `action`: `string`; `actor`: [`User`](../../../users/user/classes/User.md); `actor_id`: `string`; `id`: `string`; `occurred_at`: `string`; `payload?`: `unknown`; \\}; `message?`: `undefined`; `type`: `\"activity\"`; \\} \\| \\{ `activity?`: `undefined`; `message`: [`Comment`](../../comment/classes/Comment.md); `type`: `\"message\"`; \\})[]; `nextCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; `previousCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; \\}\\>\n\nA mixed message and activity timeline page.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `selection?` | [`TimelineOptions`](../../../messages/thread/interfaces/TimelineOptions.md)\\<[`Comment`](../../comment/classes/Comment.md)\\> |\n\n#### Returns\n\n`Promise`\\<\\{ `entries`: (\\{ `activity`: \\{ `action`: `string`; `actor`: [`User`](../../../users/user/classes/User.md); `actor_id`: `string`; `id`: `string`; `occurred_at`: `string`; `payload?`: `unknown`; \\}; `message?`: `undefined`; `type`: `\"activity\"`; \\} \\| \\{ `activity?`: `undefined`; `message`: [`Comment`](../../comment/classes/Comment.md); `type`: `\"message\"`; \\})[]; `nextCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; `previousCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; \\}\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`DocumentMetadataWithContent`](../../../../../generated/storage/types.gen/type-aliases/DocumentMetadataWithContent.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`DocumentMetadataWithContent`](../../../../../generated/storage/types.gen/type-aliases/DocumentMetadataWithContent.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`DocumentMetadataWithContent`](../../../../../generated/storage/types.gen/type-aliases/DocumentMetadataWithContent.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`toJSON`](../../../entity/classes/PropertiedEntity.md#tojson)\n\n***\n\n### toMention()\n\n> **toMention**(): [`MentionPart`](../../../../mentions/interfaces/MentionPart.md)\n\n#### Returns\n\n[`MentionPart`](../../../../mentions/interfaces/MentionPart.md)\n\n#### Implementation of\n\n[`Mentionable`](../../../../mentions/interfaces/Mentionable.md).[`toMention`](../../../../mentions/interfaces/Mentionable.md#tomention)\n\n***\n\n### unfavorite()\n\n> **unfavorite**(): `Promise`\\<`Document`\\>\n\nRemove this entity from the user's favorites. Returns this handle for chaining.\n\n#### Returns\n\n`Promise`\\<`Document`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`unfavorite`](../../../entity/classes/PropertiedEntity.md#unfavorite)\n\n***\n\n### updatePropertyOptions()\n\n> **updatePropertyOptions**(`changes`): `Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\nApply multi-select option deltas atomically across this entity's properties.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `changes` | [`PropertyOptionDelta`](../../../entity/interfaces/PropertyOptionDelta.md)[] |\n\n#### Returns\n\n`Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`updatePropertyOptions`](../../../entity/classes/PropertiedEntity.md#updatepropertyoptions)\n\n***\n\n### version()\n\n> **version**(`version`): [`DocumentVersion`](../../version/classes/DocumentVersion.md)\n\nA handle to an immutable version.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `version` | `number` |\n\n#### Returns\n\n[`DocumentVersion`](../../version/classes/DocumentVersion.md)\n\n***\n\n### webUrl()\n\n> **webUrl**(): `string`\n\nThe document's URL in the Macro web app.\n\n#### Returns\n\n`string`\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `Document`\n\nA handle to a document by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`Document`\n\n***\n\n### create()\n\n> `static` **create**(`client`, `opts`): `Promise`\\<`Document`\\>\n\nCreate a markdown document.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<`Document`\\>\n\n***\n\n### createSkill()\n\n> `static` **createSkill**(`client`, `opts`): `Promise`\\<`Document`\\>\n\nCreate a skill: a markdown document containing instructions that AI reads\nand follows when the skill is referenced in an AI input.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<`Document`\\>\n\n***\n\n### createSnippet()\n\n> `static` **createSnippet**(`client`, `opts`): `Promise`\\<`Document`\\>\n\nCreate a snippet: a reusable markdown document that can be inserted into\nany markdown area.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<`Document`\\>\n\n***\n\n### recent()\n\n> `static` **recent**(`client`, `opts?`): `AsyncGenerator`\\<`Document`\\>\n\nThe user's recent documents, most recent first, auto-paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts?` | \\{ `fileType?`: `string`; `pageSize?`: `number`; \\} |\n| `opts.fileType?` | `string` |\n| `opts.pageSize?` | `number` |\n\n#### Returns\n\n`AsyncGenerator`\\<`Document`\\>\n\n***\n\n### recentlyDeleted()\n\n> `static` **recentlyDeleted**(`client`): `Promise`\\<`Document`[]\\>\n\nThe user's recently soft-deleted documents. The underlying endpoint also\nreturns deleted chats and projects; those are filtered out here.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`Promise`\\<`Document`[]\\>\n\n\n<!-- src/entities/documents/document/interfaces/CommentThread.md -->\n# Interface: CommentThread\n\nOne of a document's comment threads: its state and its comments.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-comments\"></a> `comments` | [`Comment`](../../comment/classes/Comment.md)[] | The root comment followed by its replies, in order. |\n| <a id=\"property-thread\"></a> `thread` | [`ThreadState`](../../../../../generated/storage/types.gen/type-aliases/ThreadState.md) | The thread state: root id, resolved flag, owner, anchor, timestamps. |\n\n\n<!-- src/entities/documents/namespace/classes/DocumentNamespace.md -->\n# Class: DocumentNamespace\n\n## Constructors\n\n### Constructor\n\n> **new DocumentNamespace**(`client`): `DocumentNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`DocumentNamespace`\n\n## Methods\n\n### byId()\n\n> **byId**(`id`): [`Document`](../../document/classes/Document.md)\n\nA handle to a document by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Document`](../../document/classes/Document.md)\n\n***\n\n### byTeamSlug()\n\n> **byTeamSlug**(`slug`): `Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\nResolve a team task reference such as ENG-42.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `slug` | `string` |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### create()\n\n> **create**(`opts`): `Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\nCreate a markdown document.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### createCanvas()\n\n> **createCanvas**(`opts`): `Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\nCreate a native Canvas with shared content ready for reading and editing.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### createSkill()\n\n> **createSkill**(`opts`): `Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\nCreate a skill: markdown instructions that AI reads and follows.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### createSnippet()\n\n> **createSnippet**(`opts`): `Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\nCreate a snippet: a reusable markdown document.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### createUpload()\n\n> **createUpload**(`options`): `Promise`\\<\\{ `content`: [`DocumentContent`](../../../../../generated/storage/types.gen/type-aliases/DocumentContent.md); `contentType`: `string`; `document`: [`Document`](../../document/classes/Document.md); `uploadUrl`: `string` \\| `undefined`; \\}\\>\n\nReserve a binary document and return upload instructions. Upload content before saving.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | \\{ `attachment?`: [`EmailAttachment`](../../../email/attachment/classes/EmailAttachment.md); `branchedFrom?`: [`Document`](../../document/classes/Document.md); `fileType?`: `string`; `isTask?`: `boolean`; `mimeType?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); `sha`: `string`; `team?`: [`Team`](../../../teams/team/classes/Team.md); \\} |\n| `options.attachment?` | [`EmailAttachment`](../../../email/attachment/classes/EmailAttachment.md) |\n| `options.branchedFrom?` | [`Document`](../../document/classes/Document.md) |\n| `options.fileType?` | `string` |\n| `options.isTask?` | `boolean` |\n| `options.mimeType?` | `string` |\n| `options.name` | `string` |\n| `options.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n| `options.sha` | `string` |\n| `options.team?` | [`Team`](../../../teams/team/classes/Team.md) |\n\n#### Returns\n\n`Promise`\\<\\{ `content`: [`DocumentContent`](../../../../../generated/storage/types.gen/type-aliases/DocumentContent.md); `contentType`: `string`; `document`: [`Document`](../../document/classes/Document.md); `uploadUrl`: `string` \\| `undefined`; \\}\\>\n\n***\n\n### recent()\n\n> **recent**(`opts?`): `AsyncGenerator`\\<[`Document`](../../document/classes/Document.md)\\>\n\nThe user's recent documents, most recent first, auto-paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `fileType?`: `string`; `pageSize?`: `number`; \\} |\n| `opts.fileType?` | `string` |\n| `opts.pageSize?` | `number` |\n\n#### Returns\n\n`AsyncGenerator`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### recentlyDeleted()\n\n> **recentlyDeleted**(): `Promise`\\<[`Document`](../../document/classes/Document.md)[]\\>\n\nThe user's recently soft-deleted documents.\n\n#### Returns\n\n`Promise`\\<[`Document`](../../document/classes/Document.md)[]\\>\n\n***\n\n### search()\n\n> **search**(`query`, `opts?`): `AsyncGenerator`\\<[`Document`](../../document/classes/Document.md)\\>\n\nSearch documents by name and content, most relevant first, auto-paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `query` | `string` |\n| `opts?` | [`SearchOpts`](../../../search/interfaces/SearchOpts.md) |\n\n#### Returns\n\n`AsyncGenerator`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### systemSkills()\n\n> **systemSkills**(): `Promise`\\<[`SystemSkill`](../../system-skill/classes/SystemSkill.md)[]\\>\n\nThe built-in system skills: static AI instructions with no document\nbehind them. Unlike user skills they cannot be opened or edited.\n\n#### Returns\n\n`Promise`\\<[`SystemSkill`](../../system-skill/classes/SystemSkill.md)[]\\>\n\n***\n\n### validatePermissionsToken()\n\n> **validatePermissionsToken**(`token`): `Promise`\\<\\{ `accessLevel`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md); `document`: [`Document`](../../document/classes/Document.md); `expiresAt`: `number`; `issuer`: `string`; `user`: [`User`](../../../users/user/classes/User.md) \\| `undefined`; \\}\\>\n\nValidate a permissions token, returning its document and optional user handles.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `token` | `string` |\n\n#### Returns\n\n`Promise`\\<\\{ `accessLevel`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md); `document`: [`Document`](../../document/classes/Document.md); `expiresAt`: `number`; `issuer`: `string`; `user`: [`User`](../../../users/user/classes/User.md) \\| `undefined`; \\}\\>\n\n\n<!-- src/entities/documents/system-skill/classes/SystemSkill.md -->\n# Class: SystemSkill\n\nA built-in system skill: static, code-defined AI instructions that surface\nto AI like skill documents but have no document behind them. System skills\ncannot be opened, edited, or deleted; reference them in AI inputs by id the\nsame way as skill documents.\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `readonly` | `string` | The well-known id the skill is referenced by in mentions and AI tools. |\n| <a id=\"property-name\"></a> `name` | `readonly` | `string` | The skill's display name. |\n\n## Methods\n\n### list()\n\n> `static` **list**(`client`): `Promise`\\<`SystemSkill`[]\\>\n\nThe built-in system skills, in display order.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`Promise`\\<`SystemSkill`[]\\>\n\n\n<!-- src/entities/documents/version/classes/DocumentVersion.md -->\n# Class: DocumentVersion\n\nAn immutable document version, scoped to its document.\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-document\"></a> `document` | `readonly` | [`Document`](../../document/classes/Document.md) | Parent document. |\n| <a id=\"property-id\"></a> `id` | `readonly` | `number` | Version number. |\n\n## Methods\n\n### read()\n\n> **read**(): `Promise`\\<[`GetDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/GetDocumentResponseData.md)\\>\n\nVersion metadata and the caller's access.\n\n#### Returns\n\n`Promise`\\<[`GetDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/GetDocumentResponseData.md)\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `documentId`: `string`; `id`: `number`; \\}\n\nSerialize only scoped identity.\n\n#### Returns\n\n\\{ `documentId`: `string`; `id`: `number`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `documentId` | `string` |\n| `id` | `number` |\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `document`, `id`): `DocumentVersion`\n\nConstruct a version handle.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `document` | [`Document`](../../document/classes/Document.md) |\n| `id` | `number` |\n\n#### Returns\n\n`DocumentVersion`\n"
+ "documentation": "# Macro SDK: documents\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/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md -->\n# Type Alias: BulkUpdateEntityPropertyOptionsResponse\n\n> **BulkUpdateEntityPropertyOptionsResponse** = \\{ `properties`: [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[]; \\}\n\nResponse for a bulk option update: each property's reconciled final ids.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-properties\"></a> `properties` | [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[] | The final option ids per updated property. |\n\n\n<!-- generated/properties/types.gen/type-aliases/DataType.md -->\n# Type Alias: DataType\n\n> **DataType** = `\"BOOLEAN\"` \\| `\"DATE\"` \\| `\"NUMBER\"` \\| `\"STRING\"` \\| `\"SELECT_NUMBER\"` \\| `\"SELECT_STRING\"` \\| `\"TAG\"` \\| `\"ENTITY\"` \\| `\"LINK\"`\n\nData type for property values, determining storage and validation.\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityProperty.md -->\n# Type Alias: EntityProperty\n\n> **EntityProperty** = \\{ `created_at`: `string`; `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; \\}\n\nAssignment of a property definition to a specific entity (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyOptionSelectionResponse.md -->\n# Type Alias: EntityPropertyOptionSelectionResponse\n\n> **EntityPropertyOptionSelectionResponse** = \\{ `option_ids`: `string`[]; `property_id`: `string`; \\}\n\nThe reconciled final option ids stored for one property after a bulk update.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-option_ids\"></a> `option_ids` | `string`[] | The final option ids the server persisted, in stored order. |\n| <a id=\"property-property_id\"></a> `property_id` | `string` | The property definition the options belong to. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md -->\n# Type Alias: EntityPropertyWithDefinition\n\n> **EntityPropertyWithDefinition** = \\{ `definition`: [`PropertyDefinition`](PropertyDefinition.md); `options?`: [`PropertyOption`](PropertyOption.md)[] \\| `null`; `property`: [`EntityProperty`](EntityProperty.md); `value?`: `null` \\| [`PropertyValue`](PropertyValue.md); \\}\n\nEntity property with its definition, value, and options (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-definition\"></a> `definition` | [`PropertyDefinition`](PropertyDefinition.md) |\n| <a id=\"property-options\"></a> `options?` | [`PropertyOption`](PropertyOption.md)[] \\| `null` |\n| <a id=\"property-property\"></a> `property` | [`EntityProperty`](EntityProperty.md) |\n| <a id=\"property-value\"></a> `value?` | `null` \\| [`PropertyValue`](PropertyValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityReference.md -->\n# Type Alias: EntityReference\n\n> **EntityReference** = \\{ `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `specific_message_id?`: `string` \\| `null`; \\}\n\nEntity reference for entity-type property values.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | - |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) | - |\n| <a id=\"property-specific_message_id\"></a> `specific_message_id?` | `string` \\| `null` | For CHANNEL, CHAT, THREAD entity types - optional specific message ID. This allows referencing a specific message within a thread/channel/chat. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityType.md -->\n# Type Alias: EntityType\n\n> **EntityType** = `\"CALENDAR_EVENT\"` \\| `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"CONTACT\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"TASK\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nType of entity that can be referenced by entity properties.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyDefinition.md -->\n# Type Alias: PropertyDefinition\n\n> **PropertyDefinition** = \\{ `created_at`: `string`; `data_type`: [`DataType`](DataType.md); `display_name`: `string`; `id`: `string`; `is_metadata`: `boolean`; `is_multi_select`: `boolean`; `is_system`: `boolean`; `owner`: [`PropertyOwner`](PropertyOwner.md); `specific_entity_type`: `null` \\| [`EntityType`](EntityType.md); `updated_at`: `string`; \\}\n\nProperty definition model (service representation).\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | - |\n| <a id=\"property-data_type\"></a> `data_type` | [`DataType`](DataType.md) | - |\n| <a id=\"property-display_name\"></a> `display_name` | `string` | - |\n| <a id=\"property-id\"></a> `id` | `string` | - |\n| <a id=\"property-is_metadata\"></a> `is_metadata` | `boolean` | Flag to indicate if this is a system-generated metadata property. Not stored in database - computed at service layer. |\n| <a id=\"property-is_multi_select\"></a> `is_multi_select` | `boolean` | - |\n| <a id=\"property-is_system\"></a> `is_system` | `boolean` | Flag to indicate if this is a system property (stored in DB). |\n| <a id=\"property-owner\"></a> `owner` | [`PropertyOwner`](PropertyOwner.md) | - |\n| <a id=\"property-specific_entity_type\"></a> `specific_entity_type` | `null` \\| [`EntityType`](EntityType.md) | - |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | - |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOption.md -->\n# Type Alias: PropertyOption\n\n> **PropertyOption** = \\{ `color`: `string` \\| `null`; `created_at`: `string`; `display_order`: `number`; `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; `value`: [`PropertyOptionValue`](PropertyOptionValue.md); \\}\n\nA selectable option for select-type properties (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-color\"></a> `color` | `string` \\| `null` |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-display_order\"></a> `display_order` | `number` |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n| <a id=\"property-value\"></a> `value` | [`PropertyOptionValue`](PropertyOptionValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOptionValue.md -->\n# Type Alias: PropertyOptionValue\n\n> **PropertyOptionValue** = \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\}\n\nThe value of a property option - either a string or a number.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"string\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"string\"` | - |\n| `value` | `string` | String value for SelectString properties |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"number\"` | - |\n| `value` | `number` | Number value for SelectNumber properties |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOwner.md -->\n# Type Alias: PropertyOwner\n\n> **PropertyOwner** = \\{ `scope`: `\"user\"`; `user_id`: `string`; \\} \\| \\{ `scope`: `\"team\"`; `team_id`: `string`; \\} \\| \\{ `database_id`: `string`; `scope`: `\"database\"`; \\} \\| \\{ `scope`: `\"system\"`; \\}\n\nDefines who owns a property - user-scoped, team-scoped, database-scoped, or system.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetEntityType.md -->\n# Type Alias: PropertyTargetEntityType\n\n> **PropertyTargetEntityType** = `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nCanonical type of an entity receiving properties.\n\nTasks are documents at API boundaries. `Task` intentionally does not exist\nhere; task classification is resolved by the properties domain from the\ndocument subtype.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetReference.md -->\n# Type Alias: PropertyTargetReference\n\n> **PropertyTargetReference** = \\{ `entity_id`: `string`; `entity_type`: [`PropertyTargetEntityType`](PropertyTargetEntityType.md); \\}\n\nCanonical reference to an entity receiving properties.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Entity identifier. |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`PropertyTargetEntityType`](PropertyTargetEntityType.md) | Canonical entity type. |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyValue.md -->\n# Type Alias: PropertyValue\n\n> **PropertyValue** = \\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"Number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"String\"`; `value`: `string`; \\} \\| \\{ `type`: `\"Date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\} \\| \\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\} \\| \\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\nProperty value (service representation).\n\nRepresents the actual value stored for an entity property.\nThis is serialized to/from JSONB in the database.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Boolean\"` | - |\n| `value` | `boolean` | Boolean value Serializes as: {\"type\": \"Boolean\", \"value\": true} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Number\"` | - |\n| `value` | `number` | Numeric value Serializes as: {\"type\": \"Number\", \"value\": 42.5} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"String\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"String\"` | - |\n| `value` | `string` | String value Serializes as: {\"type\": \"String\", \"value\": \"text\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Date\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Date\"` | - |\n| `value` | `string` | Date/timestamp value Serializes as: {\"type\": \"Date\", \"value\": \"2025-01-01T00:00:00Z\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"SelectOption\"` | - |\n| `value` | `string`[] | Select option(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"SelectOption\", \"value\": [\"uuid\"]} (length 0 or 1) Multi-select: {\"type\": \"SelectOption\", \"value\": [\"uuid1\", \"uuid2\", ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"EntityReference\"` | - |\n| `value` | [`EntityReference`](EntityReference.md)[] | Entity reference(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"EntityReference\", \"value\": [{...}]} (length 0 or 1) Multi-select: {\"type\": \"EntityReference\", \"value\": [{...}, {...}, ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Link\"` | - |\n| `value` | `string`[] | Link value(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"Link\", \"value\": [\"https://example.com\"]} (length 0 or 1) Multi-select: {\"type\": \"Link\", \"value\": [\"https://example.com\", \"https://other.com\"]} (length 0+) |\n\n\n<!-- generated/properties/types.gen/type-aliases/SetPropertyValue.md -->\n# Type Alias: SetPropertyValue\n\n> **SetPropertyValue** = \\{ `type`: `\"boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `option_id`: `string`; `type`: `\"select_option\"`; \\} \\| \\{ `option_ids`: `string`[]; `type`: `\"multi_select_option\"`; \\} \\| \\{ `reference`: [`EntityReference`](EntityReference.md); `type`: `\"entity_reference\"`; \\} \\| \\{ `references`: [`EntityReference`](EntityReference.md)[]; `type`: `\"multi_entity_reference\"`; \\} \\| \\{ `type`: `\"link\"`; `url`: `string`; \\} \\| \\{ `type`: `\"multi_link\"`; `urls`: `string`[]; \\}\n\nType-safe enum for setting entity property values - provides compile-time validation.\n\n\n<!-- generated/storage/types.gen/type-aliases/AccessLevel.md -->\n# Type Alias: AccessLevel\n\n> **AccessLevel** = `\"view\"` \\| `\"comment\"` \\| `\"edit\"` \\| `\"owner\"`\n\nOrdered from least to most access top -> bottom\n\n\n<!-- generated/storage/types.gen/type-aliases/Anchor.md -->\n# Type Alias: Anchor\n\n> **Anchor** = [`PdfAnchor`](PdfAnchor.md)\n\n\n<!-- generated/storage/types.gen/type-aliases/BomPart.md -->\n# Type Alias: BomPart\n\n> **BomPart** = \\{ `id`: `string`; `path`: `string`; `sha`: `string`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `string` | The uuid of the bom part |\n| <a id=\"property-path\"></a> `path` | `string` | The file path of the bom part content |\n| <a id=\"property-sha\"></a> `sha` | `string` | The sha of the bom part content There is an index on sha for more performant queries based on it. |\n\n\n<!-- generated/storage/types.gen/type-aliases/BotSenderProfile.md -->\n# Type Alias: BotSenderProfile\n\n> **BotSenderProfile** = \\{ `avatar_url?`: `string` \\| `null`; `name`: `string`; \\}\n\nPublic bot profile attached to bot-authored messages.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-avatar_url\"></a> `avatar_url?` | `string` \\| `null` | Bot avatar URL. |\n| <a id=\"property-name\"></a> `name` | `string` | Bot display name. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ChannelSharePermission.md -->\n# Type Alias: ChannelSharePermission\n\n> **ChannelSharePermission** = \\{ `access_level`: [`AccessLevel`](AccessLevel.md); `channel_id`: `string`; \\}\n\nThe channel share permission\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-access_level\"></a> `access_level` | [`AccessLevel`](AccessLevel.md) | The access level for the channel |\n| <a id=\"property-channel_id\"></a> `channel_id` | `string` | The channel id |\n\n\n<!-- generated/storage/types.gen/type-aliases/CountedReaction.md -->\n# Type Alias: CountedReaction\n\n> **CountedReaction** = \\{ `emoji`: `string`; `users`: `string`[]; \\}\n\nReaction emoji and the users who added it.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-emoji\"></a> `emoji` | `string` | Emoji being reacted with. |\n| <a id=\"property-users\"></a> `users` | `string`[] | User identifiers. |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentContent.md -->\n# Type Alias: DocumentContent\n\n> **DocumentContent** = \\{ `location?`: `null` \\| [`DocumentContentLocation`](DocumentContentLocation.md); `state`: [`DocumentContentState`](DocumentContentState.md); \\}\n\nAPI-visible content lifecycle and location metadata.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-location\"></a> `location?` | `null` \\| [`DocumentContentLocation`](DocumentContentLocation.md) | - |\n| <a id=\"property-state\"></a> `state` | [`DocumentContentState`](DocumentContentState.md) | The current lifecycle state of the content. |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentContentLocation.md -->\n# Type Alias: DocumentContentLocation\n\n> **DocumentContentLocation** = `\"object_storage\"` \\| `\"sync_service\"` \\| `\"docx_bom_parts\"` \\| `\"converted_pdf\"` \\| `\"unknown\"`\n\nWhere document content is, or is expected to be, read from.\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentContentState.md -->\n# Type Alias: DocumentContentState\n\n> **DocumentContentState** = `\"unknown\"` \\| `\"pending\"` \\| `\"ready\"`\n\nAPI-visible content lifecycle state derived from current document metadata.\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentId.md -->\n# Type Alias: DocumentId\n\n> **DocumentId** = `string`\n\nA validated document identifier. Historical document ids need not be UUIDs.\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentMetadata.md -->\n# Type Alias: DocumentMetadata\n\n> **DocumentMetadata** = \\{ `branchedFromId?`: `string` \\| `null`; `branchedFromVersionId?`: `number` \\| `null`; `createdAt?`: `string` \\| `null`; `deletedAt?`: `string` \\| `null`; `documentBom?`: [`BomPart`](BomPart.md)[] \\| `null`; `documentFamilyId?`: `number` \\| `null`; `documentId`: `string`; `documentName`: `string`; `documentVersionId`: `number`; `fileType?`: `string` \\| `null`; `modificationData?`: `unknown`; `owner`: `string`; `projectId?`: `string` \\| `null`; `projectName?`: `string` \\| `null`; `sha?`: `string` \\| `null`; `subType?`: `null` \\| [`DocumentSubType`](DocumentSubType.md); `updatedAt?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-branchedfromid\"></a> `branchedFromId?` | `string` \\| `null` | The id of the document this document branched from |\n| <a id=\"property-branchedfromversionid\"></a> `branchedFromVersionId?` | `number` \\| `null` | The id of the version this document branched from This could be either DocumentInstance or DocumentBom id depending on the file type |\n| <a id=\"property-createdat\"></a> `createdAt?` | `string` \\| `null` | The time the document was created |\n| <a id=\"property-deletedat\"></a> `deletedAt?` | `string` \\| `null` | The time the document was deleted |\n| <a id=\"property-documentbom\"></a> `documentBom?` | [`BomPart`](BomPart.md)[] \\| `null` | If the document is a DOCX document and unzipped, the document_bom will be present |\n| <a id=\"property-documentfamilyid\"></a> `documentFamilyId?` | `number` \\| `null` | The id of the document family this document belongs to |\n| <a id=\"property-documentid\"></a> `documentId` | `string` | The document id |\n| <a id=\"property-documentname\"></a> `documentName` | `string` | The name of the document |\n| <a id=\"property-documentversionid\"></a> `documentVersionId` | `number` | The version of the document This could be the document_instance_id or document_bom_id depending on the file type |\n| <a id=\"property-filetype\"></a> `fileType?` | `string` \\| `null` | The file type of the document (file extension) |\n| <a id=\"property-modificationdata\"></a> `modificationData?` | `unknown` | The modification data for the document instance. This is only used for PDF documents. |\n| <a id=\"property-owner\"></a> `owner` | `string` | The owner of the document |\n| <a id=\"property-projectid\"></a> `projectId?` | `string` \\| `null` | The id of the project that this document belongs to |\n| <a id=\"property-projectname\"></a> `projectName?` | `string` \\| `null` | The name of the project that this document belongs to |\n| <a id=\"property-sha\"></a> `sha?` | `string` \\| `null` | If the document is a PDF, this is the SHA of the pdf If the document is a DOCX, this will not be present |\n| <a id=\"property-subtype\"></a> `subType?` | `null` \\| [`DocumentSubType`](DocumentSubType.md) | - |\n| <a id=\"property-updatedat\"></a> `updatedAt?` | `string` \\| `null` | The time the document instance / document BOM was updated |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentMetadataWithContent.md -->\n# Type Alias: DocumentMetadataWithContent\n\n> **DocumentMetadataWithContent** = [`DocumentMetadata`](DocumentMetadata.md) & \\{ `content`: [`DocumentContent`](DocumentContent.md); `teamId?`: `string` \\| `null`; `teamTaskId?`: `number` \\| `null`; \\}\n\nFull document metadata plus content lifecycle metadata.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `content` | [`DocumentContent`](DocumentContent.md) | Content lifecycle and location metadata. |\n| `teamId?` | `string` \\| `null` | The team this task number is scoped to, for task documents. |\n| `teamTaskId?` | `number` \\| `null` | The task number assigned within the team, for task documents. |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentResponseMetadata.md -->\n# Type Alias: DocumentResponseMetadata\n\n> **DocumentResponseMetadata** = \\{ `branchedFromId?`: `string` \\| `null`; `branchedFromVersionId?`: `number` \\| `null`; `createdAt?`: `string` \\| `null`; `documentBom?`: [`BomPart`](BomPart.md)[] \\| `null`; `documentFamilyId?`: `number` \\| `null`; `documentId`: `string`; `documentName`: `string`; `documentVersionId`: `number`; `fileType?`: `string` \\| `null`; `modificationData?`: `unknown`; `owner`: `string`; `sha?`: `string` \\| `null`; `subType?`: `null` \\| [`DocumentSubType`](DocumentSubType.md); `updatedAt?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-branchedfromid\"></a> `branchedFromId?` | `string` \\| `null` | The id of the document this document branched from |\n| <a id=\"property-branchedfromversionid\"></a> `branchedFromVersionId?` | `number` \\| `null` | The id of the version this document branched from This could be either DocumentInstance or DocumentBom id depending on the file type |\n| <a id=\"property-createdat\"></a> `createdAt?` | `string` \\| `null` | The time the document was created |\n| <a id=\"property-documentbom\"></a> `documentBom?` | [`BomPart`](BomPart.md)[] \\| `null` | If the document is a DOCX document, the document_bom will be present |\n| <a id=\"property-documentfamilyid\"></a> `documentFamilyId?` | `number` \\| `null` | The id of the document family this document belongs to |\n| <a id=\"property-documentid\"></a> `documentId` | `string` | The document id |\n| <a id=\"property-documentname\"></a> `documentName` | `string` | The name of the document |\n| <a id=\"property-documentversionid\"></a> `documentVersionId` | `number` | The version of the document This could be the document_instance_id or document_bom_id depending on the file type |\n| <a id=\"property-filetype\"></a> `fileType?` | `string` \\| `null` | The file type of the document |\n| <a id=\"property-modificationdata\"></a> `modificationData?` | `unknown` | The modification data for the document instance. This is only used for PDF documents. |\n| <a id=\"property-owner\"></a> `owner` | `string` | The owner of the document |\n| <a id=\"property-sha\"></a> `sha?` | `string` \\| `null` | If the document is a PDF, this is the SHA of the pdf If the document is a DOCX, this will not be present |\n| <a id=\"property-subtype\"></a> `subType?` | `null` \\| [`DocumentSubType`](DocumentSubType.md) | - |\n| <a id=\"property-updatedat\"></a> `updatedAt?` | `string` \\| `null` | The time the document instance / document BOM was updated |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentSubType.md -->\n# Type Alias: DocumentSubType\n\n> **DocumentSubType** = `\"task\"` \\| `\"snippet\"` \\| `\"skill\"` \\| `\"initiative_description\"`\n\nThe document sub type enum represents all values of document sub types.\nThese values should match the `document_sub_type_value` table in macrodb.\n\nWire, database, and `Display` spellings are all `snake_case` so a\nmulti-word variant serializes identically in every system.\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentTeamShareResponse.md -->\n# Type Alias: DocumentTeamShareResponse\n\n> **DocumentTeamShareResponse** = \\{ `sharedWithTeam`: `boolean`; `teamId?`: `string` \\| `null`; \\}\n\nThe team-share state of a document. The team is resolved from the document\nowner's team membership.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-sharedwithteam\"></a> `sharedWithTeam` | `boolean` | Whether explicit team sharing is enabled; inherited team access does not count. |\n| <a id=\"property-teamid\"></a> `teamId?` | `string` \\| `null` | The owner's team the document is (or would be) shared with. `None` when the owner does not belong to a team. |\n\n\n<!-- generated/storage/types.gen/type-aliases/EditPdfPlaceableCommentAnchorRequest.md -->\n# Type Alias: EditPdfPlaceableCommentAnchorRequest\n\n> **EditPdfPlaceableCommentAnchorRequest** = \\{ `allowableEdits?`: `unknown`; `heightPct?`: `number` \\| `null`; `originalIndex?`: `number` \\| `null`; `originalPage?`: `number` \\| `null`; `page?`: `number` \\| `null`; `rotation?`: `number` \\| `null`; `shouldLockOnSave?`: `boolean` \\| `null`; `uuid`: `string`; `wasDeleted?`: `boolean` \\| `null`; `wasEdited?`: `boolean` \\| `null`; `widthPct?`: `number` \\| `null`; `xPct?`: `number` \\| `null`; `yPct?`: `number` \\| `null`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-allowableedits\"></a> `allowableEdits?` | `unknown` |\n| <a id=\"property-heightpct\"></a> `heightPct?` | `number` \\| `null` |\n| <a id=\"property-originalindex\"></a> `originalIndex?` | `number` \\| `null` |\n| <a id=\"property-originalpage\"></a> `originalPage?` | `number` \\| `null` |\n| <a id=\"property-page\"></a> `page?` | `number` \\| `null` |\n| <a id=\"property-rotation\"></a> `rotation?` | `number` \\| `null` |\n| <a id=\"property-shouldlockonsave\"></a> `shouldLockOnSave?` | `boolean` \\| `null` |\n| <a id=\"property-uuid\"></a> `uuid` | `string` |\n| <a id=\"property-wasdeleted\"></a> `wasDeleted?` | `boolean` \\| `null` |\n| <a id=\"property-wasedited\"></a> `wasEdited?` | `boolean` \\| `null` |\n| <a id=\"property-widthpct\"></a> `widthPct?` | `number` \\| `null` |\n| <a id=\"property-xpct\"></a> `xPct?` | `number` \\| `null` |\n| <a id=\"property-ypct\"></a> `yPct?` | `number` \\| `null` |\n\n\n<!-- generated/storage/types.gen/type-aliases/EntityPermission.md -->\n# Type Alias: EntityPermission\n\n> **EntityPermission** = \\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\} \\| \\{ `type`: `\"channel_view_only\"`; \\} \\| \\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\} \\| \\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\nA user's permission for an entity, discriminated by entity kind.\n\nItems (documents, chats, projects, threads) use access levels.\nChannels use view-only permission or participant roles.\n\n## Union Members\n\n### Type Literal\n\n\\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `access_level` | [`AccessLevel`](AccessLevel.md) | The access level the user has. |\n| `type` | `\"access_level\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"channel_view_only\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`ParticipantRole`](ParticipantRole.md) | The role the user has in the channel. |\n| `type` | `\"channel_role\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`TeamRole`](TeamRole.md) | The role the user has in the team. |\n| `type` | `\"team_role\"` | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/GetDocumentResponseData.md -->\n# Type Alias: GetDocumentResponseData\n\n> **GetDocumentResponseData** = \\{ `documentMetadata`: [`DocumentMetadata`](DocumentMetadata.md); `userAccessLevel`: [`AccessLevel`](AccessLevel.md); `viewLocation?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-documentmetadata\"></a> `documentMetadata` | [`DocumentMetadata`](DocumentMetadata.md) | The metadata of the document |\n| <a id=\"property-useraccesslevel\"></a> `userAccessLevel` | [`AccessLevel`](AccessLevel.md) | The users level of access to the document |\n| <a id=\"property-viewlocation\"></a> `viewLocation?` | `string` \\| `null` | The users view location if there is one |\n\n\n<!-- generated/storage/types.gen/type-aliases/GithubPullRequest.md -->\n# Type Alias: GithubPullRequest\n\n> **GithubPullRequest** = \\{ `additions?`: `number` \\| `null`; `checks?`: [`GithubPullRequestCheckRun`](GithubPullRequestCheckRun.md)[] \\| `null`; `comments?`: [`GithubPullRequestComment`](GithubPullRequestComment.md)[] \\| `null`; `deletions?`: `number` \\| `null`; `displayName`: `string`; `foreignEntityId?`: `string` \\| `null`; `githubKey`: `string`; `name?`: `string` \\| `null`; `number`: `number`; `owner`: `string`; `repo`: `string`; `status?`: `string` \\| `null`; `url`: `string`; \\}\n\nDisplay-ready data for a GitHub pull request associated with a task.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-additions\"></a> `additions?` | `number` \\| `null` | The number of added lines in the pull request, when enrichment data is available. |\n| <a id=\"property-checks\"></a> `checks?` | [`GithubPullRequestCheckRun`](GithubPullRequestCheckRun.md)[] \\| `null` | Check runs collected from the pull request head commit, when enrichment data is available. |\n| <a id=\"property-comments\"></a> `comments?` | [`GithubPullRequestComment`](GithubPullRequestComment.md)[] \\| `null` | Comments collected from the pull request, when enrichment data is available. |\n| <a id=\"property-deletions\"></a> `deletions?` | `number` \\| `null` | The number of deleted lines in the pull request, when enrichment data is available. |\n| <a id=\"property-displayname\"></a> `displayName` | `string` | A compact label suitable for display in the UI. |\n| <a id=\"property-foreignentityid\"></a> `foreignEntityId?` | `string` \\| `null` | The internal `foreign_entity.id` UUID for the GitHub pull request row. |\n| <a id=\"property-githubkey\"></a> `githubKey` | `string` | The stored GitHub association key, in `owner/repo/pull/number` format. |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | The GitHub pull request title, when enrichment data is available. |\n| <a id=\"property-number\"></a> `number` | `number` | The GitHub pull request number. |\n| <a id=\"property-owner\"></a> `owner` | `string` | The GitHub repository owner or organization. |\n| <a id=\"property-repo\"></a> `repo` | `string` | The GitHub repository name. |\n| <a id=\"property-status\"></a> `status?` | `string` \\| `null` | The GitHub pull request status, when enrichment data is available. |\n| <a id=\"property-url\"></a> `url` | `string` | The public GitHub URL for the pull request. |\n\n\n<!-- generated/storage/types.gen/type-aliases/GithubPullRequestCheckRun.md -->\n# Type Alias: GithubPullRequestCheckRun\n\n> **GithubPullRequestCheckRun** = \\{ `completedAt?`: `string` \\| `null`; `conclusion?`: `string` \\| `null`; `id`: `number`; `name`: `string`; `startedAt?`: `string` \\| `null`; `status`: `string`; `url?`: `string` \\| `null`; \\}\n\nA check run associated with a GitHub pull request.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-completedat\"></a> `completedAt?` | `string` \\| `null` | When the check run completed, when available. |\n| <a id=\"property-conclusion\"></a> `conclusion?` | `string` \\| `null` | The raw GitHub check run conclusion, when the run has completed. |\n| <a id=\"property-id\"></a> `id` | `number` | The unique GitHub identifier for the check run. |\n| <a id=\"property-name\"></a> `name` | `string` | The check run name. |\n| <a id=\"property-startedat\"></a> `startedAt?` | `string` \\| `null` | When the check run started, when available. |\n| <a id=\"property-status\"></a> `status` | `string` | The raw GitHub check run status. |\n| <a id=\"property-url\"></a> `url?` | `string` \\| `null` | The public GitHub URL for the check run, when available. |\n\n\n<!-- generated/storage/types.gen/type-aliases/GithubPullRequestComment.md -->\n# Type Alias: GithubPullRequestComment\n\n> **GithubPullRequestComment** = \\{ `authorAssociation?`: `string` \\| `null`; `authorId?`: `number` \\| `null`; `authorLogin?`: `string` \\| `null`; `body`: `string`; `createdAt?`: `string` \\| `null`; `id`: `number`; `inReplyToId?`: `number` \\| `null`; `line?`: `number` \\| `null`; `originalLine?`: `number` \\| `null`; `path?`: `string` \\| `null`; `pullRequestReviewId?`: `number` \\| `null`; `source`: `string`; `updatedAt?`: `string` \\| `null`; `url?`: `string` \\| `null`; \\}\n\nA comment associated with a GitHub pull request.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-authorassociation\"></a> `authorAssociation?` | `string` \\| `null` | GitHub's relationship label for the author, when available. |\n| <a id=\"property-authorid\"></a> `authorId?` | `number` \\| `null` | The stable numeric GitHub user id for the comment author, when available. |\n| <a id=\"property-authorlogin\"></a> `authorLogin?` | `string` \\| `null` | The GitHub login for the comment author, when available. |\n| <a id=\"property-body\"></a> `body` | `string` | The comment or review body text. |\n| <a id=\"property-createdat\"></a> `createdAt?` | `string` \\| `null` | When the comment was created or the review was submitted. |\n| <a id=\"property-id\"></a> `id` | `number` | The unique GitHub identifier for the comment or review. |\n| <a id=\"property-inreplytoid\"></a> `inReplyToId?` | `number` \\| `null` | The id of the comment this one replies to, when it is part of a review thread. Only ever present on `review_comment` sources. |\n| <a id=\"property-line\"></a> `line?` | `number` \\| `null` | The line in the current diff the comment is anchored to. Cleared by GitHub when later commits outdate the comment's diff. |\n| <a id=\"property-originalline\"></a> `originalLine?` | `number` \\| `null` | The line the comment was originally anchored to, kept even when the diff has since changed. |\n| <a id=\"property-path\"></a> `path?` | `string` \\| `null` | The repository-relative file path the review comment is anchored to. Only ever present on `review_comment` sources. |\n| <a id=\"property-pullrequestreviewid\"></a> `pullRequestReviewId?` | `number` \\| `null` | The id of the pull request review this comment was submitted with. Only ever present on `review_comment` sources. |\n| <a id=\"property-source\"></a> `source` | `string` | The GitHub source for the comment, such as `issue_comment` or `review_comment`. |\n| <a id=\"property-updatedat\"></a> `updatedAt?` | `string` \\| `null` | When the comment or review was last updated. |\n| <a id=\"property-url\"></a> `url?` | `string` \\| `null` | The public GitHub URL for the comment or review, when available. |\n\n\n<!-- generated/storage/types.gen/type-aliases/HighlightType.md -->\n# Type Alias: HighlightType\n\n> **HighlightType** = `1` \\| `2` \\| `3`\n\n\n<!-- generated/storage/types.gen/type-aliases/ImportedAuthor.md -->\n# Type Alias: ImportedAuthor\n\n> **ImportedAuthor** = \\{ `name`: `string`; \\}\n\nDisplay attribution for a comment imported from an external document.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-name\"></a> `name` | `string` | Original author text; never interpreted as an authenticated principal. |\n\n\n<!-- generated/storage/types.gen/type-aliases/LinkShare.md -->\n# Type Alias: LinkShare\n\n> **LinkShare** = `\"PUBLIC\"` \\| `\"TEAM\"`\n\nDefines who can access an item through its share link.\n\n\n<!-- generated/storage/types.gen/type-aliases/Message.md -->\n# Type Alias: Message\n\n> **Message** = \\{ `attachments`: [`MessageAttachment`](MessageAttachment.md)[]; `bot_profile?`: `null` \\| [`BotSenderProfile`](BotSenderProfile.md); `content`: `string`; `created_at`: `string`; `deleted_at?`: `string` \\| `null`; `edited_at?`: `string` \\| `null`; `guest_name?`: `string` \\| `null`; `id`: `string`; `imported_author?`: `null` \\| [`ImportedAuthor`](ImportedAuthor.md); `mentions`: [`SimpleMention`](SimpleMention.md)[]; `parent`: [`MessageParent`](MessageParent.md); `reactions`: [`CountedReaction`](CountedReaction.md)[]; `sender_id`: `string`; `thread_id?`: `string` \\| `null`; `triggered_by?`: `string` \\| `null`; `updated_at`: `string`; \\}\n\nShared message representation for channel timelines and entity discussions.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-attachments\"></a> `attachments` | [`MessageAttachment`](MessageAttachment.md)[] | Attached entities. |\n| <a id=\"property-bot_profile\"></a> `bot_profile?` | `null` \\| [`BotSenderProfile`](BotSenderProfile.md) | - |\n| <a id=\"property-content\"></a> `content` | `string` | Macro Markdown body. |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Creation time. |\n| <a id=\"property-deleted_at\"></a> `deleted_at?` | `string` \\| `null` | Message tombstone, independent of thread deletion. |\n| <a id=\"property-edited_at\"></a> `edited_at?` | `string` \\| `null` | Last content edit, if any. |\n| <a id=\"property-guest_name\"></a> `guest_name?` | `string` \\| `null` | Display name of a verified call guest, retained after the call ends. |\n| <a id=\"property-id\"></a> `id` | `string` | Message UUID. |\n| <a id=\"property-imported_author\"></a> `imported_author?` | `null` \\| [`ImportedAuthor`](ImportedAuthor.md) | - |\n| <a id=\"property-mentions\"></a> `mentions` | [`SimpleMention`](SimpleMention.md)[] | Tracked mentions, retained when a caller changes attachments only. |\n| <a id=\"property-parent\"></a> `parent` | [`MessageParent`](MessageParent.md) | Entity that owns this conversation. |\n| <a id=\"property-reactions\"></a> `reactions` | [`CountedReaction`](CountedReaction.md)[] | Aggregated reactions. |\n| <a id=\"property-sender_id\"></a> `sender_id` | `string` | Authenticated actor or owner of imported content. |\n| <a id=\"property-thread_id\"></a> `thread_id?` | `string` \\| `null` | Root message UUID for replies; absent on roots. |\n| <a id=\"property-triggered_by\"></a> `triggered_by?` | `string` \\| `null` | User who triggered a bot-authored message. |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | Last persisted update. |\n\n\n<!-- generated/storage/types.gen/type-aliases/MessageAttachment.md -->\n# Type Alias: MessageAttachment\n\n> **MessageAttachment** = \\{ `created_at`: `string`; `entity_id`: `string`; `entity_type`: `string`; `height?`: `number` \\| `null`; `id`: `string`; `width?`: `number` \\| `null`; \\}\n\nAn entity attached to a message.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | When the attachment was added. |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Attached entity identifier. |\n| <a id=\"property-entity_type\"></a> `entity_type` | `string` | Attached entity type. |\n| <a id=\"property-height\"></a> `height?` | `number` \\| `null` | Optional media height. |\n| <a id=\"property-id\"></a> `id` | `string` | Attachment UUID. |\n| <a id=\"property-width\"></a> `width?` | `number` \\| `null` | Optional media width. |\n\n\n<!-- generated/storage/types.gen/type-aliases/MessageCursor.md -->\n# Type Alias: MessageCursor\n\n> **MessageCursor** = \\{ `created_at`: `string`; `id`: `string`; \\}\n\nCursor for a chronological parent timeline.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Last message creation time or activity occurrence time. |\n| <a id=\"property-id\"></a> `id` | `string` | Last entry UUID, used to break timestamp ties across both sources. |\n\n\n<!-- generated/storage/types.gen/type-aliases/MessageParent.md -->\n# Type Alias: MessageParent\n\n> **MessageParent** = \\{ `id`: `string`; `type`: `\"channel\"`; \\} \\| \\{ `id`: [`DocumentId`](DocumentId.md); `type`: `\"document\"`; \\} \\| \\{ `id`: `string`; `type`: `\"initiative\"`; \\} \\| \\{ `id`: `string`; `type`: `\"crm_company\"`; \\} \\| \\{ `id`: `string`; `type`: `\"crm_contact\"`; \\} \\| \\{ `id`: `string`; `type`: `\"call\"`; \\}\n\nThe entity whose permissions and lifecycle govern a message.\n\n## Union Members\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"channel\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A channel, including direct messages. |\n| `type` | `\"channel\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: [`DocumentId`](DocumentId.md); `type`: `\"document\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | [`DocumentId`](DocumentId.md) | A document, including tasks and PDFs. |\n| `type` | `\"document\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"initiative\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | An initiative, presented as a project in the application. |\n| `type` | `\"initiative\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"crm_company\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A CRM company. |\n| `type` | `\"crm_company\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"crm_contact\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A CRM contact. |\n| `type` | `\"crm_contact\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `id`: `string`; `type`: `\"call\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `id` | `string` | A video call and its persistent chat thread. |\n| `type` | `\"call\"` | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/ParticipantRole.md -->\n# Type Alias: ParticipantRole\n\n> **ParticipantRole** = `\"owner\"` \\| `\"admin\"` \\| `\"member\"`\n\nThe role a user has within a channel.\n\n\n<!-- generated/storage/types.gen/type-aliases/PdfAnchor.md -->\n# Type Alias: PdfAnchor\n\n> **PdfAnchor** = [`PdfPlaceableCommentAnchor`](PdfPlaceableCommentAnchor.md) & \\{ `anchorType`: `\"placeable\"`; \\} \\| [`PdfHighlightAnchor`](PdfHighlightAnchor.md) & \\{ `anchorType`: `\"highlight\"`; \\}\n\n\n<!-- generated/storage/types.gen/type-aliases/PdfHighlightAnchor.md -->\n# Type Alias: PdfHighlightAnchor\n\n> **PdfHighlightAnchor** = \\{ `alpha`: `number`; `blue`: `number`; `createdAt?`: `string` \\| `null`; `deletedAt?`: `string` \\| `null`; `documentId`: `string`; `green`: `number`; `highlightRects`: [`PdfHighlightRect`](PdfHighlightRect.md)[]; `highlightType`: [`HighlightType`](HighlightType.md); `owner`: `string`; `page`: `number`; `pageViewportHeight`: `number`; `pageViewportWidth`: `number`; `red`: `number`; `rootId?`: `string` \\| `null`; `text`: `string`; `updatedAt?`: `string` \\| `null`; `uuid`: `string`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-alpha\"></a> `alpha` | `number` |\n| <a id=\"property-blue\"></a> `blue` | `number` |\n| <a id=\"property-createdat\"></a> `createdAt?` | `string` \\| `null` |\n| <a id=\"property-deletedat\"></a> `deletedAt?` | `string` \\| `null` |\n| <a id=\"property-documentid\"></a> `documentId` | `string` |\n| <a id=\"property-green\"></a> `green` | `number` |\n| <a id=\"property-highlightrects\"></a> `highlightRects` | [`PdfHighlightRect`](PdfHighlightRect.md)[] |\n| <a id=\"property-highlighttype\"></a> `highlightType` | [`HighlightType`](HighlightType.md) |\n| <a id=\"property-owner\"></a> `owner` | `string` |\n| <a id=\"property-page\"></a> `page` | `number` |\n| <a id=\"property-pageviewportheight\"></a> `pageViewportHeight` | `number` |\n| <a id=\"property-pageviewportwidth\"></a> `pageViewportWidth` | `number` |\n| <a id=\"property-red\"></a> `red` | `number` |\n| <a id=\"property-rootid\"></a> `rootId?` | `string` \\| `null` |\n| <a id=\"property-text\"></a> `text` | `string` |\n| <a id=\"property-updatedat\"></a> `updatedAt?` | `string` \\| `null` |\n| <a id=\"property-uuid\"></a> `uuid` | `string` |\n\n\n<!-- generated/storage/types.gen/type-aliases/PdfHighlightAnchorRequest.md -->\n# Type Alias: PdfHighlightAnchorRequest\n\n> **PdfHighlightAnchorRequest** = \\{ `alpha`: `number`; `blue`: `number`; `green`: `number`; `highlightRects`: [`PdfHighlightRectAnchorRequest`](PdfHighlightRectAnchorRequest.md)[]; `highlightType`: [`HighlightType`](HighlightType.md); `page`: `number`; `pageViewportHeight`: `number`; `pageViewportWidth`: `number`; `red`: `number`; `text`: `string`; `uuid?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-alpha\"></a> `alpha` | `number` |\n| <a id=\"property-blue\"></a> `blue` | `number` |\n| <a id=\"property-green\"></a> `green` | `number` |\n| <a id=\"property-highlightrects\"></a> `highlightRects` | [`PdfHighlightRectAnchorRequest`](PdfHighlightRectAnchorRequest.md)[] |\n| <a id=\"property-highlighttype\"></a> `highlightType` | [`HighlightType`](HighlightType.md) |\n| <a id=\"property-page\"></a> `page` | `number` |\n| <a id=\"property-pageviewportheight\"></a> `pageViewportHeight` | `number` |\n| <a id=\"property-pageviewportwidth\"></a> `pageViewportWidth` | `number` |\n| <a id=\"property-red\"></a> `red` | `number` |\n| <a id=\"property-text\"></a> `text` | `string` |\n| <a id=\"property-uuid\"></a> `uuid?` | `string` \\| `null` |\n\n\n<!-- generated/storage/types.gen/type-aliases/PdfHighlightRect.md -->\n# Type Alias: PdfHighlightRect\n\n> **PdfHighlightRect** = \\{ `height`: `number`; `id`: `number`; `left`: `number`; `top`: `number`; `width`: `number`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-height\"></a> `height` | `number` |\n| <a id=\"property-id\"></a> `id` | `number` |\n| <a id=\"property-left\"></a> `left` | `number` |\n| <a id=\"property-top\"></a> `top` | `number` |\n| <a id=\"property-width\"></a> `width` | `number` |\n\n\n<!-- generated/storage/types.gen/type-aliases/PdfHighlightRectAnchorRequest.md -->\n# Type Alias: PdfHighlightRectAnchorRequest\n\n> **PdfHighlightRectAnchorRequest** = \\{ `height`: `number`; `left`: `number`; `top`: `number`; `width`: `number`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-height\"></a> `height` | `number` |\n| <a id=\"property-left\"></a> `left` | `number` |\n| <a id=\"property-top\"></a> `top` | `number` |\n| <a id=\"property-width\"></a> `width` | `number` |\n\n\n<!-- generated/storage/types.gen/type-aliases/PdfPlaceableCommentAnchor.md -->\n# Type Alias: PdfPlaceableCommentAnchor\n\n> **PdfPlaceableCommentAnchor** = \\{ `allowableEdits?`: `unknown`; `documentId`: `string`; `heightPct`: `number`; `originalIndex`: `number`; `originalPage`: `number`; `owner`: `string`; `page`: `number`; `rootId?`: `string` \\| `null`; `rotation`: `number`; `shouldLockOnSave`: `boolean`; `uuid`: `string`; `wasDeleted`: `boolean`; `wasEdited`: `boolean`; `widthPct`: `number`; `xPct`: `number`; `yPct`: `number`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-allowableedits\"></a> `allowableEdits?` | `unknown` |\n| <a id=\"property-documentid\"></a> `documentId` | `string` |\n| <a id=\"property-heightpct\"></a> `heightPct` | `number` |\n| <a id=\"property-originalindex\"></a> `originalIndex` | `number` |\n| <a id=\"property-originalpage\"></a> `originalPage` | `number` |\n| <a id=\"property-owner\"></a> `owner` | `string` |\n| <a id=\"property-page\"></a> `page` | `number` |\n| <a id=\"property-rootid\"></a> `rootId?` | `string` \\| `null` |\n| <a id=\"property-rotation\"></a> `rotation` | `number` |\n| <a id=\"property-shouldlockonsave\"></a> `shouldLockOnSave` | `boolean` |\n| <a id=\"property-uuid\"></a> `uuid` | `string` |\n| <a id=\"property-wasdeleted\"></a> `wasDeleted` | `boolean` |\n| <a id=\"property-wasedited\"></a> `wasEdited` | `boolean` |\n| <a id=\"property-widthpct\"></a> `widthPct` | `number` |\n| <a id=\"property-xpct\"></a> `xPct` | `number` |\n| <a id=\"property-ypct\"></a> `yPct` | `number` |\n\n\n<!-- generated/storage/types.gen/type-aliases/PreSaveDocumentResponseData.md -->\n# Type Alias: PreSaveDocumentResponseData\n\n> **PreSaveDocumentResponseData** = \\{ `presignedUrls`: [`PresignedUrl`](PresignedUrl.md)[]; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-presignedurls\"></a> `presignedUrls` | [`PresignedUrl`](PresignedUrl.md)[] | Contains any presigned urls you need to upload specific bom parts with. |\n\n\n<!-- generated/storage/types.gen/type-aliases/PresignedUrl.md -->\n# Type Alias: PresignedUrl\n\n> **PresignedUrl** = \\{ `presignedUrl`: `string`; `sha`: `string`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-presignedurl\"></a> `presignedUrl` | `string` | The presigned url used to upload the sha |\n| <a id=\"property-sha\"></a> `sha` | `string` | The sha of the item |\n\n\n<!-- generated/storage/types.gen/type-aliases/SaveBomPart.md -->\n# Type Alias: SaveBomPart\n\n> **SaveBomPart** = \\{ `path`: `string`; `sha`: `string`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-path\"></a> `path` | `string` | The file path of the bom part content |\n| <a id=\"property-sha\"></a> `sha` | `string` | The sha of the bom part content There is an index on sha for more performant queries based on it. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SaveDocumentRequest.md -->\n# Type Alias: SaveDocumentRequest\n\n> **SaveDocumentRequest** = \\{ `modificationData?`: `unknown`; `newBom?`: [`SaveBomPart`](SaveBomPart.md)[] \\| `null`; `sha?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-modificationdata\"></a> `modificationData?` | `unknown` | The modification data for the document instance. Used to store highlights and other overlays onto a static file |\n| <a id=\"property-newbom\"></a> `newBom?` | [`SaveBomPart`](SaveBomPart.md)[] \\| `null` | **DOCX ONLY** The updated BOM for the document. Containing the file path and the sha. |\n| <a id=\"property-sha\"></a> `sha?` | `string` \\| `null` | The sha of the new document. This is used to generate a presigned url to upload the new document content to s3. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md -->\n# Type Alias: SaveDocumentResponseData\n\n> **SaveDocumentResponseData** = \\{ `documentMetadata`: [`DocumentResponseMetadata`](DocumentResponseMetadata.md); `presignedUrl?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-documentmetadata\"></a> `documentMetadata` | [`DocumentResponseMetadata`](DocumentResponseMetadata.md) | The updated document metadata |\n| <a id=\"property-presignedurl\"></a> `presignedUrl?` | `string` \\| `null` | If the document is an editable file, we provide a presigned url to save the updated file to. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SharePermissionV2.md -->\n# Type Alias: SharePermissionV2\n\n> **SharePermissionV2** = \\{ `channelSharePermissions?`: [`ChannelSharePermission`](ChannelSharePermission.md)[] \\| `null`; `id`: `string`; `linkShare?`: `null` \\| [`LinkShare`](LinkShare.md); `linkShareAccessLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); `owner`: `string`; `teamShareAccessLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channelsharepermissions\"></a> `channelSharePermissions?` | [`ChannelSharePermission`](ChannelSharePermission.md)[] \\| `null` | The channel share permissions for the item |\n| <a id=\"property-id\"></a> `id` | `string` | The share permission id |\n| <a id=\"property-linkshare\"></a> `linkShare?` | `null` \\| [`LinkShare`](LinkShare.md) | - |\n| <a id=\"property-linkshareaccesslevel\"></a> `linkShareAccessLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n| <a id=\"property-owner\"></a> `owner` | `string` | The owner of the item |\n| <a id=\"property-teamshareaccesslevel\"></a> `teamShareAccessLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/SimpleMention.md -->\n# Type Alias: SimpleMention\n\n> **SimpleMention** = \\{ `entity_id`: `string`; `entity_type`: `string`; \\}\n\nA mention tracked in a message body.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Mentioned entity identifier. |\n| <a id=\"property-entity_type\"></a> `entity_type` | `string` | Mentioned entity type. |\n\n\n<!-- generated/storage/types.gen/type-aliases/TeamRole.md -->\n# Type Alias: TeamRole\n\n> **TeamRole** = `\"member\"` \\| `\"admin\"` \\| `\"owner\"`\n\nThe role a user has within a team.\n\nOrdered least to most privileged so comparisons reflect access strength.\n\n\n<!-- generated/storage/types.gen/type-aliases/ThreadAnchor.md -->\n# Type Alias: ThreadAnchor\n\n> **ThreadAnchor** = \\{ `mark_id`: `string`; `marked_text?`: `string` \\| `null`; `type`: `\"markdown\"`; \\} \\| \\{ `anchor_id`: `string`; `marked_text?`: `string` \\| `null`; `type`: `\"pdf_highlight\"`; \\} \\| \\{ `anchor_id`: `string`; `type`: `\"pdf_placeable\"`; \\} \\| \\{ `range`: `string`; `sheetId`: `string`; `sheetName`: `string`; `type`: `\"spreadsheet\"`; \\} \\| \\{ `nodeId?`: `string` \\| `null`; `pageId`: `string`; `type`: `\"fig\"`; `x`: `number`; `y`: `number`; \\}\n\nA thread's location within its document. PDF geometry remains annotation-owned.\n\n## Union Members\n\n### Type Literal\n\n\\{ `mark_id`: `string`; `marked_text?`: `string` \\| `null`; `type`: `\"markdown\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `mark_id` | `string` | Mark UUID serialized in the document. |\n| `marked_text?` | `string` \\| `null` | The marked text as it read when the discussion was created, already trimmed and bounded. Absent on threads created or imported before snapshots were captured: the text a mark covers cannot be recovered from the mark id alone. |\n| `type` | `\"markdown\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `anchor_id`: `string`; `marked_text?`: `string` \\| `null`; `type`: `\"pdf_highlight\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `anchor_id` | `string` | Highlight annotation UUID. |\n| `marked_text?` | `string` \\| `null` | The text the highlight covers, trimmed and bounded like a markdown snapshot. The highlight owns it and it can be edited there, so it is read from the highlight whenever the thread is, never stored on the thread. Absent when the highlight carries no text. |\n| `type` | `\"pdf_highlight\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `anchor_id`: `string`; `type`: `\"pdf_placeable\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `anchor_id` | `string` | Placeable annotation UUID. |\n| `type` | `\"pdf_placeable\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `range`: `string`; `sheetId`: `string`; `sheetName`: `string`; `type`: `\"spreadsheet\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `range` | `string` | A1 cell or range, such as B4 or B4:C9. |\n| `sheetId` | `string` | Stable sheet identity within the workbook. |\n| `sheetName` | `string` | Sheet name when the discussion was created. |\n| `type` | `\"spreadsheet\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `nodeId?`: `string` \\| `null`; `pageId`: `string`; `type`: `\"fig\"`; `x`: `number`; `y`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `nodeId?` | `string` \\| `null` | Layer the pin follows; absent for a pin on the bare canvas. |\n| `pageId` | `string` | Page (canvas) the pin is on. |\n| `type` | `\"fig\"` | - |\n| `x` | `number` | Horizontal offset from the layer's origin, or the page's when the pin is on no layer, in design units. |\n| `y` | `number` | Vertical offset, measured like `x`. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ThreadState.md -->\n# Type Alias: ThreadState\n\n> **ThreadState** = \\{ `anchor?`: `null` \\| [`ThreadAnchor`](ThreadAnchor.md); `created_at`: `string`; `deleted_at?`: `string` \\| `null`; `resolved`: `boolean`; `root_id`: `string`; `updated_at`: `string`; `user_id`: `string`; \\}\n\nState belonging to a whole thread, keyed by its root message.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-anchor\"></a> `anchor?` | `null` \\| [`ThreadAnchor`](ThreadAnchor.md) | - |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Creation time of the discussion. |\n| <a id=\"property-deleted_at\"></a> `deleted_at?` | `string` \\| `null` | Explicit deletion of the entire thread, distinct from root deletion. |\n| <a id=\"property-resolved\"></a> `resolved` | `boolean` | Whether this discussion has been resolved. |\n| <a id=\"property-root_id\"></a> `root_id` | `string` | Root message UUID; there is no separate thread identity. |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | Last state change. |\n| <a id=\"property-user_id\"></a> `user_id` | `string` | User who owns this discussion, including imported discussions. |\n\n\n<!-- src/entities/documents/anchor/classes/DocumentAnchor.md -->\n# Class: DocumentAnchor\n\nA PDF annotation scoped to its document.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`Anchor`](../../../../../generated/storage/types.gen/type-aliases/Anchor.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-document\"></a> `document` | `readonly` | [`Document`](../../document/classes/Document.md) | Owning document. | - |\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-kind\"></a> `kind` | `readonly` | () => `Promise`\\<`\"highlight\"` \\| `\"placeable\"`\\> | Annotation kind. | - |\n| <a id=\"property-page\"></a> `page` | `readonly` | () => `Promise`\\<`number`\\> | Page containing the annotation. | - |\n\n## Methods\n\n### delete()\n\n> **delete**(): `Promise`\\<`void`\\>\n\nDelete a standalone highlight annotation.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### edit()\n\n> **edit**(`options`): `Promise`\\<`void`\\>\n\nEdit a placeable comment's position and display settings.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | `Omit`\\<[`EditPdfPlaceableCommentAnchorRequest`](../../../../../generated/storage/types.gen/type-aliases/EditPdfPlaceableCommentAnchorRequest.md), `\"uuid\"`\\> |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`PdfAnchor`](../../../../../generated/storage/types.gen/type-aliases/PdfAnchor.md); `documentId`: `string`; `id`: `string`; \\}\n\nSerialize identity with its owning resource.\n\n#### Returns\n\n\\{ `detail?`: [`PdfAnchor`](../../../../../generated/storage/types.gen/type-aliases/PdfAnchor.md); `documentId`: `string`; `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`PdfAnchor`](../../../../../generated/storage/types.gen/type-aliases/PdfAnchor.md) |\n| `documentId` | `string` |\n| `id` | `string` |\n\n#### Overrides\n\n[`MacroEntity`](../../../entity/classes/MacroEntity.md).[`toJSON`](../../../entity/classes/MacroEntity.md#tojson)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `document`, `id`): `DocumentAnchor`\n\nConstruct a document scoped annotation handle.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `document` | [`Document`](../../document/classes/Document.md) |\n| `id` | `string` |\n\n#### Returns\n\n`DocumentAnchor`\n\n***\n\n### from()\n\n> `static` **from**(`client`, `document`, `record`): `DocumentAnchor`\n\nSeed an annotation from a document annotation listing.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `document` | [`Document`](../../document/classes/Document.md) |\n| `record` | [`PdfAnchor`](../../../../../generated/storage/types.gen/type-aliases/PdfAnchor.md) |\n\n#### Returns\n\n`DocumentAnchor`\n\n\n<!-- src/entities/documents/comment/classes/Comment.md -->\n# Class: Comment\n\nA comment on a document: a document-parent message, addressed by its\ndocument and message UUID. Its record and mutations are the ones channel\nmessages use.\n\n## Extends\n\n- [`MacroEntity`](../../../entity/classes/MacroEntity.md)\\<[`Message`](../../../../../generated/storage/types.gen/type-aliases/Message.md)\\>\n\n## Properties\n\n| Property | Modifier | Type | Description | Inherited from |\n| ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-createdat\"></a> `createdAt` | `readonly` | () => `Promise`\\<`string`\\> | When the comment was created. | - |\n| <a id=\"property-documentid\"></a> `documentId` | `readonly` | `string` | The document this comment belongs to. | - |\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-text\"></a> `text` | `readonly` | () => `Promise`\\<`string`\\> | The comment's text. | - |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `readonly` | () => `Promise`\\<`string`\\> | When the comment was last updated. | - |\n\n## Methods\n\n### author()\n\n> **author**(): `Promise`\\<[`User`](../../../users/user/classes/User.md)\\>\n\nThe user who wrote this comment.\n\n#### Returns\n\n`Promise`\\<[`User`](../../../users/user/classes/User.md)\\>\n\n***\n\n### delete()\n\n> **delete**(): `Promise`\\<`void`\\>\n\nDelete this comment.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### document()\n\n> **document**(): [`Document`](../../document/classes/Document.md)\n\nThe document this comment is on.\n\n#### Returns\n\n[`Document`](../../document/classes/Document.md)\n\n***\n\n### edit()\n\n> **edit**(`body`): `Promise`\\<`Comment`\\>\n\nReplace the comment's text.\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `body` | `string` \\| [`RichMessage`](../../../../mentions/interfaces/RichMessage.md) | Plain text, or a rich body composed with msg. |\n\n#### Returns\n\n`Promise`\\<`Comment`\\>\n\n***\n\n### reply()\n\n> **reply**(`body`): `Promise`\\<`Comment`\\>\n\nReply in this comment's thread.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `body` | `string` \\| [`RichMessage`](../../../../mentions/interfaces/RichMessage.md) |\n\n#### Returns\n\n`Promise`\\<`Comment`\\>\n\n***\n\n### threadId()\n\n> **threadId**(): `Promise`\\<`string`\\>\n\nThe id of the thread this comment belongs to: its root, or itself for a root.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`Message`](../../../../../generated/storage/types.gen/type-aliases/Message.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`Message`](../../../../../generated/storage/types.gen/type-aliases/Message.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`Message`](../../../../../generated/storage/types.gen/type-aliases/Message.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`, `documentId`, `id`): `Comment`\n\nA handle to a comment by id. Fields load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `documentId` | `string` |\n| `id` | `string` |\n\n#### Returns\n\n`Comment`\n\n***\n\n### from()\n\n> `static` **from**(`client`, `documentId`, `record`): `Comment`\n\nBuild a comment from a message record (pre-seeded, no fetch).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `documentId` | `string` |\n| `record` | [`Message`](../../../../../generated/storage/types.gen/type-aliases/Message.md) |\n\n#### Returns\n\n`Comment`\n\n\n<!-- src/entities/documents/document/classes/Document.md -->\n# Class: Document\n\nA Macro document. Can be dropped into a msg template to render an\ninline link to the document.\n\n## Extends\n\n- [`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md)\\<`DocumentDetail`\\>\n\n## Extended by\n\n- [`Task`](../../../tasks/task/classes/Task.md)\n\n## Implements\n\n- [`Mentionable`](../../../../mentions/interfaces/Mentionable.md)\n\n## Properties\n\n| Property | Modifier | Type | Default value | Description | Overrides | Inherited from |\n| ------ | ------ | ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-access\"></a> `access` | `readonly` | [`EntityAccess`](../../../sharing/access/classes/EntityAccess.md) | `...` | Access requests and direct user grants. | - | - |\n| <a id=\"property-branchedfrom\"></a> `branchedFrom` | `readonly` | () => `Promise`\\<`Document` \\| `undefined`\\> | `...` | The document this one was branched from, if any. | - | - |\n| <a id=\"property-createdat\"></a> `createdAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | When the document was created. | - | - |\n| <a id=\"property-deletedat\"></a> `deletedAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | When the document was deleted, if it has been. | - | - |\n| <a id=\"property-entitytype\"></a> `entityType` | `readonly` | `\"document\"` | `'document'` | Favorites identify documents as `document`. | [`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`entityType`](../../../entity/classes/PropertiedEntity.md#property-entitytype) | - |\n| <a id=\"property-filetype\"></a> `fileType` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | The document's file type (e.g. `md`, `pdf`, `docx`). | - | - |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | `undefined` | - | - | [`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`id`](../../../entity/classes/PropertiedEntity.md#property-id) |\n| <a id=\"property-name\"></a> `name` | `readonly` | () => `Promise`\\<`string`\\> | `...` | The document's display name. | - | - |\n| <a id=\"property-owner\"></a> `owner` | `readonly` | () => `Promise`\\<[`User`](../../../users/user/classes/User.md)\\> | `...` | The user who owns the document. | - | - |\n| <a id=\"property-project\"></a> `project` | `readonly` | () => `Promise`\\<[`Project`](../../../projects/project/classes/Project.md) \\| `undefined`\\> | `...` | The project this document belongs to, if any. | - | - |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | When the document was last updated. | - | - |\n| <a id=\"property-search\"></a> `search` | `static` | (`client`, `query`, `searchOpts?`) => `AsyncGenerator`\\<`Document`\\> | `...` | Search documents by name and content, most relevant first, auto-paginated. | - | - |\n\n## Methods\n\n### anchors()\n\n> **anchors**(): `Promise`\\<[`DocumentAnchor`](../../anchor/classes/DocumentAnchor.md)[]\\>\n\nPDF annotations in this document.\n\n#### Returns\n\n`Promise`\\<[`DocumentAnchor`](../../anchor/classes/DocumentAnchor.md)[]\\>\n\n***\n\n### branchName()\n\n> **branchName**(): `Promise`\\<`string`\\>\n\nThe git branch name derived for the document (task documents).\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### comment()\n\n> **comment**(`body`, `opts?`): `Promise`\\<[`Comment`](../../comment/classes/Comment.md)\\>\n\nAdd a comment. Starts a new unanchored thread, or replies to an existing\none when `threadId` (the thread's root comment id) is given.\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `body` | `string` \\| [`RichMessage`](../../../../mentions/interfaces/RichMessage.md) | Plain text, or a rich body composed with msg. |\n| `opts?` | \\{ `threadId?`: `string`; \\} | - |\n| `opts.threadId?` | `string` | - |\n\n#### Returns\n\n`Promise`\\<[`Comment`](../../comment/classes/Comment.md)\\>\n\nThe created comment.\n\n***\n\n### comments()\n\n> **comments**(): `Promise`\\<[`CommentThread`](../interfaces/CommentThread.md)[]\\>\n\nThe document's live comment threads, each with its comments, newest thread first.\n\n#### Returns\n\n`Promise`\\<[`CommentThread`](../interfaces/CommentThread.md)[]\\>\n\n***\n\n### content()\n\n> **content**(): `Promise`\\<`string`\\>\n\nCurrent Markdown for native documents, extracted text for PDF/Word,\nor raw file content for other formats. Native reads include live edits.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### copy()\n\n> **copy**(`opts`): `Promise`\\<`Document`\\>\n\nCopy the document under a new name, optionally from a specific version.\nReturns a handle to the new document.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `name`: `string`; `versionId?`: `number`; \\} |\n| `opts.name` | `string` |\n| `opts.versionId?` | `number` |\n\n#### Returns\n\n`Promise`\\<`Document`\\>\n\n***\n\n### createHighlight()\n\n> **createHighlight**(`options`): `Promise`\\<[`DocumentAnchor`](../../anchor/classes/DocumentAnchor.md)\\>\n\nCreate a standalone PDF highlight.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | `Omit`\\<[`PdfHighlightAnchorRequest`](../../../../../generated/storage/types.gen/type-aliases/PdfHighlightAnchorRequest.md), `\"uuid\"`\\> |\n\n#### Returns\n\n`Promise`\\<[`DocumentAnchor`](../../anchor/classes/DocumentAnchor.md)\\>\n\n***\n\n### delete()\n\n> **delete**(`opts?`): `Promise`\\<`void`\\>\n\nDelete the document. Soft by default (reversible with [restore](#restore));\npass `permanent: true` to delete irreversibly.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `permanent?`: `boolean`; \\} |\n| `opts.permanent?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### deleteProperty()\n\n> **deleteProperty**(`assignment`): `Promise`\\<`void`\\>\n\nRemove a property from this entity, given its [properties](#properties) entry.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `assignment` | [`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`deleteProperty`](../../../entity/classes/PropertiedEntity.md#deleteproperty)\n\n***\n\n### favorite()\n\n> **favorite**(): `Promise`\\<`Document`\\>\n\nAdd this entity to the user's favorites. Returns this handle for chaining.\nPlain unwrap: favoriting alters the user's favorites collection, not this\nentity's own detail, so there's nothing cached to invalidate.\n\n#### Returns\n\n`Promise`\\<`Document`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`favorite`](../../../entity/classes/PropertiedEntity.md#favorite)\n\n***\n\n### githubPullRequests()\n\n> **githubPullRequests**(): `Promise`\\<[`GithubPullRequest`](../../../../../generated/storage/types.gen/type-aliases/GithubPullRequest.md)[]\\>\n\nGitHub pull requests associated with the document.\n\n#### Returns\n\n`Promise`\\<[`GithubPullRequest`](../../../../../generated/storage/types.gen/type-aliases/GithubPullRequest.md)[]\\>\n\n***\n\n### meetingNotes()\n\n> **meetingNotes**(): `Promise`\\<\\{ `eventTitle`: `string`; `note`: [`CalendarNote`](../../../calendar/note/classes/CalendarNote.md); \\}[]\\>\n\nMeeting links visible to the reader. Owners also receive unavailable grants and may unlink them to revoke meeting/team access.\n\n#### Returns\n\n`Promise`\\<\\{ `eventTitle`: `string`; `note`: [`CalendarNote`](../../../calendar/note/classes/CalendarNote.md); \\}[]\\>\n\n***\n\n### messageThreadById()\n\n> **messageThreadById**(`id`): [`MessageThread`](../../../messages/thread/classes/MessageThread.md)\n\nA shared message thread scoped to this resource.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`MessageThread`](../../../messages/thread/classes/MessageThread.md)\n\n***\n\n### move()\n\n> **move**(`project`): `Promise`\\<`void`\\>\n\nMove the document into a project (or out of one, with `null`).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `project` | [`Project`](../../../projects/project/classes/Project.md) \\| `null` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### permission()\n\n> **permission**(): `Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\nRead the caller's effective permission on this entity.\n\n#### Returns\n\n`Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`permission`](../../../entity/classes/PropertiedEntity.md#permission)\n\n***\n\n### permissionsToken()\n\n> **permissionsToken**(): `Promise`\\<`string`\\>\n\nMint a scoped permissions token.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### prepareSave()\n\n> **prepareSave**(`parts`): `Promise`\\<[`PreSaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/PreSaveDocumentResponseData.md)\\>\n\nPrepare multipart content saving and return the service's upload instructions.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `parts` | [`SaveBomPart`](../../../../../generated/storage/types.gen/type-aliases/SaveBomPart.md)[] |\n\n#### Returns\n\n`Promise`\\<[`PreSaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/PreSaveDocumentResponseData.md)\\>\n\n***\n\n### properties()\n\n> **properties**(`opts?`): `Promise`\\<[`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\nThe properties set on this entity, each with its definition, value, and options.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `includeMetadata?`: `boolean`; \\} |\n| `opts.includeMetadata?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<[`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`properties`](../../../entity/classes/PropertiedEntity.md#properties)\n\n***\n\n### propertyReference()\n\n> **propertyReference**(): [`PropertyTargetReference`](../../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\nThis entity's reference for bulk property operations.\n\n#### Returns\n\n[`PropertyTargetReference`](../../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`propertyReference`](../../../entity/classes/PropertiedEntity.md#propertyreference)\n\n***\n\n### rename()\n\n> **rename**(`name`): `Promise`\\<`void`\\>\n\nRename the document.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `name` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### restore()\n\n> **restore**(): `Promise`\\<`void`\\>\n\nRestore a soft-deleted document.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### save()\n\n> **save**(`options`): `Promise`\\<[`SaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md)\\>\n\nCommit uploaded content. Does not retry uncertain writes.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`SaveDocumentRequest`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentRequest.md) |\n\n#### Returns\n\n`Promise`\\<[`SaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md)\\>\n\n***\n\n### setProperty()\n\n> **setProperty**(`property`, `value?`): `Promise`\\<`void`\\>\n\nSet a property value on this entity, or attach the property without a\nvalue when `value` is omitted.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `property` | [`PropertyDefinition`](../../../properties/property-definition/classes/PropertyDefinition.md) |\n| `value?` | [`SetPropertyValue`](../../../../../generated/properties/types.gen/type-aliases/SetPropertyValue.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`setProperty`](../../../entity/classes/PropertiedEntity.md#setproperty)\n\n***\n\n### setTeamShare()\n\n> **setTeamShare**(`shared`): `Promise`\\<`void`\\>\n\nShare the document with the owner's team, or unshare it.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `shared` | `boolean` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n***\n\n### sharePermissions()\n\n> **sharePermissions**(): `Promise`\\<[`SharePermissionV2`](../../../../../generated/storage/types.gen/type-aliases/SharePermissionV2.md)\\>\n\nSharing configuration.\n\n#### Returns\n\n`Promise`\\<[`SharePermissionV2`](../../../../../generated/storage/types.gen/type-aliases/SharePermissionV2.md)\\>\n\n***\n\n### shortId()\n\n> **shortId**(): `Promise`\\<`string`\\>\n\nThe document's short id (used in compact links and branch names).\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n***\n\n### simpleSave()\n\n> **simpleSave**(): `Promise`\\<[`SaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md)\\>\n\nCommit a simple document save.\n\n#### Returns\n\n`Promise`\\<[`SaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md)\\>\n\n***\n\n### teamShare()\n\n> **teamShare**(): `Promise`\\<[`DocumentTeamShareResponse`](../../../../../generated/storage/types.gen/type-aliases/DocumentTeamShareResponse.md)\\>\n\nWhether the document is shared with the owner's team, and which team.\n\n#### Returns\n\n`Promise`\\<[`DocumentTeamShareResponse`](../../../../../generated/storage/types.gen/type-aliases/DocumentTeamShareResponse.md)\\>\n\n***\n\n### timelinePage()\n\n> **timelinePage**(`selection?`): `Promise`\\<\\{ `entries`: (\\{ `activity`: \\{ `action`: `string`; `actor`: [`User`](../../../users/user/classes/User.md); `actor_id`: `string`; `id`: `string`; `occurred_at`: `string`; `payload?`: `unknown`; \\}; `message?`: `undefined`; `type`: `\"activity\"`; \\} \\| \\{ `activity?`: `undefined`; `message`: [`Comment`](../../comment/classes/Comment.md); `type`: `\"message\"`; \\})[]; `nextCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; `previousCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; \\}\\>\n\nA mixed message and activity timeline page.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `selection?` | [`TimelineOptions`](../../../messages/thread/interfaces/TimelineOptions.md)\\<[`Comment`](../../comment/classes/Comment.md)\\> |\n\n#### Returns\n\n`Promise`\\<\\{ `entries`: (\\{ `activity`: \\{ `action`: `string`; `actor`: [`User`](../../../users/user/classes/User.md); `actor_id`: `string`; `id`: `string`; `occurred_at`: `string`; `payload?`: `unknown`; \\}; `message?`: `undefined`; `type`: `\"activity\"`; \\} \\| \\{ `activity?`: `undefined`; `message`: [`Comment`](../../comment/classes/Comment.md); `type`: `\"message\"`; \\})[]; `nextCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; `previousCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; \\}\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`DocumentMetadataWithContent`](../../../../../generated/storage/types.gen/type-aliases/DocumentMetadataWithContent.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`DocumentMetadataWithContent`](../../../../../generated/storage/types.gen/type-aliases/DocumentMetadataWithContent.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`DocumentMetadataWithContent`](../../../../../generated/storage/types.gen/type-aliases/DocumentMetadataWithContent.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`toJSON`](../../../entity/classes/PropertiedEntity.md#tojson)\n\n***\n\n### toMention()\n\n> **toMention**(): [`MentionPart`](../../../../mentions/interfaces/MentionPart.md)\n\n#### Returns\n\n[`MentionPart`](../../../../mentions/interfaces/MentionPart.md)\n\n#### Implementation of\n\n[`Mentionable`](../../../../mentions/interfaces/Mentionable.md).[`toMention`](../../../../mentions/interfaces/Mentionable.md#tomention)\n\n***\n\n### unfavorite()\n\n> **unfavorite**(): `Promise`\\<`Document`\\>\n\nRemove this entity from the user's favorites. Returns this handle for chaining.\n\n#### Returns\n\n`Promise`\\<`Document`\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`unfavorite`](../../../entity/classes/PropertiedEntity.md#unfavorite)\n\n***\n\n### updatePropertyOptions()\n\n> **updatePropertyOptions**(`changes`): `Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\nApply multi-select option deltas atomically across this entity's properties.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `changes` | [`PropertyOptionDelta`](../../../entity/interfaces/PropertyOptionDelta.md)[] |\n\n#### Returns\n\n`Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\n#### Inherited from\n\n[`PropertiedEntity`](../../../entity/classes/PropertiedEntity.md).[`updatePropertyOptions`](../../../entity/classes/PropertiedEntity.md#updatepropertyoptions)\n\n***\n\n### version()\n\n> **version**(`version`): [`DocumentVersion`](../../version/classes/DocumentVersion.md)\n\nA handle to an immutable version.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `version` | `number` |\n\n#### Returns\n\n[`DocumentVersion`](../../version/classes/DocumentVersion.md)\n\n***\n\n### webUrl()\n\n> **webUrl**(): `string`\n\nThe document's URL in the Macro web app.\n\n#### Returns\n\n`string`\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `Document`\n\nA handle to a document by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`Document`\n\n***\n\n### create()\n\n> `static` **create**(`client`, `opts`): `Promise`\\<`Document`\\>\n\nCreate a markdown document.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<`Document`\\>\n\n***\n\n### createSkill()\n\n> `static` **createSkill**(`client`, `opts`): `Promise`\\<`Document`\\>\n\nCreate a skill: a markdown document containing instructions that AI reads\nand follows when the skill is referenced in an AI input.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<`Document`\\>\n\n***\n\n### createSnippet()\n\n> `static` **createSnippet**(`client`, `opts`): `Promise`\\<`Document`\\>\n\nCreate a snippet: a reusable markdown document that can be inserted into\nany markdown area.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<`Document`\\>\n\n***\n\n### recent()\n\n> `static` **recent**(`client`, `opts?`): `AsyncGenerator`\\<`Document`\\>\n\nThe user's recent documents, most recent first, auto-paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts?` | \\{ `fileType?`: `string`; `pageSize?`: `number`; \\} |\n| `opts.fileType?` | `string` |\n| `opts.pageSize?` | `number` |\n\n#### Returns\n\n`AsyncGenerator`\\<`Document`\\>\n\n***\n\n### recentlyDeleted()\n\n> `static` **recentlyDeleted**(`client`): `Promise`\\<`Document`[]\\>\n\nThe user's recently soft-deleted documents. The underlying endpoint also\nreturns deleted chats and projects; those are filtered out here.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`Promise`\\<`Document`[]\\>\n\n\n<!-- src/entities/documents/document/interfaces/CommentThread.md -->\n# Interface: CommentThread\n\nOne of a document's comment threads: its state and its comments.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-comments\"></a> `comments` | [`Comment`](../../comment/classes/Comment.md)[] | The root comment followed by its replies, in order. |\n| <a id=\"property-thread\"></a> `thread` | [`ThreadState`](../../../../../generated/storage/types.gen/type-aliases/ThreadState.md) | The thread state: root id, resolved flag, owner, anchor, timestamps. |\n\n\n<!-- src/entities/documents/namespace/classes/DocumentNamespace.md -->\n# Class: DocumentNamespace\n\n## Constructors\n\n### Constructor\n\n> **new DocumentNamespace**(`client`): `DocumentNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`DocumentNamespace`\n\n## Methods\n\n### byId()\n\n> **byId**(`id`): [`Document`](../../document/classes/Document.md)\n\nA handle to a document by id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Document`](../../document/classes/Document.md)\n\n***\n\n### byTeamSlug()\n\n> **byTeamSlug**(`slug`): `Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\nResolve a team task reference such as ENG-42.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `slug` | `string` |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### create()\n\n> **create**(`opts`): `Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\nCreate a markdown document.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### createCanvas()\n\n> **createCanvas**(`opts`): `Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\nCreate a native Canvas with shared content ready for reading and editing.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### createSkill()\n\n> **createSkill**(`opts`): `Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\nCreate a skill: markdown instructions that AI reads and follows.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### createSnippet()\n\n> **createSnippet**(`opts`): `Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\nCreate a snippet: a reusable markdown document.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### createUpload()\n\n> **createUpload**(`options`): `Promise`\\<\\{ `content`: [`DocumentContent`](../../../../../generated/storage/types.gen/type-aliases/DocumentContent.md); `contentType`: `string`; `document`: [`Document`](../../document/classes/Document.md); `uploadUrl`: `string` \\| `undefined`; \\}\\>\n\nReserve a binary document and return upload instructions. Upload content before saving.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | \\{ `attachment?`: [`EmailAttachment`](../../../email/attachment/classes/EmailAttachment.md); `branchedFrom?`: [`Document`](../../document/classes/Document.md); `fileType?`: `string`; `isTask?`: `boolean`; `mimeType?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); `sha`: `string`; `team?`: [`Team`](../../../teams/team/classes/Team.md); \\} |\n| `options.attachment?` | [`EmailAttachment`](../../../email/attachment/classes/EmailAttachment.md) |\n| `options.branchedFrom?` | [`Document`](../../document/classes/Document.md) |\n| `options.fileType?` | `string` |\n| `options.isTask?` | `boolean` |\n| `options.mimeType?` | `string` |\n| `options.name` | `string` |\n| `options.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n| `options.sha` | `string` |\n| `options.team?` | [`Team`](../../../teams/team/classes/Team.md) |\n\n#### Returns\n\n`Promise`\\<\\{ `content`: [`DocumentContent`](../../../../../generated/storage/types.gen/type-aliases/DocumentContent.md); `contentType`: `string`; `document`: [`Document`](../../document/classes/Document.md); `uploadUrl`: `string` \\| `undefined`; \\}\\>\n\n***\n\n### recent()\n\n> **recent**(`opts?`): `AsyncGenerator`\\<[`Document`](../../document/classes/Document.md)\\>\n\nThe user's recent documents, most recent first, auto-paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `fileType?`: `string`; `pageSize?`: `number`; \\} |\n| `opts.fileType?` | `string` |\n| `opts.pageSize?` | `number` |\n\n#### Returns\n\n`AsyncGenerator`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### recentlyDeleted()\n\n> **recentlyDeleted**(): `Promise`\\<[`Document`](../../document/classes/Document.md)[]\\>\n\nThe user's recently soft-deleted documents.\n\n#### Returns\n\n`Promise`\\<[`Document`](../../document/classes/Document.md)[]\\>\n\n***\n\n### search()\n\n> **search**(`query`, `opts?`): `AsyncGenerator`\\<[`Document`](../../document/classes/Document.md)\\>\n\nSearch documents by name and content, most relevant first, auto-paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `query` | `string` |\n| `opts?` | [`SearchOpts`](../../../search/interfaces/SearchOpts.md) |\n\n#### Returns\n\n`AsyncGenerator`\\<[`Document`](../../document/classes/Document.md)\\>\n\n***\n\n### systemSkills()\n\n> **systemSkills**(): `Promise`\\<[`SystemSkill`](../../system-skill/classes/SystemSkill.md)[]\\>\n\nThe built-in system skills: static AI instructions with no document\nbehind them. Unlike user skills they cannot be opened or edited.\n\n#### Returns\n\n`Promise`\\<[`SystemSkill`](../../system-skill/classes/SystemSkill.md)[]\\>\n\n***\n\n### validatePermissionsToken()\n\n> **validatePermissionsToken**(`token`): `Promise`\\<\\{ `accessLevel`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md); `document`: [`Document`](../../document/classes/Document.md); `expiresAt`: `number`; `issuer`: `string`; `user`: [`User`](../../../users/user/classes/User.md) \\| `undefined`; \\}\\>\n\nValidate a permissions token, returning its document and optional user handles.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `token` | `string` |\n\n#### Returns\n\n`Promise`\\<\\{ `accessLevel`: [`AccessLevel`](../../../../../generated/storage/types.gen/type-aliases/AccessLevel.md); `document`: [`Document`](../../document/classes/Document.md); `expiresAt`: `number`; `issuer`: `string`; `user`: [`User`](../../../users/user/classes/User.md) \\| `undefined`; \\}\\>\n\n\n<!-- src/entities/documents/system-skill/classes/SystemSkill.md -->\n# Class: SystemSkill\n\nA built-in system skill: static, code-defined AI instructions that surface\nto AI like skill documents but have no document behind them. System skills\ncannot be opened, edited, or deleted; reference them in AI inputs by id the\nsame way as skill documents.\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `readonly` | `string` | The well-known id the skill is referenced by in mentions and AI tools. |\n| <a id=\"property-name\"></a> `name` | `readonly` | `string` | The skill's display name. |\n\n## Methods\n\n### list()\n\n> `static` **list**(`client`): `Promise`\\<`SystemSkill`[]\\>\n\nThe built-in system skills, in display order.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`Promise`\\<`SystemSkill`[]\\>\n\n\n<!-- src/entities/documents/version/classes/DocumentVersion.md -->\n# Class: DocumentVersion\n\nAn immutable document version, scoped to its document.\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-document\"></a> `document` | `readonly` | [`Document`](../../document/classes/Document.md) | Parent document. |\n| <a id=\"property-id\"></a> `id` | `readonly` | `number` | Version number. |\n\n## Methods\n\n### read()\n\n> **read**(): `Promise`\\<[`GetDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/GetDocumentResponseData.md)\\>\n\nVersion metadata and the caller's access.\n\n#### Returns\n\n`Promise`\\<[`GetDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/GetDocumentResponseData.md)\\>\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `documentId`: `string`; `id`: `number`; \\}\n\nSerialize only scoped identity.\n\n#### Returns\n\n\\{ `documentId`: `string`; `id`: `number`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `documentId` | `string` |\n| `id` | `number` |\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `document`, `id`): `DocumentVersion`\n\nConstruct a version handle.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `document` | [`Document`](../../document/classes/Document.md) |\n| `id` | `number` |\n\n#### Returns\n\n`DocumentVersion`\n"
},
{
"name": "email",
@@ -153,7 +153,7 @@
"name": "tasks",
"description": "Search, create, and update tasks.",
"overview": "<!-- src/entities/tasks/namespace/classes/TaskNamespace.md -->\n# Class: TaskNamespace\n\n## Constructors\n\n### Constructor\n\n> **new TaskNamespace**(`client`): `TaskNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`TaskNamespace`\n\n## Methods\n\n### byId()\n\n> **byId**(`id`): [`Task`](../../task/classes/Task.md)\n\nA handle to a task by document id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Task`](../../task/classes/Task.md)\n\n***\n\n### create()\n\n> **create**(`opts`): `Promise`\\<[`Task`](../../task/classes/Task.md)\\>\n\nCreate a task.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); `shareWithTeam?`: `boolean`; `team?`: [`Team`](../../../teams/team/classes/Team.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n| `opts.shareWithTeam?` | `boolean` |\n| `opts.team?` | [`Team`](../../../teams/team/classes/Team.md) |\n\n#### Returns\n\n`Promise`\\<[`Task`](../../task/classes/Task.md)\\>\n\n***\n\n### forPullRequest()\n\n> **forPullRequest**(`url`): `Promise`\\<[`Task`](../../task/classes/Task.md)[]\\>\n\nThe tasks the GitHub pull request at `url` references, oldest link first.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `url` | `string` |\n\n#### Returns\n\n`Promise`\\<[`Task`](../../task/classes/Task.md)[]\\>\n\n***\n\n### search()\n\n> **search**(`query`, `opts?`): `AsyncGenerator`\\<[`Task`](../../task/classes/Task.md)\\>\n\nSearch tasks by name and content, most relevant first, auto-paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `query` | `string` |\n| `opts?` | [`SearchOpts`](../../../search/interfaces/SearchOpts.md) |\n\n#### Returns\n\n`AsyncGenerator`\\<[`Task`](../../task/classes/Task.md)\\>\n",
- "documentation": "# Macro SDK: tasks\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/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md -->\n# Type Alias: BulkUpdateEntityPropertyOptionsResponse\n\n> **BulkUpdateEntityPropertyOptionsResponse** = \\{ `properties`: [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[]; \\}\n\nResponse for a bulk option update: each property's reconciled final ids.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-properties\"></a> `properties` | [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[] | The final option ids per updated property. |\n\n\n<!-- generated/properties/types.gen/type-aliases/DataType.md -->\n# Type Alias: DataType\n\n> **DataType** = `\"BOOLEAN\"` \\| `\"DATE\"` \\| `\"NUMBER\"` \\| `\"STRING\"` \\| `\"SELECT_NUMBER\"` \\| `\"SELECT_STRING\"` \\| `\"TAG\"` \\| `\"ENTITY\"` \\| `\"LINK\"`\n\nData type for property values, determining storage and validation.\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityProperty.md -->\n# Type Alias: EntityProperty\n\n> **EntityProperty** = \\{ `created_at`: `string`; `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; \\}\n\nAssignment of a property definition to a specific entity (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyOptionSelectionResponse.md -->\n# Type Alias: EntityPropertyOptionSelectionResponse\n\n> **EntityPropertyOptionSelectionResponse** = \\{ `option_ids`: `string`[]; `property_id`: `string`; \\}\n\nThe reconciled final option ids stored for one property after a bulk update.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-option_ids\"></a> `option_ids` | `string`[] | The final option ids the server persisted, in stored order. |\n| <a id=\"property-property_id\"></a> `property_id` | `string` | The property definition the options belong to. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md -->\n# Type Alias: EntityPropertyWithDefinition\n\n> **EntityPropertyWithDefinition** = \\{ `definition`: [`PropertyDefinition`](PropertyDefinition.md); `options?`: [`PropertyOption`](PropertyOption.md)[] \\| `null`; `property`: [`EntityProperty`](EntityProperty.md); `value?`: `null` \\| [`PropertyValue`](PropertyValue.md); \\}\n\nEntity property with its definition, value, and options (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-definition\"></a> `definition` | [`PropertyDefinition`](PropertyDefinition.md) |\n| <a id=\"property-options\"></a> `options?` | [`PropertyOption`](PropertyOption.md)[] \\| `null` |\n| <a id=\"property-property\"></a> `property` | [`EntityProperty`](EntityProperty.md) |\n| <a id=\"property-value\"></a> `value?` | `null` \\| [`PropertyValue`](PropertyValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityReference.md -->\n# Type Alias: EntityReference\n\n> **EntityReference** = \\{ `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `specific_message_id?`: `string` \\| `null`; \\}\n\nEntity reference for entity-type property values.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | - |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) | - |\n| <a id=\"property-specific_message_id\"></a> `specific_message_id?` | `string` \\| `null` | For CHANNEL, CHAT, THREAD entity types - optional specific message ID. This allows referencing a specific message within a thread/channel/chat. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityType.md -->\n# Type Alias: EntityType\n\n> **EntityType** = `\"CALENDAR_EVENT\"` \\| `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"CONTACT\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"TASK\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nType of entity that can be referenced by entity properties.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyDefinition.md -->\n# Type Alias: PropertyDefinition\n\n> **PropertyDefinition** = \\{ `created_at`: `string`; `data_type`: [`DataType`](DataType.md); `display_name`: `string`; `id`: `string`; `is_metadata`: `boolean`; `is_multi_select`: `boolean`; `is_system`: `boolean`; `owner`: [`PropertyOwner`](PropertyOwner.md); `specific_entity_type`: `null` \\| [`EntityType`](EntityType.md); `updated_at`: `string`; \\}\n\nProperty definition model (service representation).\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | - |\n| <a id=\"property-data_type\"></a> `data_type` | [`DataType`](DataType.md) | - |\n| <a id=\"property-display_name\"></a> `display_name` | `string` | - |\n| <a id=\"property-id\"></a> `id` | `string` | - |\n| <a id=\"property-is_metadata\"></a> `is_metadata` | `boolean` | Flag to indicate if this is a system-generated metadata property. Not stored in database - computed at service layer. |\n| <a id=\"property-is_multi_select\"></a> `is_multi_select` | `boolean` | - |\n| <a id=\"property-is_system\"></a> `is_system` | `boolean` | Flag to indicate if this is a system property (stored in DB). |\n| <a id=\"property-owner\"></a> `owner` | [`PropertyOwner`](PropertyOwner.md) | - |\n| <a id=\"property-specific_entity_type\"></a> `specific_entity_type` | `null` \\| [`EntityType`](EntityType.md) | - |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | - |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOption.md -->\n# Type Alias: PropertyOption\n\n> **PropertyOption** = \\{ `color`: `string` \\| `null`; `created_at`: `string`; `display_order`: `number`; `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; `value`: [`PropertyOptionValue`](PropertyOptionValue.md); \\}\n\nA selectable option for select-type properties (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-color\"></a> `color` | `string` \\| `null` |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-display_order\"></a> `display_order` | `number` |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n| <a id=\"property-value\"></a> `value` | [`PropertyOptionValue`](PropertyOptionValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOptionValue.md -->\n# Type Alias: PropertyOptionValue\n\n> **PropertyOptionValue** = \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\}\n\nThe value of a property option - either a string or a number.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"string\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"string\"` | - |\n| `value` | `string` | String value for SelectString properties |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"number\"` | - |\n| `value` | `number` | Number value for SelectNumber properties |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOwner.md -->\n# Type Alias: PropertyOwner\n\n> **PropertyOwner** = \\{ `scope`: `\"user\"`; `user_id`: `string`; \\} \\| \\{ `scope`: `\"team\"`; `team_id`: `string`; \\} \\| \\{ `database_id`: `string`; `scope`: `\"database\"`; \\} \\| \\{ `scope`: `\"system\"`; \\}\n\nDefines who owns a property - user-scoped, team-scoped, database-scoped, or system.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetEntityType.md -->\n# Type Alias: PropertyTargetEntityType\n\n> **PropertyTargetEntityType** = `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nCanonical type of an entity receiving properties.\n\nTasks are documents at API boundaries. `Task` intentionally does not exist\nhere; task classification is resolved by the properties domain from the\ndocument subtype.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetReference.md -->\n# Type Alias: PropertyTargetReference\n\n> **PropertyTargetReference** = \\{ `entity_id`: `string`; `entity_type`: [`PropertyTargetEntityType`](PropertyTargetEntityType.md); \\}\n\nCanonical reference to an entity receiving properties.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Entity identifier. |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`PropertyTargetEntityType`](PropertyTargetEntityType.md) | Canonical entity type. |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyValue.md -->\n# Type Alias: PropertyValue\n\n> **PropertyValue** = \\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"Number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"String\"`; `value`: `string`; \\} \\| \\{ `type`: `\"Date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\} \\| \\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\} \\| \\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\nProperty value (service representation).\n\nRepresents the actual value stored for an entity property.\nThis is serialized to/from JSONB in the database.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Boolean\"` | - |\n| `value` | `boolean` | Boolean value Serializes as: {\"type\": \"Boolean\", \"value\": true} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Number\"` | - |\n| `value` | `number` | Numeric value Serializes as: {\"type\": \"Number\", \"value\": 42.5} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"String\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"String\"` | - |\n| `value` | `string` | String value Serializes as: {\"type\": \"String\", \"value\": \"text\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Date\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Date\"` | - |\n| `value` | `string` | Date/timestamp value Serializes as: {\"type\": \"Date\", \"value\": \"2025-01-01T00:00:00Z\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"SelectOption\"` | - |\n| `value` | `string`[] | Select option(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"SelectOption\", \"value\": [\"uuid\"]} (length 0 or 1) Multi-select: {\"type\": \"SelectOption\", \"value\": [\"uuid1\", \"uuid2\", ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"EntityReference\"` | - |\n| `value` | [`EntityReference`](EntityReference.md)[] | Entity reference(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"EntityReference\", \"value\": [{...}]} (length 0 or 1) Multi-select: {\"type\": \"EntityReference\", \"value\": [{...}, {...}, ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Link\"` | - |\n| `value` | `string`[] | Link value(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"Link\", \"value\": [\"https://example.com\"]} (length 0 or 1) Multi-select: {\"type\": \"Link\", \"value\": [\"https://example.com\", \"https://other.com\"]} (length 0+) |\n\n\n<!-- generated/properties/types.gen/type-aliases/SetPropertyValue.md -->\n# Type Alias: SetPropertyValue\n\n> **SetPropertyValue** = \\{ `type`: `\"boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `option_id`: `string`; `type`: `\"select_option\"`; \\} \\| \\{ `option_ids`: `string`[]; `type`: `\"multi_select_option\"`; \\} \\| \\{ `reference`: [`EntityReference`](EntityReference.md); `type`: `\"entity_reference\"`; \\} \\| \\{ `references`: [`EntityReference`](EntityReference.md)[]; `type`: `\"multi_entity_reference\"`; \\} \\| \\{ `type`: `\"link\"`; `url`: `string`; \\} \\| \\{ `type`: `\"multi_link\"`; `urls`: `string`[]; \\}\n\nType-safe enum for setting entity property values - provides compile-time validation.\n\n\n<!-- generated/storage/types.gen/type-aliases/AccessLevel.md -->\n# Type Alias: AccessLevel\n\n> **AccessLevel** = `\"view\"` \\| `\"comment\"` \\| `\"edit\"` \\| `\"owner\"`\n\nOrdered from least to most access top -> bottom\n\n\n<!-- generated/storage/types.gen/type-aliases/BomPart.md -->\n# Type Alias: BomPart\n\n> **BomPart** = \\{ `id`: `string`; `path`: `string`; `sha`: `string`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `string` | The uuid of the bom part |\n| <a id=\"property-path\"></a> `path` | `string` | The file path of the bom part content |\n| <a id=\"property-sha\"></a> `sha` | `string` | The sha of the bom part content There is an index on sha for more performant queries based on it. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ChannelSharePermission.md -->\n# Type Alias: ChannelSharePermission\n\n> **ChannelSharePermission** = \\{ `access_level`: [`AccessLevel`](AccessLevel.md); `channel_id`: `string`; \\}\n\nThe channel share permission\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-access_level\"></a> `access_level` | [`AccessLevel`](AccessLevel.md) | The access level for the channel |\n| <a id=\"property-channel_id\"></a> `channel_id` | `string` | The channel id |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentContent.md -->\n# Type Alias: DocumentContent\n\n> **DocumentContent** = \\{ `location?`: `null` \\| [`DocumentContentLocation`](DocumentContentLocation.md); `state`: [`DocumentContentState`](DocumentContentState.md); \\}\n\nAPI-visible content lifecycle and location metadata.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-location\"></a> `location?` | `null` \\| [`DocumentContentLocation`](DocumentContentLocation.md) | - |\n| <a id=\"property-state\"></a> `state` | [`DocumentContentState`](DocumentContentState.md) | The current lifecycle state of the content. |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentContentLocation.md -->\n# Type Alias: DocumentContentLocation\n\n> **DocumentContentLocation** = `\"object_storage\"` \\| `\"sync_service\"` \\| `\"docx_bom_parts\"` \\| `\"converted_pdf\"` \\| `\"unknown\"`\n\nWhere document content is, or is expected to be, read from.\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentContentState.md -->\n# Type Alias: DocumentContentState\n\n> **DocumentContentState** = `\"unknown\"` \\| `\"pending\"` \\| `\"ready\"`\n\nAPI-visible content lifecycle state derived from current document metadata.\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentMetadata.md -->\n# Type Alias: DocumentMetadata\n\n> **DocumentMetadata** = \\{ `branchedFromId?`: `string` \\| `null`; `branchedFromVersionId?`: `number` \\| `null`; `createdAt?`: `string` \\| `null`; `deletedAt?`: `string` \\| `null`; `documentBom?`: [`BomPart`](BomPart.md)[] \\| `null`; `documentFamilyId?`: `number` \\| `null`; `documentId`: `string`; `documentName`: `string`; `documentVersionId`: `number`; `fileType?`: `string` \\| `null`; `modificationData?`: `unknown`; `owner`: `string`; `projectId?`: `string` \\| `null`; `projectName?`: `string` \\| `null`; `sha?`: `string` \\| `null`; `subType?`: `null` \\| [`DocumentSubType`](DocumentSubType.md); `updatedAt?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-branchedfromid\"></a> `branchedFromId?` | `string` \\| `null` | The id of the document this document branched from |\n| <a id=\"property-branchedfromversionid\"></a> `branchedFromVersionId?` | `number` \\| `null` | The id of the version this document branched from This could be either DocumentInstance or DocumentBom id depending on the file type |\n| <a id=\"property-createdat\"></a> `createdAt?` | `string` \\| `null` | The time the document was created |\n| <a id=\"property-deletedat\"></a> `deletedAt?` | `string` \\| `null` | The time the document was deleted |\n| <a id=\"property-documentbom\"></a> `documentBom?` | [`BomPart`](BomPart.md)[] \\| `null` | If the document is a DOCX document and unzipped, the document_bom will be present |\n| <a id=\"property-documentfamilyid\"></a> `documentFamilyId?` | `number` \\| `null` | The id of the document family this document belongs to |\n| <a id=\"property-documentid\"></a> `documentId` | `string` | The document id |\n| <a id=\"property-documentname\"></a> `documentName` | `string` | The name of the document |\n| <a id=\"property-documentversionid\"></a> `documentVersionId` | `number` | The version of the document This could be the document_instance_id or document_bom_id depending on the file type |\n| <a id=\"property-filetype\"></a> `fileType?` | `string` \\| `null` | The file type of the document (file extension) |\n| <a id=\"property-modificationdata\"></a> `modificationData?` | `unknown` | The modification data for the document instance. This is only used for PDF documents. |\n| <a id=\"property-owner\"></a> `owner` | `string` | The owner of the document |\n| <a id=\"property-projectid\"></a> `projectId?` | `string` \\| `null` | The id of the project that this document belongs to |\n| <a id=\"property-projectname\"></a> `projectName?` | `string` \\| `null` | The name of the project that this document belongs to |\n| <a id=\"property-sha\"></a> `sha?` | `string` \\| `null` | If the document is a PDF, this is the SHA of the pdf If the document is a DOCX, this will not be present |\n| <a id=\"property-subtype\"></a> `subType?` | `null` \\| [`DocumentSubType`](DocumentSubType.md) | - |\n| <a id=\"property-updatedat\"></a> `updatedAt?` | `string` \\| `null` | The time the document instance / document BOM was updated |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentMetadataWithContent.md -->\n# Type Alias: DocumentMetadataWithContent\n\n> **DocumentMetadataWithContent** = [`DocumentMetadata`](DocumentMetadata.md) & \\{ `content`: [`DocumentContent`](DocumentContent.md); `teamId?`: `string` \\| `null`; `teamTaskId?`: `number` \\| `null`; \\}\n\nFull document metadata plus content lifecycle metadata.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `content` | [`DocumentContent`](DocumentContent.md) | Content lifecycle and location metadata. |\n| `teamId?` | `string` \\| `null` | The team this task number is scoped to, for task documents. |\n| `teamTaskId?` | `number` \\| `null` | The task number assigned within the team, for task documents. |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentResponseMetadata.md -->\n# Type Alias: DocumentResponseMetadata\n\n> **DocumentResponseMetadata** = \\{ `branchedFromId?`: `string` \\| `null`; `branchedFromVersionId?`: `number` \\| `null`; `createdAt?`: `string` \\| `null`; `documentBom?`: [`BomPart`](BomPart.md)[] \\| `null`; `documentFamilyId?`: `number` \\| `null`; `documentId`: `string`; `documentName`: `string`; `documentVersionId`: `number`; `fileType?`: `string` \\| `null`; `modificationData?`: `unknown`; `owner`: `string`; `sha?`: `string` \\| `null`; `subType?`: `null` \\| [`DocumentSubType`](DocumentSubType.md); `updatedAt?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-branchedfromid\"></a> `branchedFromId?` | `string` \\| `null` | The id of the document this document branched from |\n| <a id=\"property-branchedfromversionid\"></a> `branchedFromVersionId?` | `number` \\| `null` | The id of the version this document branched from This could be either DocumentInstance or DocumentBom id depending on the file type |\n| <a id=\"property-createdat\"></a> `createdAt?` | `string` \\| `null` | The time the document was created |\n| <a id=\"property-documentbom\"></a> `documentBom?` | [`BomPart`](BomPart.md)[] \\| `null` | If the document is a DOCX document, the document_bom will be present |\n| <a id=\"property-documentfamilyid\"></a> `documentFamilyId?` | `number` \\| `null` | The id of the document family this document belongs to |\n| <a id=\"property-documentid\"></a> `documentId` | `string` | The document id |\n| <a id=\"property-documentname\"></a> `documentName` | `string` | The name of the document |\n| <a id=\"property-documentversionid\"></a> `documentVersionId` | `number` | The version of the document This could be the document_instance_id or document_bom_id depending on the file type |\n| <a id=\"property-filetype\"></a> `fileType?` | `string` \\| `null` | The file type of the document |\n| <a id=\"property-modificationdata\"></a> `modificationData?` | `unknown` | The modification data for the document instance. This is only used for PDF documents. |\n| <a id=\"property-owner\"></a> `owner` | `string` | The owner of the document |\n| <a id=\"property-sha\"></a> `sha?` | `string` \\| `null` | If the document is a PDF, this is the SHA of the pdf If the document is a DOCX, this will not be present |\n| <a id=\"property-subtype\"></a> `subType?` | `null` \\| [`DocumentSubType`](DocumentSubType.md) | - |\n| <a id=\"property-updatedat\"></a> `updatedAt?` | `string` \\| `null` | The time the document instance / document BOM was updated |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentSubType.md -->\n# Type Alias: DocumentSubType\n\n> **DocumentSubType** = `\"task\"` \\| `\"snippet\"` \\| `\"skill\"` \\| `\"initiative_description\"`\n\nThe document sub type enum represents all values of document sub types.\nThese values should match the `document_sub_type_value` table in macrodb.\n\nWire, database, and `Display` spellings are all `snake_case` so a\nmulti-word variant serializes identically in every system.\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentTeamShareResponse.md -->\n# Type Alias: DocumentTeamShareResponse\n\n> **DocumentTeamShareResponse** = \\{ `sharedWithTeam`: `boolean`; `teamId?`: `string` \\| `null`; \\}\n\nThe team-share state of a document. The team is resolved from the document\nowner's team membership.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-sharedwithteam\"></a> `sharedWithTeam` | `boolean` | Whether explicit team sharing is enabled; inherited team access does not count. |\n| <a id=\"property-teamid\"></a> `teamId?` | `string` \\| `null` | The owner's team the document is (or would be) shared with. `None` when the owner does not belong to a team. |\n\n\n<!-- generated/storage/types.gen/type-aliases/EntityPermission.md -->\n# Type Alias: EntityPermission\n\n> **EntityPermission** = \\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\} \\| \\{ `type`: `\"channel_view_only\"`; \\} \\| \\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\} \\| \\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\nA user's permission for an entity, discriminated by entity kind.\n\nItems (documents, chats, projects, threads) use access levels.\nChannels use view-only permission or participant roles.\n\n## Union Members\n\n### Type Literal\n\n\\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `access_level` | [`AccessLevel`](AccessLevel.md) | The access level the user has. |\n| `type` | `\"access_level\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"channel_view_only\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`ParticipantRole`](ParticipantRole.md) | The role the user has in the channel. |\n| `type` | `\"channel_role\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`TeamRole`](TeamRole.md) | The role the user has in the team. |\n| `type` | `\"team_role\"` | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/GithubPullRequest.md -->\n# Type Alias: GithubPullRequest\n\n> **GithubPullRequest** = \\{ `additions?`: `number` \\| `null`; `checks?`: [`GithubPullRequestCheckRun`](GithubPullRequestCheckRun.md)[] \\| `null`; `comments?`: [`GithubPullRequestComment`](GithubPullRequestComment.md)[] \\| `null`; `deletions?`: `number` \\| `null`; `displayName`: `string`; `foreignEntityId?`: `string` \\| `null`; `githubKey`: `string`; `name?`: `string` \\| `null`; `number`: `number`; `owner`: `string`; `repo`: `string`; `status?`: `string` \\| `null`; `url`: `string`; \\}\n\nDisplay-ready data for a GitHub pull request associated with a task.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-additions\"></a> `additions?` | `number` \\| `null` | The number of added lines in the pull request, when enrichment data is available. |\n| <a id=\"property-checks\"></a> `checks?` | [`GithubPullRequestCheckRun`](GithubPullRequestCheckRun.md)[] \\| `null` | Check runs collected from the pull request head commit, when enrichment data is available. |\n| <a id=\"property-comments\"></a> `comments?` | [`GithubPullRequestComment`](GithubPullRequestComment.md)[] \\| `null` | Comments collected from the pull request, when enrichment data is available. |\n| <a id=\"property-deletions\"></a> `deletions?` | `number` \\| `null` | The number of deleted lines in the pull request, when enrichment data is available. |\n| <a id=\"property-displayname\"></a> `displayName` | `string` | A compact label suitable for display in the UI. |\n| <a id=\"property-foreignentityid\"></a> `foreignEntityId?` | `string` \\| `null` | The internal `foreign_entity.id` UUID for the GitHub pull request row. |\n| <a id=\"property-githubkey\"></a> `githubKey` | `string` | The stored GitHub association key, in `owner/repo/pull/number` format. |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | The GitHub pull request title, when enrichment data is available. |\n| <a id=\"property-number\"></a> `number` | `number` | The GitHub pull request number. |\n| <a id=\"property-owner\"></a> `owner` | `string` | The GitHub repository owner or organization. |\n| <a id=\"property-repo\"></a> `repo` | `string` | The GitHub repository name. |\n| <a id=\"property-status\"></a> `status?` | `string` \\| `null` | The GitHub pull request status, when enrichment data is available. |\n| <a id=\"property-url\"></a> `url` | `string` | The public GitHub URL for the pull request. |\n\n\n<!-- generated/storage/types.gen/type-aliases/GithubPullRequestCheckRun.md -->\n# Type Alias: GithubPullRequestCheckRun\n\n> **GithubPullRequestCheckRun** = \\{ `completedAt?`: `string` \\| `null`; `conclusion?`: `string` \\| `null`; `id`: `number`; `name`: `string`; `startedAt?`: `string` \\| `null`; `status`: `string`; `url?`: `string` \\| `null`; \\}\n\nA check run associated with a GitHub pull request.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-completedat\"></a> `completedAt?` | `string` \\| `null` | When the check run completed, when available. |\n| <a id=\"property-conclusion\"></a> `conclusion?` | `string` \\| `null` | The raw GitHub check run conclusion, when the run has completed. |\n| <a id=\"property-id\"></a> `id` | `number` | The unique GitHub identifier for the check run. |\n| <a id=\"property-name\"></a> `name` | `string` | The check run name. |\n| <a id=\"property-startedat\"></a> `startedAt?` | `string` \\| `null` | When the check run started, when available. |\n| <a id=\"property-status\"></a> `status` | `string` | The raw GitHub check run status. |\n| <a id=\"property-url\"></a> `url?` | `string` \\| `null` | The public GitHub URL for the check run, when available. |\n\n\n<!-- generated/storage/types.gen/type-aliases/GithubPullRequestComment.md -->\n# Type Alias: GithubPullRequestComment\n\n> **GithubPullRequestComment** = \\{ `authorAssociation?`: `string` \\| `null`; `authorId?`: `number` \\| `null`; `authorLogin?`: `string` \\| `null`; `body`: `string`; `createdAt?`: `string` \\| `null`; `id`: `number`; `inReplyToId?`: `number` \\| `null`; `line?`: `number` \\| `null`; `originalLine?`: `number` \\| `null`; `path?`: `string` \\| `null`; `pullRequestReviewId?`: `number` \\| `null`; `source`: `string`; `updatedAt?`: `string` \\| `null`; `url?`: `string` \\| `null`; \\}\n\nA comment associated with a GitHub pull request.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-authorassociation\"></a> `authorAssociation?` | `string` \\| `null` | GitHub's relationship label for the author, when available. |\n| <a id=\"property-authorid\"></a> `authorId?` | `number` \\| `null` | The stable numeric GitHub user id for the comment author, when available. |\n| <a id=\"property-authorlogin\"></a> `authorLogin?` | `string` \\| `null` | The GitHub login for the comment author, when available. |\n| <a id=\"property-body\"></a> `body` | `string` | The comment or review body text. |\n| <a id=\"property-createdat\"></a> `createdAt?` | `string` \\| `null` | When the comment was created or the review was submitted. |\n| <a id=\"property-id\"></a> `id` | `number` | The unique GitHub identifier for the comment or review. |\n| <a id=\"property-inreplytoid\"></a> `inReplyToId?` | `number` \\| `null` | The id of the comment this one replies to, when it is part of a review thread. Only ever present on `review_comment` sources. |\n| <a id=\"property-line\"></a> `line?` | `number` \\| `null` | The line in the current diff the comment is anchored to. Cleared by GitHub when later commits outdate the comment's diff. |\n| <a id=\"property-originalline\"></a> `originalLine?` | `number` \\| `null` | The line the comment was originally anchored to, kept even when the diff has since changed. |\n| <a id=\"property-path\"></a> `path?` | `string` \\| `null` | The repository-relative file path the review comment is anchored to. Only ever present on `review_comment` sources. |\n| <a id=\"property-pullrequestreviewid\"></a> `pullRequestReviewId?` | `number` \\| `null` | The id of the pull request review this comment was submitted with. Only ever present on `review_comment` sources. |\n| <a id=\"property-source\"></a> `source` | `string` | The GitHub source for the comment, such as `issue_comment` or `review_comment`. |\n| <a id=\"property-updatedat\"></a> `updatedAt?` | `string` \\| `null` | When the comment or review was last updated. |\n| <a id=\"property-url\"></a> `url?` | `string` \\| `null` | The public GitHub URL for the comment or review, when available. |\n\n\n<!-- generated/storage/types.gen/type-aliases/HighlightType.md -->\n# Type Alias: HighlightType\n\n> **HighlightType** = `1` \\| `2` \\| `3`\n\n\n<!-- generated/storage/types.gen/type-aliases/LinkShare.md -->\n# Type Alias: LinkShare\n\n> **LinkShare** = `\"PUBLIC\"` \\| `\"TEAM\"`\n\nDefines who can access an item through its share link.\n\n\n<!-- generated/storage/types.gen/type-aliases/MessageCursor.md -->\n# Type Alias: MessageCursor\n\n> **MessageCursor** = \\{ `created_at`: `string`; `id`: `string`; \\}\n\nCursor for a chronological parent timeline.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Last message creation time or activity occurrence time. |\n| <a id=\"property-id\"></a> `id` | `string` | Last entry UUID, used to break timestamp ties across both sources. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ParticipantRole.md -->\n# Type Alias: ParticipantRole\n\n> **ParticipantRole** = `\"owner\"` \\| `\"admin\"` \\| `\"member\"`\n\nThe role a user has within a channel.\n\n\n<!-- generated/storage/types.gen/type-aliases/PdfHighlightAnchorRequest.md -->\n# Type Alias: PdfHighlightAnchorRequest\n\n> **PdfHighlightAnchorRequest** = \\{ `alpha`: `number`; `blue`: `number`; `green`: `number`; `highlightRects`: [`PdfHighlightRectAnchorRequest`](PdfHighlightRectAnchorRequest.md)[]; `highlightType`: [`HighlightType`](HighlightType.md); `page`: `number`; `pageViewportHeight`: `number`; `pageViewportWidth`: `number`; `red`: `number`; `text`: `string`; `uuid?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-alpha\"></a> `alpha` | `number` |\n| <a id=\"property-blue\"></a> `blue` | `number` |\n| <a id=\"property-green\"></a> `green` | `number` |\n| <a id=\"property-highlightrects\"></a> `highlightRects` | [`PdfHighlightRectAnchorRequest`](PdfHighlightRectAnchorRequest.md)[] |\n| <a id=\"property-highlighttype\"></a> `highlightType` | [`HighlightType`](HighlightType.md) |\n| <a id=\"property-page\"></a> `page` | `number` |\n| <a id=\"property-pageviewportheight\"></a> `pageViewportHeight` | `number` |\n| <a id=\"property-pageviewportwidth\"></a> `pageViewportWidth` | `number` |\n| <a id=\"property-red\"></a> `red` | `number` |\n| <a id=\"property-text\"></a> `text` | `string` |\n| <a id=\"property-uuid\"></a> `uuid?` | `string` \\| `null` |\n\n\n<!-- generated/storage/types.gen/type-aliases/PdfHighlightRectAnchorRequest.md -->\n# Type Alias: PdfHighlightRectAnchorRequest\n\n> **PdfHighlightRectAnchorRequest** = \\{ `height`: `number`; `left`: `number`; `top`: `number`; `width`: `number`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-height\"></a> `height` | `number` |\n| <a id=\"property-left\"></a> `left` | `number` |\n| <a id=\"property-top\"></a> `top` | `number` |\n| <a id=\"property-width\"></a> `width` | `number` |\n\n\n<!-- generated/storage/types.gen/type-aliases/PreSaveDocumentResponseData.md -->\n# Type Alias: PreSaveDocumentResponseData\n\n> **PreSaveDocumentResponseData** = \\{ `presignedUrls`: [`PresignedUrl`](PresignedUrl.md)[]; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-presignedurls\"></a> `presignedUrls` | [`PresignedUrl`](PresignedUrl.md)[] | Contains any presigned urls you need to upload specific bom parts with. |\n\n\n<!-- generated/storage/types.gen/type-aliases/PresignedUrl.md -->\n# Type Alias: PresignedUrl\n\n> **PresignedUrl** = \\{ `presignedUrl`: `string`; `sha`: `string`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-presignedurl\"></a> `presignedUrl` | `string` | The presigned url used to upload the sha |\n| <a id=\"property-sha\"></a> `sha` | `string` | The sha of the item |\n\n\n<!-- generated/storage/types.gen/type-aliases/SaveBomPart.md -->\n# Type Alias: SaveBomPart\n\n> **SaveBomPart** = \\{ `path`: `string`; `sha`: `string`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-path\"></a> `path` | `string` | The file path of the bom part content |\n| <a id=\"property-sha\"></a> `sha` | `string` | The sha of the bom part content There is an index on sha for more performant queries based on it. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SaveDocumentRequest.md -->\n# Type Alias: SaveDocumentRequest\n\n> **SaveDocumentRequest** = \\{ `modificationData?`: `unknown`; `newBom?`: [`SaveBomPart`](SaveBomPart.md)[] \\| `null`; `sha?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-modificationdata\"></a> `modificationData?` | `unknown` | The modification data for the document instance. Used to store highlights and other overlays onto a static file |\n| <a id=\"property-newbom\"></a> `newBom?` | [`SaveBomPart`](SaveBomPart.md)[] \\| `null` | **DOCX ONLY** The updated BOM for the document. Containing the file path and the sha. |\n| <a id=\"property-sha\"></a> `sha?` | `string` \\| `null` | The sha of the new document. This is used to generate a presigned url to upload the new document content to s3. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md -->\n# Type Alias: SaveDocumentResponseData\n\n> **SaveDocumentResponseData** = \\{ `documentMetadata`: [`DocumentResponseMetadata`](DocumentResponseMetadata.md); `presignedUrl?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-documentmetadata\"></a> `documentMetadata` | [`DocumentResponseMetadata`](DocumentResponseMetadata.md) | The updated document metadata |\n| <a id=\"property-presignedurl\"></a> `presignedUrl?` | `string` \\| `null` | If the document is an editable file, we provide a presigned url to save the updated file to. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SharePermissionV2.md -->\n# Type Alias: SharePermissionV2\n\n> **SharePermissionV2** = \\{ `channelSharePermissions?`: [`ChannelSharePermission`](ChannelSharePermission.md)[] \\| `null`; `id`: `string`; `linkShare?`: `null` \\| [`LinkShare`](LinkShare.md); `linkShareAccessLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); `owner`: `string`; `teamShareAccessLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channelsharepermissions\"></a> `channelSharePermissions?` | [`ChannelSharePermission`](ChannelSharePermission.md)[] \\| `null` | The channel share permissions for the item |\n| <a id=\"property-id\"></a> `id` | `string` | The share permission id |\n| <a id=\"property-linkshare\"></a> `linkShare?` | `null` \\| [`LinkShare`](LinkShare.md) | - |\n| <a id=\"property-linkshareaccesslevel\"></a> `linkShareAccessLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n| <a id=\"property-owner\"></a> `owner` | `string` | The owner of the item |\n| <a id=\"property-teamshareaccesslevel\"></a> `teamShareAccessLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/TeamRole.md -->\n# Type Alias: TeamRole\n\n> **TeamRole** = `\"member\"` \\| `\"admin\"` \\| `\"owner\"`\n\nThe role a user has within a team.\n\nOrdered least to most privileged so comparisons reflect access strength.\n\n\n<!-- src/entities/tasks/namespace/classes/TaskNamespace.md -->\n# Class: TaskNamespace\n\n## Constructors\n\n### Constructor\n\n> **new TaskNamespace**(`client`): `TaskNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`TaskNamespace`\n\n## Methods\n\n### byId()\n\n> **byId**(`id`): [`Task`](../../task/classes/Task.md)\n\nA handle to a task by document id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Task`](../../task/classes/Task.md)\n\n***\n\n### create()\n\n> **create**(`opts`): `Promise`\\<[`Task`](../../task/classes/Task.md)\\>\n\nCreate a task.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); `shareWithTeam?`: `boolean`; `team?`: [`Team`](../../../teams/team/classes/Team.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n| `opts.shareWithTeam?` | `boolean` |\n| `opts.team?` | [`Team`](../../../teams/team/classes/Team.md) |\n\n#### Returns\n\n`Promise`\\<[`Task`](../../task/classes/Task.md)\\>\n\n***\n\n### forPullRequest()\n\n> **forPullRequest**(`url`): `Promise`\\<[`Task`](../../task/classes/Task.md)[]\\>\n\nThe tasks the GitHub pull request at `url` references, oldest link first.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `url` | `string` |\n\n#### Returns\n\n`Promise`\\<[`Task`](../../task/classes/Task.md)[]\\>\n\n***\n\n### search()\n\n> **search**(`query`, `opts?`): `AsyncGenerator`\\<[`Task`](../../task/classes/Task.md)\\>\n\nSearch tasks by name and content, most relevant first, auto-paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `query` | `string` |\n| `opts?` | [`SearchOpts`](../../../search/interfaces/SearchOpts.md) |\n\n#### Returns\n\n`AsyncGenerator`\\<[`Task`](../../task/classes/Task.md)\\>\n\n\n<!-- src/entities/tasks/task/classes/Task.md -->\n# Class: Task\n\nA Macro task: a document with sub-type `task`. Inherits the full document\nsurface ([Document.rename](../../../documents/document/classes/Document.md#rename), move, delete, restore, content, events)\nand adds task-specific state.\n\n## Extends\n\n- [`Document`](../../../documents/document/classes/Document.md)\n\n## Properties\n\n| Property | Modifier | Type | Default value | Description | Overrides | Inherited from |\n| ------ | ------ | ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-access\"></a> `access` | `readonly` | [`EntityAccess`](../../../sharing/access/classes/EntityAccess.md) | `...` | Access requests and direct user grants. | - | [`Document`](../../../documents/document/classes/Document.md).[`access`](../../../documents/document/classes/Document.md#property-access) |\n| <a id=\"property-branchedfrom\"></a> `branchedFrom` | `readonly` | () => `Promise`\\<[`Document`](../../../documents/document/classes/Document.md) \\| `undefined`\\> | `...` | The document this one was branched from, if any. | - | [`Document`](../../../documents/document/classes/Document.md).[`branchedFrom`](../../../documents/document/classes/Document.md#property-branchedfrom) |\n| <a id=\"property-createdat\"></a> `createdAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | When the document was created. | - | [`Document`](../../../documents/document/classes/Document.md).[`createdAt`](../../../documents/document/classes/Document.md#property-createdat) |\n| <a id=\"property-deletedat\"></a> `deletedAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | When the document was deleted, if it has been. | - | [`Document`](../../../documents/document/classes/Document.md).[`deletedAt`](../../../documents/document/classes/Document.md#property-deletedat) |\n| <a id=\"property-entitytype\"></a> `entityType` | `readonly` | `\"document\"` | `'document'` | Favorites identify documents as `document`. | - | [`Document`](../../../documents/document/classes/Document.md).[`entityType`](../../../documents/document/classes/Document.md#property-entitytype) |\n| <a id=\"property-filetype\"></a> `fileType` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | The document's file type (e.g. `md`, `pdf`, `docx`). | - | [`Document`](../../../documents/document/classes/Document.md).[`fileType`](../../../documents/document/classes/Document.md#property-filetype) |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | `undefined` | - | - | [`Document`](../../../documents/document/classes/Document.md).[`id`](../../../documents/document/classes/Document.md#property-id) |\n| <a id=\"property-name\"></a> `name` | `readonly` | () => `Promise`\\<`string`\\> | `...` | The document's display name. | - | [`Document`](../../../documents/document/classes/Document.md).[`name`](../../../documents/document/classes/Document.md#property-name) |\n| <a id=\"property-owner\"></a> `owner` | `readonly` | () => `Promise`\\<[`User`](../../../users/user/classes/User.md)\\> | `...` | The user who owns the document. | - | [`Document`](../../../documents/document/classes/Document.md).[`owner`](../../../documents/document/classes/Document.md#property-owner) |\n| <a id=\"property-project\"></a> `project` | `readonly` | () => `Promise`\\<[`Project`](../../../projects/project/classes/Project.md) \\| `undefined`\\> | `...` | The project this document belongs to, if any. | - | [`Document`](../../../documents/document/classes/Document.md).[`project`](../../../documents/document/classes/Document.md#property-project) |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | When the document was last updated. | - | [`Document`](../../../documents/document/classes/Document.md).[`updatedAt`](../../../documents/document/classes/Document.md#property-updatedat) |\n| <a id=\"property-search\"></a> `search` | `static` | (`client`, `query`, `searchOpts?`) => `AsyncGenerator`\\<`Task`\\> | `...` | Search tasks by name and content, most relevant first, auto-paginated. | [`Document`](../../../documents/document/classes/Document.md).[`search`](../../../documents/document/classes/Document.md#property-search) | - |\n\n## Methods\n\n### anchors()\n\n> **anchors**(): `Promise`\\<[`DocumentAnchor`](../../../documents/anchor/classes/DocumentAnchor.md)[]\\>\n\nPDF annotations in this document.\n\n#### Returns\n\n`Promise`\\<[`DocumentAnchor`](../../../documents/anchor/classes/DocumentAnchor.md)[]\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`anchors`](../../../documents/document/classes/Document.md#anchors)\n\n***\n\n### branchName()\n\n> **branchName**(): `Promise`\\<`string`\\>\n\nThe git branch name derived for the document (task documents).\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`branchName`](../../../documents/document/classes/Document.md#branchname)\n\n***\n\n### comment()\n\n> **comment**(`body`, `opts?`): `Promise`\\<[`Comment`](../../../documents/comment/classes/Comment.md)\\>\n\nAdd a comment. Starts a new unanchored thread, or replies to an existing\none when `threadId` (the thread's root comment id) is given.\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `body` | `string` \\| [`RichMessage`](../../../../mentions/interfaces/RichMessage.md) | Plain text, or a rich body composed with msg. |\n| `opts?` | \\{ `threadId?`: `string`; \\} | - |\n| `opts.threadId?` | `string` | - |\n\n#### Returns\n\n`Promise`\\<[`Comment`](../../../documents/comment/classes/Comment.md)\\>\n\nThe created comment.\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`comment`](../../../documents/document/classes/Document.md#comment)\n\n***\n\n### comments()\n\n> **comments**(): `Promise`\\<[`CommentThread`](../../../documents/document/interfaces/CommentThread.md)[]\\>\n\nThe document's live comment threads, each with its comments, newest thread first.\n\n#### Returns\n\n`Promise`\\<[`CommentThread`](../../../documents/document/interfaces/CommentThread.md)[]\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`comments`](../../../documents/document/classes/Document.md#comments)\n\n***\n\n### completed()\n\n> **completed**(): `Promise`\\<`boolean` \\| `undefined`\\>\n\nWhether the task is completed (its Status property is \"Completed\");\n`undefined` if the document is not a task.\n\n#### Returns\n\n`Promise`\\<`boolean` \\| `undefined`\\>\n\n***\n\n### content()\n\n> **content**(): `Promise`\\<`string`\\>\n\nCurrent Markdown for native documents, extracted text for PDF/Word,\nor raw file content for other formats. Native reads include live edits.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`content`](../../../documents/document/classes/Document.md#content)\n\n***\n\n### copy()\n\n> **copy**(`opts`): `Promise`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\nCopy the document under a new name, optionally from a specific version.\nReturns a handle to the new document.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `name`: `string`; `versionId?`: `number`; \\} |\n| `opts.name` | `string` |\n| `opts.versionId?` | `number` |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`copy`](../../../documents/document/classes/Document.md#copy)\n\n***\n\n### createHighlight()\n\n> **createHighlight**(`options`): `Promise`\\<[`DocumentAnchor`](../../../documents/anchor/classes/DocumentAnchor.md)\\>\n\nCreate a standalone PDF highlight.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | `Omit`\\<[`PdfHighlightAnchorRequest`](../../../../../generated/storage/types.gen/type-aliases/PdfHighlightAnchorRequest.md), `\"uuid\"`\\> |\n\n#### Returns\n\n`Promise`\\<[`DocumentAnchor`](../../../documents/anchor/classes/DocumentAnchor.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`createHighlight`](../../../documents/document/classes/Document.md#createhighlight)\n\n***\n\n### delete()\n\n> **delete**(`opts?`): `Promise`\\<`void`\\>\n\nDelete the document. Soft by default (reversible with [restore](../../../documents/document/classes/Document.md#restore));\npass `permanent: true` to delete irreversibly.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `permanent?`: `boolean`; \\} |\n| `opts.permanent?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`delete`](../../../documents/document/classes/Document.md#delete)\n\n***\n\n### deleteProperty()\n\n> **deleteProperty**(`assignment`): `Promise`\\<`void`\\>\n\nRemove a property from this entity, given its [properties](#properties) entry.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `assignment` | [`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`deleteProperty`](../../../documents/document/classes/Document.md#deleteproperty)\n\n***\n\n### favorite()\n\n> **favorite**(): `Promise`\\<`Task`\\>\n\nAdd this entity to the user's favorites. Returns this handle for chaining.\nPlain unwrap: favoriting alters the user's favorites collection, not this\nentity's own detail, so there's nothing cached to invalidate.\n\n#### Returns\n\n`Promise`\\<`Task`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`favorite`](../../../documents/document/classes/Document.md#favorite)\n\n***\n\n### githubPullRequests()\n\n> **githubPullRequests**(): `Promise`\\<[`GithubPullRequest`](../../../../../generated/storage/types.gen/type-aliases/GithubPullRequest.md)[]\\>\n\nGitHub pull requests associated with the document.\n\n#### Returns\n\n`Promise`\\<[`GithubPullRequest`](../../../../../generated/storage/types.gen/type-aliases/GithubPullRequest.md)[]\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`githubPullRequests`](../../../documents/document/classes/Document.md#githubpullrequests)\n\n***\n\n### meetingNotes()\n\n> **meetingNotes**(): `Promise`\\<\\{ `eventTitle`: `string`; `note`: [`CalendarNote`](../../../calendar/note/classes/CalendarNote.md); \\}[]\\>\n\nOwner-only meeting grants, including unavailable meetings. Unlink a returned note to revoke its meeting/team access.\n\n#### Returns\n\n`Promise`\\<\\{ `eventTitle`: `string`; `note`: [`CalendarNote`](../../../calendar/note/classes/CalendarNote.md); \\}[]\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`meetingNotes`](../../../documents/document/classes/Document.md#meetingnotes)\n\n***\n\n### messageThreadById()\n\n> **messageThreadById**(`id`): [`MessageThread`](../../../messages/thread/classes/MessageThread.md)\n\nA shared message thread scoped to this resource.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`MessageThread`](../../../messages/thread/classes/MessageThread.md)\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`messageThreadById`](../../../documents/document/classes/Document.md#messagethreadbyid)\n\n***\n\n### move()\n\n> **move**(`project`): `Promise`\\<`void`\\>\n\nMove the document into a project (or out of one, with `null`).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `project` | [`Project`](../../../projects/project/classes/Project.md) \\| `null` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`move`](../../../documents/document/classes/Document.md#move)\n\n***\n\n### permission()\n\n> **permission**(): `Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\nRead the caller's effective permission on this entity.\n\n#### Returns\n\n`Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`permission`](../../../documents/document/classes/Document.md#permission)\n\n***\n\n### permissionsToken()\n\n> **permissionsToken**(): `Promise`\\<`string`\\>\n\nMint a scoped permissions token.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`permissionsToken`](../../../documents/document/classes/Document.md#permissionstoken)\n\n***\n\n### prepareSave()\n\n> **prepareSave**(`parts`): `Promise`\\<[`PreSaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/PreSaveDocumentResponseData.md)\\>\n\nPrepare multipart content saving and return the service's upload instructions.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `parts` | [`SaveBomPart`](../../../../../generated/storage/types.gen/type-aliases/SaveBomPart.md)[] |\n\n#### Returns\n\n`Promise`\\<[`PreSaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/PreSaveDocumentResponseData.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`prepareSave`](../../../documents/document/classes/Document.md#preparesave)\n\n***\n\n### properties()\n\n> **properties**(`opts?`): `Promise`\\<[`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\nThe properties set on this entity, each with its definition, value, and options.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `includeMetadata?`: `boolean`; \\} |\n| `opts.includeMetadata?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<[`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`properties`](../../../documents/document/classes/Document.md#properties)\n\n***\n\n### propertyReference()\n\n> **propertyReference**(): [`PropertyTargetReference`](../../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\nThis entity's reference for bulk property operations.\n\n#### Returns\n\n[`PropertyTargetReference`](../../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`propertyReference`](../../../documents/document/classes/Document.md#propertyreference)\n\n***\n\n### rename()\n\n> **rename**(`name`): `Promise`\\<`void`\\>\n\nRename the document.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `name` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`rename`](../../../documents/document/classes/Document.md#rename)\n\n***\n\n### restore()\n\n> **restore**(): `Promise`\\<`void`\\>\n\nRestore a soft-deleted document.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`restore`](../../../documents/document/classes/Document.md#restore)\n\n***\n\n### save()\n\n> **save**(`options`): `Promise`\\<[`SaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md)\\>\n\nCommit uploaded content. Does not retry uncertain writes.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`SaveDocumentRequest`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentRequest.md) |\n\n#### Returns\n\n`Promise`\\<[`SaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`save`](../../../documents/document/classes/Document.md#save)\n\n***\n\n### setProperty()\n\n> **setProperty**(`property`, `value?`): `Promise`\\<`void`\\>\n\nSet a property value on this entity, or attach the property without a\nvalue when `value` is omitted.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `property` | [`PropertyDefinition`](../../../properties/property-definition/classes/PropertyDefinition.md) |\n| `value?` | [`SetPropertyValue`](../../../../../generated/properties/types.gen/type-aliases/SetPropertyValue.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`setProperty`](../../../documents/document/classes/Document.md#setproperty)\n\n***\n\n### setTeamShare()\n\n> **setTeamShare**(`shared`): `Promise`\\<`void`\\>\n\nShare the document with the owner's team, or unshare it.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `shared` | `boolean` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`setTeamShare`](../../../documents/document/classes/Document.md#setteamshare)\n\n***\n\n### sharePermissions()\n\n> **sharePermissions**(): `Promise`\\<[`SharePermissionV2`](../../../../../generated/storage/types.gen/type-aliases/SharePermissionV2.md)\\>\n\nSharing configuration.\n\n#### Returns\n\n`Promise`\\<[`SharePermissionV2`](../../../../../generated/storage/types.gen/type-aliases/SharePermissionV2.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`sharePermissions`](../../../documents/document/classes/Document.md#sharepermissions)\n\n***\n\n### shortId()\n\n> **shortId**(): `Promise`\\<`string`\\>\n\nThe document's short id (used in compact links and branch names).\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`shortId`](../../../documents/document/classes/Document.md#shortid)\n\n***\n\n### simpleSave()\n\n> **simpleSave**(): `Promise`\\<[`SaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md)\\>\n\nCommit a simple document save.\n\n#### Returns\n\n`Promise`\\<[`SaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`simpleSave`](../../../documents/document/classes/Document.md#simplesave)\n\n***\n\n### teamShare()\n\n> **teamShare**(): `Promise`\\<[`DocumentTeamShareResponse`](../../../../../generated/storage/types.gen/type-aliases/DocumentTeamShareResponse.md)\\>\n\nWhether the document is shared with the owner's team, and which team.\n\n#### Returns\n\n`Promise`\\<[`DocumentTeamShareResponse`](../../../../../generated/storage/types.gen/type-aliases/DocumentTeamShareResponse.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`teamShare`](../../../documents/document/classes/Document.md#teamshare)\n\n***\n\n### timelinePage()\n\n> **timelinePage**(`selection?`): `Promise`\\<\\{ `entries`: (\\{ `activity`: \\{ `action`: `string`; `actor`: [`User`](../../../users/user/classes/User.md); `actor_id`: `string`; `id`: `string`; `occurred_at`: `string`; `payload?`: `unknown`; \\}; `message?`: `undefined`; `type`: `\"activity\"`; \\} \\| \\{ `activity?`: `undefined`; `message`: [`Comment`](../../../documents/comment/classes/Comment.md); `type`: `\"message\"`; \\})[]; `nextCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; `previousCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; \\}\\>\n\nA mixed message and activity timeline page.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `selection?` | [`TimelineOptions`](../../../messages/thread/interfaces/TimelineOptions.md)\\<[`Comment`](../../../documents/comment/classes/Comment.md)\\> |\n\n#### Returns\n\n`Promise`\\<\\{ `entries`: (\\{ `activity`: \\{ `action`: `string`; `actor`: [`User`](../../../users/user/classes/User.md); `actor_id`: `string`; `id`: `string`; `occurred_at`: `string`; `payload?`: `unknown`; \\}; `message?`: `undefined`; `type`: `\"activity\"`; \\} \\| \\{ `activity?`: `undefined`; `message`: [`Comment`](../../../documents/comment/classes/Comment.md); `type`: `\"message\"`; \\})[]; `nextCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; `previousCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; \\}\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`timelinePage`](../../../documents/document/classes/Document.md#timelinepage)\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`DocumentMetadataWithContent`](../../../../../generated/storage/types.gen/type-aliases/DocumentMetadataWithContent.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`DocumentMetadataWithContent`](../../../../../generated/storage/types.gen/type-aliases/DocumentMetadataWithContent.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`DocumentMetadataWithContent`](../../../../../generated/storage/types.gen/type-aliases/DocumentMetadataWithContent.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`toJSON`](../../../documents/document/classes/Document.md#tojson)\n\n***\n\n### toMention()\n\n> **toMention**(): [`MentionPart`](../../../../mentions/interfaces/MentionPart.md)\n\n#### Returns\n\n[`MentionPart`](../../../../mentions/interfaces/MentionPart.md)\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`toMention`](../../../documents/document/classes/Document.md#tomention)\n\n***\n\n### unfavorite()\n\n> **unfavorite**(): `Promise`\\<`Task`\\>\n\nRemove this entity from the user's favorites. Returns this handle for chaining.\n\n#### Returns\n\n`Promise`\\<`Task`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`unfavorite`](../../../documents/document/classes/Document.md#unfavorite)\n\n***\n\n### updatePropertyOptions()\n\n> **updatePropertyOptions**(`changes`): `Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\nApply multi-select option deltas atomically across this entity's properties.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `changes` | [`PropertyOptionDelta`](../../../entity/interfaces/PropertyOptionDelta.md)[] |\n\n#### Returns\n\n`Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`updatePropertyOptions`](../../../documents/document/classes/Document.md#updatepropertyoptions)\n\n***\n\n### version()\n\n> **version**(`version`): [`DocumentVersion`](../../../documents/version/classes/DocumentVersion.md)\n\nA handle to an immutable version.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `version` | `number` |\n\n#### Returns\n\n[`DocumentVersion`](../../../documents/version/classes/DocumentVersion.md)\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`version`](../../../documents/document/classes/Document.md#version)\n\n***\n\n### webUrl()\n\n> **webUrl**(): `string`\n\nThe task's URL in the Macro web app.\n\n#### Returns\n\n`string`\n\n#### Overrides\n\n[`Document`](../../../documents/document/classes/Document.md).[`webUrl`](../../../documents/document/classes/Document.md#weburl)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `Task`\n\nA handle to a task by document id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`Task`\n\n#### Overrides\n\n[`Document`](../../../documents/document/classes/Document.md).[`byId`](../../../documents/document/classes/Document.md#byid)\n\n***\n\n### create()\n\n> `static` **create**(`client`, `opts`): `Promise`\\<`Task`\\>\n\nCreate a task. `team` scopes the team task number and may be omitted\nwhen the creator belongs to exactly one team; `shareWithTeam` defaults\nto true.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); `shareWithTeam?`: `boolean`; `team?`: [`Team`](../../../teams/team/classes/Team.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n| `opts.shareWithTeam?` | `boolean` |\n| `opts.team?` | [`Team`](../../../teams/team/classes/Team.md) |\n\n#### Returns\n\n`Promise`\\<`Task`\\>\n\n#### Overrides\n\n[`Document`](../../../documents/document/classes/Document.md).[`create`](../../../documents/document/classes/Document.md#create)\n\n***\n\n### createSkill()\n\n> `static` **createSkill**(`client`, `opts`): `Promise`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\nCreate a skill: a markdown document containing instructions that AI reads\nand follows when the skill is referenced in an AI input.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`createSkill`](../../../documents/document/classes/Document.md#createskill)\n\n***\n\n### createSnippet()\n\n> `static` **createSnippet**(`client`, `opts`): `Promise`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\nCreate a snippet: a reusable markdown document that can be inserted into\nany markdown area.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`createSnippet`](../../../documents/document/classes/Document.md#createsnippet)\n\n***\n\n### forPullRequest()\n\n> `static` **forPullRequest**(`client`, `url`): `Promise`\\<`Task`[]\\>\n\nThe tasks the GitHub pull request at `url` references (as `MACRO-<id>` in\nits text, branch, or comments), oldest link first. Empty when the caller\ncannot see the pull request; tasks the caller cannot open still appear.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `url` | `string` |\n\n#### Returns\n\n`Promise`\\<`Task`[]\\>\n\n***\n\n### recent()\n\n> `static` **recent**(`client`, `opts?`): `AsyncGenerator`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\nThe user's recent documents, most recent first, auto-paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts?` | \\{ `fileType?`: `string`; `pageSize?`: `number`; \\} |\n| `opts.fileType?` | `string` |\n| `opts.pageSize?` | `number` |\n\n#### Returns\n\n`AsyncGenerator`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`recent`](../../../documents/document/classes/Document.md#recent)\n\n***\n\n### recentlyDeleted()\n\n> `static` **recentlyDeleted**(`client`): `Promise`\\<[`Document`](../../../documents/document/classes/Document.md)[]\\>\n\nThe user's recently soft-deleted documents. The underlying endpoint also\nreturns deleted chats and projects; those are filtered out here.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../../documents/document/classes/Document.md)[]\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`recentlyDeleted`](../../../documents/document/classes/Document.md#recentlydeleted)\n"
+ "documentation": "# Macro SDK: tasks\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/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md -->\n# Type Alias: BulkUpdateEntityPropertyOptionsResponse\n\n> **BulkUpdateEntityPropertyOptionsResponse** = \\{ `properties`: [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[]; \\}\n\nResponse for a bulk option update: each property's reconciled final ids.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-properties\"></a> `properties` | [`EntityPropertyOptionSelectionResponse`](EntityPropertyOptionSelectionResponse.md)[] | The final option ids per updated property. |\n\n\n<!-- generated/properties/types.gen/type-aliases/DataType.md -->\n# Type Alias: DataType\n\n> **DataType** = `\"BOOLEAN\"` \\| `\"DATE\"` \\| `\"NUMBER\"` \\| `\"STRING\"` \\| `\"SELECT_NUMBER\"` \\| `\"SELECT_STRING\"` \\| `\"TAG\"` \\| `\"ENTITY\"` \\| `\"LINK\"`\n\nData type for property values, determining storage and validation.\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityProperty.md -->\n# Type Alias: EntityProperty\n\n> **EntityProperty** = \\{ `created_at`: `string`; `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; \\}\n\nAssignment of a property definition to a specific entity (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyOptionSelectionResponse.md -->\n# Type Alias: EntityPropertyOptionSelectionResponse\n\n> **EntityPropertyOptionSelectionResponse** = \\{ `option_ids`: `string`[]; `property_id`: `string`; \\}\n\nThe reconciled final option ids stored for one property after a bulk update.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-option_ids\"></a> `option_ids` | `string`[] | The final option ids the server persisted, in stored order. |\n| <a id=\"property-property_id\"></a> `property_id` | `string` | The property definition the options belong to. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md -->\n# Type Alias: EntityPropertyWithDefinition\n\n> **EntityPropertyWithDefinition** = \\{ `definition`: [`PropertyDefinition`](PropertyDefinition.md); `options?`: [`PropertyOption`](PropertyOption.md)[] \\| `null`; `property`: [`EntityProperty`](EntityProperty.md); `value?`: `null` \\| [`PropertyValue`](PropertyValue.md); \\}\n\nEntity property with its definition, value, and options (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-definition\"></a> `definition` | [`PropertyDefinition`](PropertyDefinition.md) |\n| <a id=\"property-options\"></a> `options?` | [`PropertyOption`](PropertyOption.md)[] \\| `null` |\n| <a id=\"property-property\"></a> `property` | [`EntityProperty`](EntityProperty.md) |\n| <a id=\"property-value\"></a> `value?` | `null` \\| [`PropertyValue`](PropertyValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityReference.md -->\n# Type Alias: EntityReference\n\n> **EntityReference** = \\{ `entity_id`: `string`; `entity_type`: [`EntityType`](EntityType.md); `specific_message_id?`: `string` \\| `null`; \\}\n\nEntity reference for entity-type property values.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | - |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`EntityType`](EntityType.md) | - |\n| <a id=\"property-specific_message_id\"></a> `specific_message_id?` | `string` \\| `null` | For CHANNEL, CHAT, THREAD entity types - optional specific message ID. This allows referencing a specific message within a thread/channel/chat. |\n\n\n<!-- generated/properties/types.gen/type-aliases/EntityType.md -->\n# Type Alias: EntityType\n\n> **EntityType** = `\"CALENDAR_EVENT\"` \\| `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"CONTACT\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"TASK\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nType of entity that can be referenced by entity properties.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyDefinition.md -->\n# Type Alias: PropertyDefinition\n\n> **PropertyDefinition** = \\{ `created_at`: `string`; `data_type`: [`DataType`](DataType.md); `display_name`: `string`; `id`: `string`; `is_metadata`: `boolean`; `is_multi_select`: `boolean`; `is_system`: `boolean`; `owner`: [`PropertyOwner`](PropertyOwner.md); `specific_entity_type`: `null` \\| [`EntityType`](EntityType.md); `updated_at`: `string`; \\}\n\nProperty definition model (service representation).\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | - |\n| <a id=\"property-data_type\"></a> `data_type` | [`DataType`](DataType.md) | - |\n| <a id=\"property-display_name\"></a> `display_name` | `string` | - |\n| <a id=\"property-id\"></a> `id` | `string` | - |\n| <a id=\"property-is_metadata\"></a> `is_metadata` | `boolean` | Flag to indicate if this is a system-generated metadata property. Not stored in database - computed at service layer. |\n| <a id=\"property-is_multi_select\"></a> `is_multi_select` | `boolean` | - |\n| <a id=\"property-is_system\"></a> `is_system` | `boolean` | Flag to indicate if this is a system property (stored in DB). |\n| <a id=\"property-owner\"></a> `owner` | [`PropertyOwner`](PropertyOwner.md) | - |\n| <a id=\"property-specific_entity_type\"></a> `specific_entity_type` | `null` \\| [`EntityType`](EntityType.md) | - |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` | - |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOption.md -->\n# Type Alias: PropertyOption\n\n> **PropertyOption** = \\{ `color`: `string` \\| `null`; `created_at`: `string`; `display_order`: `number`; `id`: `string`; `property_definition_id`: `string`; `updated_at`: `string`; `value`: [`PropertyOptionValue`](PropertyOptionValue.md); \\}\n\nA selectable option for select-type properties (service representation).\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-color\"></a> `color` | `string` \\| `null` |\n| <a id=\"property-created_at\"></a> `created_at` | `string` |\n| <a id=\"property-display_order\"></a> `display_order` | `number` |\n| <a id=\"property-id\"></a> `id` | `string` |\n| <a id=\"property-property_definition_id\"></a> `property_definition_id` | `string` |\n| <a id=\"property-updated_at\"></a> `updated_at` | `string` |\n| <a id=\"property-value\"></a> `value` | [`PropertyOptionValue`](PropertyOptionValue.md) |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOptionValue.md -->\n# Type Alias: PropertyOptionValue\n\n> **PropertyOptionValue** = \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\}\n\nThe value of a property option - either a string or a number.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"string\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"string\"` | - |\n| `value` | `string` | String value for SelectString properties |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"number\"` | - |\n| `value` | `number` | Number value for SelectNumber properties |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyOwner.md -->\n# Type Alias: PropertyOwner\n\n> **PropertyOwner** = \\{ `scope`: `\"user\"`; `user_id`: `string`; \\} \\| \\{ `scope`: `\"team\"`; `team_id`: `string`; \\} \\| \\{ `database_id`: `string`; `scope`: `\"database\"`; \\} \\| \\{ `scope`: `\"system\"`; \\}\n\nDefines who owns a property - user-scoped, team-scoped, database-scoped, or system.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetEntityType.md -->\n# Type Alias: PropertyTargetEntityType\n\n> **PropertyTargetEntityType** = `\"CALL_RECORD\"` \\| `\"CHANNEL\"` \\| `\"CHAT\"` \\| `\"COMPANY\"` \\| `\"DATABASE_ROW\"` \\| `\"DOCUMENT\"` \\| `\"INITIATIVE\"` \\| `\"PROJECT\"` \\| `\"THREAD\"` \\| `\"USER\"`\n\nCanonical type of an entity receiving properties.\n\nTasks are documents at API boundaries. `Task` intentionally does not exist\nhere; task classification is resolved by the properties domain from the\ndocument subtype.\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyTargetReference.md -->\n# Type Alias: PropertyTargetReference\n\n> **PropertyTargetReference** = \\{ `entity_id`: `string`; `entity_type`: [`PropertyTargetEntityType`](PropertyTargetEntityType.md); \\}\n\nCanonical reference to an entity receiving properties.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-entity_id\"></a> `entity_id` | `string` | Entity identifier. |\n| <a id=\"property-entity_type\"></a> `entity_type` | [`PropertyTargetEntityType`](PropertyTargetEntityType.md) | Canonical entity type. |\n\n\n<!-- generated/properties/types.gen/type-aliases/PropertyValue.md -->\n# Type Alias: PropertyValue\n\n> **PropertyValue** = \\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"Number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"String\"`; `value`: `string`; \\} \\| \\{ `type`: `\"Date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\} \\| \\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\} \\| \\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\nProperty value (service representation).\n\nRepresents the actual value stored for an entity property.\nThis is serialized to/from JSONB in the database.\n\n## Union Members\n\n### Type Literal\n\n\\{ `type`: `\"Boolean\"`; `value`: `boolean`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Boolean\"` | - |\n| `value` | `boolean` | Boolean value Serializes as: {\"type\": \"Boolean\", \"value\": true} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Number\"`; `value`: `number`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Number\"` | - |\n| `value` | `number` | Numeric value Serializes as: {\"type\": \"Number\", \"value\": 42.5} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"String\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"String\"` | - |\n| `value` | `string` | String value Serializes as: {\"type\": \"String\", \"value\": \"text\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Date\"`; `value`: `string`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Date\"` | - |\n| `value` | `string` | Date/timestamp value Serializes as: {\"type\": \"Date\", \"value\": \"2025-01-01T00:00:00Z\"} |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"SelectOption\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"SelectOption\"` | - |\n| `value` | `string`[] | Select option(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"SelectOption\", \"value\": [\"uuid\"]} (length 0 or 1) Multi-select: {\"type\": \"SelectOption\", \"value\": [\"uuid1\", \"uuid2\", ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"EntityReference\"`; `value`: [`EntityReference`](EntityReference.md)[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"EntityReference\"` | - |\n| `value` | [`EntityReference`](EntityReference.md)[] | Entity reference(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"EntityReference\", \"value\": [{...}]} (length 0 or 1) Multi-select: {\"type\": \"EntityReference\", \"value\": [{...}, {...}, ...]} (length 0+) |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"Link\"`; `value`: `string`[]; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `type` | `\"Link\"` | - |\n| `value` | `string`[] | Link value(s) - always an array (check is_multi_select to determine if single or multi) Single-select: {\"type\": \"Link\", \"value\": [\"https://example.com\"]} (length 0 or 1) Multi-select: {\"type\": \"Link\", \"value\": [\"https://example.com\", \"https://other.com\"]} (length 0+) |\n\n\n<!-- generated/properties/types.gen/type-aliases/SetPropertyValue.md -->\n# Type Alias: SetPropertyValue\n\n> **SetPropertyValue** = \\{ `type`: `\"boolean\"`; `value`: `boolean`; \\} \\| \\{ `type`: `\"date\"`; `value`: `string`; \\} \\| \\{ `type`: `\"number\"`; `value`: `number`; \\} \\| \\{ `type`: `\"string\"`; `value`: `string`; \\} \\| \\{ `option_id`: `string`; `type`: `\"select_option\"`; \\} \\| \\{ `option_ids`: `string`[]; `type`: `\"multi_select_option\"`; \\} \\| \\{ `reference`: [`EntityReference`](EntityReference.md); `type`: `\"entity_reference\"`; \\} \\| \\{ `references`: [`EntityReference`](EntityReference.md)[]; `type`: `\"multi_entity_reference\"`; \\} \\| \\{ `type`: `\"link\"`; `url`: `string`; \\} \\| \\{ `type`: `\"multi_link\"`; `urls`: `string`[]; \\}\n\nType-safe enum for setting entity property values - provides compile-time validation.\n\n\n<!-- generated/storage/types.gen/type-aliases/AccessLevel.md -->\n# Type Alias: AccessLevel\n\n> **AccessLevel** = `\"view\"` \\| `\"comment\"` \\| `\"edit\"` \\| `\"owner\"`\n\nOrdered from least to most access top -> bottom\n\n\n<!-- generated/storage/types.gen/type-aliases/BomPart.md -->\n# Type Alias: BomPart\n\n> **BomPart** = \\{ `id`: `string`; `path`: `string`; `sha`: `string`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `string` | The uuid of the bom part |\n| <a id=\"property-path\"></a> `path` | `string` | The file path of the bom part content |\n| <a id=\"property-sha\"></a> `sha` | `string` | The sha of the bom part content There is an index on sha for more performant queries based on it. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ChannelSharePermission.md -->\n# Type Alias: ChannelSharePermission\n\n> **ChannelSharePermission** = \\{ `access_level`: [`AccessLevel`](AccessLevel.md); `channel_id`: `string`; \\}\n\nThe channel share permission\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-access_level\"></a> `access_level` | [`AccessLevel`](AccessLevel.md) | The access level for the channel |\n| <a id=\"property-channel_id\"></a> `channel_id` | `string` | The channel id |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentContent.md -->\n# Type Alias: DocumentContent\n\n> **DocumentContent** = \\{ `location?`: `null` \\| [`DocumentContentLocation`](DocumentContentLocation.md); `state`: [`DocumentContentState`](DocumentContentState.md); \\}\n\nAPI-visible content lifecycle and location metadata.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-location\"></a> `location?` | `null` \\| [`DocumentContentLocation`](DocumentContentLocation.md) | - |\n| <a id=\"property-state\"></a> `state` | [`DocumentContentState`](DocumentContentState.md) | The current lifecycle state of the content. |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentContentLocation.md -->\n# Type Alias: DocumentContentLocation\n\n> **DocumentContentLocation** = `\"object_storage\"` \\| `\"sync_service\"` \\| `\"docx_bom_parts\"` \\| `\"converted_pdf\"` \\| `\"unknown\"`\n\nWhere document content is, or is expected to be, read from.\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentContentState.md -->\n# Type Alias: DocumentContentState\n\n> **DocumentContentState** = `\"unknown\"` \\| `\"pending\"` \\| `\"ready\"`\n\nAPI-visible content lifecycle state derived from current document metadata.\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentMetadata.md -->\n# Type Alias: DocumentMetadata\n\n> **DocumentMetadata** = \\{ `branchedFromId?`: `string` \\| `null`; `branchedFromVersionId?`: `number` \\| `null`; `createdAt?`: `string` \\| `null`; `deletedAt?`: `string` \\| `null`; `documentBom?`: [`BomPart`](BomPart.md)[] \\| `null`; `documentFamilyId?`: `number` \\| `null`; `documentId`: `string`; `documentName`: `string`; `documentVersionId`: `number`; `fileType?`: `string` \\| `null`; `modificationData?`: `unknown`; `owner`: `string`; `projectId?`: `string` \\| `null`; `projectName?`: `string` \\| `null`; `sha?`: `string` \\| `null`; `subType?`: `null` \\| [`DocumentSubType`](DocumentSubType.md); `updatedAt?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-branchedfromid\"></a> `branchedFromId?` | `string` \\| `null` | The id of the document this document branched from |\n| <a id=\"property-branchedfromversionid\"></a> `branchedFromVersionId?` | `number` \\| `null` | The id of the version this document branched from This could be either DocumentInstance or DocumentBom id depending on the file type |\n| <a id=\"property-createdat\"></a> `createdAt?` | `string` \\| `null` | The time the document was created |\n| <a id=\"property-deletedat\"></a> `deletedAt?` | `string` \\| `null` | The time the document was deleted |\n| <a id=\"property-documentbom\"></a> `documentBom?` | [`BomPart`](BomPart.md)[] \\| `null` | If the document is a DOCX document and unzipped, the document_bom will be present |\n| <a id=\"property-documentfamilyid\"></a> `documentFamilyId?` | `number` \\| `null` | The id of the document family this document belongs to |\n| <a id=\"property-documentid\"></a> `documentId` | `string` | The document id |\n| <a id=\"property-documentname\"></a> `documentName` | `string` | The name of the document |\n| <a id=\"property-documentversionid\"></a> `documentVersionId` | `number` | The version of the document This could be the document_instance_id or document_bom_id depending on the file type |\n| <a id=\"property-filetype\"></a> `fileType?` | `string` \\| `null` | The file type of the document (file extension) |\n| <a id=\"property-modificationdata\"></a> `modificationData?` | `unknown` | The modification data for the document instance. This is only used for PDF documents. |\n| <a id=\"property-owner\"></a> `owner` | `string` | The owner of the document |\n| <a id=\"property-projectid\"></a> `projectId?` | `string` \\| `null` | The id of the project that this document belongs to |\n| <a id=\"property-projectname\"></a> `projectName?` | `string` \\| `null` | The name of the project that this document belongs to |\n| <a id=\"property-sha\"></a> `sha?` | `string` \\| `null` | If the document is a PDF, this is the SHA of the pdf If the document is a DOCX, this will not be present |\n| <a id=\"property-subtype\"></a> `subType?` | `null` \\| [`DocumentSubType`](DocumentSubType.md) | - |\n| <a id=\"property-updatedat\"></a> `updatedAt?` | `string` \\| `null` | The time the document instance / document BOM was updated |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentMetadataWithContent.md -->\n# Type Alias: DocumentMetadataWithContent\n\n> **DocumentMetadataWithContent** = [`DocumentMetadata`](DocumentMetadata.md) & \\{ `content`: [`DocumentContent`](DocumentContent.md); `teamId?`: `string` \\| `null`; `teamTaskId?`: `number` \\| `null`; \\}\n\nFull document metadata plus content lifecycle metadata.\n\n## Type Declaration\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `content` | [`DocumentContent`](DocumentContent.md) | Content lifecycle and location metadata. |\n| `teamId?` | `string` \\| `null` | The team this task number is scoped to, for task documents. |\n| `teamTaskId?` | `number` \\| `null` | The task number assigned within the team, for task documents. |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentResponseMetadata.md -->\n# Type Alias: DocumentResponseMetadata\n\n> **DocumentResponseMetadata** = \\{ `branchedFromId?`: `string` \\| `null`; `branchedFromVersionId?`: `number` \\| `null`; `createdAt?`: `string` \\| `null`; `documentBom?`: [`BomPart`](BomPart.md)[] \\| `null`; `documentFamilyId?`: `number` \\| `null`; `documentId`: `string`; `documentName`: `string`; `documentVersionId`: `number`; `fileType?`: `string` \\| `null`; `modificationData?`: `unknown`; `owner`: `string`; `sha?`: `string` \\| `null`; `subType?`: `null` \\| [`DocumentSubType`](DocumentSubType.md); `updatedAt?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-branchedfromid\"></a> `branchedFromId?` | `string` \\| `null` | The id of the document this document branched from |\n| <a id=\"property-branchedfromversionid\"></a> `branchedFromVersionId?` | `number` \\| `null` | The id of the version this document branched from This could be either DocumentInstance or DocumentBom id depending on the file type |\n| <a id=\"property-createdat\"></a> `createdAt?` | `string` \\| `null` | The time the document was created |\n| <a id=\"property-documentbom\"></a> `documentBom?` | [`BomPart`](BomPart.md)[] \\| `null` | If the document is a DOCX document, the document_bom will be present |\n| <a id=\"property-documentfamilyid\"></a> `documentFamilyId?` | `number` \\| `null` | The id of the document family this document belongs to |\n| <a id=\"property-documentid\"></a> `documentId` | `string` | The document id |\n| <a id=\"property-documentname\"></a> `documentName` | `string` | The name of the document |\n| <a id=\"property-documentversionid\"></a> `documentVersionId` | `number` | The version of the document This could be the document_instance_id or document_bom_id depending on the file type |\n| <a id=\"property-filetype\"></a> `fileType?` | `string` \\| `null` | The file type of the document |\n| <a id=\"property-modificationdata\"></a> `modificationData?` | `unknown` | The modification data for the document instance. This is only used for PDF documents. |\n| <a id=\"property-owner\"></a> `owner` | `string` | The owner of the document |\n| <a id=\"property-sha\"></a> `sha?` | `string` \\| `null` | If the document is a PDF, this is the SHA of the pdf If the document is a DOCX, this will not be present |\n| <a id=\"property-subtype\"></a> `subType?` | `null` \\| [`DocumentSubType`](DocumentSubType.md) | - |\n| <a id=\"property-updatedat\"></a> `updatedAt?` | `string` \\| `null` | The time the document instance / document BOM was updated |\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentSubType.md -->\n# Type Alias: DocumentSubType\n\n> **DocumentSubType** = `\"task\"` \\| `\"snippet\"` \\| `\"skill\"` \\| `\"initiative_description\"`\n\nThe document sub type enum represents all values of document sub types.\nThese values should match the `document_sub_type_value` table in macrodb.\n\nWire, database, and `Display` spellings are all `snake_case` so a\nmulti-word variant serializes identically in every system.\n\n\n<!-- generated/storage/types.gen/type-aliases/DocumentTeamShareResponse.md -->\n# Type Alias: DocumentTeamShareResponse\n\n> **DocumentTeamShareResponse** = \\{ `sharedWithTeam`: `boolean`; `teamId?`: `string` \\| `null`; \\}\n\nThe team-share state of a document. The team is resolved from the document\nowner's team membership.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-sharedwithteam\"></a> `sharedWithTeam` | `boolean` | Whether explicit team sharing is enabled; inherited team access does not count. |\n| <a id=\"property-teamid\"></a> `teamId?` | `string` \\| `null` | The owner's team the document is (or would be) shared with. `None` when the owner does not belong to a team. |\n\n\n<!-- generated/storage/types.gen/type-aliases/EntityPermission.md -->\n# Type Alias: EntityPermission\n\n> **EntityPermission** = \\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\} \\| \\{ `type`: `\"channel_view_only\"`; \\} \\| \\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\} \\| \\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\nA user's permission for an entity, discriminated by entity kind.\n\nItems (documents, chats, projects, threads) use access levels.\nChannels use view-only permission or participant roles.\n\n## Union Members\n\n### Type Literal\n\n\\{ `access_level`: [`AccessLevel`](AccessLevel.md); `type`: `\"access_level\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `access_level` | [`AccessLevel`](AccessLevel.md) | The access level the user has. |\n| `type` | `\"access_level\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `type`: `\"channel_view_only\"`; \\}\n\n***\n\n### Type Literal\n\n\\{ `role`: [`ParticipantRole`](ParticipantRole.md); `type`: `\"channel_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`ParticipantRole`](ParticipantRole.md) | The role the user has in the channel. |\n| `type` | `\"channel_role\"` | - |\n\n***\n\n### Type Literal\n\n\\{ `role`: [`TeamRole`](TeamRole.md); `type`: `\"team_role\"`; \\}\n\n| Name | Type | Description |\n| ------ | ------ | ------ |\n| `role` | [`TeamRole`](TeamRole.md) | The role the user has in the team. |\n| `type` | `\"team_role\"` | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/GithubPullRequest.md -->\n# Type Alias: GithubPullRequest\n\n> **GithubPullRequest** = \\{ `additions?`: `number` \\| `null`; `checks?`: [`GithubPullRequestCheckRun`](GithubPullRequestCheckRun.md)[] \\| `null`; `comments?`: [`GithubPullRequestComment`](GithubPullRequestComment.md)[] \\| `null`; `deletions?`: `number` \\| `null`; `displayName`: `string`; `foreignEntityId?`: `string` \\| `null`; `githubKey`: `string`; `name?`: `string` \\| `null`; `number`: `number`; `owner`: `string`; `repo`: `string`; `status?`: `string` \\| `null`; `url`: `string`; \\}\n\nDisplay-ready data for a GitHub pull request associated with a task.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-additions\"></a> `additions?` | `number` \\| `null` | The number of added lines in the pull request, when enrichment data is available. |\n| <a id=\"property-checks\"></a> `checks?` | [`GithubPullRequestCheckRun`](GithubPullRequestCheckRun.md)[] \\| `null` | Check runs collected from the pull request head commit, when enrichment data is available. |\n| <a id=\"property-comments\"></a> `comments?` | [`GithubPullRequestComment`](GithubPullRequestComment.md)[] \\| `null` | Comments collected from the pull request, when enrichment data is available. |\n| <a id=\"property-deletions\"></a> `deletions?` | `number` \\| `null` | The number of deleted lines in the pull request, when enrichment data is available. |\n| <a id=\"property-displayname\"></a> `displayName` | `string` | A compact label suitable for display in the UI. |\n| <a id=\"property-foreignentityid\"></a> `foreignEntityId?` | `string` \\| `null` | The internal `foreign_entity.id` UUID for the GitHub pull request row. |\n| <a id=\"property-githubkey\"></a> `githubKey` | `string` | The stored GitHub association key, in `owner/repo/pull/number` format. |\n| <a id=\"property-name\"></a> `name?` | `string` \\| `null` | The GitHub pull request title, when enrichment data is available. |\n| <a id=\"property-number\"></a> `number` | `number` | The GitHub pull request number. |\n| <a id=\"property-owner\"></a> `owner` | `string` | The GitHub repository owner or organization. |\n| <a id=\"property-repo\"></a> `repo` | `string` | The GitHub repository name. |\n| <a id=\"property-status\"></a> `status?` | `string` \\| `null` | The GitHub pull request status, when enrichment data is available. |\n| <a id=\"property-url\"></a> `url` | `string` | The public GitHub URL for the pull request. |\n\n\n<!-- generated/storage/types.gen/type-aliases/GithubPullRequestCheckRun.md -->\n# Type Alias: GithubPullRequestCheckRun\n\n> **GithubPullRequestCheckRun** = \\{ `completedAt?`: `string` \\| `null`; `conclusion?`: `string` \\| `null`; `id`: `number`; `name`: `string`; `startedAt?`: `string` \\| `null`; `status`: `string`; `url?`: `string` \\| `null`; \\}\n\nA check run associated with a GitHub pull request.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-completedat\"></a> `completedAt?` | `string` \\| `null` | When the check run completed, when available. |\n| <a id=\"property-conclusion\"></a> `conclusion?` | `string` \\| `null` | The raw GitHub check run conclusion, when the run has completed. |\n| <a id=\"property-id\"></a> `id` | `number` | The unique GitHub identifier for the check run. |\n| <a id=\"property-name\"></a> `name` | `string` | The check run name. |\n| <a id=\"property-startedat\"></a> `startedAt?` | `string` \\| `null` | When the check run started, when available. |\n| <a id=\"property-status\"></a> `status` | `string` | The raw GitHub check run status. |\n| <a id=\"property-url\"></a> `url?` | `string` \\| `null` | The public GitHub URL for the check run, when available. |\n\n\n<!-- generated/storage/types.gen/type-aliases/GithubPullRequestComment.md -->\n# Type Alias: GithubPullRequestComment\n\n> **GithubPullRequestComment** = \\{ `authorAssociation?`: `string` \\| `null`; `authorId?`: `number` \\| `null`; `authorLogin?`: `string` \\| `null`; `body`: `string`; `createdAt?`: `string` \\| `null`; `id`: `number`; `inReplyToId?`: `number` \\| `null`; `line?`: `number` \\| `null`; `originalLine?`: `number` \\| `null`; `path?`: `string` \\| `null`; `pullRequestReviewId?`: `number` \\| `null`; `source`: `string`; `updatedAt?`: `string` \\| `null`; `url?`: `string` \\| `null`; \\}\n\nA comment associated with a GitHub pull request.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-authorassociation\"></a> `authorAssociation?` | `string` \\| `null` | GitHub's relationship label for the author, when available. |\n| <a id=\"property-authorid\"></a> `authorId?` | `number` \\| `null` | The stable numeric GitHub user id for the comment author, when available. |\n| <a id=\"property-authorlogin\"></a> `authorLogin?` | `string` \\| `null` | The GitHub login for the comment author, when available. |\n| <a id=\"property-body\"></a> `body` | `string` | The comment or review body text. |\n| <a id=\"property-createdat\"></a> `createdAt?` | `string` \\| `null` | When the comment was created or the review was submitted. |\n| <a id=\"property-id\"></a> `id` | `number` | The unique GitHub identifier for the comment or review. |\n| <a id=\"property-inreplytoid\"></a> `inReplyToId?` | `number` \\| `null` | The id of the comment this one replies to, when it is part of a review thread. Only ever present on `review_comment` sources. |\n| <a id=\"property-line\"></a> `line?` | `number` \\| `null` | The line in the current diff the comment is anchored to. Cleared by GitHub when later commits outdate the comment's diff. |\n| <a id=\"property-originalline\"></a> `originalLine?` | `number` \\| `null` | The line the comment was originally anchored to, kept even when the diff has since changed. |\n| <a id=\"property-path\"></a> `path?` | `string` \\| `null` | The repository-relative file path the review comment is anchored to. Only ever present on `review_comment` sources. |\n| <a id=\"property-pullrequestreviewid\"></a> `pullRequestReviewId?` | `number` \\| `null` | The id of the pull request review this comment was submitted with. Only ever present on `review_comment` sources. |\n| <a id=\"property-source\"></a> `source` | `string` | The GitHub source for the comment, such as `issue_comment` or `review_comment`. |\n| <a id=\"property-updatedat\"></a> `updatedAt?` | `string` \\| `null` | When the comment or review was last updated. |\n| <a id=\"property-url\"></a> `url?` | `string` \\| `null` | The public GitHub URL for the comment or review, when available. |\n\n\n<!-- generated/storage/types.gen/type-aliases/HighlightType.md -->\n# Type Alias: HighlightType\n\n> **HighlightType** = `1` \\| `2` \\| `3`\n\n\n<!-- generated/storage/types.gen/type-aliases/LinkShare.md -->\n# Type Alias: LinkShare\n\n> **LinkShare** = `\"PUBLIC\"` \\| `\"TEAM\"`\n\nDefines who can access an item through its share link.\n\n\n<!-- generated/storage/types.gen/type-aliases/MessageCursor.md -->\n# Type Alias: MessageCursor\n\n> **MessageCursor** = \\{ `created_at`: `string`; `id`: `string`; \\}\n\nCursor for a chronological parent timeline.\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-created_at\"></a> `created_at` | `string` | Last message creation time or activity occurrence time. |\n| <a id=\"property-id\"></a> `id` | `string` | Last entry UUID, used to break timestamp ties across both sources. |\n\n\n<!-- generated/storage/types.gen/type-aliases/ParticipantRole.md -->\n# Type Alias: ParticipantRole\n\n> **ParticipantRole** = `\"owner\"` \\| `\"admin\"` \\| `\"member\"`\n\nThe role a user has within a channel.\n\n\n<!-- generated/storage/types.gen/type-aliases/PdfHighlightAnchorRequest.md -->\n# Type Alias: PdfHighlightAnchorRequest\n\n> **PdfHighlightAnchorRequest** = \\{ `alpha`: `number`; `blue`: `number`; `green`: `number`; `highlightRects`: [`PdfHighlightRectAnchorRequest`](PdfHighlightRectAnchorRequest.md)[]; `highlightType`: [`HighlightType`](HighlightType.md); `page`: `number`; `pageViewportHeight`: `number`; `pageViewportWidth`: `number`; `red`: `number`; `text`: `string`; `uuid?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-alpha\"></a> `alpha` | `number` |\n| <a id=\"property-blue\"></a> `blue` | `number` |\n| <a id=\"property-green\"></a> `green` | `number` |\n| <a id=\"property-highlightrects\"></a> `highlightRects` | [`PdfHighlightRectAnchorRequest`](PdfHighlightRectAnchorRequest.md)[] |\n| <a id=\"property-highlighttype\"></a> `highlightType` | [`HighlightType`](HighlightType.md) |\n| <a id=\"property-page\"></a> `page` | `number` |\n| <a id=\"property-pageviewportheight\"></a> `pageViewportHeight` | `number` |\n| <a id=\"property-pageviewportwidth\"></a> `pageViewportWidth` | `number` |\n| <a id=\"property-red\"></a> `red` | `number` |\n| <a id=\"property-text\"></a> `text` | `string` |\n| <a id=\"property-uuid\"></a> `uuid?` | `string` \\| `null` |\n\n\n<!-- generated/storage/types.gen/type-aliases/PdfHighlightRectAnchorRequest.md -->\n# Type Alias: PdfHighlightRectAnchorRequest\n\n> **PdfHighlightRectAnchorRequest** = \\{ `height`: `number`; `left`: `number`; `top`: `number`; `width`: `number`; \\}\n\n## Properties\n\n| Property | Type |\n| ------ | ------ |\n| <a id=\"property-height\"></a> `height` | `number` |\n| <a id=\"property-left\"></a> `left` | `number` |\n| <a id=\"property-top\"></a> `top` | `number` |\n| <a id=\"property-width\"></a> `width` | `number` |\n\n\n<!-- generated/storage/types.gen/type-aliases/PreSaveDocumentResponseData.md -->\n# Type Alias: PreSaveDocumentResponseData\n\n> **PreSaveDocumentResponseData** = \\{ `presignedUrls`: [`PresignedUrl`](PresignedUrl.md)[]; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-presignedurls\"></a> `presignedUrls` | [`PresignedUrl`](PresignedUrl.md)[] | Contains any presigned urls you need to upload specific bom parts with. |\n\n\n<!-- generated/storage/types.gen/type-aliases/PresignedUrl.md -->\n# Type Alias: PresignedUrl\n\n> **PresignedUrl** = \\{ `presignedUrl`: `string`; `sha`: `string`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-presignedurl\"></a> `presignedUrl` | `string` | The presigned url used to upload the sha |\n| <a id=\"property-sha\"></a> `sha` | `string` | The sha of the item |\n\n\n<!-- generated/storage/types.gen/type-aliases/SaveBomPart.md -->\n# Type Alias: SaveBomPart\n\n> **SaveBomPart** = \\{ `path`: `string`; `sha`: `string`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-path\"></a> `path` | `string` | The file path of the bom part content |\n| <a id=\"property-sha\"></a> `sha` | `string` | The sha of the bom part content There is an index on sha for more performant queries based on it. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SaveDocumentRequest.md -->\n# Type Alias: SaveDocumentRequest\n\n> **SaveDocumentRequest** = \\{ `modificationData?`: `unknown`; `newBom?`: [`SaveBomPart`](SaveBomPart.md)[] \\| `null`; `sha?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-modificationdata\"></a> `modificationData?` | `unknown` | The modification data for the document instance. Used to store highlights and other overlays onto a static file |\n| <a id=\"property-newbom\"></a> `newBom?` | [`SaveBomPart`](SaveBomPart.md)[] \\| `null` | **DOCX ONLY** The updated BOM for the document. Containing the file path and the sha. |\n| <a id=\"property-sha\"></a> `sha?` | `string` \\| `null` | The sha of the new document. This is used to generate a presigned url to upload the new document content to s3. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md -->\n# Type Alias: SaveDocumentResponseData\n\n> **SaveDocumentResponseData** = \\{ `documentMetadata`: [`DocumentResponseMetadata`](DocumentResponseMetadata.md); `presignedUrl?`: `string` \\| `null`; \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-documentmetadata\"></a> `documentMetadata` | [`DocumentResponseMetadata`](DocumentResponseMetadata.md) | The updated document metadata |\n| <a id=\"property-presignedurl\"></a> `presignedUrl?` | `string` \\| `null` | If the document is an editable file, we provide a presigned url to save the updated file to. |\n\n\n<!-- generated/storage/types.gen/type-aliases/SharePermissionV2.md -->\n# Type Alias: SharePermissionV2\n\n> **SharePermissionV2** = \\{ `channelSharePermissions?`: [`ChannelSharePermission`](ChannelSharePermission.md)[] \\| `null`; `id`: `string`; `linkShare?`: `null` \\| [`LinkShare`](LinkShare.md); `linkShareAccessLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); `owner`: `string`; `teamShareAccessLevel?`: `null` \\| [`AccessLevel`](AccessLevel.md); \\}\n\n## Properties\n\n| Property | Type | Description |\n| ------ | ------ | ------ |\n| <a id=\"property-channelsharepermissions\"></a> `channelSharePermissions?` | [`ChannelSharePermission`](ChannelSharePermission.md)[] \\| `null` | The channel share permissions for the item |\n| <a id=\"property-id\"></a> `id` | `string` | The share permission id |\n| <a id=\"property-linkshare\"></a> `linkShare?` | `null` \\| [`LinkShare`](LinkShare.md) | - |\n| <a id=\"property-linkshareaccesslevel\"></a> `linkShareAccessLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n| <a id=\"property-owner\"></a> `owner` | `string` | The owner of the item |\n| <a id=\"property-teamshareaccesslevel\"></a> `teamShareAccessLevel?` | `null` \\| [`AccessLevel`](AccessLevel.md) | - |\n\n\n<!-- generated/storage/types.gen/type-aliases/TeamRole.md -->\n# Type Alias: TeamRole\n\n> **TeamRole** = `\"member\"` \\| `\"admin\"` \\| `\"owner\"`\n\nThe role a user has within a team.\n\nOrdered least to most privileged so comparisons reflect access strength.\n\n\n<!-- src/entities/tasks/namespace/classes/TaskNamespace.md -->\n# Class: TaskNamespace\n\n## Constructors\n\n### Constructor\n\n> **new TaskNamespace**(`client`): `TaskNamespace`\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`TaskNamespace`\n\n## Methods\n\n### byId()\n\n> **byId**(`id`): [`Task`](../../task/classes/Task.md)\n\nA handle to a task by document id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`Task`](../../task/classes/Task.md)\n\n***\n\n### create()\n\n> **create**(`opts`): `Promise`\\<[`Task`](../../task/classes/Task.md)\\>\n\nCreate a task.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); `shareWithTeam?`: `boolean`; `team?`: [`Team`](../../../teams/team/classes/Team.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n| `opts.shareWithTeam?` | `boolean` |\n| `opts.team?` | [`Team`](../../../teams/team/classes/Team.md) |\n\n#### Returns\n\n`Promise`\\<[`Task`](../../task/classes/Task.md)\\>\n\n***\n\n### forPullRequest()\n\n> **forPullRequest**(`url`): `Promise`\\<[`Task`](../../task/classes/Task.md)[]\\>\n\nThe tasks the GitHub pull request at `url` references, oldest link first.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `url` | `string` |\n\n#### Returns\n\n`Promise`\\<[`Task`](../../task/classes/Task.md)[]\\>\n\n***\n\n### search()\n\n> **search**(`query`, `opts?`): `AsyncGenerator`\\<[`Task`](../../task/classes/Task.md)\\>\n\nSearch tasks by name and content, most relevant first, auto-paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `query` | `string` |\n| `opts?` | [`SearchOpts`](../../../search/interfaces/SearchOpts.md) |\n\n#### Returns\n\n`AsyncGenerator`\\<[`Task`](../../task/classes/Task.md)\\>\n\n\n<!-- src/entities/tasks/task/classes/Task.md -->\n# Class: Task\n\nA Macro task: a document with sub-type `task`. Inherits the full document\nsurface ([Document.rename](../../../documents/document/classes/Document.md#rename), move, delete, restore, content, events)\nand adds task-specific state.\n\n## Extends\n\n- [`Document`](../../../documents/document/classes/Document.md)\n\n## Properties\n\n| Property | Modifier | Type | Default value | Description | Overrides | Inherited from |\n| ------ | ------ | ------ | ------ | ------ | ------ | ------ |\n| <a id=\"property-access\"></a> `access` | `readonly` | [`EntityAccess`](../../../sharing/access/classes/EntityAccess.md) | `...` | Access requests and direct user grants. | - | [`Document`](../../../documents/document/classes/Document.md).[`access`](../../../documents/document/classes/Document.md#property-access) |\n| <a id=\"property-branchedfrom\"></a> `branchedFrom` | `readonly` | () => `Promise`\\<[`Document`](../../../documents/document/classes/Document.md) \\| `undefined`\\> | `...` | The document this one was branched from, if any. | - | [`Document`](../../../documents/document/classes/Document.md).[`branchedFrom`](../../../documents/document/classes/Document.md#property-branchedfrom) |\n| <a id=\"property-createdat\"></a> `createdAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | When the document was created. | - | [`Document`](../../../documents/document/classes/Document.md).[`createdAt`](../../../documents/document/classes/Document.md#property-createdat) |\n| <a id=\"property-deletedat\"></a> `deletedAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | When the document was deleted, if it has been. | - | [`Document`](../../../documents/document/classes/Document.md).[`deletedAt`](../../../documents/document/classes/Document.md#property-deletedat) |\n| <a id=\"property-entitytype\"></a> `entityType` | `readonly` | `\"document\"` | `'document'` | Favorites identify documents as `document`. | - | [`Document`](../../../documents/document/classes/Document.md).[`entityType`](../../../documents/document/classes/Document.md#property-entitytype) |\n| <a id=\"property-filetype\"></a> `fileType` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | The document's file type (e.g. `md`, `pdf`, `docx`). | - | [`Document`](../../../documents/document/classes/Document.md).[`fileType`](../../../documents/document/classes/Document.md#property-filetype) |\n| <a id=\"property-id\"></a> `id` | `public readonly` | `string` | `undefined` | - | - | [`Document`](../../../documents/document/classes/Document.md).[`id`](../../../documents/document/classes/Document.md#property-id) |\n| <a id=\"property-name\"></a> `name` | `readonly` | () => `Promise`\\<`string`\\> | `...` | The document's display name. | - | [`Document`](../../../documents/document/classes/Document.md).[`name`](../../../documents/document/classes/Document.md#property-name) |\n| <a id=\"property-owner\"></a> `owner` | `readonly` | () => `Promise`\\<[`User`](../../../users/user/classes/User.md)\\> | `...` | The user who owns the document. | - | [`Document`](../../../documents/document/classes/Document.md).[`owner`](../../../documents/document/classes/Document.md#property-owner) |\n| <a id=\"property-project\"></a> `project` | `readonly` | () => `Promise`\\<[`Project`](../../../projects/project/classes/Project.md) \\| `undefined`\\> | `...` | The project this document belongs to, if any. | - | [`Document`](../../../documents/document/classes/Document.md).[`project`](../../../documents/document/classes/Document.md#property-project) |\n| <a id=\"property-updatedat\"></a> `updatedAt` | `readonly` | () => `Promise`\\<`string` \\| `undefined`\\> | `...` | When the document was last updated. | - | [`Document`](../../../documents/document/classes/Document.md).[`updatedAt`](../../../documents/document/classes/Document.md#property-updatedat) |\n| <a id=\"property-search\"></a> `search` | `static` | (`client`, `query`, `searchOpts?`) => `AsyncGenerator`\\<`Task`\\> | `...` | Search tasks by name and content, most relevant first, auto-paginated. | [`Document`](../../../documents/document/classes/Document.md).[`search`](../../../documents/document/classes/Document.md#property-search) | - |\n\n## Methods\n\n### anchors()\n\n> **anchors**(): `Promise`\\<[`DocumentAnchor`](../../../documents/anchor/classes/DocumentAnchor.md)[]\\>\n\nPDF annotations in this document.\n\n#### Returns\n\n`Promise`\\<[`DocumentAnchor`](../../../documents/anchor/classes/DocumentAnchor.md)[]\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`anchors`](../../../documents/document/classes/Document.md#anchors)\n\n***\n\n### branchName()\n\n> **branchName**(): `Promise`\\<`string`\\>\n\nThe git branch name derived for the document (task documents).\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`branchName`](../../../documents/document/classes/Document.md#branchname)\n\n***\n\n### comment()\n\n> **comment**(`body`, `opts?`): `Promise`\\<[`Comment`](../../../documents/comment/classes/Comment.md)\\>\n\nAdd a comment. Starts a new unanchored thread, or replies to an existing\none when `threadId` (the thread's root comment id) is given.\n\n#### Parameters\n\n| Parameter | Type | Description |\n| ------ | ------ | ------ |\n| `body` | `string` \\| [`RichMessage`](../../../../mentions/interfaces/RichMessage.md) | Plain text, or a rich body composed with msg. |\n| `opts?` | \\{ `threadId?`: `string`; \\} | - |\n| `opts.threadId?` | `string` | - |\n\n#### Returns\n\n`Promise`\\<[`Comment`](../../../documents/comment/classes/Comment.md)\\>\n\nThe created comment.\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`comment`](../../../documents/document/classes/Document.md#comment)\n\n***\n\n### comments()\n\n> **comments**(): `Promise`\\<[`CommentThread`](../../../documents/document/interfaces/CommentThread.md)[]\\>\n\nThe document's live comment threads, each with its comments, newest thread first.\n\n#### Returns\n\n`Promise`\\<[`CommentThread`](../../../documents/document/interfaces/CommentThread.md)[]\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`comments`](../../../documents/document/classes/Document.md#comments)\n\n***\n\n### completed()\n\n> **completed**(): `Promise`\\<`boolean` \\| `undefined`\\>\n\nWhether the task is completed (its Status property is \"Completed\");\n`undefined` if the document is not a task.\n\n#### Returns\n\n`Promise`\\<`boolean` \\| `undefined`\\>\n\n***\n\n### content()\n\n> **content**(): `Promise`\\<`string`\\>\n\nCurrent Markdown for native documents, extracted text for PDF/Word,\nor raw file content for other formats. Native reads include live edits.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`content`](../../../documents/document/classes/Document.md#content)\n\n***\n\n### copy()\n\n> **copy**(`opts`): `Promise`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\nCopy the document under a new name, optionally from a specific version.\nReturns a handle to the new document.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts` | \\{ `name`: `string`; `versionId?`: `number`; \\} |\n| `opts.name` | `string` |\n| `opts.versionId?` | `number` |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`copy`](../../../documents/document/classes/Document.md#copy)\n\n***\n\n### createHighlight()\n\n> **createHighlight**(`options`): `Promise`\\<[`DocumentAnchor`](../../../documents/anchor/classes/DocumentAnchor.md)\\>\n\nCreate a standalone PDF highlight.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | `Omit`\\<[`PdfHighlightAnchorRequest`](../../../../../generated/storage/types.gen/type-aliases/PdfHighlightAnchorRequest.md), `\"uuid\"`\\> |\n\n#### Returns\n\n`Promise`\\<[`DocumentAnchor`](../../../documents/anchor/classes/DocumentAnchor.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`createHighlight`](../../../documents/document/classes/Document.md#createhighlight)\n\n***\n\n### delete()\n\n> **delete**(`opts?`): `Promise`\\<`void`\\>\n\nDelete the document. Soft by default (reversible with [restore](../../../documents/document/classes/Document.md#restore));\npass `permanent: true` to delete irreversibly.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `permanent?`: `boolean`; \\} |\n| `opts.permanent?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`delete`](../../../documents/document/classes/Document.md#delete)\n\n***\n\n### deleteProperty()\n\n> **deleteProperty**(`assignment`): `Promise`\\<`void`\\>\n\nRemove a property from this entity, given its [properties](#properties) entry.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `assignment` | [`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`deleteProperty`](../../../documents/document/classes/Document.md#deleteproperty)\n\n***\n\n### favorite()\n\n> **favorite**(): `Promise`\\<`Task`\\>\n\nAdd this entity to the user's favorites. Returns this handle for chaining.\nPlain unwrap: favoriting alters the user's favorites collection, not this\nentity's own detail, so there's nothing cached to invalidate.\n\n#### Returns\n\n`Promise`\\<`Task`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`favorite`](../../../documents/document/classes/Document.md#favorite)\n\n***\n\n### githubPullRequests()\n\n> **githubPullRequests**(): `Promise`\\<[`GithubPullRequest`](../../../../../generated/storage/types.gen/type-aliases/GithubPullRequest.md)[]\\>\n\nGitHub pull requests associated with the document.\n\n#### Returns\n\n`Promise`\\<[`GithubPullRequest`](../../../../../generated/storage/types.gen/type-aliases/GithubPullRequest.md)[]\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`githubPullRequests`](../../../documents/document/classes/Document.md#githubpullrequests)\n\n***\n\n### meetingNotes()\n\n> **meetingNotes**(): `Promise`\\<\\{ `eventTitle`: `string`; `note`: [`CalendarNote`](../../../calendar/note/classes/CalendarNote.md); \\}[]\\>\n\nMeeting links visible to the reader. Owners also receive unavailable grants and may unlink them to revoke meeting/team access.\n\n#### Returns\n\n`Promise`\\<\\{ `eventTitle`: `string`; `note`: [`CalendarNote`](../../../calendar/note/classes/CalendarNote.md); \\}[]\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`meetingNotes`](../../../documents/document/classes/Document.md#meetingnotes)\n\n***\n\n### messageThreadById()\n\n> **messageThreadById**(`id`): [`MessageThread`](../../../messages/thread/classes/MessageThread.md)\n\nA shared message thread scoped to this resource.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n[`MessageThread`](../../../messages/thread/classes/MessageThread.md)\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`messageThreadById`](../../../documents/document/classes/Document.md#messagethreadbyid)\n\n***\n\n### move()\n\n> **move**(`project`): `Promise`\\<`void`\\>\n\nMove the document into a project (or out of one, with `null`).\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `project` | [`Project`](../../../projects/project/classes/Project.md) \\| `null` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`move`](../../../documents/document/classes/Document.md#move)\n\n***\n\n### permission()\n\n> **permission**(): `Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\nRead the caller's effective permission on this entity.\n\n#### Returns\n\n`Promise`\\<\\{ `permission`: [`EntityPermission`](../../../../../generated/storage/types.gen/type-aliases/EntityPermission.md); `status`: `\"access\"`; \\} \\| \\{ `status`: `\"no_access\"`; \\}\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`permission`](../../../documents/document/classes/Document.md#permission)\n\n***\n\n### permissionsToken()\n\n> **permissionsToken**(): `Promise`\\<`string`\\>\n\nMint a scoped permissions token.\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`permissionsToken`](../../../documents/document/classes/Document.md#permissionstoken)\n\n***\n\n### prepareSave()\n\n> **prepareSave**(`parts`): `Promise`\\<[`PreSaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/PreSaveDocumentResponseData.md)\\>\n\nPrepare multipart content saving and return the service's upload instructions.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `parts` | [`SaveBomPart`](../../../../../generated/storage/types.gen/type-aliases/SaveBomPart.md)[] |\n\n#### Returns\n\n`Promise`\\<[`PreSaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/PreSaveDocumentResponseData.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`prepareSave`](../../../documents/document/classes/Document.md#preparesave)\n\n***\n\n### properties()\n\n> **properties**(`opts?`): `Promise`\\<[`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\nThe properties set on this entity, each with its definition, value, and options.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `opts?` | \\{ `includeMetadata?`: `boolean`; \\} |\n| `opts.includeMetadata?` | `boolean` |\n\n#### Returns\n\n`Promise`\\<[`EntityPropertyWithDefinition`](../../../../../generated/properties/types.gen/type-aliases/EntityPropertyWithDefinition.md)[]\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`properties`](../../../documents/document/classes/Document.md#properties)\n\n***\n\n### propertyReference()\n\n> **propertyReference**(): [`PropertyTargetReference`](../../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\nThis entity's reference for bulk property operations.\n\n#### Returns\n\n[`PropertyTargetReference`](../../../../../generated/properties/types.gen/type-aliases/PropertyTargetReference.md)\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`propertyReference`](../../../documents/document/classes/Document.md#propertyreference)\n\n***\n\n### rename()\n\n> **rename**(`name`): `Promise`\\<`void`\\>\n\nRename the document.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `name` | `string` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`rename`](../../../documents/document/classes/Document.md#rename)\n\n***\n\n### restore()\n\n> **restore**(): `Promise`\\<`void`\\>\n\nRestore a soft-deleted document.\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`restore`](../../../documents/document/classes/Document.md#restore)\n\n***\n\n### save()\n\n> **save**(`options`): `Promise`\\<[`SaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md)\\>\n\nCommit uploaded content. Does not retry uncertain writes.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `options` | [`SaveDocumentRequest`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentRequest.md) |\n\n#### Returns\n\n`Promise`\\<[`SaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`save`](../../../documents/document/classes/Document.md#save)\n\n***\n\n### setProperty()\n\n> **setProperty**(`property`, `value?`): `Promise`\\<`void`\\>\n\nSet a property value on this entity, or attach the property without a\nvalue when `value` is omitted.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `property` | [`PropertyDefinition`](../../../properties/property-definition/classes/PropertyDefinition.md) |\n| `value?` | [`SetPropertyValue`](../../../../../generated/properties/types.gen/type-aliases/SetPropertyValue.md) |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`setProperty`](../../../documents/document/classes/Document.md#setproperty)\n\n***\n\n### setTeamShare()\n\n> **setTeamShare**(`shared`): `Promise`\\<`void`\\>\n\nShare the document with the owner's team, or unshare it.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `shared` | `boolean` |\n\n#### Returns\n\n`Promise`\\<`void`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`setTeamShare`](../../../documents/document/classes/Document.md#setteamshare)\n\n***\n\n### sharePermissions()\n\n> **sharePermissions**(): `Promise`\\<[`SharePermissionV2`](../../../../../generated/storage/types.gen/type-aliases/SharePermissionV2.md)\\>\n\nSharing configuration.\n\n#### Returns\n\n`Promise`\\<[`SharePermissionV2`](../../../../../generated/storage/types.gen/type-aliases/SharePermissionV2.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`sharePermissions`](../../../documents/document/classes/Document.md#sharepermissions)\n\n***\n\n### shortId()\n\n> **shortId**(): `Promise`\\<`string`\\>\n\nThe document's short id (used in compact links and branch names).\n\n#### Returns\n\n`Promise`\\<`string`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`shortId`](../../../documents/document/classes/Document.md#shortid)\n\n***\n\n### simpleSave()\n\n> **simpleSave**(): `Promise`\\<[`SaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md)\\>\n\nCommit a simple document save.\n\n#### Returns\n\n`Promise`\\<[`SaveDocumentResponseData`](../../../../../generated/storage/types.gen/type-aliases/SaveDocumentResponseData.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`simpleSave`](../../../documents/document/classes/Document.md#simplesave)\n\n***\n\n### teamShare()\n\n> **teamShare**(): `Promise`\\<[`DocumentTeamShareResponse`](../../../../../generated/storage/types.gen/type-aliases/DocumentTeamShareResponse.md)\\>\n\nWhether the document is shared with the owner's team, and which team.\n\n#### Returns\n\n`Promise`\\<[`DocumentTeamShareResponse`](../../../../../generated/storage/types.gen/type-aliases/DocumentTeamShareResponse.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`teamShare`](../../../documents/document/classes/Document.md#teamshare)\n\n***\n\n### timelinePage()\n\n> **timelinePage**(`selection?`): `Promise`\\<\\{ `entries`: (\\{ `activity`: \\{ `action`: `string`; `actor`: [`User`](../../../users/user/classes/User.md); `actor_id`: `string`; `id`: `string`; `occurred_at`: `string`; `payload?`: `unknown`; \\}; `message?`: `undefined`; `type`: `\"activity\"`; \\} \\| \\{ `activity?`: `undefined`; `message`: [`Comment`](../../../documents/comment/classes/Comment.md); `type`: `\"message\"`; \\})[]; `nextCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; `previousCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; \\}\\>\n\nA mixed message and activity timeline page.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `selection?` | [`TimelineOptions`](../../../messages/thread/interfaces/TimelineOptions.md)\\<[`Comment`](../../../documents/comment/classes/Comment.md)\\> |\n\n#### Returns\n\n`Promise`\\<\\{ `entries`: (\\{ `activity`: \\{ `action`: `string`; `actor`: [`User`](../../../users/user/classes/User.md); `actor_id`: `string`; `id`: `string`; `occurred_at`: `string`; `payload?`: `unknown`; \\}; `message?`: `undefined`; `type`: `\"activity\"`; \\} \\| \\{ `activity?`: `undefined`; `message`: [`Comment`](../../../documents/comment/classes/Comment.md); `type`: `\"message\"`; \\})[]; `nextCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; `previousCursor`: [`MessageCursor`](../../../../../generated/storage/types.gen/type-aliases/MessageCursor.md) \\| `undefined`; \\}\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`timelinePage`](../../../documents/document/classes/Document.md#timelinepage)\n\n***\n\n### toJSON()\n\n> **toJSON**(): \\{ `detail?`: [`DocumentMetadataWithContent`](../../../../../generated/storage/types.gen/type-aliases/DocumentMetadataWithContent.md); `id`: `string`; \\}\n\n#### Returns\n\n\\{ `detail?`: [`DocumentMetadataWithContent`](../../../../../generated/storage/types.gen/type-aliases/DocumentMetadataWithContent.md); `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `detail?` | [`DocumentMetadataWithContent`](../../../../../generated/storage/types.gen/type-aliases/DocumentMetadataWithContent.md) |\n| `id` | `string` |\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`toJSON`](../../../documents/document/classes/Document.md#tojson)\n\n***\n\n### toMention()\n\n> **toMention**(): [`MentionPart`](../../../../mentions/interfaces/MentionPart.md)\n\n#### Returns\n\n[`MentionPart`](../../../../mentions/interfaces/MentionPart.md)\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`toMention`](../../../documents/document/classes/Document.md#tomention)\n\n***\n\n### unfavorite()\n\n> **unfavorite**(): `Promise`\\<`Task`\\>\n\nRemove this entity from the user's favorites. Returns this handle for chaining.\n\n#### Returns\n\n`Promise`\\<`Task`\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`unfavorite`](../../../documents/document/classes/Document.md#unfavorite)\n\n***\n\n### updatePropertyOptions()\n\n> **updatePropertyOptions**(`changes`): `Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\nApply multi-select option deltas atomically across this entity's properties.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `changes` | [`PropertyOptionDelta`](../../../entity/interfaces/PropertyOptionDelta.md)[] |\n\n#### Returns\n\n`Promise`\\<[`BulkUpdateEntityPropertyOptionsResponse`](../../../../../generated/properties/types.gen/type-aliases/BulkUpdateEntityPropertyOptionsResponse.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`updatePropertyOptions`](../../../documents/document/classes/Document.md#updatepropertyoptions)\n\n***\n\n### version()\n\n> **version**(`version`): [`DocumentVersion`](../../../documents/version/classes/DocumentVersion.md)\n\nA handle to an immutable version.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `version` | `number` |\n\n#### Returns\n\n[`DocumentVersion`](../../../documents/version/classes/DocumentVersion.md)\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`version`](../../../documents/document/classes/Document.md#version)\n\n***\n\n### webUrl()\n\n> **webUrl**(): `string`\n\nThe task's URL in the Macro web app.\n\n#### Returns\n\n`string`\n\n#### Overrides\n\n[`Document`](../../../documents/document/classes/Document.md).[`webUrl`](../../../documents/document/classes/Document.md#weburl)\n\n***\n\n### byId()\n\n> `static` **byId**(`client`, `id`): `Task`\n\nA handle to a task by document id. Details load on first access.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `id` | `string` |\n\n#### Returns\n\n`Task`\n\n#### Overrides\n\n[`Document`](../../../documents/document/classes/Document.md).[`byId`](../../../documents/document/classes/Document.md#byid)\n\n***\n\n### create()\n\n> `static` **create**(`client`, `opts`): `Promise`\\<`Task`\\>\n\nCreate a task. `team` scopes the team task number and may be omitted\nwhen the creator belongs to exactly one team; `shareWithTeam` defaults\nto true.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); `shareWithTeam?`: `boolean`; `team?`: [`Team`](../../../teams/team/classes/Team.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n| `opts.shareWithTeam?` | `boolean` |\n| `opts.team?` | [`Team`](../../../teams/team/classes/Team.md) |\n\n#### Returns\n\n`Promise`\\<`Task`\\>\n\n#### Overrides\n\n[`Document`](../../../documents/document/classes/Document.md).[`create`](../../../documents/document/classes/Document.md#create)\n\n***\n\n### createSkill()\n\n> `static` **createSkill**(`client`, `opts`): `Promise`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\nCreate a skill: a markdown document containing instructions that AI reads\nand follows when the skill is referenced in an AI input.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`createSkill`](../../../documents/document/classes/Document.md#createskill)\n\n***\n\n### createSnippet()\n\n> `static` **createSnippet**(`client`, `opts`): `Promise`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\nCreate a snippet: a reusable markdown document that can be inserted into\nany markdown area.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts` | \\{ `markdown?`: `string`; `name`: `string`; `project?`: [`Project`](../../../projects/project/classes/Project.md); \\} |\n| `opts.markdown?` | `string` |\n| `opts.name` | `string` |\n| `opts.project?` | [`Project`](../../../projects/project/classes/Project.md) |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`createSnippet`](../../../documents/document/classes/Document.md#createsnippet)\n\n***\n\n### forPullRequest()\n\n> `static` **forPullRequest**(`client`, `url`): `Promise`\\<`Task`[]\\>\n\nThe tasks the GitHub pull request at `url` references (as `MACRO-<id>` in\nits text, branch, or comments), oldest link first. Empty when the caller\ncannot see the pull request; tasks the caller cannot open still appear.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `url` | `string` |\n\n#### Returns\n\n`Promise`\\<`Task`[]\\>\n\n***\n\n### recent()\n\n> `static` **recent**(`client`, `opts?`): `AsyncGenerator`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\nThe user's recent documents, most recent first, auto-paginated.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n| `opts?` | \\{ `fileType?`: `string`; `pageSize?`: `number`; \\} |\n| `opts.fileType?` | `string` |\n| `opts.pageSize?` | `number` |\n\n#### Returns\n\n`AsyncGenerator`\\<[`Document`](../../../documents/document/classes/Document.md)\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`recent`](../../../documents/document/classes/Document.md#recent)\n\n***\n\n### recentlyDeleted()\n\n> `static` **recentlyDeleted**(`client`): `Promise`\\<[`Document`](../../../documents/document/classes/Document.md)[]\\>\n\nThe user's recently soft-deleted documents. The underlying endpoint also\nreturns deleted chats and projects; those are filtered out here.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `client` | `MacroClient` |\n\n#### Returns\n\n`Promise`\\<[`Document`](../../../documents/document/classes/Document.md)[]\\>\n\n#### Inherited from\n\n[`Document`](../../../documents/document/classes/Document.md).[`recentlyDeleted`](../../../documents/document/classes/Document.md#recentlydeleted)\n"
},
{
"name": "teams",
diff --git a/crates/calendar_events/AGENTS.md b/crates/calendar_events/AGENTS.md
index 33f162d3e5..ffa6b881d0 100644
--- a/crates/calendar_events/AGENTS.md
+++ b/crates/calendar_events/AGENTS.md
@@ -59,7 +59,9 @@ reminder dispatch, team availability, and provider/Postgres persistence.
- Keep note links separate from sync-owned occurrence rows; require a live
occurrence and corroborated inbox copies for inherited view access. A document
- owner can unlink after losing meeting access. See
+ owner can unlink after losing meeting access. Document readers can discover
+ only links whose meeting details they can currently see; owners also retain
+ unavailable links for revocation. See
[meeting-note access](../../docs/architecture/calendar-meeting-notes.md).
- `CalendarEvent` is the stable Macro entity; external calendars and email
invitations are sources feeding it, and recurrence instances are queryable
diff --git a/crates/calendar_events/src/domain/notes.rs b/crates/calendar_events/src/domain/notes.rs
index 0968b4541e..e8e87d4dde 100644
--- a/crates/calendar_events/src/domain/notes.rs
+++ b/crates/calendar_events/src/domain/notes.rs
@@ -1,6 +1,13 @@
//! Meeting-note links and their view-only, live audience.
-use entity_access::domain::models::{EntityAccessReceipt, EntityType, OwnerAccessLevel};
+use super::models::{CalendarMentionEvent, CalendarMentionPreview};
+use super::team::{
+ TeamCalendarContent, TeamCalendarItem, TeamCalendarSharing, TeamSourceOccurrence,
+ project_team_source,
+};
+use entity_access::domain::models::{
+ EntityAccessReceipt, EntityType, OwnerAccessLevel, ViewAccessLevel,
+};
use serde::{Deserialize, Serialize};
use uuid::Uuid;
@@ -61,12 +68,12 @@ pub struct NotePicker {
pub teams: Vec<NoteTeam>,
}
-/// An owner's durable sharing link, including meetings they can no longer open.
+/// A visible meeting link, or an owner's durable grant they can no longer open.
#[derive(Clone, Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct DocumentNoteLink {
- /// Current name of the owned markdown document.
+ /// Current name of the markdown document.
pub document_name: String,
/// Linked calendar copy.
pub event_id: Uuid,
@@ -74,8 +81,26 @@ pub struct DocumentNoteLink {
pub occurrence_key: String,
/// Current title, or a safe placeholder when meeting details are unavailable.
pub event_title: String,
+ /// Whether the reader may resolve this exact meeting's details right now.
+ pub can_view_meeting: bool,
+ /// Exact accessible calendar preview, resolved with this link's authorization snapshot.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub event: Option<CalendarMentionEvent>,
/// Independent optional team audience.
pub team: Option<NoteTeam>,
+ /// Exact, sanitized team-calendar details when the meeting is shared through a team.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub team_event: Option<TeamCalendarItem>,
+}
+
+/// An exact linked occurrence from a currently authorized full-detail team source.
+pub struct NoteReferenceSource {
+ /// Durable link this source resolves.
+ pub target: NoteTarget,
+ /// Source-scoped event and occurrence; never borrowed from another calendar.
+ pub source: TeamSourceOccurrence,
+ /// Addresses owned by the reader, for requester-relative attendee fields.
+ pub viewer_emails: Vec<String>,
}
/// Failures with safe, user-facing semantics.
@@ -102,12 +127,24 @@ pub enum NoteError {
pub trait NoteRepository: Send + Sync + 'static {
/// Adapter error.
type Err: std::error::Error + Send + Sync + 'static;
- /// All links on the caller's document, even after meeting access is lost.
+ /// Visible meeting links; document owners also retain unavailable grants.
fn document_links(
&self,
user: &str,
document: &str,
) -> impl Future<Output = Result<Vec<DocumentNoteLink>, Self::Err>> + Send;
+ /// Exact linked sources with live full-detail team policy and source access.
+ fn team_reference_sources(
+ &self,
+ user: &str,
+ document: &str,
+ ) -> impl Future<Output = Result<Vec<NoteReferenceSource>, rootcause::Report>> + Send;
+ /// Resolve visible link targets through the existing own/channel preview reader.
+ fn reference_previews(
+ &self,
+ user: &str,
+ targets: Vec<NoteTarget>,
+ ) -> impl Future<Output = Result<Vec<CalendarMentionPreview>, rootcause::Report>> + Send;
/// Current full-detail access; busy-only projections never qualify.
fn visible(
&self,
@@ -157,10 +194,10 @@ pub trait NoteRepository: Send + Sync + 'static {
/// Inbound contract; mutation receipts prove ownership before granting access.
pub trait MeetingNotesService: Send + Sync + 'static {
- /// List an owned document's durable calendar sharing grants.
+ /// List visible meeting links; owners also receive unavailable durable grants.
fn document_links(
&self,
- receipt: EntityAccessReceipt<OwnerAccessLevel>,
+ receipt: EntityAccessReceipt<ViewAccessLevel>,
) -> impl Future<Output = Result<Vec<DocumentNoteLink>, NoteError>> + Send;
/// Read notes using the current meeting audience.
fn list(
@@ -224,7 +261,7 @@ impl<R: NoteRepository> MeetingNotesService for MeetingNotes<R> {
#[tracing::instrument(name = "calendar.notes.document_links", skip_all, fields(document_id = %receipt.entity().entity_id), err)]
async fn document_links(
&self,
- receipt: EntityAccessReceipt<OwnerAccessLevel>,
+ receipt: EntityAccessReceipt<ViewAccessLevel>,
) -> Result<Vec<DocumentNoteLink>, NoteError> {
let user = receipt
.get_authenticated_user()
@@ -232,10 +269,71 @@ impl<R: NoteRepository> MeetingNotesService for MeetingNotes<R> {
if receipt.entity().entity_type != EntityType::Document {
return Err(NoteError::Forbidden);
}
- self.repo
+ let mut links = self
+ .repo
.document_links(user.as_ref(), &receipt.entity().entity_id)
.await
- .map_err(internal)
+ .map_err(internal)?;
+ if links.is_empty() {
+ return Ok(links);
+ }
+ let visible_targets = links
+ .iter()
+ .filter(|link| link.can_view_meeting)
+ .map(|link| NoteTarget {
+ event_id: link.event_id,
+ occurrence_key: link.occurrence_key.clone(),
+ })
+ .collect::<Vec<_>>();
+ if !visible_targets.is_empty() {
+ let previews = self
+ .repo
+ .reference_previews(user.as_ref(), visible_targets)
+ .await
+ .map_err(NoteError::Internal)?;
+ for (link, preview) in links
+ .iter_mut()
+ .filter(|link| link.can_view_meeting)
+ .zip(previews)
+ {
+ if let CalendarMentionPreview::Accessible(event) = preview {
+ let exact = if link.occurrence_key == "single" {
+ !event.is_recurring
+ } else {
+ event.occurrence_key.as_deref() == Some(link.occurrence_key.as_str())
+ };
+ if exact {
+ link.event = Some(*event);
+ }
+ }
+ }
+ }
+ let sources = self
+ .repo
+ .team_reference_sources(user.as_ref(), &receipt.entity().entity_id)
+ .await
+ .map_err(NoteError::Internal)?;
+ for reference in sources {
+ let Some(projected) = project_team_source(
+ &reference.source,
+ TeamCalendarSharing::All,
+ &reference.viewer_emails,
+ ) else {
+ continue;
+ };
+ if !matches!(projected.content, TeamCalendarContent::Details { .. }) {
+ continue;
+ }
+ if let Some(link) = links.iter_mut().find(|link| {
+ link.event_id == reference.target.event_id
+ && link.occurrence_key == reference.target.occurrence_key
+ && link.can_view_meeting
+ && link.team_event.is_none()
+ }) {
+ link.team_event = Some(projected);
+ }
+ }
+ Ok(links)
}
#[tracing::instrument(name = "calendar.notes.list", skip_all, fields(event_id = %target.event_id), err)]
async fn list(&self, user: &str, target: NoteTarget) -> Result<Vec<MeetingNote>, NoteError> {
diff --git a/crates/calendar_events/src/domain/notes/test.rs b/crates/calendar_events/src/domain/notes/test.rs
index c83b3a1072..6a64c4206e 100644
--- a/crates/calendar_events/src/domain/notes/test.rs
+++ b/crates/calendar_events/src/domain/notes/test.rs
@@ -14,6 +14,20 @@ impl NoteRepository for Repo {
async fn document_links(&self, _: &str, _: &str) -> Result<Vec<DocumentNoteLink>, Self::Err> {
Ok(vec![])
}
+ async fn team_reference_sources(
+ &self,
+ _: &str,
+ _: &str,
+ ) -> Result<Vec<NoteReferenceSource>, rootcause::Report> {
+ Ok(vec![])
+ }
+ async fn reference_previews(
+ &self,
+ _: &str,
+ _: Vec<NoteTarget>,
+ ) -> Result<Vec<CalendarMentionPreview>, rootcause::Report> {
+ Ok(vec![])
+ }
async fn visible(&self, _: &str, _: &NoteTarget) -> Result<bool, Self::Err> {
Ok(self.visible)
}
@@ -143,3 +157,22 @@ async fn an_owner_can_revoke_sharing_after_losing_meeting_access() {
.unwrap();
assert_eq!(service.repo.writes.load(Ordering::SeqCst), 1);
}
+
+#[tokio::test]
+async fn document_references_require_a_document_view_receipt() {
+ let service = MeetingNotes::new(Repo {
+ visible: true,
+ markdown: true,
+ member: false,
+ writes: AtomicUsize::new(0),
+ });
+ for (entity_type, allowed) in [(EntityType::Document, true), (EntityType::Project, false)] {
+ let receipt = EntityAccessReceipt::<ViewAccessLevel>::dangerously_assert_authenticated_user(
+ MacroUserIdStr::parse_from_str("macro|[email protected]").unwrap(),
+ "019f85aa-984e-7022-a018-4a242bcafe23",
+ entity_type,
+ );
+ assert_eq!(service.document_links(receipt).await.is_ok(), allowed);
+ }
+ assert_eq!(service.repo.writes.load(Ordering::SeqCst), 0);
+}
diff --git a/crates/calendar_events/src/domain/team.rs b/crates/calendar_events/src/domain/team.rs
index ff5d218cd3..0440d57f75 100644
--- a/crates/calendar_events/src/domain/team.rs
+++ b/crates/calendar_events/src/domain/team.rs
@@ -6,4 +6,6 @@ mod service;
pub use models::*;
pub use ports::*;
+#[cfg(feature = "notes")]
+pub(crate) use service::project as project_team_source;
pub use service::{CalendarTeamServiceImpl, TeamCalendarError};
diff --git a/crates/calendar_events/src/domain/team/service.rs b/crates/calendar_events/src/domain/team/service.rs
index 4f0a58647b..1a3a86997d 100644
--- a/crates/calendar_events/src/domain/team/service.rs
+++ b/crates/calendar_events/src/domain/team/service.rs
@@ -274,7 +274,7 @@ impl<R: CalendarTeamRepository, N: CalendarTeamNotifier> CalendarTeamService
}
}
-fn project(
+pub(crate) fn project(
source: &TeamSourceOccurrence,
sharing: TeamCalendarSharing,
viewer_emails: &[String],
diff --git a/crates/calendar_events/src/inbound/notes_router.rs b/crates/calendar_events/src/inbound/notes_router.rs
index 78674d62b9..8cbe6226ad 100644
--- a/crates/calendar_events/src/inbound/notes_router.rs
+++ b/crates/calendar_events/src/inbound/notes_router.rs
@@ -11,7 +11,7 @@ use axum::{
routing::{get, put},
};
use entity_access::domain::{
- models::{AccessError, EntityType, OwnerAccessLevel},
+ models::{AccessError, EntityType, OwnerAccessLevel, ViewAccessLevel},
ports::EntityAccessService,
};
use macro_authorization::{
@@ -199,7 +199,7 @@ pub async fn note_documents<
))
}
-/// List an owned document's meeting grants, including unavailable meetings.
+/// List a document's visible meeting links; owners also see unavailable grants.
#[utoipa::path(get, path="/meeting-notes/documents/{document_id}/links", params(("document_id" = String, Path)), responses((status=200, body=Vec<DocumentNoteLink>)), tag="calendar_events")]
pub async fn document_note_links<
S: MeetingNotesService,
@@ -212,7 +212,7 @@ pub async fn document_note_links<
) -> Result<Json<Vec<DocumentNoteLink>>, NotesApiError> {
let receipt = state
.access
- .generate_entity_access_receipt::<OwnerAccessLevel>(
+ .generate_entity_access_receipt::<ViewAccessLevel>(
&user.authorization.user.macro_user_id,
user.authorization
.user
diff --git a/crates/calendar_events/src/outbound/pg/test/notes.rs b/crates/calendar_events/src/outbound/pg/test/notes.rs
index 37e7cbeceb..cafee6b704 100644
--- a/crates/calendar_events/src/outbound/pg/test/notes.rs
+++ b/crates/calendar_events/src/outbound/pg/test/notes.rs
@@ -44,6 +44,10 @@ async fn a_one_time_meeting_keeps_its_notes_after_a_provider_reschedule(pool: Pg
.unwrap();
let notes = PgNoteRepository::new(pool.clone());
notes.link(owner, &original, &document, None).await.unwrap();
+ // A reader who can see this meeting can discover it from the document.
+ let references = notes.document_links(viewer, &document).await.unwrap();
+ assert_eq!(references.len(), 1);
+ assert_eq!(references[0].event_id, original.event_id);
let starts_at = Utc.with_ymd_and_hms(2026, 7, 26, 16, 0, 0).unwrap();
event.event.sequence += 1;
@@ -74,6 +78,31 @@ async fn a_one_time_meeting_keeps_its_notes_after_a_provider_reschedule(pool: Pg
notes.document_links(owner, &document).await.unwrap()[0].occurrence_key,
"single"
);
+ // Losing calendar access hides the reference from a reader, even if a
+ // separate document grant remains. The owner retains the durable link.
+ let document_uuid = Uuid::parse_str(&document).unwrap();
+ sqlx::query!("INSERT INTO entity_access (entity_id, entity_type, source_id, source_type, access_level) VALUES ($1, 'document', $2, 'user', 'view')", document_uuid, viewer)
+ .execute(&pool).await.unwrap();
+ sqlx::query!("UPDATE comms_channel_participants SET left_at = now() WHERE channel_id = $1 AND user_id = $2", channel, viewer)
+ .execute(&pool).await.unwrap();
+ assert_eq!(
+ PgAccessRepository::new(pool.clone())
+ .get_document_access(&document, Some(&viewer_id))
+ .await
+ .unwrap(),
+ Some(AccessLevel::View)
+ );
+ assert!(
+ notes
+ .document_links(viewer, &document)
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ assert_eq!(
+ notes.document_links(owner, &document).await.unwrap().len(),
+ 1
+ );
// A previously returned handle remains able to revoke after the move.
notes.unlink(&original, &document).await.unwrap();
assert!(notes.list(viewer, &moved).await.unwrap().is_empty());
@@ -362,10 +391,36 @@ async fn channel_note_access_observes_membership_and_private_occurrences(pool: P
sqlx::query!("INSERT INTO entity_access (entity_id, entity_type, source_id, source_type, access_level) VALUES ($1, 'calendar_event', $2, 'channel', 'view')", target.event_id, channel.to_string()).execute(&pool).await.unwrap();
let notes = PgNoteRepository::new(pool.clone());
assert!(notes.visible(viewer, &target).await.unwrap());
+ let document = Uuid::now_v7().to_string();
+ sqlx::query!("INSERT INTO \"Document\" (id, name, owner, \"fileType\") VALUES ($1, 'Channel notes', $2, 'md')", document, viewer).execute(&pool).await.unwrap();
+ notes.link(viewer, &target, &document, None).await.unwrap();
+ use crate::domain::notes::{MeetingNotes, MeetingNotesService};
+ use entity_access::domain::models::{EntityAccessReceipt, EntityType, ViewAccessLevel};
+ let service = MeetingNotes::new(PgNoteRepository::new(pool.clone()));
+ let receipt = EntityAccessReceipt::<ViewAccessLevel>::dangerously_assert_authenticated_user(
+ MacroUserIdStr::parse_from_str(viewer).unwrap(),
+ &document,
+ EntityType::Document,
+ );
+ let references = service.document_links(receipt.clone()).await.unwrap();
+ assert!(references[0].can_view_meeting);
+ assert_eq!(
+ references[0]
+ .event
+ .as_ref()
+ .unwrap()
+ .occurrence_key
+ .as_deref(),
+ Some(target.occurrence_key.as_str())
+ );
let overrides =
serde_json::json!([{ "recurrenceId": target.occurrence_key, "visibility": "private" }]);
sqlx::query!("UPDATE calendar_event_sources SET normalized_payload = jsonb_set(jsonb_set(normalized_payload, '{occurrences,0,recurrenceId}', to_jsonb($2::text)), '{overrides}', $3) WHERE event_id = $1", target.event_id, target.occurrence_key, overrides).execute(&pool).await.unwrap();
assert!(!notes.visible(viewer, &target).await.unwrap());
+ let references = service.document_links(receipt).await.unwrap();
+ assert!(!references[0].can_view_meeting);
+ assert!(references[0].event.is_none());
+ assert!(references[0].team_event.is_none());
sqlx::query!("UPDATE calendar_event_sources SET normalized_payload = jsonb_set(normalized_payload, '{overrides}', '[]') WHERE event_id = $1", target.event_id).execute(&pool).await.unwrap();
assert!(notes.visible(viewer, &target).await.unwrap());
sqlx::query!("UPDATE comms_channel_participants SET left_at = now() WHERE channel_id = $1 AND user_id = $2", channel, viewer).execute(&pool).await.unwrap();
@@ -571,8 +626,35 @@ async fn team_detail_access_is_live_and_busy_only_never_reveals_notes(pool: PgPo
notes.document_links(viewer, &document).await.unwrap()[0].event_title,
"Shared meeting"
);
+ use crate::domain::notes::{MeetingNotes, MeetingNotesService};
+ use crate::domain::team::TeamCalendarContent;
+ use entity_access::domain::models::{EntityAccessReceipt, EntityType, ViewAccessLevel};
+ let service = MeetingNotes::new(PgNoteRepository::new(pool.clone()));
+ let receipt = EntityAccessReceipt::<ViewAccessLevel>::dangerously_assert_authenticated_user(
+ MacroUserIdStr::parse_from_str(viewer).unwrap(),
+ &document,
+ EntityType::Document,
+ );
+ let references = service.document_links(receipt.clone()).await.unwrap();
+ let projection = references[0].team_event.as_ref().unwrap();
+ assert!(
+ matches!(&projection.content, TeamCalendarContent::Details { details } if details.title == "Planning")
+ );
+ assert_eq!(
+ notes
+ .team_reference_sources(viewer, &document)
+ .await
+ .unwrap()
+ .len(),
+ 1
+ );
sqlx::query!("UPDATE calendar_event_sources SET normalized_payload = jsonb_set(normalized_payload, '{event,visibility}', '\"private\"') WHERE event_id=$1", target.event_id).execute(&pool).await.unwrap();
assert!(!notes.visible(viewer, &target).await.unwrap());
+ assert!(
+ service.document_links(receipt.clone()).await.unwrap()[0]
+ .team_event
+ .is_none()
+ );
sqlx::query!("UPDATE calendar_event_sources SET normalized_payload = jsonb_set(normalized_payload, '{event,visibility}', '\"default\"') WHERE event_id=$1", target.event_id).execute(&pool).await.unwrap();
assert!(notes.visible(viewer, &target).await.unwrap());
sqlx::query!(
@@ -583,4 +665,9 @@ async fn team_detail_access_is_live_and_busy_only_never_reveals_notes(pool: PgPo
.await
.unwrap();
assert!(!notes.visible(viewer, &target).await.unwrap());
+ assert!(
+ service.document_links(receipt).await.unwrap()[0]
+ .team_event
+ .is_none()
+ );
}
diff --git a/crates/calendar_events/src/outbound/pg/test/team_sharing.rs b/crates/calendar_events/src/outbound/pg/test/team_sharing.rs
index 44023563ff..17370a835b 100644
--- a/crates/calendar_events/src/outbound/pg/test/team_sharing.rs
+++ b/crates/calendar_events/src/outbound/pg/test/team_sharing.rs
@@ -361,6 +361,14 @@ async fn team_sources_require_current_membership_and_verified_source_entitlement
.await
.unwrap();
assert_eq!(rows.len(), 4, "all synced source calendars are included");
+ assert_eq!(
+ team.sources(owner, july_2026_range(), &owners, None, 100)
+ .await
+ .unwrap()
+ .len(),
+ 4,
+ "the owner's busy-only policy must not duplicate their own sources"
+ );
sqlx::query!(
"UPDATE calendars SET snapshot_normalization_version=0 WHERE account_id=$1",
account
diff --git a/crates/calendar_events/src/outbound/pg_notes.rs b/crates/calendar_events/src/outbound/pg_notes.rs
index e71823ac54..7a7c3cf439 100644
--- a/crates/calendar_events/src/outbound/pg_notes.rs
+++ b/crates/calendar_events/src/outbound/pg_notes.rs
@@ -26,6 +26,7 @@ impl NoteRepository for PgNoteRepository {
) -> Result<Vec<DocumentNoteLink>, Self::Err> {
let rows = sqlx::query!(r#"
SELECT note.event_id, note.occurrence_key, document.name AS document_name,
+ calendar_note_event_visible($1, note.event_id, note.occurrence_key) AS "can_view_meeting!",
CASE WHEN calendar_note_event_visible($1, note.event_id, note.occurrence_key)
THEN CASE WHEN event.owner_id = $1 OR EXISTS (
SELECT 1 FROM macro_user_links delegate
@@ -34,10 +35,11 @@ impl NoteRepository for PgNoteRepository {
ELSE 'Unavailable meeting' END AS "event_title!",
team.id AS "team_id?", team.name AS "team_name?"
FROM calendar_event_notes note
- JOIN "Document" document ON document.id = note.document_id AND document.owner = $1 AND document."deletedAt" IS NULL
+ JOIN "Document" document ON document.id = note.document_id AND document."deletedAt" IS NULL
JOIN calendar_events event ON event.id = note.event_id
LEFT JOIN team ON team.id = note.team_id
WHERE note.document_id = $2
+ AND (document.owner = $1 OR calendar_note_event_visible($1, note.event_id, note.occurrence_key))
ORDER BY note.created_at, note.event_id, note.occurrence_key
"#, user, document).fetch_all(&self.pool).await?;
Ok(rows
@@ -47,6 +49,9 @@ impl NoteRepository for PgNoteRepository {
event_id: row.event_id,
occurrence_key: row.occurrence_key,
event_title: row.event_title,
+ can_view_meeting: row.can_view_meeting,
+ event: None,
+ team_event: None,
team: row
.team_id
.zip(row.team_name)
@@ -55,6 +60,35 @@ impl NoteRepository for PgNoteRepository {
.collect())
}
+ async fn team_reference_sources(
+ &self,
+ user: &str,
+ document: &str,
+ ) -> Result<Vec<NoteReferenceSource>, rootcause::Report> {
+ super::pg_team::PgCalendarTeamRepository::new(self.pool.clone())
+ .note_reference_sources(user, document)
+ .await
+ }
+
+ async fn reference_previews(
+ &self,
+ user: &str,
+ targets: Vec<NoteTarget>,
+ ) -> Result<Vec<crate::domain::models::CalendarMentionPreview>, rootcause::Report> {
+ use crate::domain::ports::CalendarRepository;
+ let items = targets
+ .into_iter()
+ .map(|target| crate::domain::models::CalendarMentionRequestItem {
+ event_id: target.event_id,
+ occurrence_key: (target.occurrence_key != "single")
+ .then_some(target.occurrence_key),
+ })
+ .collect();
+ super::pg::PgCalendarRepository::new(self.pool.clone())
+ .mention_previews(user, items, chrono::Utc::now())
+ .await
+ }
+
async fn visible(&self, user: &str, target: &NoteTarget) -> Result<bool, Self::Err> {
sqlx::query_scalar!(
"SELECT calendar_note_event_visible($1, $2, calendar_note_link_key($2, $3)) AS \"visible!\"",
diff --git a/crates/calendar_events/src/outbound/pg_team.rs b/crates/calendar_events/src/outbound/pg_team.rs
index 363f2370f3..99732d4e85 100644
--- a/crates/calendar_events/src/outbound/pg_team.rs
+++ b/crates/calendar_events/src/outbound/pg_team.rs
@@ -42,6 +42,164 @@ fn sharing(value: &str) -> Result<TeamCalendarSharing, Report> {
}
}
+struct SourceRead<'a> {
+ range: Option<OccurrenceRange>,
+ owners: &'a [String],
+ cursor: Option<&'a TeamCalendarCursor>,
+ limit: u32,
+ document: Option<&'a str>,
+}
+
+impl PgCalendarTeamRepository {
+ /// Read exact linked occurrences through the same source entitlement as team calendars.
+ #[cfg(feature = "notes")]
+ pub(super) async fn note_reference_sources(
+ &self,
+ requester: &str,
+ document: &str,
+ ) -> Result<Vec<crate::domain::notes::NoteReferenceSource>, Report> {
+ let viewer_emails = self.owned_emails(requester).await?;
+ let rows = self
+ .read_sources(
+ requester,
+ SourceRead {
+ range: None,
+ owners: &[],
+ cursor: None,
+ limit: 2000,
+ document: Some(document),
+ },
+ )
+ .await?;
+ Ok(rows
+ .into_iter()
+ .filter_map(|(source, target)| {
+ target.map(
+ |(event_id, occurrence_key)| crate::domain::notes::NoteReferenceSource {
+ target: crate::domain::notes::NoteTarget {
+ event_id,
+ occurrence_key,
+ },
+ source,
+ viewer_emails: viewer_emails.clone(),
+ },
+ )
+ })
+ .collect())
+ }
+
+ async fn read_sources(
+ &self,
+ requester: &str,
+ request: SourceRead<'_>,
+ ) -> Result<Vec<(TeamSourceOccurrence, Option<(Uuid, String)>)>, Report> {
+ // The normalized source payload holds this source's schedule, guests,
+ // conference, and exceptions. Joining canonical entity fields here would
+ // borrow richer content from a different calendar's entitlement.
+ let rows = sqlx::query!(r#"
+ WITH reference_targets AS MATERIALIZED (
+ SELECT candidate.id AS event_id, note.event_id AS reference_event_id,
+ note.occurrence_key AS reference_occurrence_key
+ FROM calendar_event_notes note
+ JOIN calendar_events linked ON linked.id = note.event_id
+ JOIN calendar_events candidate ON candidate.ical_uid = linked.ical_uid
+ AND lower(candidate.organizer_email) IS NOT DISTINCT FROM lower(linked.organizer_email)
+ WHERE note.document_id = $11
+ AND calendar_note_copies_match(note.event_id, candidate.id, note.occurrence_key)
+ ), eligible AS (
+ SELECT teammate.user_id, COALESCE(policy.sharing, 'busy_only') AS sharing FROM team_user viewer
+ JOIN team_user teammate ON teammate.team_id = viewer.team_id
+ LEFT JOIN calendar_team_sharing policy ON policy.user_id = teammate.user_id
+ WHERE viewer.user_id = $1 AND teammate.user_id <> $1
+ AND COALESCE(policy.sharing, 'busy_only') <> 'none'
+ UNION SELECT $1::text, 'all'
+ ), visible_accounts AS MATERIALIZED (
+ SELECT eligible.user_id, eligible.sharing, account.id AS account_id
+ FROM eligible JOIN calendar_accounts account ON account.owner_id = eligible.user_id
+ WHERE ($11::text IS NOT NULL OR eligible.user_id = ANY($2::text[]))
+ UNION
+ SELECT eligible.user_id, eligible.sharing, account.id AS account_id
+ FROM eligible
+ JOIN macro_user_links link ON link.primary_macro_id = eligible.user_id
+ JOIN calendar_accounts account ON account.email_link_id = link.link_id
+ WHERE ($11::text IS NOT NULL OR eligible.user_id = ANY($2::text[]))
+ ), authorized_sources AS MATERIALIZED (
+ SELECT eligible.user_id AS shared_by, source.id AS source_id,
+ calendar.id AS calendar_id, calendar.name AS calendar_name, calendar.time_zone,
+ COALESCE(preference.contributes_to_availability,
+ account.owner_id = eligible.user_id AND calendar.is_primary) AS contributes,
+ source.normalized_payload, reference.reference_event_id,
+ reference.reference_occurrence_key
+ FROM visible_accounts eligible
+ JOIN calendar_accounts account ON account.id = eligible.account_id
+ AND account.sync_status IN ('ready', 'syncing')
+ AND account.last_sync_error IS NULL
+ AND account.last_synced_at > now() - interval '15 minutes'
+ JOIN calendars calendar ON calendar.account_id = account.id AND NOT calendar.is_deleted
+ AND calendar.synced_at IS NOT NULL AND calendar.last_sync_error IS NULL
+ AND calendar.snapshot_normalization_version >= 1
+ JOIN calendar_event_sources source ON source.calendar_id = calendar.id AND source.account_id = account.id
+ AND source.provider_access_role IS NOT NULL
+ AND source.provider_access_role IS NOT DISTINCT FROM calendar.access_role
+ LEFT JOIN calendar_availability_preferences preference ON preference.user_id = eligible.user_id AND preference.calendar_id = calendar.id
+ LEFT JOIN reference_targets reference ON reference.event_id = source.event_id
+ WHERE ($11::text IS NULL OR (eligible.sharing = 'all' AND reference.event_id IS NOT NULL))
+ AND ($7::text IS NULL OR (eligible.user_id, source.id) >= ($7,$8))
+ )
+ SELECT shared_by AS "shared_by!", source_id AS "source_id!",
+ calendar_id AS "calendar_id!", calendar_name AS "calendar_name!", time_zone,
+ contributes AS "contributes!", reference_event_id AS "reference_event_id?",
+ reference_occurrence_key AS "reference_occurrence_key?",
+ ARRAY(SELECT owned.email_address::text FROM email_links owned WHERE owned.macro_id = shared_by) AS "owner_emails!",
+ (normalized_payload - 'occurrences') AS "snapshot!", occurrence.value AS "occurrence!"
+ FROM authorized_sources
+ CROSS JOIN LATERAL jsonb_array_elements(normalized_payload->'occurrences') occurrence(value)
+ WHERE (normalized_payload->'event'->>'status') <> 'cancelled'
+ AND NOT COALESCE((occurrence.value->>'isCancelled')::boolean, false)
+ AND ($11::text IS NOT NULL OR (
+ ((occurrence.value->'time'->>'kind') = 'timed'
+ AND (occurrence.value->'time'->>'startsAt')::timestamptz < $4
+ AND ((occurrence.value->'time'->>'endsAt')::timestamptz > $3
+ OR ((occurrence.value->'time'->>'startsAt')::timestamptz = (occurrence.value->'time'->>'endsAt')::timestamptz
+ AND (occurrence.value->'time'->>'startsAt')::timestamptz >= $3)))
+ OR ((occurrence.value->'time'->>'kind') = 'allDay'
+ AND (occurrence.value->'time'->>'startDate')::date < $6
+ AND (occurrence.value->'time'->>'endDate')::date > $5)
+ ))
+ AND ($11::text IS NULL OR occurrence.value->>'occurrenceKey' = reference_occurrence_key
+ OR (reference_occurrence_key = 'single' AND jsonb_array_length(normalized_payload->'event'->'recurrenceLines') = 0))
+ AND ($7::text IS NULL OR (shared_by, source_id, occurrence.value->>'occurrenceKey') > ($7,$8,$9))
+ ORDER BY shared_by, source_id, occurrence.value->>'occurrenceKey'
+ LIMIT $10
+ "#, requester, request.owners, request.range.as_ref().map(|r| r.starts_at), request.range.as_ref().map(|r| r.ends_at),
+ request.range.as_ref().map(|r| r.start_date), request.range.as_ref().map(|r| r.end_date),
+ request.cursor.map(|cursor| cursor.user_id.as_str()), request.cursor.map(|cursor| cursor.source_id), request.cursor.map(|cursor| cursor.occurrence_key.as_str()), i64::from(request.limit), request.document)
+ .fetch_all(&self.pool).await.map_err(|error| rootcause::report!(error))?;
+ rows.into_iter()
+ .map(|row| {
+ let snapshot: SourceSnapshot = serde_json::from_value(row.snapshot)
+ .map_err(|error| rootcause::report!(error))?;
+ Ok((
+ TeamSourceOccurrence {
+ shared_by: row.shared_by,
+ source_id: row.source_id,
+ calendar_id: row.calendar_id,
+ calendar_name: row.calendar_name,
+ calendar_time_zone: row.time_zone,
+ contributes_to_availability: row.contributes,
+ owner_emails: row.owner_emails,
+ event: snapshot.event,
+ overrides: snapshot.overrides,
+ occurrence: serde_json::from_value(row.occurrence)
+ .map_err(|error| rootcause::report!(error))?,
+ },
+ row.reference_event_id.zip(row.reference_occurrence_key),
+ ))
+ })
+ .collect()
+ }
+}
+
impl CalendarTeamRepository for PgCalendarTeamRepository {
async fn projection_revision(&self, requester: &str) -> Result<String, Report> {
sqlx::query_scalar!(r#"
@@ -141,90 +299,21 @@ impl CalendarTeamRepository for PgCalendarTeamRepository {
cursor: Option<&TeamCalendarCursor>,
limit: u32,
) -> Result<Vec<TeamSourceOccurrence>, Report> {
- // The normalized source payload holds this source's schedule, guests,
- // conference, and exceptions. Joining canonical entity fields here would
- // borrow richer content from a different calendar's entitlement.
- let rows = sqlx::query!(r#"
- WITH eligible AS (
- SELECT teammate.user_id FROM team_user viewer
- JOIN team_user teammate ON teammate.team_id = viewer.team_id
- LEFT JOIN calendar_team_sharing policy ON policy.user_id = teammate.user_id
- WHERE viewer.user_id = $1 AND COALESCE(policy.sharing, 'busy_only') <> 'none'
- UNION SELECT $1::text
- ), visible_accounts AS MATERIALIZED (
- SELECT eligible.user_id, account.id AS account_id
- FROM eligible JOIN calendar_accounts account ON account.owner_id = eligible.user_id
- WHERE eligible.user_id = ANY($2::text[])
- UNION
- SELECT eligible.user_id, account.id AS account_id
- FROM eligible
- JOIN macro_user_links link ON link.primary_macro_id = eligible.user_id
- JOIN calendar_accounts account ON account.email_link_id = link.link_id
- WHERE eligible.user_id = ANY($2::text[])
- ), authorized_sources AS MATERIALIZED (
- SELECT eligible.user_id AS shared_by, source.id AS source_id,
- calendar.id AS calendar_id, calendar.name AS calendar_name, calendar.time_zone,
- COALESCE(preference.contributes_to_availability,
- account.owner_id = eligible.user_id AND calendar.is_primary) AS contributes,
- source.normalized_payload
- FROM visible_accounts eligible
- JOIN calendar_accounts account ON account.id = eligible.account_id
- AND account.sync_status IN ('ready', 'syncing')
- AND account.last_sync_error IS NULL
- AND account.last_synced_at > now() - interval '15 minutes'
- JOIN calendars calendar ON calendar.account_id = account.id AND NOT calendar.is_deleted
- AND calendar.synced_at IS NOT NULL AND calendar.last_sync_error IS NULL
- AND calendar.snapshot_normalization_version >= 1
- JOIN calendar_event_sources source ON source.calendar_id = calendar.id AND source.account_id = account.id
- AND source.provider_access_role IS NOT NULL
- AND source.provider_access_role IS NOT DISTINCT FROM calendar.access_role
- LEFT JOIN calendar_availability_preferences preference ON preference.user_id = eligible.user_id AND preference.calendar_id = calendar.id
- WHERE ($7::text IS NULL OR (eligible.user_id, source.id) >= ($7,$8))
+ Ok(self
+ .read_sources(
+ requester,
+ SourceRead {
+ range: Some(range),
+ owners,
+ cursor,
+ limit,
+ document: None,
+ },
)
- SELECT shared_by AS "shared_by!", source_id AS "source_id!",
- calendar_id AS "calendar_id!", calendar_name AS "calendar_name!", time_zone,
- contributes AS "contributes!",
- ARRAY(SELECT owned.email_address::text FROM email_links owned WHERE owned.macro_id = shared_by) AS "owner_emails!",
- (normalized_payload - 'occurrences') AS "snapshot!", occurrence.value AS "occurrence!"
- FROM authorized_sources
- CROSS JOIN LATERAL jsonb_array_elements(normalized_payload->'occurrences') occurrence(value)
- WHERE (normalized_payload->'event'->>'status') <> 'cancelled'
- AND NOT COALESCE((occurrence.value->>'isCancelled')::boolean, false)
- AND (
- ((occurrence.value->'time'->>'kind') = 'timed'
- AND (occurrence.value->'time'->>'startsAt')::timestamptz < $4
- AND ((occurrence.value->'time'->>'endsAt')::timestamptz > $3
- OR ((occurrence.value->'time'->>'startsAt')::timestamptz = (occurrence.value->'time'->>'endsAt')::timestamptz
- AND (occurrence.value->'time'->>'startsAt')::timestamptz >= $3)))
- OR ((occurrence.value->'time'->>'kind') = 'allDay'
- AND (occurrence.value->'time'->>'startDate')::date < $6
- AND (occurrence.value->'time'->>'endDate')::date > $5)
- )
- AND ($7::text IS NULL OR (shared_by, source_id, occurrence.value->>'occurrenceKey') > ($7,$8,$9))
- ORDER BY shared_by, source_id, occurrence.value->>'occurrenceKey'
- LIMIT $10
- "#, requester, owners, range.starts_at, range.ends_at, range.start_date, range.end_date,
- cursor.map(|cursor| cursor.user_id.as_str()), cursor.map(|cursor| cursor.source_id), cursor.map(|cursor| cursor.occurrence_key.as_str()), i64::from(limit))
- .fetch_all(&self.pool).await.map_err(|error| rootcause::report!(error))?;
- rows.into_iter()
- .map(|row| {
- let snapshot: SourceSnapshot = serde_json::from_value(row.snapshot)
- .map_err(|error| rootcause::report!(error))?;
- Ok(TeamSourceOccurrence {
- shared_by: row.shared_by,
- source_id: row.source_id,
- calendar_id: row.calendar_id,
- calendar_name: row.calendar_name,
- calendar_time_zone: row.time_zone,
- contributes_to_availability: row.contributes,
- owner_emails: row.owner_emails,
- event: snapshot.event,
- overrides: snapshot.overrides,
- occurrence: serde_json::from_value(row.occurrence)
- .map_err(|error| rootcause::report!(error))?,
- })
- })
- .collect()
+ .await?
+ .into_iter()
+ .map(|(source, _)| source)
+ .collect())
}
async fn owned_emails(&self, requester: &str) -> Result<Vec<String>, Report> {
diff --git a/docs/agent-guide/calendar.md b/docs/agent-guide/calendar.md
index 35b9e1f4fa..1ea161e734 100644
--- a/docs/agent-guide/calendar.md
+++ b/docs/agent-guide/calendar.md
@@ -23,6 +23,10 @@ Existing document editors and other sharing keep their access.
Notes use the event details' existing row layout and controls. Team choices come
from current Macro team memberships; they do not introduce departments or subteams.
+Linked meetings also appear in the note’s side-panel **References** section.
+Only readers with meeting-detail access see those references; owners retain safe
+unavailable-meeting entries.
+
Open the linked title to read the original document. On desktop it opens in a
new split; on mobile it replaces the calendar pane and closes event details.
Opening a note leaves focus available to the document as it mounts; dismissing
diff --git a/docs/agent-guide/documents.md b/docs/agent-guide/documents.md
index f3f8df1934..42a6adc3d9 100644
--- a/docs/agent-guide/documents.md
+++ b/docs/agent-guide/documents.md
@@ -17,6 +17,25 @@ checked, the share status uses **Restricted** instead of claiming **Just me**;
known public, team, or shared access still appears.
This status follows the current document and account when navigating with Share open.
+When meeting notes are enabled, the document side panel’s **References** section
+also lists linked calendar events, including when there are no document or message
+references. Each row uses the same single-line style, with the meeting title and
+date inline. Open a row to jump to
+your calendar copy; meetings shared through a channel or team without a personal
+copy use a read-only event preview. The preview also works when the Calendar
+view is disabled. Readers see only
+meetings they can view in detail. Owners retain safe
+unavailable-meeting entries, which can be removed through Share. Linking or
+unlinking updates the References count.
+
+Verify a note linked to two meetings, a note with both message and calendar
+references, a rescheduled one-time event, and a recurring occurrence. A cancelled
+instance must never open a later instance. Check full-detail team sharing, a
+reader who can see both entities, a reader with document-only access, and the
+feature flag off. On phone, open References from the document side panel and
+follow a meeting without leaving a sheet over the calendar. Closing a read-only
+meeting preview must return to the document details sheet.
+
Verify **Public → View** links in a fresh signed-out browser context. The
`/app/drive/md/<id>` route (including folder/tab document links and legacy
`/app/md/<id>` redirects) must show the document without private Drive lists or
diff --git a/docs/agent-guide/media/calendar-notes/references-desktop.png b/docs/agent-guide/media/calendar-notes/references-desktop.png
new file mode 100644
index 0000000000..3b86d9b08d
Binary files /dev/null and b/docs/agent-guide/media/calendar-notes/references-desktop.png differ
diff --git a/docs/architecture/calendar-meeting-notes.md b/docs/architecture/calendar-meeting-notes.md
index 3793f118e6..89f18304a2 100644
--- a/docs/architecture/calendar-meeting-notes.md
+++ b/docs/architecture/calendar-meeting-notes.md
@@ -84,8 +84,27 @@ captures the account and occurrence before creation starts, suppresses duplicate
clicks, and retains the created document for retry if linking fails. A disposed
view never navigates on a late result. There is no separate calendar-owned content
store or create endpoint.
+
+The document References section lists meeting links alongside document and
+message references. Readers need document view access and current full-detail
+meeting access to discover a link. Owners also retain unavailable links; their
+labels stay safe. Calendar previews resolve titles and times through the viewer’s
+projection. Opening a reference uses the viewer’s own copy when available, or
+the existing read-only event preview otherwise. The note flag gates this query
+before it mounts.
+
+The links response includes `canViewMeeting` and an optional exact `event`
+preview, so References never performs a separate, more permissive mention read.
+It also includes an optional `teamEvent` projection, resolved through
+the same source entitlement reader and sanitizer as the team calendar. It never
+borrows canonical details, includes busy-only content, or substitutes a nearby
+occurrence. References previews expose no channel-share actions. A `single` link
+can follow a moved one-time event, but cannot become a link to a new recurring
+series.
+
The document Share panel also lists owner-only durable links, immediate optional
-team access controls, and inline unlink confirmation. That list does not require current meeting access. It uses
+team access controls, and inline unlink confirmation. That list does not require
+current meeting access. It uses
generic labels for inaccessible or indirectly shared meetings, so it cannot reveal
a richer canonical event title through a restricted provider projection.
@@ -95,7 +114,7 @@ disabled. Every response is private and non-cacheable:
| Method | Path | Purpose |
| --- | --- | --- |
| GET | `/meeting-notes/documents?query=` | Up to 30 owned markdown suggestions and current teams |
-| GET | `/meeting-notes/documents/{document_id}/links` | Owner-only durable grants, including unavailable meetings |
+| GET | `/meeting-notes/documents/{document_id}/links` | Visible links for document readers; owners also receive unavailable grants |
| GET | `/events/{event_id}/notes?occurrenceKey=` | Notes visible through this occurrence |
| PUT | `/events/{event_id}/notes/{document_id}?occurrenceKey=` | Link/update with `{ "teamId": null }` or a team UUID |
| DELETE | `/events/{event_id}/notes/{document_id}?occurrenceKey=` | Idempotently unlink the owned document |
diff --git a/packages/sdk-docs/reference/generated/calendar/types.gen/README.md b/packages/sdk-docs/reference/generated/calendar/types.gen/README.md
index d68bedcaeb..baf03ed2be 100644
--- a/packages/sdk-docs/reference/generated/calendar/types.gen/README.md
+++ b/packages/sdk-docs/reference/generated/calendar/types.gen/README.md
@@ -22,6 +22,8 @@
- [CalendarJoinRequest](type-aliases/CalendarJoinRequest.md)
- [CalendarJoinRequestDecision](type-aliases/CalendarJoinRequestDecision.md)
- [CalendarJoinRequestStatus](type-aliases/CalendarJoinRequestStatus.md)
+- [CalendarMentionEvent](type-aliases/CalendarMentionEvent.md)
+- [CalendarMentionViewerCopy](type-aliases/CalendarMentionViewerCopy.md)
- [CalendarMutationApiError](type-aliases/CalendarMutationApiError.md)
- [CalendarMutationErrorCode](type-aliases/CalendarMutationErrorCode.md)
- [CalendarProvider](type-aliases/CalendarProvider.md)
@@ -138,6 +140,9 @@
- [SetTeamSharingData](type-aliases/SetTeamSharingData.md)
- [SetTeamSharingResponse](type-aliases/SetTeamSharingResponse.md)
- [SetTeamSharingResponses](type-aliases/SetTeamSharingResponses.md)
+- [TeamCalendarContent](type-aliases/TeamCalendarContent.md)
+- [TeamCalendarDetails](type-aliases/TeamCalendarDetails.md)
+- [TeamCalendarItem](type-aliases/TeamCalendarItem.md)
- [TeamCalendarSharing](type-aliases/TeamCalendarSharing.md)
- [TeamCalendarSharingBody](type-aliases/TeamCalendarSharingBody.md)
- [UnlinkEventNoteData](type-aliases/UnlinkEventNoteData.md)
diff --git a/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/CalendarMentionEvent.md b/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/CalendarMentionEvent.md
new file mode 100644
index 0000000000..a7635b25a6
--- /dev/null
+++ b/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/CalendarMentionEvent.md
@@ -0,0 +1,26 @@
+# Type Alias: CalendarMentionEvent
+
+> **CalendarMentionEvent** = \{ `attendeeCount`: `number`; `canRequestToJoin?`: `boolean`; `description?`: `string` \| `null`; `isRecurring`: `boolean`; `joinRequestStatus?`: `null` \| [`CalendarJoinRequestStatus`](CalendarJoinRequestStatus.md); `location?`: `string` \| `null`; `occurrenceKey?`: `string` \| `null`; `organizerEmail?`: `string` \| `null`; `organizerName?`: `string` \| `null`; `time`: [`EventTime`](EventTime.md); `title`: `string`; `updatedAt`: `string`; `viewerCopy?`: `null` \| [`CalendarMentionViewerCopy`](CalendarMentionViewerCopy.md); `viewerEventId?`: `string` \| `null`; \}
+
+Meeting-level fields shown in a calendar event mention preview, taken from
+the requester's own projection of the meeting, or — when the requester has
+none — from the mentioned projection a channel they belong to was given.
+
+## Properties
+
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| <a id="property-attendeecount"></a> `attendeeCount` | `number` | Number of attendees on the previewed copy. |
+| <a id="property-canrequesttojoin"></a> `canRequestToJoin?` | `boolean` | For a channel-shared preview, whether the person who shared it can add the requester as a guest. Always false for the requester's own copy. |
+| <a id="property-description"></a> `description?` | `string` \| `null` | Provider description, plain text or HTML, truncated for the preview. Clients must sanitize it before rendering. |
+| <a id="property-isrecurring"></a> `isRecurring` | `boolean` | Whether the event repeats. |
+| <a id="property-joinrequeststatus"></a> `joinRequestStatus?` | `null` \| [`CalendarJoinRequestStatus`](CalendarJoinRequestStatus.md) | - |
+| <a id="property-location"></a> `location?` | `string` \| `null` | Location label, when set. |
+| <a id="property-occurrencekey"></a> `occurrenceKey?` | `string` \| `null` | Key of the previewed instance, absent when no occurrence is materialized. |
+| <a id="property-organizeremail"></a> `organizerEmail?` | `string` \| `null` | Organizer email. |
+| <a id="property-organizername"></a> `organizerName?` | `string` \| `null` | Organizer display name. |
+| <a id="property-time"></a> `time` | [`EventTime`](EventTime.md) | Time of the previewed instance: the requested occurrence when it exists, else the next upcoming one, else the latest past one, else the series start. |
+| <a id="property-title"></a> `title` | `string` | Display title. |
+| <a id="property-updatedat"></a> `updatedAt` | `string` | Entity update time of the previewed copy. |
+| <a id="property-viewercopy"></a> `viewerCopy?` | `null` \| [`CalendarMentionViewerCopy`](CalendarMentionViewerCopy.md) | - |
+| <a id="property-viewereventid"></a> `viewerEventId?` | `string` \| `null` | The requester's own event entity for the mentioned meeting. Differs from the mentioned id when the mention came from another attendee. Absent when the meeting is on none of the requester's calendars and they see it only because it was shared with one of their channels: that preview is read-only and there is no event of theirs to open. |
diff --git a/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/CalendarMentionViewerCopy.md b/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/CalendarMentionViewerCopy.md
new file mode 100644
index 0000000000..dc0167333d
--- /dev/null
+++ b/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/CalendarMentionViewerCopy.md
@@ -0,0 +1,7 @@
+# Type Alias: CalendarMentionViewerCopy
+
+> **CalendarMentionViewerCopy** = `"snapshot"` \| `"invitation"` \| `"event"`
+
+How a requester holds a mentioned meeting on their own calendar, decided
+by the copy's own inbox, the way viewer capabilities decide organizer and
+guest.
diff --git a/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/DocumentNoteLink.md b/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/DocumentNoteLink.md
index a73a8c1be4..12b09329e8 100644
--- a/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/DocumentNoteLink.md
+++ b/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/DocumentNoteLink.md
@@ -1,15 +1,18 @@
# Type Alias: DocumentNoteLink
-> **DocumentNoteLink** = \{ `documentName`: `string`; `eventId`: `string`; `eventTitle`: `string`; `occurrenceKey`: `string`; `team?`: `null` \| [`NoteTeam`](NoteTeam.md); \}
+> **DocumentNoteLink** = \{ `canViewMeeting`: `boolean`; `documentName`: `string`; `event?`: `null` \| [`CalendarMentionEvent`](CalendarMentionEvent.md); `eventId`: `string`; `eventTitle`: `string`; `occurrenceKey`: `string`; `team?`: `null` \| [`NoteTeam`](NoteTeam.md); `teamEvent?`: `null` \| [`TeamCalendarItem`](TeamCalendarItem.md); \}
-An owner's durable sharing link, including meetings they can no longer open.
+A visible meeting link, or an owner's durable grant they can no longer open.
## Properties
| Property | Type | Description |
| ------ | ------ | ------ |
-| <a id="property-documentname"></a> `documentName` | `string` | Current name of the owned markdown document. |
+| <a id="property-canviewmeeting"></a> `canViewMeeting` | `boolean` | Whether the reader may resolve this exact meeting's details right now. |
+| <a id="property-documentname"></a> `documentName` | `string` | Current name of the markdown document. |
+| <a id="property-event"></a> `event?` | `null` \| [`CalendarMentionEvent`](CalendarMentionEvent.md) | - |
| <a id="property-eventid"></a> `eventId` | `string` | Linked calendar copy. |
| <a id="property-eventtitle"></a> `eventTitle` | `string` | Current title, or a safe placeholder when meeting details are unavailable. |
| <a id="property-occurrencekey"></a> `occurrenceKey` | `string` | Original occurrence start, or `single` for a one-time meeting. |
| <a id="property-team"></a> `team?` | `null` \| [`NoteTeam`](NoteTeam.md) | - |
+| <a id="property-teamevent"></a> `teamEvent?` | `null` \| [`TeamCalendarItem`](TeamCalendarItem.md) | - |
diff --git a/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/TeamCalendarContent.md b/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/TeamCalendarContent.md
new file mode 100644
index 0000000000..3137706b9b
--- /dev/null
+++ b/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/TeamCalendarContent.md
@@ -0,0 +1,22 @@
+# Type Alias: TeamCalendarContent
+
+> **TeamCalendarContent** = \{ `kind`: `"busy"`; \} \| \{ `details`: [`TeamCalendarDetails`](TeamCalendarDetails.md); `kind`: `"details"`; \}
+
+Disjoint busy/detail shapes prevent new event fields leaking by default.
+
+## Union Members
+
+### Type Literal
+
+\{ `kind`: `"busy"`; \}
+
+***
+
+### Type Literal
+
+\{ `details`: [`TeamCalendarDetails`](TeamCalendarDetails.md); `kind`: `"details"`; \}
+
+| Name | Type | Description |
+| ------ | ------ | ------ |
+| `details` | [`TeamCalendarDetails`](TeamCalendarDetails.md) | Detail projection. |
+| `kind` | `"details"` | - |
diff --git a/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/TeamCalendarDetails.md b/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/TeamCalendarDetails.md
new file mode 100644
index 0000000000..61b08a55e5
--- /dev/null
+++ b/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/TeamCalendarDetails.md
@@ -0,0 +1,18 @@
+# Type Alias: TeamCalendarDetails
+
+> **TeamCalendarDetails** = \{ `attendees`: [`CalendarAttendee`](CalendarAttendee.md)[]; `calendarName`: `string`; `conferenceUrl?`: `string` \| `null`; `description?`: `string` \| `null`; `location?`: `string` \| `null`; `organizerEmail?`: `string` \| `null`; `organizerName?`: `string` \| `null`; `title`: `string`; \}
+
+Safe details from a single authorized source.
+
+## Properties
+
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| <a id="property-attendees"></a> `attendees` | [`CalendarAttendee`](CalendarAttendee.md)[] | Attendees; self flags are relative to the requesting viewer. |
+| <a id="property-calendarname"></a> `calendarName` | `string` | Source calendar name, shown only with details. |
+| <a id="property-conferenceurl"></a> `conferenceUrl?` | `string` \| `null` | Join URL, if supplied by this source. |
+| <a id="property-description"></a> `description?` | `string` \| `null` | Body, if supplied by this source. |
+| <a id="property-location"></a> `location?` | `string` \| `null` | Location, if supplied by this source. |
+| <a id="property-organizeremail"></a> `organizerEmail?` | `string` \| `null` | Organizer address from this source. |
+| <a id="property-organizername"></a> `organizerName?` | `string` \| `null` | Organizer name from this source. |
+| <a id="property-title"></a> `title` | `string` | Display title. |
diff --git a/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/TeamCalendarItem.md b/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/TeamCalendarItem.md
new file mode 100644
index 0000000000..77afbf862d
--- /dev/null
+++ b/packages/sdk-docs/reference/generated/calendar/types.gen/type-aliases/TeamCalendarItem.md
@@ -0,0 +1,14 @@
+# Type Alias: TeamCalendarItem
+
+> **TeamCalendarItem** = [`TeamCalendarContent`](TeamCalendarContent.md) & \{ `contributesToAvailability`: `boolean`; `id`: `string`; `ownerId`: `string`; `time`: [`EventTime`](EventTime.md); \}
+
+A read-only team calendar occurrence.
+
+## Type Declaration
+
+| Name | Type | Description |
+| ------ | ------ | ------ |
+| `contributesToAvailability` | `boolean` | Whether this occurrence blocks the sharer's personal availability. A subscribed calendar's block can be shared without occupying the sharer. |
+| `id` | `string` | Stable opaque projection identity, never an event entity id. |
+| `ownerId` | `string` | The person sharing access to the source. |
+| `time` | [`EventTime`](EventTime.md) | Occurrence interval. |
diff --git a/packages/sdk-docs/reference/src/entities/documents/document/classes/Document.md b/packages/sdk-docs/reference/src/entities/documents/document/classes/Document.md
index 6a71d4ebd8..78a99aee9f 100644
--- a/packages/sdk-docs/reference/src/entities/documents/document/classes/Document.md
+++ b/packages/sdk-docs/reference/src/entities/documents/document/classes/Document.md
@@ -221,7 +221,7 @@ GitHub pull requests associated with the document.
> **meetingNotes**(): `Promise`\<\{ `eventTitle`: `string`; `note`: [`CalendarNote`](../../../calendar/note/classes/CalendarNote.md); \}[]\>
-Owner-only meeting grants, including unavailable meetings. Unlink a returned note to revoke its meeting/team access.
+Meeting links visible to the reader. Owners also receive unavailable grants and may unlink them to revoke meeting/team access.
#### Returns
diff --git a/packages/sdk-docs/reference/src/entities/tasks/task/classes/Task.md b/packages/sdk-docs/reference/src/entities/tasks/task/classes/Task.md
index 88c2eb2a14..3440d7af03 100644
--- a/packages/sdk-docs/reference/src/entities/tasks/task/classes/Task.md
+++ b/packages/sdk-docs/reference/src/entities/tasks/task/classes/Task.md
@@ -263,7 +263,7 @@ GitHub pull requests associated with the document.
> **meetingNotes**(): `Promise`\<\{ `eventTitle`: `string`; `note`: [`CalendarNote`](../../../calendar/note/classes/CalendarNote.md); \}[]\>
-Owner-only meeting grants, including unavailable meetings. Unlink a returned note to revoke its meeting/team access.
+Meeting links visible to the reader. Owners also receive unavailable grants and may unlink them to revoke meeting/team access.
#### Returns
diff --git a/packages/sdk/AGENTS.md b/packages/sdk/AGENTS.md
index 25c8a2c32c..e8c28589b8 100644
--- a/packages/sdk/AGENTS.md
+++ b/packages/sdk/AGENTS.md
@@ -57,7 +57,8 @@ the existing gateway prefixes.
- Calendar notes accept a document handle and the occurrence returned by calendar
reads. `CalendarNote` owns optional team sharing and unlinking; clearing its team
sends explicit null and never changes the document's other permissions.
- `Document.meetingNotes()` discovers durable grants for revocation after losing
+ `Document.meetingNotes()` discovers visible meeting links for readers and
+ durable grants for owners to revoke after losing
meeting access.
- Regenerate Rust OpenAPI and web service clients before `bun run sync-specs &&
bun run generate`; do not copy deployed schemas over a local API change.
diff --git a/packages/sdk/generated/calendar/index.ts b/packages/sdk/generated/calendar/index.ts
index 6d2725b607..c24732256d 100644
--- a/packages/sdk/generated/calendar/index.ts
+++ b/packages/sdk/generated/calendar/index.ts
@@ -1,4 +1,4 @@
// This file is auto-generated by @hey-api/openapi-ts
export { type Options, Sdk } from './sdk.gen';
-export type { AttendeeResponseStatus, AvailabilityCalendar, AvailabilityCalendarBody, AvailabilityCalendarsResponse, CalendarAttendee, CalendarAttendeeInputBody, CalendarCapabilities, CalendarDeletionScopeParam, CalendarEvent, CalendarEventProviderUrl, CalendarEventProviderUrlData, CalendarEventProviderUrlError, CalendarEventProviderUrlErrors, CalendarEventProviderUrlResponse, CalendarEventProviderUrlResponses, CalendarEventSourceContent, CalendarGuestInputBody, CalendarJoinRequest, CalendarJoinRequestDecision, CalendarJoinRequestStatus, CalendarMutationApiError, CalendarMutationErrorCode, CalendarProvider, CalendarReplacementStatusData, CalendarReplacementStatusError, CalendarReplacementStatusErrors, CalendarReplacementStatusResponse, CalendarReplacementStatusResponses, CalendarReplacementView, CalendarRsvpScopeParam, CalendarUpdateScopeParam, ClientOptions, ConferenceChange, ConferenceProvider, ConfirmCalendarReplacementData, ConfirmCalendarReplacementError, ConfirmCalendarReplacementErrors, ConfirmCalendarReplacementResponse, ConfirmCalendarReplacementResponses, CopyCalendarEventData, CopyCalendarEventError, CopyCalendarEventErrors, CopyCalendarEventRequest, CopyCalendarEventResponse, CopyCalendarEventResponses, CreateCalendarEventData, CreateCalendarEventError, CreateCalendarEventErrors, CreateCalendarEventRequest, CreateCalendarEventResponse, CreateCalendarEventResponses, DeleteCalendarEventData, DeleteCalendarEventError, DeleteCalendarEventErrors, DeleteCalendarEventResponse, DeleteCalendarEventResponses, DiscardCalendarReplacementData, DiscardCalendarReplacementError, DiscardCalendarReplacementErrors, DiscardCalendarReplacementResponse, DiscardCalendarReplacementResponses, DocumentNoteLink, DocumentNoteLinksData, DocumentNoteLinksResponse, DocumentNoteLinksResponses, EventNotesData, EventNotesResponse, EventNotesResponses, EventReminderOverride, EventReminders, EventStatus, EventTime, EventTransparency, EventType, EventVisibility, GetAvailabilityCalendarsData, GetAvailabilityCalendarsResponse, GetAvailabilityCalendarsResponses, GetTeamSharingData, GetTeamSharingResponse, GetTeamSharingResponses, GuestPolicy, HealthHandlerData, HealthHandlerResponse, HealthHandlerResponses, InviteCalendarEventGuestsData, InviteCalendarEventGuestsError, InviteCalendarEventGuestsErrors, InviteCalendarEventGuestsRequest, InviteCalendarEventGuestsResponse, InviteCalendarEventGuestsResponses, LinkEventNoteData, LinkEventNoteResponse, LinkEventNoteResponses, LinkNoteRequest, ListCalendarsData, ListCalendarsError, ListCalendarsErrors, ListCalendarsResponse, ListCalendarsResponse2, ListCalendarsResponses, MeetingNote, NoteDocument, NoteDocumentsData, NoteDocumentsResponse, NoteDocumentsResponses, NotePicker, NoteTeam, OutOfOfficeAutoDeclineMode, OutOfOfficeProperties, PrepareCalendarReplacementData, PrepareCalendarReplacementError, PrepareCalendarReplacementErrors, PrepareCalendarReplacementRequest, PrepareCalendarReplacementResponse, PrepareCalendarReplacementResponses, RefreshCalendarEvent, ReplacementStatus, RespondToJoinRequestData, RespondToJoinRequestError, RespondToJoinRequestErrors, RespondToJoinRequestRequest, RespondToJoinRequestResponse, RespondToJoinRequestResponses, RsvpCalendarEventData, RsvpCalendarEventError, RsvpCalendarEventErrors, RsvpCalendarEventRequest, RsvpCalendarEventResponse, RsvpCalendarEventResponses, SetAvailabilityCalendarData, SetAvailabilityCalendarResponse, SetAvailabilityCalendarResponses, SetTeamSharingData, SetTeamSharingResponse, SetTeamSharingResponses, TeamCalendarSharing, TeamCalendarSharingBody, UnlinkEventNoteData, UnlinkEventNoteResponse, UnlinkEventNoteResponses, UpdateCalendarEventData, UpdateCalendarEventError, UpdateCalendarEventErrors, UpdateCalendarEventRequest, UpdateCalendarEventResponse, UpdateCalendarEventResponses, ViewerCapabilities, VisibleCalendar } from './types.gen';
+export type { AttendeeResponseStatus, AvailabilityCalendar, AvailabilityCalendarBody, AvailabilityCalendarsResponse, CalendarAttendee, CalendarAttendeeInputBody, CalendarCapabilities, CalendarDeletionScopeParam, CalendarEvent, CalendarEventProviderUrl, CalendarEventProviderUrlData, CalendarEventProviderUrlError, CalendarEventProviderUrlErrors, CalendarEventProviderUrlResponse, CalendarEventProviderUrlResponses, CalendarEventSourceContent, CalendarGuestInputBody, CalendarJoinRequest, CalendarJoinRequestDecision, CalendarJoinRequestStatus, CalendarMentionEvent, CalendarMentionViewerCopy, CalendarMutationApiError, CalendarMutationErrorCode, CalendarProvider, CalendarReplacementStatusData, CalendarReplacementStatusError, CalendarReplacementStatusErrors, CalendarReplacementStatusResponse, CalendarReplacementStatusResponses, CalendarReplacementView, CalendarRsvpScopeParam, CalendarUpdateScopeParam, ClientOptions, ConferenceChange, ConferenceProvider, ConfirmCalendarReplacementData, ConfirmCalendarReplacementError, ConfirmCalendarReplacementErrors, ConfirmCalendarReplacementResponse, ConfirmCalendarReplacementResponses, CopyCalendarEventData, CopyCalendarEventError, CopyCalendarEventErrors, CopyCalendarEventRequest, CopyCalendarEventResponse, CopyCalendarEventResponses, CreateCalendarEventData, CreateCalendarEventError, CreateCalendarEventErrors, CreateCalendarEventRequest, CreateCalendarEventResponse, CreateCalendarEventResponses, DeleteCalendarEventData, DeleteCalendarEventError, DeleteCalendarEventErrors, DeleteCalendarEventResponse, DeleteCalendarEventResponses, DiscardCalendarReplacementData, DiscardCalendarReplacementError, DiscardCalendarReplacementErrors, DiscardCalendarReplacementResponse, DiscardCalendarReplacementResponses, DocumentNoteLink, DocumentNoteLinksData, DocumentNoteLinksResponse, DocumentNoteLinksResponses, EventNotesData, EventNotesResponse, EventNotesResponses, EventReminderOverride, EventReminders, EventStatus, EventTime, EventTransparency, EventType, EventVisibility, GetAvailabilityCalendarsData, GetAvailabilityCalendarsResponse, GetAvailabilityCalendarsResponses, GetTeamSharingData, GetTeamSharingResponse, GetTeamSharingResponses, GuestPolicy, HealthHandlerData, HealthHandlerResponse, HealthHandlerResponses, InviteCalendarEventGuestsData, InviteCalendarEventGuestsError, InviteCalendarEventGuestsErrors, InviteCalendarEventGuestsRequest, InviteCalendarEventGuestsResponse, InviteCalendarEventGuestsResponses, LinkEventNoteData, LinkEventNoteResponse, LinkEventNoteResponses, LinkNoteRequest, ListCalendarsData, ListCalendarsError, ListCalendarsErrors, ListCalendarsResponse, ListCalendarsResponse2, ListCalendarsResponses, MeetingNote, NoteDocument, NoteDocumentsData, NoteDocumentsResponse, NoteDocumentsResponses, NotePicker, NoteTeam, OutOfOfficeAutoDeclineMode, OutOfOfficeProperties, PrepareCalendarReplacementData, PrepareCalendarReplacementError, PrepareCalendarReplacementErrors, PrepareCalendarReplacementRequest, PrepareCalendarReplacementResponse, PrepareCalendarReplacementResponses, RefreshCalendarEvent, ReplacementStatus, RespondToJoinRequestData, RespondToJoinRequestError, RespondToJoinRequestErrors, RespondToJoinRequestRequest, RespondToJoinRequestResponse, RespondToJoinRequestResponses, RsvpCalendarEventData, RsvpCalendarEventError, RsvpCalendarEventErrors, RsvpCalendarEventRequest, RsvpCalendarEventResponse, RsvpCalendarEventResponses, SetAvailabilityCalendarData, SetAvailabilityCalendarResponse, SetAvailabilityCalendarResponses, SetTeamSharingData, SetTeamSharingResponse, SetTeamSharingResponses, TeamCalendarContent, TeamCalendarDetails, TeamCalendarItem, TeamCalendarSharing, TeamCalendarSharingBody, UnlinkEventNoteData, UnlinkEventNoteResponse, UnlinkEventNoteResponses, UpdateCalendarEventData, UpdateCalendarEventError, UpdateCalendarEventErrors, UpdateCalendarEventRequest, UpdateCalendarEventResponse, UpdateCalendarEventResponses, ViewerCapabilities, VisibleCalendar } from './types.gen';
diff --git a/packages/sdk/generated/calendar/sdk.gen.ts b/packages/sdk/generated/calendar/sdk.gen.ts
index a2d98fa499..61719da738 100644
--- a/packages/sdk/generated/calendar/sdk.gen.ts
+++ b/packages/sdk/generated/calendar/sdk.gen.ts
@@ -250,7 +250,7 @@ export class Sdk extends HeyApiClient {
}
/**
- * List an owned document's meeting grants, including unavailable meetings.
+ * List a document's visible meeting links; owners also see unavailable grants.
*/
public documentNoteLinks<ThrowOnError extends boolean = false>(options: Options<DocumentNoteLinksData, ThrowOnError>): RequestResult<DocumentNoteLinksResponses, unknown, ThrowOnError> {
return (options.client ?? this.client).get<DocumentNoteLinksResponses, unknown, ThrowOnError>({ url: '/meeting-notes/documents/{document_id}/links', ...options });
diff --git a/packages/sdk/generated/calendar/types.gen.ts b/packages/sdk/generated/calendar/types.gen.ts
index 8a45370adc..f7c2d0eafd 100644
--- a/packages/sdk/generated/calendar/types.gen.ts
+++ b/packages/sdk/generated/calendar/types.gen.ts
@@ -394,6 +394,81 @@ export type CalendarJoinRequestDecision = 'accept' | 'decline';
*/
export type CalendarJoinRequestStatus = 'pending' | 'accepted' | 'declined';
+/**
+ * Meeting-level fields shown in a calendar event mention preview, taken from
+ * the requester's own projection of the meeting, or — when the requester has
+ * none — from the mentioned projection a channel they belong to was given.
+ */
+export type CalendarMentionEvent = {
+ /**
+ * Number of attendees on the previewed copy.
+ */
+ attendeeCount: number;
+ /**
+ * For a channel-shared preview, whether the person who shared it can
+ * add the requester as a guest. Always false for the requester's own
+ * copy.
+ */
+ canRequestToJoin?: boolean;
+ /**
+ * Provider description, plain text or HTML, truncated for the preview.
+ * Clients must sanitize it before rendering.
+ */
+ description?: string | null;
+ /**
+ * Whether the event repeats.
+ */
+ isRecurring: boolean;
+ joinRequestStatus?: null | CalendarJoinRequestStatus;
+ /**
+ * Location label, when set.
+ */
+ location?: string | null;
+ /**
+ * Key of the previewed instance, absent when no occurrence is
+ * materialized.
+ */
+ occurrenceKey?: string | null;
+ /**
+ * Organizer email.
+ */
+ organizerEmail?: string | null;
+ /**
+ * Organizer display name.
+ */
+ organizerName?: string | null;
+ /**
+ * Time of the previewed instance: the requested occurrence when it
+ * exists, else the next upcoming one, else the latest past one, else the
+ * series start.
+ */
+ time: EventTime;
+ /**
+ * Display title.
+ */
+ title: string;
+ /**
+ * Entity update time of the previewed copy.
+ */
+ updatedAt: string;
+ viewerCopy?: null | CalendarMentionViewerCopy;
+ /**
+ * The requester's own event entity for the mentioned meeting. Differs
+ * from the mentioned id when the mention came from another attendee.
+ * Absent when the meeting is on none of the requester's calendars and
+ * they see it only because it was shared with one of their channels:
+ * that preview is read-only and there is no event of theirs to open.
+ */
+ viewerEventId?: string | null;
+};
+
+/**
+ * How a requester holds a mentioned meeting on their own calendar, decided
+ * by the copy's own inbox, the way viewer capabilities decide organizer and
+ * guest.
+ */
+export type CalendarMentionViewerCopy = 'snapshot' | 'invitation' | 'event';
+
/**
* HTTP error body returned by calendar mutation endpoints.
*/
@@ -573,13 +648,18 @@ export type CreateCalendarEventRequest = {
};
/**
- * An owner's durable sharing link, including meetings they can no longer open.
+ * A visible meeting link, or an owner's durable grant they can no longer open.
*/
export type DocumentNoteLink = {
/**
- * Current name of the owned markdown document.
+ * Whether the reader may resolve this exact meeting's details right now.
+ */
+ canViewMeeting: boolean;
+ /**
+ * Current name of the markdown document.
*/
documentName: string;
+ event?: null | CalendarMentionEvent;
/**
* Linked calendar copy.
*/
@@ -593,6 +673,7 @@ export type DocumentNoteLink = {
*/
occurrenceKey: string;
team?: null | NoteTeam;
+ teamEvent?: null | TeamCalendarItem;
};
/**
@@ -911,6 +992,80 @@ export type RsvpCalendarEventRequest = {
scope?: null | CalendarRsvpScopeParam;
};
+/**
+ * Disjoint busy/detail shapes prevent new event fields leaking by default.
+ */
+export type TeamCalendarContent = {
+ kind: 'busy';
+} | {
+ /**
+ * Detail projection.
+ */
+ details: TeamCalendarDetails;
+ kind: 'details';
+};
+
+/**
+ * Safe details from a single authorized source.
+ */
+export type TeamCalendarDetails = {
+ /**
+ * Attendees; self flags are relative to the requesting viewer.
+ */
+ attendees: Array<CalendarAttendee>;
+ /**
+ * Source calendar name, shown only with details.
+ */
+ calendarName: string;
+ /**
+ * Join URL, if supplied by this source.
+ */
+ conferenceUrl?: string | null;
+ /**
+ * Body, if supplied by this source.
+ */
+ description?: string | null;
+ /**
+ * Location, if supplied by this source.
+ */
+ location?: string | null;
+ /**
+ * Organizer address from this source.
+ */
+ organizerEmail?: string | null;
+ /**
+ * Organizer name from this source.
+ */
+ organizerName?: string | null;
+ /**
+ * Display title.
+ */
+ title: string;
+};
+
+/**
+ * A read-only team calendar occurrence.
+ */
+export type TeamCalendarItem = TeamCalendarContent & {
+ /**
+ * Whether this occurrence blocks the sharer's personal availability.
+ * A subscribed calendar's block can be shared without occupying the sharer.
+ */
+ contributesToAvailability: boolean;
+ /**
+ * Stable opaque projection identity, never an event entity id.
+ */
+ id: string;
+ /**
+ * The person sharing access to the source.
+ */
+ ownerId: string;
+ /**
+ * Occurrence interval.
+ */
+ time: EventTime;
+};
+
/**
* What a user exposes through their team membership.
*/
diff --git a/packages/sdk/specs/calendar.json b/packages/sdk/specs/calendar.json
index 7afaad6b95..fafd7f2792 100644
--- a/packages/sdk/specs/calendar.json
+++ b/packages/sdk/specs/calendar.json
@@ -1008,7 +1008,7 @@
"/meeting-notes/documents/{document_id}/links": {
"get": {
"tags": ["calendar_events"],
- "summary": "List an owned document's meeting grants, including unavailable meetings.",
+ "summary": "List a document's visible meeting links; owners also see unavailable grants.",
"operationId": "document_note_links",
"parameters": [
{
@@ -1665,6 +1665,97 @@
"description": "Lifecycle of a request to be added as a guest of a shared event.",
"enum": ["pending", "accepted", "declined"]
},
+ "CalendarMentionEvent": {
+ "type": "object",
+ "description": "Meeting-level fields shown in a calendar event mention preview, taken from\nthe requester's own projection of the meeting, or — when the requester has\nnone — from the mentioned projection a channel they belong to was given.",
+ "required": [
+ "title",
+ "time",
+ "isRecurring",
+ "attendeeCount",
+ "updatedAt"
+ ],
+ "properties": {
+ "attendeeCount": {
+ "type": "integer",
+ "description": "Number of attendees on the previewed copy.",
+ "minimum": 0
+ },
+ "canRequestToJoin": {
+ "type": "boolean",
+ "description": "For a channel-shared preview, whether the person who shared it can\nadd the requester as a guest. Always false for the requester's own\ncopy."
+ },
+ "description": {
+ "type": ["string", "null"],
+ "description": "Provider description, plain text or HTML, truncated for the preview.\nClients must sanitize it before rendering."
+ },
+ "isRecurring": {
+ "type": "boolean",
+ "description": "Whether the event repeats."
+ },
+ "joinRequestStatus": {
+ "oneOf": [
+ {
+ "type": "null"
+ },
+ {
+ "$ref": "#/components/schemas/CalendarJoinRequestStatus",
+ "description": "For a channel-shared preview, the requester's request to join, if any."
+ }
+ ]
+ },
+ "location": {
+ "type": ["string", "null"],
+ "description": "Location label, when set."
+ },
+ "occurrenceKey": {
+ "type": ["string", "null"],
+ "description": "Key of the previewed instance, absent when no occurrence is\nmaterialized."
+ },
+ "organizerEmail": {
+ "type": ["string", "null"],
+ "description": "Organizer email."
+ },
+ "organizerName": {
+ "type": ["string", "null"],
+ "description": "Organizer display name."
+ },
+ "time": {
+ "$ref": "#/components/schemas/EventTime",
+ "description": "Time of the previewed instance: the requested occurrence when it\nexists, else the next upcoming one, else the latest past one, else the\nseries start."
+ },
+ "title": {
+ "type": "string",
+ "description": "Display title."
+ },
+ "updatedAt": {
+ "type": "string",
+ "format": "date-time",
+ "description": "Entity update time of the previewed copy."
+ },
+ "viewerCopy": {
+ "oneOf": [
+ {
+ "type": "null"
+ },
+ {
+ "$ref": "#/components/schemas/CalendarMentionViewerCopy",
+ "description": "How the requester holds the meeting through `viewer_event_id`; absent\nexactly when that is."
+ }
+ ]
+ },
+ "viewerEventId": {
+ "type": ["string", "null"],
+ "format": "uuid",
+ "description": "The requester's own event entity for the mentioned meeting. Differs\nfrom the mentioned id when the mention came from another attendee.\nAbsent when the meeting is on none of the requester's calendars and\nthey see it only because it was shared with one of their channels:\nthat preview is read-only and there is no event of theirs to open."
+ }
+ }
+ },
+ "CalendarMentionViewerCopy": {
+ "type": "string",
+ "description": "How a requester holds a mentioned meeting on their own calendar, decided\nby the copy's own inbox, the way viewer capabilities decide organizer and\nguest.",
+ "enum": ["snapshot", "invitation", "event"]
+ },
"CalendarMutationApiError": {
"type": "object",
"description": "HTTP error body returned by calendar mutation endpoints.",
@@ -1942,12 +2033,33 @@
},
"DocumentNoteLink": {
"type": "object",
- "description": "An owner's durable sharing link, including meetings they can no longer open.",
- "required": ["documentName", "eventId", "occurrenceKey", "eventTitle"],
+ "description": "A visible meeting link, or an owner's durable grant they can no longer open.",
+ "required": [
+ "documentName",
+ "eventId",
+ "occurrenceKey",
+ "eventTitle",
+ "canViewMeeting"
+ ],
"properties": {
+ "canViewMeeting": {
+ "type": "boolean",
+ "description": "Whether the reader may resolve this exact meeting's details right now."
+ },
"documentName": {
"type": "string",
- "description": "Current name of the owned markdown document."
+ "description": "Current name of the markdown document."
+ },
+ "event": {
+ "oneOf": [
+ {
+ "type": "null"
+ },
+ {
+ "$ref": "#/components/schemas/CalendarMentionEvent",
+ "description": "Exact accessible calendar preview, resolved with this link's authorization snapshot."
+ }
+ ]
},
"eventId": {
"type": "string",
@@ -1972,6 +2084,17 @@
"description": "Independent optional team audience."
}
]
+ },
+ "teamEvent": {
+ "oneOf": [
+ {
+ "type": "null"
+ },
+ {
+ "$ref": "#/components/schemas/TeamCalendarItem",
+ "description": "Exact, sanitized team-calendar details when the meeting is shared through a team."
+ }
+ ]
}
}
},
@@ -2386,6 +2509,110 @@
}
}
},
+ "TeamCalendarContent": {
+ "oneOf": [
+ {
+ "type": "object",
+ "description": "No provider or event metadata.",
+ "required": ["kind"],
+ "properties": {
+ "kind": {
+ "type": "string",
+ "enum": ["busy"]
+ }
+ }
+ },
+ {
+ "type": "object",
+ "description": "Explicitly authorized source content.",
+ "required": ["details", "kind"],
+ "properties": {
+ "details": {
+ "$ref": "#/components/schemas/TeamCalendarDetails",
+ "description": "Detail projection."
+ },
+ "kind": {
+ "type": "string",
+ "enum": ["details"]
+ }
+ }
+ }
+ ],
+ "description": "Disjoint busy/detail shapes prevent new event fields leaking by default."
+ },
+ "TeamCalendarDetails": {
+ "type": "object",
+ "description": "Safe details from a single authorized source.",
+ "required": ["title", "attendees", "calendarName"],
+ "properties": {
+ "attendees": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/CalendarAttendee"
+ },
+ "description": "Attendees; self flags are relative to the requesting viewer."
+ },
+ "calendarName": {
+ "type": "string",
+ "description": "Source calendar name, shown only with details."
+ },
+ "conferenceUrl": {
+ "type": ["string", "null"],
+ "description": "Join URL, if supplied by this source."
+ },
+ "description": {
+ "type": ["string", "null"],
+ "description": "Body, if supplied by this source."
+ },
+ "location": {
+ "type": ["string", "null"],
+ "description": "Location, if supplied by this source."
+ },
+ "organizerEmail": {
+ "type": ["string", "null"],
+ "description": "Organizer address from this source."
+ },
+ "organizerName": {
+ "type": ["string", "null"],
+ "description": "Organizer name from this source."
+ },
+ "title": {
+ "type": "string",
+ "description": "Display title."
+ }
+ }
+ },
+ "TeamCalendarItem": {
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/TeamCalendarContent",
+ "description": "Authorized content variant."
+ },
+ {
+ "type": "object",
+ "required": ["id", "ownerId", "time", "contributesToAvailability"],
+ "properties": {
+ "contributesToAvailability": {
+ "type": "boolean",
+ "description": "Whether this occurrence blocks the sharer's personal availability.\nA subscribed calendar's block can be shared without occupying the sharer."
+ },
+ "id": {
+ "type": "string",
+ "description": "Stable opaque projection identity, never an event entity id."
+ },
+ "ownerId": {
+ "type": "string",
+ "description": "The person sharing access to the source."
+ },
+ "time": {
+ "$ref": "#/components/schemas/EventTime",
+ "description": "Occurrence interval."
+ }
+ }
+ }
+ ],
+ "description": "A read-only team calendar occurrence."
+ },
"TeamCalendarSharing": {
"type": "string",
"description": "What a user exposes through their team membership.",
diff --git a/packages/sdk/src/entities/documents/document.ts b/packages/sdk/src/entities/documents/document.ts
index 8a90fd26b1..ca12389a78 100644
--- a/packages/sdk/src/entities/documents/document.ts
+++ b/packages/sdk/src/entities/documents/document.ts
@@ -56,7 +56,7 @@ export class Document
extends PropertiedEntity<DocumentDetail>
implements Mentionable
{
- /** Owner-only meeting grants, including unavailable meetings. Unlink a returned note to revoke its meeting/team access. */
+ /** Meeting links visible to the reader. Owners also receive unavailable grants and may unlink them to revoke meeting/team access. */
async meetingNotes(): Promise<
Array<{ note: CalendarNote; eventTitle: string }>
> {