@macro-inc/sdk 0.2.2 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (175) hide show
  1. package/README.md +177 -3
  2. package/dist/{chunk-OGE7WXJE.js → chunk-AZJUIUIV.js} +177 -23
  3. package/dist/{chunk-PRUFPW3B.js → chunk-G43PLP2U.js} +144 -0
  4. package/dist/{chunk-7LVVPVNT.js → chunk-K4G5VO4P.js} +76 -1
  5. package/dist/{chunk-PAAFJYGO.js → chunk-PPR7IWZ7.js} +77 -51
  6. package/dist/{chunk-QVBNNMQS.js → chunk-PTX2RV2N.js} +169 -20
  7. package/dist/{chunk-SUINKDXF.js → chunk-PZPTJI6F.js} +42 -0
  8. package/dist/{chunk-7YJ6Y7HJ.js → chunk-XFA7NCJ5.js} +207 -0
  9. package/dist/{chunk-ZQXOHNDB.js → chunk-ZLBDES7U.js} +789 -12
  10. package/dist/generated/agent-fold/index.d.ts +4332 -0
  11. package/dist/generated/agent-fold/index.js +0 -0
  12. package/dist/generated/agent-harness/index.d.ts +1 -1
  13. package/dist/generated/agent-harness/index.js +1 -1
  14. package/dist/generated/agent-harness/sdk.gen.d.ts +83 -9
  15. package/dist/generated/agent-harness/types.gen.d.ts +1504 -160
  16. package/dist/generated/agent-reviews/index.d.ts +893 -0
  17. package/dist/generated/agent-reviews/index.js +0 -0
  18. package/dist/generated/auth/index.d.ts +1 -1
  19. package/dist/generated/auth/index.js +1 -1
  20. package/dist/generated/auth/sdk.gen.d.ts +108 -2
  21. package/dist/generated/auth/types.gen.d.ts +799 -6
  22. package/dist/generated/calendar/index.d.ts +1 -1
  23. package/dist/generated/calendar/index.js +1 -1
  24. package/dist/generated/calendar/sdk.gen.d.ts +63 -1
  25. package/dist/generated/calendar/types.gen.d.ts +1234 -5
  26. package/dist/generated/cognition/index.d.ts +1 -1
  27. package/dist/generated/cognition/index.js +1 -1
  28. package/dist/generated/cognition/sdk.gen.d.ts +85 -20
  29. package/dist/generated/cognition/types.gen.d.ts +1040 -121
  30. package/dist/generated/connection/index.d.ts +1 -1
  31. package/dist/generated/connection/index.js +15 -0
  32. package/dist/generated/connection/sdk.gen.d.ts +6 -1
  33. package/dist/generated/connection/types.gen.d.ts +18 -1
  34. package/dist/generated/email/index.d.ts +1 -1
  35. package/dist/generated/email/index.js +1 -1
  36. package/dist/generated/email/sdk.gen.d.ts +44 -2
  37. package/dist/generated/email/types.gen.d.ts +475 -10
  38. package/dist/generated/notification/index.d.ts +1 -1
  39. package/dist/generated/notification/index.js +1 -1
  40. package/dist/generated/notification/sdk.gen.d.ts +29 -21
  41. package/dist/generated/notification/types.gen.d.ts +267 -73
  42. package/dist/generated/properties/index.d.ts +1 -1
  43. package/dist/generated/properties/types.gen.d.ts +21 -1
  44. package/dist/generated/scheduled-action/index.d.ts +1 -1
  45. package/dist/generated/scheduled-action/index.js +1 -1
  46. package/dist/generated/scheduled-action/sdk.gen.d.ts +8 -1
  47. package/dist/generated/scheduled-action/types.gen.d.ts +669 -19
  48. package/dist/generated/search/index.d.ts +1 -1
  49. package/dist/generated/search/types.gen.d.ts +87 -7
  50. package/dist/generated/static-files/types.gen.d.ts +6 -0
  51. package/dist/generated/storage/index.d.ts +1 -1
  52. package/dist/generated/storage/index.js +1 -1
  53. package/dist/generated/storage/sdk.gen.d.ts +376 -13
  54. package/dist/generated/storage/types.gen.d.ts +12038 -5562
  55. package/dist/src/entities/account-managers/grant.d.ts +39 -0
  56. package/dist/src/entities/account-managers/namespace.d.ts +17 -0
  57. package/dist/src/entities/agent-sessions/activity.d.ts +39 -0
  58. package/dist/src/entities/agent-sessions/agent-session.d.ts +148 -6
  59. package/dist/src/entities/agent-sessions/code-execution.d.ts +5 -0
  60. package/dist/src/entities/agent-sessions/namespace.d.ts +54 -4
  61. package/dist/src/entities/agent-sessions/origin.d.ts +94 -0
  62. package/dist/src/entities/agent-sessions/review.d.ts +18 -62
  63. package/dist/src/entities/agent-sessions/view.d.ts +11 -0
  64. package/dist/src/entities/agents/namespace.d.ts +11 -2
  65. package/dist/src/entities/ai/namespace.d.ts +5 -1
  66. package/dist/src/entities/api-keys/namespace.d.ts +5 -1
  67. package/dist/src/entities/bots/bot.d.ts +108 -0
  68. package/dist/src/entities/bots/namespace.d.ts +17 -4
  69. package/dist/src/entities/bots/token.d.ts +34 -0
  70. package/dist/src/entities/calendar/booking-link.d.ts +49 -0
  71. package/dist/src/entities/calendar/booking-namespace.d.ts +130 -0
  72. package/dist/src/entities/calendar/booking-namespace.test.d.ts +1 -0
  73. package/dist/src/entities/calendar/booking.d.ts +77 -0
  74. package/dist/src/entities/calendar/calendar.d.ts +11 -4
  75. package/dist/src/entities/calendar/create-confirmed.test.d.ts +1 -0
  76. package/dist/src/entities/calendar/event.d.ts +104 -3
  77. package/dist/src/entities/calendar/namespace.d.ts +151 -7
  78. package/dist/src/entities/calendar/namespace.test.d.ts +1 -0
  79. package/dist/src/entities/calls/call-record.d.ts +34 -4
  80. package/dist/src/entities/calls/connection.d.ts +53 -0
  81. package/dist/src/entities/calls/errors.d.ts +15 -0
  82. package/dist/src/entities/calls/namespace.d.ts +21 -1
  83. package/dist/src/entities/calls/participant.d.ts +22 -0
  84. package/dist/src/entities/channels/access-request.d.ts +34 -0
  85. package/dist/src/entities/channels/channel.d.ts +47 -1
  86. package/dist/src/entities/channels/namespace.d.ts +21 -5
  87. package/dist/src/entities/channels/namespace.test.d.ts +1 -0
  88. package/dist/src/entities/channels/post.d.ts +14 -3
  89. package/dist/src/entities/channels/thread.d.ts +10 -1
  90. package/dist/src/entities/chats/chat.d.ts +7 -1
  91. package/dist/src/entities/chats/namespace.d.ts +14 -1
  92. package/dist/src/entities/connected-apps/connected-app.d.ts +107 -0
  93. package/dist/src/entities/connected-apps/connector.d.ts +56 -0
  94. package/dist/src/entities/connected-apps/namespace.d.ts +74 -0
  95. package/dist/src/entities/crm/company.d.ts +7 -3
  96. package/dist/src/entities/crm/contact.d.ts +4 -4
  97. package/dist/src/entities/crm/namespace.d.ts +34 -1
  98. package/dist/src/entities/crm/pipeline.d.ts +43 -2
  99. package/dist/src/entities/databases/database.d.ts +17 -0
  100. package/dist/src/entities/databases/namespace.d.ts +56 -0
  101. package/dist/src/entities/documents/ai-edit.d.ts +52 -0
  102. package/dist/src/entities/documents/document.d.ts +244 -5
  103. package/dist/src/entities/documents/namespace.d.ts +89 -4
  104. package/dist/src/entities/documents/office-files.d.ts +47 -0
  105. package/dist/src/entities/email/draft.d.ts +36 -7
  106. package/dist/src/entities/email/message.d.ts +99 -3
  107. package/dist/src/entities/email/namespace.d.ts +47 -4
  108. package/dist/src/entities/email/namespace.test.d.ts +1 -0
  109. package/dist/src/entities/email/thread.d.ts +55 -3
  110. package/dist/src/entities/entity-mentions/namespace.d.ts +5 -1
  111. package/dist/src/entities/external-chat/chat.d.ts +105 -0
  112. package/dist/src/entities/external-chat/message.d.ts +54 -0
  113. package/dist/src/entities/external-chat/namespace.d.ts +18 -0
  114. package/dist/src/entities/external-chat/participant.d.ts +28 -0
  115. package/dist/src/entities/external-chat/send.d.ts +32 -0
  116. package/dist/src/entities/external-chat/upload.d.ts +25 -0
  117. package/dist/src/entities/favorites/namespace.d.ts +5 -1
  118. package/dist/src/entities/foreign/namespace.d.ts +3 -0
  119. package/dist/src/entities/forms/form.d.ts +17 -2
  120. package/dist/src/entities/forms/namespace.d.ts +5 -1
  121. package/dist/src/entities/github-pull-requests/namespace.d.ts +5 -1
  122. package/dist/src/entities/harnesses/harness.d.ts +9 -0
  123. package/dist/src/entities/harnesses/namespace.d.ts +5 -1
  124. package/dist/src/entities/images/image.d.ts +77 -0
  125. package/dist/src/entities/images/namespace.d.ts +48 -0
  126. package/dist/src/entities/images/namespace.test.d.ts +1 -0
  127. package/dist/src/entities/initiatives/initiative.d.ts +12 -1
  128. package/dist/src/entities/initiatives/namespace.d.ts +15 -2
  129. package/dist/src/entities/me/namespace.d.ts +43 -0
  130. package/dist/src/entities/meetings/meeting.d.ts +5 -0
  131. package/dist/src/entities/meetings/namespace.d.ts +5 -1
  132. package/dist/src/entities/messages/thread.d.ts +1 -1
  133. package/dist/src/entities/notifications/namespace.d.ts +3 -0
  134. package/dist/src/entities/pins/namespace.d.ts +5 -1
  135. package/dist/src/entities/projects/namespace.d.ts +4 -1
  136. package/dist/src/entities/projects/project.d.ts +9 -1
  137. package/dist/src/entities/properties/namespace.d.ts +2 -0
  138. package/dist/src/entities/referrals/namespace.d.ts +33 -0
  139. package/dist/src/entities/routines/namespace.d.ts +42 -2
  140. package/dist/src/entities/routines/routine.d.ts +84 -5
  141. package/dist/src/entities/search/namespace.d.ts +65 -0
  142. package/dist/src/entities/{search.d.ts → search/options.d.ts} +8 -2
  143. package/dist/src/entities/search/types.d.ts +90 -0
  144. package/dist/src/entities/sharing/access.d.ts +14 -0
  145. package/dist/src/entities/tasks/namespace.d.ts +42 -3
  146. package/dist/src/entities/tasks/task.d.ts +47 -6
  147. package/dist/src/entities/teams/invite.d.ts +30 -0
  148. package/dist/src/entities/teams/namespace.d.ts +3 -0
  149. package/dist/src/entities/teams/team.d.ts +37 -0
  150. package/dist/src/entities/unfurls/namespace.d.ts +5 -1
  151. package/dist/src/entities/users/namespace.d.ts +9 -0
  152. package/dist/src/entities/users/user.d.ts +8 -0
  153. package/dist/src/entities/web/namespace.d.ts +61 -0
  154. package/dist/src/entities/web/namespace.test.d.ts +1 -0
  155. package/dist/src/entities/webhooks/namespace.d.ts +2 -0
  156. package/dist/src/entities/whatsapp/account.d.ts +20 -0
  157. package/dist/src/entities/whatsapp/chat.d.ts +54 -0
  158. package/dist/src/entities/whatsapp/namespace.d.ts +23 -0
  159. package/dist/src/entities/workspace/items.d.ts +7 -0
  160. package/dist/src/entities/workspace/namespace.d.ts +14 -9
  161. package/dist/src/entities/workspace/query.d.ts +23 -0
  162. package/dist/src/entities/workspace/types.d.ts +6 -3
  163. package/dist/src/events/hydrate/agentSession.d.ts +1 -1
  164. package/dist/src/events/hydrate/call.d.ts +101 -0
  165. package/dist/src/events/hydrate/channel.d.ts +8 -1
  166. package/dist/src/events/hydrate/document.d.ts +1 -1
  167. package/dist/src/events/hydrate/message.d.ts +1 -1
  168. package/dist/src/events/types.d.ts +2 -1
  169. package/dist/src/macro.d.ts +73 -4
  170. package/dist/src/macro.js +8235 -3701
  171. package/dist/src/mentions.d.ts +6 -1
  172. package/dist/src/utils/activity.d.ts +23 -2
  173. package/dist/src/utils/index.d.ts +1 -1
  174. package/dist/src/utils/unwrap.d.ts +27 -2
  175. package/package.json +2 -2
@@ -1,4 +1,4 @@
1
- import type { AttendeeResponseStatus, CalendarAttendeeInputBody, CalendarDeletionScopeParam, CalendarEvent as CalendarEventRecord, CalendarRsvpScopeParam, CalendarUpdateScopeParam, ConferenceChange, EventReminders, EventTime, EventTransparency, EventVisibility, OutOfOfficeProperties } from '../../../generated/calendar/types.gen';
1
+ import type { AttendeeResponseStatus, CalendarAttendeeInputBody, CalendarDeletionScopeParam, CalendarEvent as CalendarEventRecord, CalendarGuestInputBody, CalendarRsvpScopeParam, CalendarUpdateScopeParam, ConferenceChange, EventReminders, EventTime, EventTransparency, EventVisibility, GuestPolicy, OutOfOfficeProperties } from '../../../generated/calendar/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import { MacroEntity } from '../entity';
4
4
  import { Calendar } from './calendar';
@@ -29,6 +29,11 @@ export interface UpdateEventOptions {
29
29
  /** Replacement out-of-office properties, applied only to an event that is
30
30
  * already out-of-office. */
31
31
  outOfOffice?: OutOfOfficeProperties;
32
+ /** Replacement guest policy; only the organizer of a Google event may change
33
+ * it (`viewerCan.setGuestPolicy`). It applies to the whole series, so an
34
+ * update scoped to one occurrence (`scope: 'this_event'`, or a `recurrenceId`)
35
+ * that changes it is rejected; use scope `'all'`. */
36
+ guestPolicy?: GuestPolicy;
32
37
  /** How much of a recurring series the update covers. Omit to let
33
38
  * `recurrenceId` decide. */
34
39
  scope?: CalendarUpdateScopeParam;
@@ -37,6 +42,12 @@ export interface UpdateEventOptions {
37
42
  /** Calendar whose copy of the event is patched, for a multi-calendar event.
38
43
  * Omit to patch the canonical copy. */
39
44
  calendar?: Calendar;
45
+ /** Address of the inbox holding the copy this call changes (an occurrence
46
+ * listing's `inbox`). When the meeting is on more than one of the user's
47
+ * inboxes, an agent must name it: the call is refused with
48
+ * `copy_choice_required`, listing each copy's inbox, role and event, until
49
+ * it does. It must be the inbox holding this copy. */
50
+ inbox?: string;
40
51
  }
41
52
  /** How a deletion is scoped across a recurring series. */
42
53
  export interface DeleteEventOptions {
@@ -47,6 +58,31 @@ export interface DeleteEventOptions {
47
58
  /** Calendar whose copy of the event is deleted, for a multi-calendar event.
48
59
  * Omit to delete the canonical copy. */
49
60
  calendar?: Calendar;
61
+ /** Address of the inbox holding the copy this call deletes (an occurrence
62
+ * listing's `inbox`). When the meeting is on more than one of the user's
63
+ * inboxes, an agent must name it: the call is refused with
64
+ * `copy_choice_required`, listing each copy's inbox, role and event, until
65
+ * it does. It must be the inbox holding this copy. */
66
+ inbox?: string;
67
+ }
68
+ /** Guests to add and how much of a recurring series gains them. */
69
+ export interface InviteGuestsOptions {
70
+ /** Guests to add; anyone already on the event is skipped. */
71
+ guests: CalendarGuestInputBody[];
72
+ /** How much of a recurring series gains the guests. Omit to let
73
+ * `recurrenceId` decide. */
74
+ scope?: CalendarUpdateScopeParam;
75
+ /** Original-start key of the occurrence the guests are added to. */
76
+ recurrenceId?: string;
77
+ /** Calendar whose copy of the event is written, for a multi-calendar event.
78
+ * Omit to write the canonical copy. */
79
+ calendar?: Calendar;
80
+ /** Address of the inbox holding the copy this call changes (an occurrence
81
+ * listing's `inbox`). When the meeting is on more than one of the user's
82
+ * inboxes, an agent must name it: the call is refused with
83
+ * `copy_choice_required`, listing each copy's inbox, role and event, until
84
+ * it does. It must be the inbox holding this copy. */
85
+ inbox?: string;
50
86
  }
51
87
  /** The RSVP to record and how it is scoped across a recurring series. */
52
88
  export interface RsvpEventOptions {
@@ -97,14 +133,46 @@ export declare class CalendarEvent extends MacroEntity<CalendarEventRecord> {
97
133
  readonly isReadOnly: () => Promise<boolean>;
98
134
  /** Raw RFC 5545 recurrence properties (`RRULE`, `RDATE`, `EXDATE`). */
99
135
  readonly recurrenceLines: () => Promise<string[]>;
136
+ /** What the organizer lets guests do: modify, invite others, see the guest list. */
137
+ readonly guestPolicy: () => Promise<GuestPolicy>;
138
+ /** What the connected account may do with this event under its guest policy. */
139
+ readonly viewerCan: () => Promise<import("../../../generated/calendar").ViewerCapabilities>;
100
140
  /** The calendar the canonical source belongs to, when known. */
101
141
  readonly calendar: () => Promise<Calendar | undefined>;
102
142
  /** The full synced event record. Available on a seeded handle (from create /
103
143
  * update / rsvp); a bare `byId` handle throws (no fetch-by-id endpoint). */
104
144
  record(): Promise<CalendarEventRecord>;
105
- /** Update the event and return a handle to its synced record. */
145
+ /** Update the event and return a handle to its synced record.
146
+ *
147
+ * A meeting on more than one of the user's inboxes is one event per inbox,
148
+ * each with its own id (see the occurrence listing's `inbox` and `role`).
149
+ * Before changing its details, guests or guest permissions, ask the user
150
+ * which inbox's copy to change, then pass that copy's `inbox`. Never choose
151
+ * between the user's inboxes yourself, whatever they look like: a test,
152
+ * secondary or unfamiliar address is still the user's own inbox. Skip the
153
+ * question only when the user already named the inbox, when only one copy's
154
+ * `viewerCan` allows the change (use it and say why), or when adding guests
155
+ * to a meeting the user organizes from one of the inboxes (add them from
156
+ * that copy and say why). Reminders belong to one copy, so set them on one
157
+ * copy and say which inbox you used. Without `inbox` the call is refused
158
+ * with `copy_choice_required`, listing each copy and the question to ask. */
106
159
  update(options: UpdateEventOptions): Promise<CalendarEvent>;
107
- /** Delete the event (or a scoped part of a recurring series) at its provider. */
160
+ /** Delete the event (or a scoped part of a recurring series) at its provider.
161
+ *
162
+ * A meeting on more than one of the user's inboxes is one event per inbox.
163
+ * Before deleting any of them, ask the user which inbox's copy to delete,
164
+ * then pass that copy's `inbox`. Never choose between the user's inboxes
165
+ * yourself, whatever they look like: a test, secondary or unfamiliar address
166
+ * is still the user's own inbox. Skip the question only when the user
167
+ * already named the inbox, or when only one copy can be deleted; then delete
168
+ * that copy and say why. Without `inbox` the call is refused with
169
+ * `copy_choice_required`, listing each copy and the question to ask.
170
+ *
171
+ * Deleting the copy the user organizes cancels the meeting for every guest.
172
+ * Deleting a copy where they are a guest takes the meeting off that inbox's
173
+ * calendar: on Google it also declines the invitation and tells the
174
+ * organizer, while on Outlook the organizer is not told and still sees the
175
+ * invitation unanswered. */
108
176
  delete(options?: DeleteEventOptions): Promise<void>;
109
177
  /** Preview an organizer replacement without cancelling or sending invitations.
110
178
  * Review replacement.status() before explicitly calling replacement.confirm(). */
@@ -118,6 +186,39 @@ export declare class CalendarEvent extends MacroEntity<CalendarEventRecord> {
118
186
  recurrenceId?: string;
119
187
  calendar?: Calendar;
120
188
  }): Promise<string | undefined>;
189
+ /** Add guests without touching anyone already invited, and return a handle
190
+ * to the synced record.
191
+ *
192
+ * When the meeting is on more than one of the user's inboxes, add from the
193
+ * copy the user organizes when there is one (it invites directly, while a
194
+ * guest's copy invites only as far as the organizer allows) and say why;
195
+ * otherwise ask the user which inbox's copy to add them from. Never choose
196
+ * between the user's inboxes any other way, whatever they look like. Pass
197
+ * that copy's `inbox`; without it the call is refused with
198
+ * `copy_choice_required`, listing each copy and the question to ask.
199
+ *
200
+ * The organizer may add guests, and so may a guest the organizer lets
201
+ * invite others (see {@link CalendarEvent.viewerCan}); Google emails the
202
+ * new guests. */
203
+ inviteGuests(options: InviteGuestsOptions): Promise<CalendarEvent>;
204
+ /** Add a snapshot of an event shared with one of the requester's
205
+ * channels to one of their Google calendars, and return a handle to the
206
+ * synced snapshot. The snapshot keeps the meeting's iCalendar UID and
207
+ * organizer, lists only the requester as a guest, and carries no join link;
208
+ * nobody is notified, and answers or guests on it never reach the meeting.
209
+ * Refused with `already_on_calendar` when the meeting is already on one of
210
+ * their calendars, whichever calendar is named, so it cannot be added to
211
+ * another of their calendars either; with `join_request_open` while their
212
+ * request to join it is pending or accepted (the meeting then arrives as an
213
+ * invitation); and with `copy_refused` when Google will not import it. */
214
+ addToCalendar(options?: {
215
+ calendar?: Calendar;
216
+ }): Promise<CalendarEvent>;
217
+ /** The event as an iCalendar (`.ics`) document: its series, title,
218
+ * description, location and organizer, never its guests or join link.
219
+ * Available for the requester's own events and ones shared with a channel
220
+ * they belong to. */
221
+ ics(): Promise<string>;
121
222
  /** Record the requester's RSVP and return a handle to the synced record. */
122
223
  rsvp(options: RsvpEventOptions): Promise<CalendarEvent>;
123
224
  }
@@ -1,8 +1,10 @@
1
- import type { CalendarAttendeeInputBody, ConferenceChange, EventReminders, EventTime, EventTransparency, EventVisibility, OutOfOfficeProperties, TeamCalendarSharing } from '../../../generated/calendar/types.gen';
1
+ import type { CreateCalendarEvent_Deserialize } from '../../../generated/agent-reviews';
2
+ import type { CalendarAttendeeInputBody, ConferenceChange, EventReminders, EventTime, EventTransparency, EventVisibility, GuestPolicy, OutOfOfficeProperties, TeamCalendarSharing } from '../../../generated/calendar/types.gen';
2
3
  import type { ListOccurrencesData, ListTeamCalendarData, ListTeamOutOfOfficeData } from '../../../generated/storage/types.gen';
3
4
  import type { MacroClient } from '../../utils/client';
4
5
  import type { Link } from '../email/link';
5
6
  import { User } from '../users/user';
7
+ import { BookingNamespace } from './booking-namespace';
6
8
  import { Calendar } from './calendar';
7
9
  import { CalendarEvent } from './event';
8
10
  import { CalendarReplacement } from './replacement';
@@ -33,6 +35,8 @@ export interface CreateEventOptions {
33
35
  macroCall?: boolean;
34
36
  /** Out-of-office properties; present to create an out-of-office event. */
35
37
  outOfOffice?: OutOfOfficeProperties;
38
+ /** What guests may do; omit for Google's defaults. Google calendars only. */
39
+ guestPolicy?: GuestPolicy;
36
40
  /** Exact calendar to create the event on; takes precedence over the inbox
37
41
  * default. */
38
42
  calendar?: Calendar;
@@ -40,10 +44,80 @@ export interface CreateEventOptions {
40
44
  * requester's primary inbox. */
41
45
  emailLink?: Link;
42
46
  }
47
+ /** What the user is on one copy of an event, through the inbox holding it:
48
+ * its organizer (or the owner of an event without guests), or a guest. Being
49
+ * able to write someone else's calendar makes them neither, and neither does
50
+ * a read-only calendar naming them organizer; `viewerCan` says what they may
51
+ * do there. */
52
+ export type CalendarEventRole = 'organizer' | 'guest';
43
53
  /**
44
- * The calendar surface: the caller's visible calendars, event creation, and
45
- * handles to individual events and calendars. Backed by calendar_service (the
46
- * SDK reaches it on the gateway's `/calendar` route).
54
+ * The calendar surface: every calendar the caller can see (not all of them
55
+ * theirs), event creation, and handles to individual events and calendars.
56
+ * Backed by calendar_service (the SDK reaches it on the gateway's `/calendar`
57
+ * route).
58
+ *
59
+ * The user can see calendars that are not theirs, such as a colleague's or a
60
+ * team's. `inbox` is the account syncing a calendar, so it stays the user's
61
+ * own address on all of them, and neither it, `isPrimary`, `isWritable` nor
62
+ * `role` says whose calendar it is. Their schedule is the calendars with
63
+ * `contributesToAvailability`, plus meetings they attend: only those are
64
+ * "your calendar", and only those are conflicts when finding free time, as in
65
+ * team availability. Anything else is what that calendar shows, not where the
66
+ * user is or what they are doing. Call it by `calendarName`, say whose it is
67
+ * when the name shows that, and otherwise say you cannot tell rather than
68
+ * guess. When it overlaps a time you suggest, mention it so the user can
69
+ * decide, since their own other calendars read the same way.
70
+ *
71
+ * A meeting on more than one of the user's inboxes is one event per inbox;
72
+ * {@link CalendarNamespace.occurrences} lists each copy with its `inbox` and
73
+ * `role`. Before changing such a meeting's details, guests or guest
74
+ * permissions, or deleting it, ask the user which inbox's copy to change, then
75
+ * pass that copy's `inbox` to {@link CalendarEvent.update},
76
+ * {@link CalendarEvent.inviteGuests} or {@link CalendarEvent.delete}. Never
77
+ * choose between the user's inboxes yourself, whatever they look like: a
78
+ * test, secondary or unfamiliar address is still the user's own inbox. Skip
79
+ * the question only when the user already named the inbox, when only one copy
80
+ * can make the change, or when adding guests from the copy the user
81
+ * organizes, and say why. Reminders may go to one copy; name its inbox. Read
82
+ * those three methods' documentation before changing a meeting held through
83
+ * several inboxes: it says what each change does from each copy.
84
+ *
85
+ * {@link CalendarEvent.addToCalendar} adds a shared meeting only while none
86
+ * of the user's calendars holds it. Refused with `already_on_calendar`, it is
87
+ * refused on every calendar, so tell the user the meeting is already on their
88
+ * calendar and never offer to add it to another one.
89
+ *
90
+ * @routing Use when working with calendar events, availability, scheduling a meeting with people, or booking links; not reminders or recurring automations, which are routines.
91
+ *
92
+ * @agent
93
+ * ## Booking links
94
+ *
95
+ * - Booking links live under `macro.calendar.booking`. They are reusable booking pages, not
96
+ * calendar meetings; the meetings guests book through them are `Booking`s.
97
+ * - Booking links use conversational confirmation in every surface. First list
98
+ * `macro.calendar.booking.links()` to find existing links and reusable availability. Resolve
99
+ * teams and hosts from what it returns; never ask for IDs, revisions or JSON. Default to
100
+ * personal ownership unless a team is requested. Explain the complete proposal in readable
101
+ * prose: ownership and named hosts, who attends, meeting name and description, duration,
102
+ * location, Macro call or Google Meet, time zone, weekly hours and date exceptions, link name,
103
+ * buffers, minimum notice, booking window, slot interval, daily limit, guest questions, and
104
+ * whether bookings are enabled. Group related settings so it is easy to review. Ask whether to
105
+ * proceed, and end the turn. Only after the user's reply approving that proposal, call
106
+ * `booking.createLink` or `BookingLink.edit`, quoting the reply verbatim in `userConfirmation`.
107
+ * Do not quote the original request or invent approval. These save immediately, with no
108
+ * review card. For edits preserve unrequested settings, and re-read and reconfirm if the
109
+ * revision conflicts. Share the saved `webUrl()` with an `<m-booking-link-mention>` chip (see
110
+ * Mentions), not a bare URL. If the same proposal is already approved, do not ask again.
111
+ * - `booking.saveSettings` changes shared schedules, page settings and many links at once: explain
112
+ * the changes and the links they affect, and save only on the user's approving reply.
113
+ * - Cancelling, approving or rescheduling a `Booking` notifies its guest and hosts; do it only on
114
+ * the user's go-ahead. Reschedule to a start from `rescheduleSlots`.
115
+ *
116
+ * ## Creating events
117
+ *
118
+ * - Nothing lands on a calendar, and no invitation goes out, without the user seeing the event. A program cannot call `createEvent`; it is refused.
119
+ * - In an agent session, present the event as a review: `execution.reviews.create({kind: 'calendar', title, drafts})`, each draft with the same fields as `createConfirmed` (`calendarId` in place of `calendar`), then return `reviews: [await review.reference()]`. The user creates it from the card.
120
+ * - For a prompt from a channel or document thread, where no card is seen: write the whole event into your reply (title, date and time with its time zone, duration, guests, location, conference or Macro call, recurrence), ask whether to create it, and stop. Only once the user replies approving that event, call `createConfirmed` with their reply quoted in `userConfirmation`. Being asked to schedule something is a request to draft the event, never the approval.
47
121
  */
48
122
  export declare class CalendarNamespace {
49
123
  private readonly client;
@@ -58,10 +132,46 @@ export declare class CalendarNamespace {
58
132
  teamSharing(): Promise<TeamCalendarSharing>;
59
133
  /** Replace the team calendar sharing preference. */
60
134
  setTeamSharing(sharing: TeamCalendarSharing): Promise<TeamCalendarSharing>;
61
- /** Calendar occurrences in a viewport, automatically paginated. */
135
+ /** Occurrences on every calendar the user can see: their schedule is only
136
+ * `contributesToAvailability` rows and meetings they attend; call the rest
137
+ * by `calendarName`. Automatically paginated within the viewport. Each names
138
+ * its calendar (`calendarName`), whether a calendar holding it is on the
139
+ * user's schedule (`contributesToAvailability`), the address of the
140
+ * connected inbox holding that copy of the event (`inbox`) and whether the
141
+ * user organizes it or is a guest there (`role`, absent when neither, when
142
+ * they can only write that calendar, or when a read-only calendar names
143
+ * them organizer).
144
+ *
145
+ * `inbox` is the account syncing the calendar, so a colleague's calendar
146
+ * reports the user's own address; it never says whose calendar it is, and
147
+ * neither does `role`, since writing someone's calendar lets the user act
148
+ * as its organizer. Say "your calendar", and count a conflict or busy time,
149
+ * only for `contributesToAvailability` rows and meetings the user attends
150
+ * (`role`), the way team availability does. Any other row is what that
151
+ * calendar shows, not where the user is or what they are doing: "the
152
+ * Offsites calendar has...", or "alex@example.com's calendar has..." when
153
+ * the name shows whose it is. If it does not, say you cannot tell rather
154
+ * than guess. When one overlaps a time you suggest, mention it so the user
155
+ * can decide, since their own other calendars read the same way.
156
+ *
157
+ * A meeting on several of the user's inboxes appears once per inbox, each
158
+ * with its own event; describe them by inbox and role, never by id.
159
+ *
160
+ * Before changing or deleting such a meeting, ask the user which inbox's
161
+ * copy to change, unless they named it, only one copy can make the change,
162
+ * or you add guests from the copy they organize. Never choose between the
163
+ * user's inboxes yourself, whatever they look like. Pass the chosen copy's
164
+ * `inbox` to its `update`, `inviteGuests` or `delete`; without it the call
165
+ * is refused with `copy_choice_required`, which names each copy's inbox and
166
+ * event and gives the question to ask. An occurrence whose calendar is no
167
+ * longer listed has no `inbox`; take it from that refusal. */
62
168
  occurrences(options: Omit<ListOccurrencesData['query'], 'cursor'>): AsyncGenerator<{
63
169
  event: CalendarEvent;
64
170
  occurrence: import("../../../generated/storage").CalendarOccurrence;
171
+ calendarName: string | undefined;
172
+ contributesToAvailability: boolean | undefined;
173
+ inbox: string | undefined;
174
+ role: CalendarEventRole | undefined;
65
175
  }, any, any>;
66
176
  /** A page of team availability, including its roster and continuation cursor. */
67
177
  teamPage(options: NonNullable<ListTeamCalendarData['query']>): Promise<{
@@ -97,8 +207,10 @@ export declare class CalendarNamespace {
97
207
  }[];
98
208
  hasMore: boolean;
99
209
  }>;
210
+ /** Booking links, their settings, booked meetings and booking statistics. */
211
+ readonly booking: BookingNamespace;
100
212
  constructor(client: MacroClient);
101
- /** The caller's visible calendars, primaries and writable first. */
213
+ /** The calendars the caller can see, some possibly not theirs, primaries and writable first. */
102
214
  calendars(): Promise<Calendar[]>;
103
215
  /** A handle to a calendar by id. Detail loads on first access. */
104
216
  calendar(id: string): Calendar;
@@ -106,6 +218,38 @@ export declare class CalendarNamespace {
106
218
  event(id: string): CalendarEvent;
107
219
  /** Recover a saved replacement, including after its original event was retired. */
108
220
  replacement(operationId: string): CalendarReplacement;
109
- /** Create a calendar event and return a handle to its synced record. */
221
+ /**
222
+ * Create a calendar event and return a handle to its synced record; an
223
+ * agent's program is refused (403) and creates through a review or
224
+ * {@link createConfirmed} instead.
225
+ */
110
226
  createEvent(options: CreateEventOptions): Promise<CalendarEvent>;
227
+ /**
228
+ * Create a calendar event only after the user replied approving it, quoting that reply in `userConfirmation`; never on the request that asked for the event.
229
+ *
230
+ * For a prompt from a channel or document thread: write the event out
231
+ * there, ask whether to create it, and call this in a later turn on the
232
+ * user's approving reply. In the agent session view, present a review
233
+ * (`execution.reviews.create({kind: 'calendar', ...})`) instead; its card
234
+ * is the confirmation. Takes what the CreateCalendarEvent tool takes:
235
+ * guests, recurrence, reminders, a provider conference or a Macro call,
236
+ * out-of-office and guest policy, and the calendar to write to. The event
237
+ * is written to the provider at once and guests receive invitations; on an
238
+ * error, look for the event before creating it again.
239
+ */
240
+ createConfirmed(options: ConfirmedEventOptions): Promise<CalendarEvent>;
111
241
  }
242
+ /** An event the user has approved in conversation, for `calendar.createConfirmed`. */
243
+ export type ConfirmedEventOptions = EventFields<CreateCalendarEvent_Deserialize> & {
244
+ /** The calendar to write to; omit for the user's primary calendar. */
245
+ calendar?: Calendar;
246
+ /**
247
+ * The user's own reply approving this specific event, quoted verbatim, such
248
+ * as their "yes, go ahead" after you wrote the event out for them. Never the
249
+ * request that asked you to schedule it, and never your own words.
250
+ */
251
+ userConfirmation: string;
252
+ };
253
+ /** The tool's event fields, with the calendar taken as a handle instead. */
254
+ type EventFields<Event> = Event extends unknown ? Omit<Event, 'calendarId'> : never;
255
+ export {};
@@ -0,0 +1 @@
1
+ export {};
@@ -1,15 +1,37 @@
1
- import type { EditCallTranscriptRequest, GetCallRecordResponses } from '../../../generated/storage/types.gen';
1
+ import type { EditCallTranscriptRequest, GetCallRecordResponses, LiveCallSummary, RingStatus } from '../../../generated/storage/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import { Channel } from '../channels/channel';
4
+ import { Thread } from '../channels/thread';
4
5
  import { FavoritableEntity } from '../entity';
5
6
  import { Meeting } from '../meetings/meeting';
6
7
  import { MessageThread, type TimelineOptions } from '../messages/thread';
7
8
  import { EntityAccess } from '../sharing/access';
8
9
  import { User } from '../users/user';
10
+ import { CallConnection, type JoinOptions } from './connection';
9
11
  import { CallMessage } from './message';
12
+ import { CallParticipant } from './participant';
10
13
  type CallRecordDetail = GetCallRecordResponses[200];
11
14
  /** A Macro call record (an archived or still active call). */
12
15
  export declare class CallRecord extends FavoritableEntity<CallRecordDetail> {
16
+ /** Kind is available immediately on handles returned by the live list. */
17
+ readonly kind?: LiveCallSummary['kind'];
18
+ private constructor();
19
+ /** Build a live call handle without fetching its archived detail. */
20
+ static fromLive(client: MacroClient, summary: LiveCallSummary): CallRecord;
21
+ /** Join only while this call is live; never start a replacement call. */
22
+ join(opts?: JoinOptions): Promise<CallConnection>;
23
+ /** Read the current ring state for this account. */
24
+ ringState(): Promise<RingStatus>;
25
+ /** Read the connected room roster without joining. */
26
+ participants(): Promise<CallParticipant[]>;
27
+ /** Decline this call's ring for the current account. */
28
+ decline(): Promise<void>;
29
+ /** Read the persistent discussion, which may be a channel thread. */
30
+ discussion(): Promise<MessageThread | Thread>;
31
+ /** Download recording bytes through the Macro host. */
32
+ readonly recording: {
33
+ bytes: () => Promise<Uint8Array>;
34
+ };
13
35
  /** A shared message thread scoped to this resource. */
14
36
  messageThreadById(id: string): MessageThread;
15
37
  /** A mixed message and activity timeline page. */
@@ -44,6 +66,14 @@ export declare class CallRecord extends FavoritableEntity<CallRecordDetail> {
44
66
  /** Favorites identify call records as `call`. */
45
67
  readonly entityType = "call";
46
68
  protected fetch(): Promise<CallRecordDetail>;
69
+ /** The call's URL in the Macro web app; hand it to users as the link. */
70
+ webUrl(): string;
71
+ /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
72
+ toJSON(): {
73
+ url: string;
74
+ id: string;
75
+ detail?: import("../../../generated/storage").CallRecord | undefined;
76
+ };
47
77
  /** A handle to a call record by id. Details load on first access. */
48
78
  static byId(client: MacroClient, id: string): CallRecord;
49
79
  /** A message in this call's persistent chat. Fields load on first access. */
@@ -61,7 +91,7 @@ export declare class CallRecord extends FavoritableEntity<CallRecordDetail> {
61
91
  /** The call's status (undefined until set). */
62
92
  readonly status: () => Promise<NonNullable<import("../../../generated/storage").CallStatus | null | undefined> | undefined>;
63
93
  /** The realtime room the call runs in. */
64
- readonly roomName: () => Promise<string>;
94
+ readonly roomName: () => Promise<string | undefined>;
65
95
  /** When the call started. */
66
96
  readonly startedAt: () => Promise<string>;
67
97
  /** When the call ended (undefined if still active). */
@@ -73,7 +103,7 @@ export declare class CallRecord extends FavoritableEntity<CallRecordDetail> {
73
103
  /** Transcript segments, ordered by sequence number. */
74
104
  readonly transcript: () => Promise<import("../../../generated/storage").CallRecordTranscriptSegment[]>;
75
105
  /** Macro-account participants, both active and historic. */
76
- readonly participants: () => Promise<import("../../../generated/storage").CallRecordParticipant[]>;
106
+ readonly historicParticipants: () => Promise<import("../../../generated/storage").CallRecordParticipant[]>;
77
107
  /** Current and past guests; each id matches its transcript speaker id. */
78
108
  readonly guests: () => Promise<import("../../../generated/storage").CallRecordGuest[]>;
79
109
  /**
@@ -106,6 +136,6 @@ export declare class CallRecord extends FavoritableEntity<CallRecordDetail> {
106
136
  /** Delete the call record. */
107
137
  delete(): Promise<void>;
108
138
  /** Search calls by name and transcript, most relevant first, auto-paginated. */
109
- static search: (client: MacroClient, query: string, searchOpts?: import("../search").SearchOpts) => AsyncGenerator<CallRecord, any, any>;
139
+ static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<CallRecord, any, any>;
110
140
  }
111
141
  export {};
@@ -0,0 +1,53 @@
1
+ import type { CallTokenResponse, JoinCallRequest } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { CallRecord } from './call-record';
4
+ declare const inspectSymbol: unique symbol;
5
+ /** Options for entering a call. The default is to fail if already in another call. */
6
+ export type JoinOptions = JoinCallRequest;
7
+ /** A room credential. Keep `token` out of logs and serialized values. */
8
+ export declare class CallConnection {
9
+ private readonly client;
10
+ /** The call this credential enters. */
11
+ readonly call: CallRecord;
12
+ /** LiveKit server URL. */
13
+ readonly url: string;
14
+ /** Short-lived LiveKit token; never serialize or log it. */
15
+ readonly token: string;
16
+ /** RTC participant identity. */
17
+ readonly identity: string;
18
+ /** RTC room name. */
19
+ readonly roomName: string;
20
+ /** Whether this request created the call. */
21
+ readonly started: boolean;
22
+ /** Construct a connection from the server's admission response. */
23
+ constructor(client: MacroClient, response: CallTokenResponse);
24
+ /** Leave this exact call; safe to invoke after another call has started. */
25
+ leave(): Promise<{
26
+ callEnded: boolean;
27
+ }>;
28
+ /** Serialize connection metadata without the room credential. */
29
+ toJSON(): {
30
+ call: {
31
+ url: string;
32
+ id: string;
33
+ detail?: import("../../../generated/storage").CallRecord | undefined;
34
+ };
35
+ url: string;
36
+ identity: string;
37
+ roomName: string;
38
+ started: boolean;
39
+ };
40
+ /** Keep the credential out of Node's console inspection. */
41
+ [inspectSymbol](): {
42
+ call: {
43
+ url: string;
44
+ id: string;
45
+ detail?: import("../../../generated/storage").CallRecord | undefined;
46
+ };
47
+ url: string;
48
+ identity: string;
49
+ roomName: string;
50
+ started: boolean;
51
+ };
52
+ }
53
+ export {};
@@ -0,0 +1,15 @@
1
+ import { MacroApiError } from '../../utils/unwrap';
2
+ /** The account is participating in another call. */
3
+ export declare class InOtherCallError extends MacroApiError {
4
+ constructor(data: unknown);
5
+ }
6
+ /** This identity already has a room connection. */
7
+ export declare class AlreadyConnectedError extends MacroApiError {
8
+ constructor(data: unknown);
9
+ }
10
+ /** The call ended before this join completed. */
11
+ export declare class CallEndedError extends MacroApiError {
12
+ constructor(data: unknown);
13
+ }
14
+ /** Preserve the server's branchable call admission codes. */
15
+ export declare function callAdmissionError(error: unknown): never;
@@ -1,9 +1,29 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
- import type { SearchOpts } from '../search';
2
+ import { Channel } from '../channels/channel';
3
+ import type { SearchOpts } from '../search/options';
3
4
  import { CallRecord } from './call-record';
5
+ /** A lightweight preview of an existing call record. */
6
+ export type CallSummary = {
7
+ call: CallRecord;
8
+ channel?: Channel;
9
+ channelName?: string;
10
+ customName?: string;
11
+ startedAt: string;
12
+ endedAt?: string;
13
+ };
14
+ /**
15
+ * @routing Use when finding live or recorded calls, entering a room, reading a transcript, or downloading a recording; not email, messages, tables or scheduling.
16
+ * @agent A program uses an agent account's own API key to enter a call. Use active() to reconcile missed events. Join an existing call with call.join(); start a channel call only when intending to ring its members. Calls with only programs end after the server timeout. Keep room tokens private and connect with a LiveKit client outside code mode.
17
+ */
4
18
  export declare class CallRecordNamespace {
5
19
  private readonly client;
6
20
  constructor(client: MacroClient);
21
+ /** Get a lazy call handle; joining it never creates a call. */
7
22
  byId(id: string): CallRecord;
23
+ /** Search archived calls by name and transcript, not the live room roster. */
8
24
  search(query: string, opts?: SearchOpts): AsyncGenerator<CallRecord>;
25
+ /** List joinable live calls; use after an event stream reconnects. */
26
+ active(): Promise<CallRecord[]>;
27
+ /** Preview these calls in input order; missing records are omitted. */
28
+ summaries(calls: CallRecord[]): Promise<CallSummary[]>;
9
29
  }
@@ -0,0 +1,22 @@
1
+ import type { LiveCallParticipant } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { User } from '../users/user';
4
+ /** A connected participant and their published track state. */
5
+ export declare class CallParticipant {
6
+ /** RTC participant identity. */
7
+ readonly identity: string;
8
+ /** Display name in the room. */
9
+ readonly displayName: string;
10
+ /** Account, guest, or bot participant. */
11
+ readonly kind: LiveCallParticipant['kind'];
12
+ /** Whether this participant is a program. */
13
+ readonly isProgram: boolean;
14
+ /** When this RTC connection began. */
15
+ readonly joinedAt?: string;
16
+ /** Published tracks and mute state. */
17
+ readonly tracks: LiveCallParticipant['tracks'];
18
+ /** Macro account handle, when one is present. */
19
+ readonly user?: User;
20
+ /** Build a roster handle from a live participant record. */
21
+ constructor(client: MacroClient, record: LiveCallParticipant);
22
+ }
@@ -0,0 +1,34 @@
1
+ import type { ChannelAccessRequest as RequestRecord } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { MacroEntity } from '../entity';
4
+ import { User } from '../users/user';
5
+ import type { Channel } from './channel';
6
+ /**
7
+ * One attempt to join a private or team channel. Any participant of the
8
+ * channel can read and answer it; approving adds the requester as a member.
9
+ */
10
+ export declare class ChannelAccessRequest extends MacroEntity<RequestRecord> {
11
+ /** Channel the requester asked to join. */
12
+ readonly channel: Channel;
13
+ private constructor();
14
+ /** A request to join `channel`, loaded lazily for its participants. */
15
+ static byId(client: MacroClient, channel: Channel, id: string): ChannelAccessRequest;
16
+ /** Seed a request from a response that already carries it. */
17
+ static from(client: MacroClient, channel: Channel, record: RequestRecord): ChannelAccessRequest;
18
+ protected fetch(): Promise<RequestRecord>;
19
+ /** Pending, approved, denied, or cancelled by the requester. */
20
+ readonly status: () => Promise<import("../../../generated/storage").ChannelAccessRequestStatus>;
21
+ /** When the requester asked. */
22
+ readonly createdAt: () => Promise<string>;
23
+ /** When the request stopped being pending. */
24
+ readonly resolvedAt: () => Promise<string | undefined>;
25
+ /** The person asking to join. */
26
+ readonly requester: () => Promise<User>;
27
+ /** The participant who approved or denied the request. */
28
+ readonly resolvedBy: () => Promise<User | undefined>;
29
+ /** Add the requester to the channel. Fails if someone answered first. */
30
+ approve(): Promise<void>;
31
+ /** Decline the request; the requester can ask again after a day. */
32
+ deny(): Promise<void>;
33
+ private resolve;
34
+ }