@notionhq/apps 0.0.12 → 0.0.14

package/src/calendar.generated.ts

@@ -0,0 +1,1117 @@
+// Generated by notion tool-core codegen-script-types --connections. Do not edit.
+import type { ConnectionActionInvoker } from "./connection-actions.js"
+/**
+ * Script input for the "List available calendar resources (such as conference rooms)." effect (`calendar.listCalendarResources`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * Search for resources (often conference rooms) and check their availability for specific time slots.
+ * Resources are scoped to a single account; pass `calendar` to target the account of the event you intend to attach the rooms to.
+ * Only works with Google Workspace accounts that have admin permissions to view calendar resources.
+ * Use this tool to find rooms when creating in-person meetings.
+ * Pass multiple meeting times in timeSlots to get available rooms for each time slot independently.
+ */
+export type ListCalendarResourcesScriptInput = {
+	/**
+	 * Specific time slots to check. Returns available resources for each time slot independently.
+	 */
+	timeSlots: Array<{
+		/**
+		 * Start of the time slot to check, as an ISO 8601 date-time.
+		 */
+		startAt: string
+		/**
+		 * End of the time slot to check, as an ISO 8601 date-time.
+		 */
+		endAt: string
+	}>
+	/**
+	 * Minimum room capacity (number of people). MUST include the meeting organizer/user themselves in the count. For a 1-on-1, pass 2. For a meeting with N invitees besides the user, pass N+1.
+	 */
+	minCapacity: number
+	/**
+	 * Maximum number of resources to return per time slot (default: 20, max: 40)
+	 */
+	maxCount?: number
+	/**
+	 * If true, do not narrow rooms to the user's working-location building for this day. Set this when the user is explicitly asking about rooms in a different office (e.g. for a visiting team).
+	 */
+	ignoreWorkingLocation?: boolean
+	/**
+	 * Date-times of returned events will be expressed in this time-zone
+	 */
+	timeZone: string
+	/**
+	 * Calendar of the event the rooms will be attached to. Rooms are scoped to a single account.
+	 */
+	calendar?: {
+		/**
+		 * Account that owns the target calendar.
+		 */
+		accountId: string
+		/**
+		 * Target calendar identifier within the account.
+		 */
+		calendarId: string
+	}
+}
+
+/**
+ * Canonical Tool Core output for the "List available calendar resources (such as conference rooms)." effect (`calendar.listCalendarResources`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type ListCalendarResourcesScriptOutput = {
+	/**
+	 * Results for each requested time slot, with available rooms sorted by capacity
+	 */
+	resultsBySlot: Array<{
+		/**
+		 * The time slot being checked
+		 */
+		timeSlot: {
+			startAt: string
+			endAt: string
+		}
+		/**
+		 * Available conference rooms for this time slot, sorted by increasing capacity (smallest rooms first)
+		 */
+		availableResources: Array<{
+			/**
+			 * Use this as the email when adding rooms to events
+			 */
+			resourceEmail: string
+			/**
+			 * Display name of the conference room
+			 */
+			resourceName: string
+			/**
+			 * Building information
+			 */
+			building?: {
+				buildingId: string
+				buildingName?: string
+			}
+			/**
+			 * Maximum number of people the room can accommodate
+			 */
+			capacity?: number
+			/**
+			 * Floor location
+			 */
+			floor?: string
+			/**
+			 * Room description
+			 */
+			description?: string
+		}>
+	}>
+}
+
+/**
+ * Script input for the "Fetch list of calendars of the user." effect (`calendar.listCalendars`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * List of calendars grouped by account.
+ */
+export type ListCalendarsScriptInput = {
+	/**
+	 * Return only accounts linked to these email addresses. Useful to get calendars from a work account only for example. Do not specify if you are interested in getting the whole picture of someone's agenda across work and personal accounts.
+	 */
+	onlyAccountEmails?: Array<string>
+}
+
+/**
+ * Canonical Tool Core output for the "Fetch list of calendars of the user." effect (`calendar.listCalendars`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type ListCalendarsScriptOutput = {
+	accounts: Array<{
+		accountId: string
+		/**
+		 * Google, Apple iCloud, Outlook, etc.
+		 */
+		providerName: string
+		/**
+		 * The user email associated with this account. Useful to know if this account and its data should be used depending on context.
+		 */
+		email?: string
+		/**
+		 * Whether this account is work-related or a personal account, if we know this information.
+		 */
+		category?: "work" | "personal"
+		capabilities: {
+			/**
+			 * Does this account expose any calendars?
+			 */
+			readCalendars: boolean
+			/**
+			 * Can we read calendar events from calendars of this account?
+			 */
+			readEvents: boolean
+			/**
+			 * Can we write events in some calendars of this account? Calendars themselves might have their own set of restrictions.
+			 */
+			writeEvents: boolean
+			/**
+			 * Can we use a text search query to find events in the calendars of this account?
+			 */
+			searchEvents: boolean
+			/**
+			 * Does this account expose contacts?
+			 */
+			readContacts: boolean
+		}
+		/**
+		 * User can access the events of co-workers having an email address with one of these domains
+		 */
+		coworkersEmailDomains?: Array<string>
+		calendars: Array<{
+			accountId: string
+			calendarId: string
+			name: string
+			description?: string
+			colors?: {
+				foreground?: string
+				background?: string
+			}
+			isPrimary: boolean
+			/**
+			 * Is this calendar read-only or can the user create/edit/delete events?
+			 */
+			isReadOnly: boolean
+			/**
+			 * The contents of a calendar appear in the user calendar app only if that calendar is selected.
+			 * Calendars that are not selected might be useful to get lower-signal events, but probably not to create events as it might not be visible to the user.
+			 */
+			isSelected: boolean
+			/**
+			 * A hidden calendar is a calendar the user has access to but decided to hide completely from their calendar app.
+			 * Hidden calendars might be useful to know what you might have access to, but keep in mind the user hid them and is most likely not aware of their content.
+			 */
+			isHidden: boolean
+			/**
+			 * The email address of the owner of this calendar.
+			 */
+			ownerEmail?: string
+		}>
+	}>
+}
+
+/**
+ * Script input for the "List contacts" effect (`calendar.listContacts`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * List the user's contacts from different accounts. Returns contact information including email addresses, names, phone numbers, and profile photos.
+ */
+export type ListContactsScriptInput = {
+	/**
+	 * Optional search queries to filter contacts by name or email. Results matching any query are included.
+	 */
+	queries?: Array<string>
+}
+
+/**
+ * Canonical Tool Core output for the "List contacts" effect (`calendar.listContacts`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type ListContactsScriptOutput = {
+	accounts: Array<{
+		accountId: string
+		/**
+		 * Google, Apple iCloud, Outlook, etc.
+		 */
+		providerName: string
+		/**
+		 * The user email associated with this account. Useful to know if this account and its data should be used depending on context.
+		 */
+		email?: string
+		/**
+		 * Whether this account is work-related or a personal account, if we know this information.
+		 */
+		category?: "work" | "personal"
+		capabilities: {
+			/**
+			 * Does this account expose any calendars?
+			 */
+			readCalendars: boolean
+			/**
+			 * Can we read calendar events from calendars of this account?
+			 */
+			readEvents: boolean
+			/**
+			 * Can we write events in some calendars of this account? Calendars themselves might have their own set of restrictions.
+			 */
+			writeEvents: boolean
+			/**
+			 * Can we use a text search query to find events in the calendars of this account?
+			 */
+			searchEvents: boolean
+			/**
+			 * Does this account expose contacts?
+			 */
+			readContacts: boolean
+		}
+		/**
+		 * User can access the events of co-workers having an email address with one of these domains
+		 */
+		coworkersEmailDomains?: Array<string>
+		contacts: Array<{
+			/**
+			 * Unique identifier for the contact
+			 */
+			id: string
+			/**
+			 * Primary email address of the contact
+			 */
+			email: string
+			/**
+			 * Additional email addresses for this contact
+			 */
+			alternateEmails?: Array<string>
+			/**
+			 * Display name of the contact
+			 */
+			displayName?: string
+			/**
+			 * Phone numbers associated with this contact
+			 */
+			phoneNumbers?: Array<{
+				/**
+				 * The type of phone number (e.g., home, work, mobile)
+				 */
+				type?: string
+				/**
+				 * The phone number value
+				 */
+				value: string
+			}>
+			/**
+			 * URL to the contact's profile photo
+			 */
+			photoUrl?: string
+		}>
+	}>
+}
+
+/**
+ * Script input for the "View coworkers' scheduled events." effect (`calendar.listCoworkersEvents`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * Retrieves the detailed calendar events for specific coworkers within a time range.
+ * Use this to see what meetings or events people have scheduled, including event titles, times, and details.
+ * Only works for coworkers in the same organization domain.
+ */
+export type ListCoworkersEventsScriptInput = {
+	/**
+	 * Emails of relevant coworkers
+	 */
+	coworkerEmails: Array<string>
+	/**
+	 * Start of the time range, as an ISO 8601 date-time.
+	 */
+	timeMin: string
+	/**
+	 * End of the time range, as an ISO 8601 date-time.
+	 */
+	timeMax: string
+	/**
+	 * Date-times of returned events will be expressed in this time-zone
+	 */
+	timeZone: string
+}
+
+/**
+ * Canonical Tool Core output for the "View coworkers' scheduled events." effect (`calendar.listCoworkersEvents`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type ListCoworkersEventsScriptOutput = {
+	/**
+	 * List of coworkers with their scheduled calendar events. Some coworkers may be excluded if their calendar could not be accessed.
+	 */
+	coworkers: Array<{
+		accountId: string
+		coworkerEmail: string
+		profile?: {
+			displayName?: string
+			email?: string
+			photoUrl?: string
+		}
+		events: Array<{
+			calendar: {
+				accountId: string
+				calendarId: string
+			}
+			eventId: string
+			summary: string
+			description?: string
+			/**
+			 * Physical location where the event takes place, or remote conference link/info.
+			 */
+			location?: string
+			/**
+			 * Recurrence rules in RRULE format (e.g., ['RRULE:FREQ=WEEKLY;COUNT=10']). Can also include EXDATE for exception dates (e.g., ['RRULE:FREQ=WEEKLY;COUNT=10', 'EXDATE:2026-03-24T13:00:00']).
+			 */
+			recurrenceRules?: Array<string>
+			/**
+			 * The data provider this event belongs to
+			 */
+			provider?: "google" | "notion" | "icloud" | "outlook"
+			/**
+			 * The URL to view the event in the Calendar app.
+			 */
+			webUrl: string
+			/**
+			 * When the event is happening
+			 */
+			period:
+				| {
+						type: "DATE"
+						start: {
+							/**
+							 * Date in ISO 8601 format (no time)
+							 */
+							date: string
+						}
+						end: {
+							/**
+							 * Date in ISO 8601 format (no time)
+							 */
+							date: string
+						}
+				  }
+				| {
+						type: "DATE_TIME"
+						start: {
+							/**
+							 * Date-time in ISO 8601 format, in UTC (ending with Z), or with TZ offset
+							 */
+							dateTime: string
+							timeZone?: string
+						}
+						end: {
+							/**
+							 * Date-time in ISO 8601 format, in UTC (ending with Z), or with TZ offset
+							 */
+							dateTime: string
+							timeZone?: string
+						}
+				  }
+			/**
+			 * Whether it's part of a recurring event series
+			 */
+			isRecurring: boolean
+			/**
+			 * If true, the event does not block time on the calendar. This is equivalent to setting `Show me as to Available` in the Calendar UI.
+			 */
+			isTransparent: boolean
+			/**
+			 * Is the event an auto-blocking event created from another event? Used to create blocked events on a calendar from events on another calendar. You can ignore auto-blocked events if there are events happening at the exact same time on other calendars.
+			 */
+			isAutoBlock: boolean
+			/**
+			 * What kind of event is it? Standard, out of office, birthday...
+			 */
+			eventType?:
+				| "fromGmail"
+				| "default"
+				| "focusTime"
+				| "outOfOffice"
+				| "birthday"
+				| "availability"
+			/**
+			 * Is an event confirmed, tentative or cancelled? This is different from the user's RSVP
+			 */
+			eventStatus?: "confirmed" | "tentative" | "cancelled"
+			/**
+			 * Whether it's a meeting, aka an event with attendees listed
+			 */
+			isMeeting: boolean
+			conferencingEntryPoints?: Array<{
+				uri: string
+				accessCode?: string
+				entryPointType?: "video" | "phone" | "sip" | "more"
+				label?: string
+				meetingCode?: string
+				passcode?: string
+				password?: string
+				pin?: string
+				notes?: string
+				signature?: string
+			}>
+			/**
+			 * The URL to join the video conference, if available
+			 */
+			conferencingUrl?: string
+			/**
+			 * The calendar user's RSVP status
+			 */
+			responseStatus?: "needsAction" | "accepted" | "declined" | "tentative"
+			creator?: {
+				/**
+				 * Whether this entry represents the calendar user
+				 */
+				isSelf: boolean
+				displayName?: string
+				email?: string
+			}
+			organizer?: {
+				/**
+				 * Whether this entry represents the calendar user
+				 */
+				isSelf: boolean
+				displayName?: string
+				email?: string
+			}
+			attendees?: Array<{
+				/**
+				 * Whether this entry represents the calendar user
+				 */
+				isSelf: boolean
+				displayName?: string
+				email?: string
+				isOptional: boolean
+				isOrganizer?: boolean
+				/**
+				 * The calendar user's RSVP status
+				 */
+				responseStatus?: "needsAction" | "accepted" | "declined" | "tentative"
+			}>
+			resources?: Array<{
+				displayName?: string
+				email?: string
+				isOptional: boolean
+				/**
+				 * The calendar user's RSVP status
+				 */
+				responseStatus?: "needsAction" | "accepted" | "declined" | "tentative"
+			}>
+			colors?: {
+				foreground?: string
+				background?: string
+			}
+			attachments?: Array<{
+				url: string
+				mimeType?: string
+				title?: string
+				notionWorkspaceId?: string
+			}>
+		}>
+	}>
+	errors?: Array<{
+		/**
+		 * An identifier for the item that failed (e.g., event summary for creation, event ID for updates/cancellations)
+		 */
+		identifier: string
+		/**
+		 * Description of the error that occurred
+		 */
+		errorMessage: string
+	}>
+}
+
+/**
+ * Script input for the "List the user's events from different calendars." effect (`calendar.listEvents`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * Date-times will be expressed in the time-zone passed as parameter.
+ */
+export type ListEventsScriptInput = {
+	/**
+	 * Start of the time range, as an ISO 8601 date-time.
+	 */
+	timeMin: string
+	/**
+	 * End of the time range, as an ISO 8601 date-time.
+	 */
+	timeMax: string
+	/**
+	 * Date-times of returned events will be expressed in this time-zone
+	 */
+	timeZone: string
+	/**
+	 * Whether to include event invites the user has declined
+	 */
+	includeDeclinedInvites?: boolean | null
+}
+
+/**
+ * Canonical Tool Core output for the "List the user's events from different calendars." effect (`calendar.listEvents`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type ListEventsScriptOutput = {
+	accounts: Array<{
+		accountId: string
+		/**
+		 * Google, Apple iCloud, Outlook, etc.
+		 */
+		providerName: string
+		/**
+		 * The user email associated with this account. Useful to know if this account and its data should be used depending on context.
+		 */
+		email?: string
+		/**
+		 * Whether this account is work-related or a personal account, if we know this information.
+		 */
+		category?: "work" | "personal"
+		capabilities: {
+			/**
+			 * Does this account expose any calendars?
+			 */
+			readCalendars: boolean
+			/**
+			 * Can we read calendar events from calendars of this account?
+			 */
+			readEvents: boolean
+			/**
+			 * Can we write events in some calendars of this account? Calendars themselves might have their own set of restrictions.
+			 */
+			writeEvents: boolean
+			/**
+			 * Can we use a text search query to find events in the calendars of this account?
+			 */
+			searchEvents: boolean
+			/**
+			 * Does this account expose contacts?
+			 */
+			readContacts: boolean
+		}
+		/**
+		 * User can access the events of co-workers having an email address with one of these domains
+		 */
+		coworkersEmailDomains?: Array<string>
+		calendars: Array<{
+			accountId: string
+			calendarId: string
+			name: string
+			description?: string
+			colors?: {
+				foreground?: string
+				background?: string
+			}
+			isPrimary: boolean
+			/**
+			 * Is this calendar read-only or can the user create/edit/delete events?
+			 */
+			isReadOnly: boolean
+			/**
+			 * The contents of a calendar appear in the user calendar app only if that calendar is selected.
+			 * Calendars that are not selected might be useful to get lower-signal events, but probably not to create events as it might not be visible to the user.
+			 */
+			isSelected: boolean
+			/**
+			 * A hidden calendar is a calendar the user has access to but decided to hide completely from their calendar app.
+			 * Hidden calendars might be useful to know what you might have access to, but keep in mind the user hid them and is most likely not aware of their content.
+			 */
+			isHidden: boolean
+			/**
+			 * The email address of the owner of this calendar.
+			 */
+			ownerEmail?: string
+			events: Array<{
+				calendar: {
+					accountId: string
+					calendarId: string
+				}
+				eventId: string
+				summary: string
+				description?: string
+				/**
+				 * Physical location where the event takes place, or remote conference link/info.
+				 */
+				location?: string
+				/**
+				 * Recurrence rules in RRULE format (e.g., ['RRULE:FREQ=WEEKLY;COUNT=10']). Can also include EXDATE for exception dates (e.g., ['RRULE:FREQ=WEEKLY;COUNT=10', 'EXDATE:2026-03-24T13:00:00']).
+				 */
+				recurrenceRules?: Array<string>
+				/**
+				 * The data provider this event belongs to
+				 */
+				provider?: "google" | "notion" | "icloud" | "outlook"
+				/**
+				 * The URL to view the event in the Calendar app.
+				 */
+				webUrl: string
+				/**
+				 * When the event is happening
+				 */
+				period:
+					| {
+							type: "DATE"
+							start: {
+								/**
+								 * Date in ISO 8601 format (no time)
+								 */
+								date: string
+							}
+							end: {
+								/**
+								 * Date in ISO 8601 format (no time)
+								 */
+								date: string
+							}
+					  }
+					| {
+							type: "DATE_TIME"
+							start: {
+								/**
+								 * Date-time in ISO 8601 format, in UTC (ending with Z), or with TZ offset
+								 */
+								dateTime: string
+								timeZone?: string
+							}
+							end: {
+								/**
+								 * Date-time in ISO 8601 format, in UTC (ending with Z), or with TZ offset
+								 */
+								dateTime: string
+								timeZone?: string
+							}
+					  }
+				/**
+				 * Whether it's part of a recurring event series
+				 */
+				isRecurring: boolean
+				/**
+				 * If true, the event does not block time on the calendar. This is equivalent to setting `Show me as to Available` in the Calendar UI.
+				 */
+				isTransparent: boolean
+				/**
+				 * Is the event an auto-blocking event created from another event? Used to create blocked events on a calendar from events on another calendar. You can ignore auto-blocked events if there are events happening at the exact same time on other calendars.
+				 */
+				isAutoBlock: boolean
+				/**
+				 * What kind of event is it? Standard, out of office, birthday...
+				 */
+				eventType?:
+					| "fromGmail"
+					| "default"
+					| "focusTime"
+					| "outOfOffice"
+					| "birthday"
+					| "availability"
+				/**
+				 * Is an event confirmed, tentative or cancelled? This is different from the user's RSVP
+				 */
+				eventStatus?: "confirmed" | "tentative" | "cancelled"
+				/**
+				 * Whether it's a meeting, aka an event with attendees listed
+				 */
+				isMeeting: boolean
+				conferencingEntryPoints?: Array<{
+					uri: string
+					accessCode?: string
+					entryPointType?: "video" | "phone" | "sip" | "more"
+					label?: string
+					meetingCode?: string
+					passcode?: string
+					password?: string
+					pin?: string
+					notes?: string
+					signature?: string
+				}>
+				/**
+				 * The URL to join the video conference, if available
+				 */
+				conferencingUrl?: string
+				/**
+				 * The calendar user's RSVP status
+				 */
+				responseStatus?: "needsAction" | "accepted" | "declined" | "tentative"
+				creator?: {
+					/**
+					 * Whether this entry represents the calendar user
+					 */
+					isSelf: boolean
+					displayName?: string
+					email?: string
+				}
+				organizer?: {
+					/**
+					 * Whether this entry represents the calendar user
+					 */
+					isSelf: boolean
+					displayName?: string
+					email?: string
+				}
+				attendees?: Array<{
+					/**
+					 * Whether this entry represents the calendar user
+					 */
+					isSelf: boolean
+					displayName?: string
+					email?: string
+					isOptional: boolean
+					isOrganizer?: boolean
+					/**
+					 * The calendar user's RSVP status
+					 */
+					responseStatus?: "needsAction" | "accepted" | "declined" | "tentative"
+				}>
+				resources?: Array<{
+					displayName?: string
+					email?: string
+					isOptional: boolean
+					/**
+					 * The calendar user's RSVP status
+					 */
+					responseStatus?: "needsAction" | "accepted" | "declined" | "tentative"
+				}>
+				colors?: {
+					foreground?: string
+					background?: string
+				}
+				attachments?: Array<{
+					url: string
+					mimeType?: string
+					title?: string
+					notionWorkspaceId?: string
+				}>
+			}>
+		}>
+	}>
+	/**
+	 * User preferences for calendar data
+	 */
+	userPreferences: {
+		/**
+		 * Whether the user prefers to display time in 12-hour (AM/PM) or 24-hour format
+		 */
+		timeFormat?: "12_HOUR" | "24_HOUR"
+	}
+	errors: Array<{
+		accountId: string
+		calendarId: string
+		error: string
+	}>
+}
+
+/**
+ * Script input for the "List the user's scheduling links." effect (`calendar.listSchedulingLinks`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * List active, unexpired scheduling links with upcoming time ranges, optionally filtered by link type.
+ */
+export type ListSchedulingLinksScriptInput = {
+	/**
+	 * Return only scheduling links of this type
+	 */
+	type?: "singleUse" | "multiUse" | "recurring"
+}
+
+/**
+ * Canonical Tool Core output for the "List the user's scheduling links." effect (`calendar.listSchedulingLinks`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type ListSchedulingLinksScriptOutput = {
+	schedulingLinks: Array<{
+		/**
+		 * Unique ID of the created scheduling link
+		 */
+		id: string
+		/**
+		 * Short ID used in the scheduling link URL
+		 */
+		shortId: string
+		/**
+		 * Current booking calendar for this scheduling link
+		 */
+		bookingCalendarRef: {
+			accountId: string
+			calendarId: string
+		}
+		/**
+		 * Custom URL slug for the scheduling link
+		 */
+		alias?: string
+		/**
+		 * The resolved type of the link
+		 */
+		type?: "singleUse" | "multiUse" | "recurring"
+		/**
+		 * Status of the scheduling link
+		 */
+		status: string
+		title?: string
+		description?: string
+		duration?: number
+		/**
+		 * Full URL where invitees can book a meeting
+		 */
+		schedulingLinkUrl?: string
+		timeRanges: Array<{
+			/**
+			 * Start of availability window in ISO 8601 format with timezone offset, e.g. '2024-08-22T09:00:00-04:00'
+			 */
+			startDate: string
+			/**
+			 * End of availability window in ISO 8601 format with timezone offset, e.g. '2024-08-22T17:00:00-04:00'
+			 */
+			endDate: string
+			/**
+			 * Recurrence rules in RRULE format (e.g., ['RRULE:FREQ=WEEKLY;COUNT=10']). Can also include EXDATE for exception dates (e.g., ['RRULE:FREQ=WEEKLY;COUNT=10', 'EXDATE:2026-03-24T13:00:00']).
+			 */
+			recurrence?: Array<string>
+			/**
+			 * Unique identifier for this time range
+			 */
+			id: string
+		}>
+	}>
+}
+
+/**
+ * Script input for the "Find available meeting times." effect (`calendar.suggestMeetingTimes`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * Analyzes calendar availability for multiple participants and returns ranked time slots when everyone is free.
+ * Use this when scheduling meetings or finding times that work for a group of people.
+ * Returns suggestions sorted by preference, showing which participants are available, softly conflicted by an unconfirmed RSVP, busy, or have unknown status for each slot.
+ */
+export type SuggestMeetingTimesScriptInput = {
+	/**
+	 * Individual participant or group email addresses to find time with. Resolvable groups are expanded into their members.
+	 */
+	participantEmails: Array<string>
+	/**
+	 * The duration of the meeting in minutes
+	 */
+	durationMinutes: number
+	/**
+	 * Start of the time range to consider, as an ISO 8601 date-time.
+	 */
+	timeMin: string
+	/**
+	 * End of the time range to consider, as an ISO 8601 date-time.
+	 */
+	timeMax: string
+	/**
+	 * Maximum number of suggestions to return (default: 10)
+	 */
+	maxCount?: number
+	/**
+	 * Date-times of returned events will be expressed in this time-zone
+	 */
+	timeZone: string
+	/**
+	 * Whether to include participant event schedules in the response
+	 */
+	includeParticipantSchedules?: boolean
+}
+
+/**
+ * Canonical Tool Core output for the "Find available meeting times." effect (`calendar.suggestMeetingTimes`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type SuggestMeetingTimesScriptOutput = {
+	/**
+	 * Ranked list of available meeting time slots, sorted from most to least preferable. Each slot includes start/end times and categorizes participants by availability status.
+	 */
+	suggestions: Array<{
+		/**
+		 * Start time in ISO 8601 format
+		 */
+		startAt: string
+		/**
+		 * End time in ISO 8601 format
+		 */
+		endAt: string
+		/**
+		 * Total number of hard event conflicts, including multiple events for one participant
+		 */
+		hardEventConflictCount: number
+		/**
+		 * Total number of soft event conflicts, including multiple events for one participant
+		 */
+		softEventConflictCount: number
+		/**
+		 * Participant emails for invitees with conflicts with this meeting time
+		 */
+		unavailableParticipants: Array<string>
+		/**
+		 * Participant emails for invitees who are available for this meeting time
+		 */
+		availableParticipants: Array<string>
+		/**
+		 * Participant emails for invitees with overlapping events whose RSVP is not firm yet
+		 */
+		softConflictParticipants: Array<string>
+		/**
+		 * Participant emails for invitees with unknown status
+		 */
+		unknownStatus: Array<string>
+		/**
+		 * Readable participant events that overlap this meeting time, including the participant and whether each event creates a hard or soft conflict
+		 */
+		conflictingEvents: Array<{
+			participantEmail: string
+			eventId: string
+			summary?: string
+			/**
+			 * What kind of event is it? Standard, out of office, birthday...
+			 */
+			eventType:
+				| "fromGmail"
+				| "default"
+				| "focusTime"
+				| "outOfOffice"
+				| "birthday"
+				| "availability"
+			/**
+			 * The calendar user's RSVP status
+			 */
+			responseStatus?: "needsAction" | "accepted" | "declined" | "tentative"
+			conflictType: "hard" | "soft"
+		}>
+	}>
+	/**
+	 * Whether one or more suggestions use a shorter duration than requested because no sufficiently conflict-free times were available at the requested duration
+	 */
+	usedFlexibleDuration: boolean
+	/**
+	 * List of participant schedules, one for each individual participant, including resolved group members. Each schedule includes basic participant information and a list of the participant's calendar events.
+	 */
+	participantSchedules?: Array<{
+		accountId: string
+		coworkerEmail: string
+		profile?: {
+			displayName?: string
+			email?: string
+			photoUrl?: string
+		}
+		events: Array<{
+			eventId: string
+			/**
+			 * What kind of event is it? Standard, out of office, birthday...
+			 */
+			eventType?:
+				| "fromGmail"
+				| "default"
+				| "focusTime"
+				| "outOfOffice"
+				| "birthday"
+				| "availability"
+			/**
+			 * Is an event confirmed, tentative or cancelled? This is different from the user's RSVP
+			 */
+			eventStatus?: "confirmed" | "tentative" | "cancelled"
+			summary: string
+			/**
+			 * When the event is happening
+			 */
+			period:
+				| {
+						type: "DATE"
+						start: {
+							/**
+							 * Date in ISO 8601 format (no time)
+							 */
+							date: string
+						}
+						end: {
+							/**
+							 * Date in ISO 8601 format (no time)
+							 */
+							date: string
+						}
+				  }
+				| {
+						type: "DATE_TIME"
+						start: {
+							/**
+							 * Date-time in ISO 8601 format, in UTC (ending with Z), or with TZ offset
+							 */
+							dateTime: string
+							timeZone?: string
+						}
+						end: {
+							/**
+							 * Date-time in ISO 8601 format, in UTC (ending with Z), or with TZ offset
+							 */
+							dateTime: string
+							timeZone?: string
+						}
+				  }
+			/**
+			 * The calendar user's RSVP status
+			 */
+			responseStatus?: "needsAction" | "accepted" | "declined" | "tentative"
+			colors?: {
+				foreground?: string
+				background?: string
+			}
+			/**
+			 * If true, the event does not block time on the calendar. This is equivalent to setting `Show me as to Available` in the Calendar UI.
+			 */
+			isTransparent: boolean
+			/**
+			 * Whether it's a meeting, aka an event with attendees listed
+			 */
+			isMeeting: boolean
+		}>
+	}>
+	errors?: Array<{
+		/**
+		 * An identifier for the item that failed (e.g., event summary for creation, event ID for updates/cancellations)
+		 */
+		identifier: string
+		/**
+		 * Description of the error that occurred
+		 */
+		errorMessage: string
+	}>
+}
+
+export class CalendarConnectionClient {
+	constructor(private readonly invoke: ConnectionActionInvoker) {}
+	listCalendarResources(
+		args: ListCalendarResourcesScriptInput,
+	): Promise<ListCalendarResourcesScriptOutput> {
+		return this.invoke<ListCalendarResourcesScriptOutput>(
+			"listCalendarResources",
+			args,
+		)
+	}
+	listCalendars(
+		args: ListCalendarsScriptInput,
+	): Promise<ListCalendarsScriptOutput> {
+		return this.invoke<ListCalendarsScriptOutput>("listCalendars", args)
+	}
+	listContacts(
+		args: ListContactsScriptInput,
+	): Promise<ListContactsScriptOutput> {
+		return this.invoke<ListContactsScriptOutput>("listContacts", args)
+	}
+	listCoworkersEvents(
+		args: ListCoworkersEventsScriptInput,
+	): Promise<ListCoworkersEventsScriptOutput> {
+		return this.invoke<ListCoworkersEventsScriptOutput>(
+			"listCoworkersEvents",
+			args,
+		)
+	}
+	listEvents(args: ListEventsScriptInput): Promise<ListEventsScriptOutput> {
+		return this.invoke<ListEventsScriptOutput>("listEvents", args)
+	}
+	listSchedulingLinks(
+		args: ListSchedulingLinksScriptInput,
+	): Promise<ListSchedulingLinksScriptOutput> {
+		return this.invoke<ListSchedulingLinksScriptOutput>(
+			"listSchedulingLinks",
+			args,
+		)
+	}
+	suggestMeetingTimes(
+		args: SuggestMeetingTimesScriptInput,
+	): Promise<SuggestMeetingTimesScriptOutput> {
+		return this.invoke<SuggestMeetingTimesScriptOutput>(
+			"suggestMeetingTimes",
+			args,
+		)
+	}
+}