@macro-inc/sdk 0.4.1 → 0.6.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 (228) hide show
  1. package/README.md +316 -21
  2. package/dist/{chunk-PTX2RV2N.js → chunk-4MI52GWV.js} +93 -1
  3. package/dist/{chunk-XFA7NCJ5.js → chunk-HO75UE4Z.js} +146 -15
  4. package/dist/{chunk-P4DTO6VD.js → chunk-MCSQNZ4E.js} +6 -0
  5. package/dist/{chunk-ZLBDES7U.js → chunk-SJ6S2GAT.js} +1271 -87
  6. package/dist/{chunk-AZJUIUIV.js → chunk-SK5CMXRV.js} +100 -14
  7. package/dist/{chunk-PZPTJI6F.js → chunk-TMTYN2UK.js} +229 -2
  8. package/dist/{chunk-PPR7IWZ7.js → chunk-ZYBAKW25.js} +2 -1
  9. package/dist/generated/agent-fold/index.d.ts +202 -14
  10. package/dist/generated/agent-harness/index.d.ts +1 -1
  11. package/dist/generated/agent-harness/index.js +1 -1
  12. package/dist/generated/agent-harness/sdk.gen.d.ts +49 -2
  13. package/dist/generated/agent-harness/types.gen.d.ts +527 -9
  14. package/dist/generated/agent-reviews/index.d.ts +11 -9
  15. package/dist/generated/auth/index.d.ts +1 -1
  16. package/dist/generated/auth/index.js +1 -1
  17. package/dist/generated/auth/sdk.gen.d.ts +82 -16
  18. package/dist/generated/auth/types.gen.d.ts +768 -18
  19. package/dist/generated/calendar/types.gen.d.ts +10 -3
  20. package/dist/generated/cognition/index.d.ts +1 -1
  21. package/dist/generated/cognition/index.js +1 -1
  22. package/dist/generated/cognition/sdk.gen.d.ts +60 -6
  23. package/dist/generated/cognition/types.gen.d.ts +663 -106
  24. package/dist/generated/connection/types.gen.d.ts +1 -1
  25. package/dist/generated/contacts/index.d.ts +1 -1
  26. package/dist/generated/contacts/index.js +1 -1
  27. package/dist/generated/contacts/sdk.gen.d.ts +5 -1
  28. package/dist/generated/contacts/types.gen.d.ts +56 -0
  29. package/dist/generated/email/types.gen.d.ts +8 -2
  30. package/dist/generated/notification/index.d.ts +1 -1
  31. package/dist/generated/notification/index.js +1 -1
  32. package/dist/generated/notification/sdk.gen.d.ts +2 -1
  33. package/dist/generated/notification/types.gen.d.ts +174 -1
  34. package/dist/generated/scheduled-action/index.d.ts +1 -1
  35. package/dist/generated/scheduled-action/index.js +1 -1
  36. package/dist/generated/scheduled-action/sdk.gen.d.ts +107 -2
  37. package/dist/generated/scheduled-action/types.gen.d.ts +2451 -479
  38. package/dist/generated/search/index.d.ts +1 -1
  39. package/dist/generated/search/types.gen.d.ts +50 -11
  40. package/dist/generated/storage/index.d.ts +1 -1
  41. package/dist/generated/storage/index.js +1 -1
  42. package/dist/generated/storage/sdk.gen.d.ts +511 -18
  43. package/dist/generated/storage/types.gen.d.ts +18528 -11395
  44. package/dist/src/entities/account-managers/grant.d.ts +28 -5
  45. package/dist/src/entities/account-managers/namespace.d.ts +15 -3
  46. package/dist/src/entities/activity/entity.d.ts +7 -0
  47. package/dist/src/entities/activity/namespace.d.ts +58 -0
  48. package/dist/src/entities/activity/namespace.test.d.ts +1 -0
  49. package/dist/src/entities/agent-sessions/activity.d.ts +12 -3
  50. package/dist/src/entities/agent-sessions/agent-session.d.ts +209 -22
  51. package/dist/src/entities/agent-sessions/code-execution.d.ts +15 -3
  52. package/dist/src/entities/agent-sessions/conversation.d.ts +46 -9
  53. package/dist/src/entities/agent-sessions/namespace.d.ts +72 -16
  54. package/dist/src/entities/agent-sessions/origin.d.ts +1 -1
  55. package/dist/src/entities/agent-sessions/queued-action.d.ts +17 -3
  56. package/dist/src/entities/agent-sessions/review.d.ts +56 -5
  57. package/dist/src/entities/agent-sessions/tool-approval.d.ts +5 -1
  58. package/dist/src/entities/agents/agent.d.ts +98 -3
  59. package/dist/src/entities/agents/namespace.d.ts +52 -8
  60. package/dist/src/entities/ai/namespace.d.ts +10 -2
  61. package/dist/src/entities/api-keys/api-key.d.ts +6 -1
  62. package/dist/src/entities/api-keys/namespace.d.ts +18 -3
  63. package/dist/src/entities/bots/bot.d.ts +44 -9
  64. package/dist/src/entities/bots/namespace.d.ts +13 -1
  65. package/dist/src/entities/bots/token.d.ts +6 -1
  66. package/dist/src/entities/calendar/booking-link.d.ts +7 -1
  67. package/dist/src/entities/calendar/booking-namespace.d.ts +14 -1
  68. package/dist/src/entities/calendar/booking.d.ts +15 -0
  69. package/dist/src/entities/calendar/calendar.d.ts +10 -3
  70. package/dist/src/entities/calendar/event.d.ts +68 -9
  71. package/dist/src/entities/calendar/namespace.d.ts +91 -12
  72. package/dist/src/entities/calendar/replacement.d.ts +19 -3
  73. package/dist/src/entities/calls/call-record.d.ts +107 -17
  74. package/dist/src/entities/calls/connection.d.ts +7 -1
  75. package/dist/src/entities/calls/message.d.ts +27 -5
  76. package/dist/src/entities/calls/namespace.d.ts +15 -3
  77. package/dist/src/entities/canvases/canvas.d.ts +329 -0
  78. package/dist/src/entities/channels/access-request.d.ts +10 -2
  79. package/dist/src/entities/channels/activity.d.ts +20 -4
  80. package/dist/src/entities/channels/channel.d.ts +154 -27
  81. package/dist/src/entities/channels/labels.d.ts +41 -7
  82. package/dist/src/entities/channels/message.d.ts +105 -8
  83. package/dist/src/entities/channels/message.test.d.ts +1 -0
  84. package/dist/src/entities/channels/namespace.d.ts +37 -7
  85. package/dist/src/entities/channels/post.d.ts +13 -7
  86. package/dist/src/entities/channels/post.test.d.ts +1 -0
  87. package/dist/src/entities/channels/share.d.ts +9 -0
  88. package/dist/src/entities/channels/share.test.d.ts +1 -0
  89. package/dist/src/entities/channels/thread.d.ts +24 -4
  90. package/dist/src/entities/chats/chat.d.ts +57 -7
  91. package/dist/src/entities/chats/generation.d.ts +11 -2
  92. package/dist/src/entities/chats/namespace.d.ts +10 -2
  93. package/dist/src/entities/connected-apps/connected-app.d.ts +16 -2
  94. package/dist/src/entities/connected-apps/connector.d.ts +3 -0
  95. package/dist/src/entities/connected-apps/namespace.d.ts +18 -0
  96. package/dist/src/entities/crm/company.d.ts +64 -16
  97. package/dist/src/entities/crm/contact.d.ts +102 -14
  98. package/dist/src/entities/crm/namespace.d.ts +113 -22
  99. package/dist/src/entities/crm/pipeline-entry.d.ts +109 -0
  100. package/dist/src/entities/crm/pipeline.d.ts +292 -29
  101. package/dist/src/entities/crm/pipelines.d.ts +69 -4
  102. package/dist/src/entities/crm-email-privacy/email-privacy.d.ts +238 -0
  103. package/dist/src/entities/crm-email-privacy/email-rule-preview.d.ts +55 -0
  104. package/dist/src/entities/crm-email-privacy/email-rule-revision.d.ts +27 -0
  105. package/dist/src/entities/crm-email-privacy/email-rules.d.ts +32 -0
  106. package/dist/src/entities/databases/column.d.ts +54 -7
  107. package/dist/src/entities/databases/database.d.ts +160 -18
  108. package/dist/src/entities/databases/namespace.d.ts +40 -8
  109. package/dist/src/entities/databases/row.d.ts +2 -0
  110. package/dist/src/entities/databases/saved-query.d.ts +151 -0
  111. package/dist/src/entities/databases/table.d.ts +73 -10
  112. package/dist/src/entities/databases/view.d.ts +37 -5
  113. package/dist/src/entities/databases/webhook.d.ts +8 -1
  114. package/dist/src/entities/documents/ai-edit.d.ts +2 -0
  115. package/dist/src/entities/documents/anchor.d.ts +12 -2
  116. package/dist/src/entities/documents/comment.d.ts +29 -5
  117. package/dist/src/entities/documents/create.test.d.ts +1 -0
  118. package/dist/src/entities/documents/document.d.ts +284 -26
  119. package/dist/src/entities/documents/markdown.d.ts +25 -0
  120. package/dist/src/entities/documents/namespace.d.ts +146 -13
  121. package/dist/src/entities/documents/skills.test.d.ts +1 -0
  122. package/dist/src/entities/documents/system-skill.d.ts +21 -1
  123. package/dist/src/entities/documents/text-comment.d.ts +41 -0
  124. package/dist/src/entities/documents/text-comment.test.d.ts +1 -0
  125. package/dist/src/entities/documents/version.d.ts +5 -1
  126. package/dist/src/entities/email/attachment.d.ts +3 -0
  127. package/dist/src/entities/email/draft.d.ts +61 -9
  128. package/dist/src/entities/email/filter.d.ts +12 -2
  129. package/dist/src/entities/email/label.d.ts +7 -1
  130. package/dist/src/entities/email/link.d.ts +5 -1
  131. package/dist/src/entities/email/message.d.ts +72 -14
  132. package/dist/src/entities/email/namespace.d.ts +134 -24
  133. package/dist/src/entities/email/thread.d.ts +124 -18
  134. package/dist/src/entities/entity-mentions/mention.d.ts +6 -1
  135. package/dist/src/entities/entity-mentions/namespace.d.ts +5 -1
  136. package/dist/src/entities/entity.d.ts +65 -6
  137. package/dist/src/entities/external-chat/chat.d.ts +80 -12
  138. package/dist/src/entities/external-chat/message.d.ts +1 -1
  139. package/dist/src/entities/external-chat/namespace.d.ts +5 -1
  140. package/dist/src/entities/external-chat/send.d.ts +10 -2
  141. package/dist/src/entities/favorites/namespace.d.ts +20 -3
  142. package/dist/src/entities/foreign/foreign-entity.d.ts +5 -1
  143. package/dist/src/entities/foreign/namespace.d.ts +5 -1
  144. package/dist/src/entities/forms/form.d.ts +91 -14
  145. package/dist/src/entities/forms/namespace.d.ts +10 -2
  146. package/dist/src/entities/forms/question.d.ts +35 -7
  147. package/dist/src/entities/forms/response.d.ts +25 -5
  148. package/dist/src/entities/forms/section.d.ts +15 -3
  149. package/dist/src/entities/github-pull-requests/namespace.d.ts +5 -1
  150. package/dist/src/entities/github-pull-requests/pull-request.d.ts +15 -3
  151. package/dist/src/entities/harnesses/harness.d.ts +51 -3
  152. package/dist/src/entities/harnesses/namespace.d.ts +54 -8
  153. package/dist/src/entities/harnesses/pairing.d.ts +13 -2
  154. package/dist/src/entities/images/image.d.ts +16 -5
  155. package/dist/src/entities/images/namespace.d.ts +8 -1
  156. package/dist/src/entities/imports/entry.d.ts +65 -0
  157. package/dist/src/entities/imports/namespace.d.ts +103 -0
  158. package/dist/src/entities/imports/namespace.test.d.ts +1 -0
  159. package/dist/src/entities/initiatives/initiative.d.ts +128 -4
  160. package/dist/src/entities/initiatives/initiative.test.d.ts +1 -0
  161. package/dist/src/entities/initiatives/namespace.d.ts +71 -7
  162. package/dist/src/entities/me/namespace.d.ts +28 -3
  163. package/dist/src/entities/meetings/meeting.d.ts +46 -8
  164. package/dist/src/entities/meetings/namespace.d.ts +20 -4
  165. package/dist/src/entities/memory/namespace.d.ts +49 -0
  166. package/dist/src/entities/memory/namespace.test.d.ts +1 -0
  167. package/dist/src/entities/messages/discussion.d.ts +84 -0
  168. package/dist/src/entities/messages/thread.d.ts +19 -5
  169. package/dist/src/entities/notifications/namespace.d.ts +41 -7
  170. package/dist/src/entities/notifications/notification.d.ts +31 -6
  171. package/dist/src/entities/passwords/item.d.ts +118 -0
  172. package/dist/src/entities/passwords/namespace.d.ts +45 -0
  173. package/dist/src/entities/pins/namespace.d.ts +23 -4
  174. package/dist/src/entities/projects/namespace.d.ts +29 -0
  175. package/dist/src/entities/projects/project.d.ts +58 -7
  176. package/dist/src/entities/properties/namespace.d.ts +67 -11
  177. package/dist/src/entities/properties/namespace.test.d.ts +1 -0
  178. package/dist/src/entities/properties/property-definition.d.ts +30 -5
  179. package/dist/src/entities/properties/property-option.d.ts +14 -2
  180. package/dist/src/entities/referrals/namespace.d.ts +8 -1
  181. package/dist/src/entities/routines/namespace.d.ts +198 -14
  182. package/dist/src/entities/routines/routine.d.ts +174 -27
  183. package/dist/src/entities/routines/suggestion.d.ts +38 -0
  184. package/dist/src/entities/saved-views/namespace.d.ts +58 -0
  185. package/dist/src/entities/saved-views/saved-view.d.ts +78 -0
  186. package/dist/src/entities/search/exclusions.d.ts +6 -0
  187. package/dist/src/entities/search/namespace.d.ts +9 -3
  188. package/dist/src/entities/search/options.d.ts +3 -2
  189. package/dist/src/entities/sharing/access.d.ts +50 -9
  190. package/dist/src/entities/spreadsheets/spreadsheet.d.ts +201 -0
  191. package/dist/src/entities/suggestions/namespace.d.ts +118 -0
  192. package/dist/src/entities/suggestions/suggestion.d.ts +172 -0
  193. package/dist/src/entities/suggestions/suggestion.test.d.ts +1 -0
  194. package/dist/src/entities/tasks/namespace.d.ts +18 -5
  195. package/dist/src/entities/tasks/task.d.ts +21 -3
  196. package/dist/src/entities/teams/invite.d.ts +3 -0
  197. package/dist/src/entities/teams/namespace.d.ts +10 -2
  198. package/dist/src/entities/teams/team.d.ts +22 -2
  199. package/dist/src/entities/ui/app-link.d.ts +24 -0
  200. package/dist/src/entities/ui/namespace.d.ts +75 -0
  201. package/dist/src/entities/unfurls/namespace.d.ts +12 -2
  202. package/dist/src/entities/users/namespace.d.ts +26 -4
  203. package/dist/src/entities/users/profile-picture.d.ts +29 -0
  204. package/dist/src/entities/users/profile-picture.test.d.ts +1 -0
  205. package/dist/src/entities/users/user.d.ts +52 -1
  206. package/dist/src/entities/web/namespace.d.ts +6 -0
  207. package/dist/src/entities/webhooks/namespace.d.ts +5 -0
  208. package/dist/src/entities/webhooks/webhook.d.ts +47 -7
  209. package/dist/src/entities/whatsapp/account.d.ts +5 -1
  210. package/dist/src/entities/whatsapp/chat.d.ts +9 -1
  211. package/dist/src/entities/whatsapp/namespace.d.ts +7 -1
  212. package/dist/src/entities/workspace/namespace.d.ts +12 -4
  213. package/dist/src/entities/workspace/query.d.ts +5 -1
  214. package/dist/src/entities/workspace/query.test.d.ts +1 -0
  215. package/dist/src/events/hydrate/document.d.ts +5 -0
  216. package/dist/src/events/hydrate/user.d.ts +14 -0
  217. package/dist/src/events/receiver.d.ts +2 -0
  218. package/dist/src/events/types.d.ts +2 -1
  219. package/dist/src/macro.d.ts +59 -6
  220. package/dist/src/macro.js +18710 -10355
  221. package/dist/src/utils/activity.d.ts +2 -0
  222. package/dist/src/utils/index.d.ts +1 -1
  223. package/dist/src/utils/lazy.d.ts +20 -1
  224. package/dist/src/utils/options.d.ts +7 -0
  225. package/dist/src/utils/pagination.d.ts +16 -0
  226. package/dist/src/utils/verbs.d.ts +3 -0
  227. package/package.json +1 -1
  228. package/dist/src/entities/crm/comment.d.ts +0 -64
@@ -1,6 +1,7 @@
1
1
  import type { EmailConnectionProviders } from '../../../generated/auth/types.gen';
2
2
  import type { ApiSortMethod, TransferRecoveryResponse } from '../../../generated/email/types.gen';
3
3
  import type { ListEmailRemindersData } from '../../../generated/storage/types.gen';
4
+ import { type IterationOptions } from '../../utils';
4
5
  import type { MacroClient } from '../../utils/client';
5
6
  import type { SearchOpts } from '../search/options';
6
7
  import { EmailAttachment } from './attachment';
@@ -11,8 +12,8 @@ import { Link } from './link';
11
12
  import { type ConfirmedEmailOptions, EmailMessage, type SendEmailOptions, type SentEmail } from './message';
12
13
  import { EmailThread } from './thread';
13
14
  /** Options for listing inbox threads. */
14
- export interface InboxOptions {
15
- /** Page size (default 20, max 500). */
15
+ export interface InboxOptions extends IterationOptions {
16
+ /** Threads fetched per request (default 50, max 500). */
16
17
  pageSize?: number;
17
18
  /** Sort order. Defaults to `viewed_updated`. */
18
19
  sort?: ApiSortMethod;
@@ -30,31 +31,64 @@ export interface InboxOptions {
30
31
  * ## Sending email
31
32
  *
32
33
  * - Nothing leaves without the user seeing it. A program cannot call `send` or `EmailThread.reply`; they are refused, and so is a draft's `send` or `schedule` without `userConfirmation`.
33
- * - In an agent session, present the email as a review: `execution.reviews.create({kind: 'email', title, drafts})`, each draft with the same fields as `sendConfirmed` (Markdown `body`, `to`/`cc`/`bcc`, `from` as the inbox's address, `replyingToId`, `attachments: [{documentId}]`), then return `reviews: [await review.reference()]`. The user sends it from the card. For a forward, `await message.forwardDraft({to, body})` is the draft.
34
+ * - In an agent session, present the email as a review: `execution.reviews.create({kind: 'email', title, drafts})`, each draft with the same fields as `sendConfirmed` (Markdown `body`, `to`/`cc`/`bcc`, `from` as the inbox's address or a verified send-as alias of it, `replyingToId`, `attachments: [{documentId}]`), then return `reviews: [await review.reference()]`. The user sends it from the card. For a forward, `await message.forwardDraft({to, body})` is the draft.
34
35
  * - For a prompt from a channel or document thread, where no card is seen: write the whole email into your reply, ask whether to send it, and stop. Only once the user replies approving that email, send it with their reply quoted in `userConfirmation`: `sendConfirmed` for a new email or a reply, `EmailMessage.forwardConfirmed` for a forward, `EmailDraft.send` or `EmailDraft.schedule` for a saved draft. Being asked to send an email is a request to draft one, never the approval.
35
36
  */
36
37
  export declare class EmailNamespace {
37
38
  private readonly client;
38
- /** Create a draft without sending it; the inbox defaults to the caller's primary. */
39
+ /**
40
+ * Create a draft without sending it; the inbox defaults to the caller's primary.
41
+ *
42
+ * @write
43
+ * @openworld
44
+ */
39
45
  createDraft(options: DraftOptions, inbox?: Link): Promise<EmailDraft>;
40
- /** Construct a lazy draft handle. */
46
+ /**
47
+ * Construct a lazy draft handle.
48
+ *
49
+ * @readonly
50
+ */
41
51
  draftById(id: string): EmailDraft;
42
- /** Scheduled drafts, fetched lazily in bounded pages. */
52
+ /**
53
+ * Scheduled drafts, fetched lazily in bounded pages.
54
+ *
55
+ * @readonly
56
+ */
43
57
  scheduled(options?: {
44
58
  pageSize?: number;
45
59
  inbox?: Link;
60
+ maxItems?: number;
46
61
  }): AsyncGenerator<EmailDraft>;
47
- /** Importance filters. */
62
+ private scheduledPages;
63
+ /**
64
+ * Importance filters.
65
+ *
66
+ * @readonly
67
+ */
48
68
  filters(inbox?: Link): Promise<EmailFilter[]>;
49
- /** Create or replace a filter matching an address or domain. */
69
+ /**
70
+ * Create or replace a filter matching an address or domain.
71
+ *
72
+ * @write
73
+ * @idempotent
74
+ */
50
75
  upsertFilter(options: EmailFilterOptions, inbox?: Link): Promise<EmailFilter>;
51
- /** Address book contacts grouped by the service's interaction buckets. */
76
+ /**
77
+ * Address book contacts grouped by the service's interaction buckets.
78
+ *
79
+ * @readonly
80
+ */
52
81
  contacts(): Promise<{
53
82
  [key: string]: import("../../../generated/email").ContactInfoWithInteraction[];
54
83
  }>;
55
- /** Follow-up reminders with thread handles, automatically paginated. */
84
+ /**
85
+ * Follow-up reminders with thread handles, automatically paginated; `maxItems` caps the total.
86
+ *
87
+ * @readonly
88
+ */
56
89
  reminders(options?: Omit<NonNullable<ListEmailRemindersData['query']>, 'inboxIds' | 'cursor'> & {
57
90
  inboxes?: Link[];
91
+ maxItems?: number;
58
92
  }): AsyncGenerator<{
59
93
  thread: EmailThread;
60
94
  followup: import("../../../generated/storage").EmailFollowup;
@@ -62,22 +96,50 @@ export declare class EmailNamespace {
62
96
  constructor(client: MacroClient);
63
97
  /** A handle to an email thread by id. */
64
98
  byId(id: string): EmailThread;
65
- /** A handle to an email message by id. */
99
+ /**
100
+ * A handle to an email message by id.
101
+ *
102
+ * @readonly
103
+ */
66
104
  message(id: string): EmailMessage;
67
- /** A handle to an email attachment by id. */
105
+ /**
106
+ * A handle to an email attachment by id.
107
+ *
108
+ * @readonly
109
+ */
68
110
  attachment(id: string): EmailAttachment;
69
- /** A handle to a connected inbox (email link) by id. */
111
+ /**
112
+ * A handle to a connected inbox (email link) by id.
113
+ *
114
+ * @readonly
115
+ */
70
116
  link(id: string): Link;
71
- /** The caller's connected inboxes (email links). */
117
+ /**
118
+ * The caller's connected inboxes (email links).
119
+ *
120
+ * @readonly
121
+ */
72
122
  links(): Promise<Link[]>;
73
- /** Providers the server currently permits this caller to connect. */
123
+ /**
124
+ * Providers the server currently permits this caller to connect.
125
+ *
126
+ * @readonly
127
+ */
74
128
  connectionProviders(): Promise<EmailConnectionProviders>;
75
129
  /** Recover a draft move using its original operation UUID; never starts a new move.
76
- * An empty committed result fences the old move so it cannot commit later. */
130
+ * An empty committed result fences the old move so it cannot commit later.
131
+ *
132
+ * @write
133
+ * @openworld
134
+ * @idempotent
135
+ */
77
136
  recoverDraftTransfer(operationId: string): Promise<TransferRecoveryResponse>;
78
137
  /**
79
138
  * Send a new plain-text email; an agent's program is refused (403) and
80
139
  * sends through a review or {@link sendConfirmed} instead.
140
+ *
141
+ * @send
142
+ * @openworld
81
143
  */
82
144
  send(opts: SendEmailOptions): Promise<EmailMessage | undefined>;
83
145
  /**
@@ -92,6 +154,9 @@ export declare class EmailNamespace {
92
154
  * thread) and Macro documents to attach. The send takes effect at once and
93
155
  * is never retried; on an error, look for the message in the thread before
94
156
  * sending again.
157
+ *
158
+ * @send
159
+ * @openworld
95
160
  */
96
161
  sendConfirmed(opts: ConfirmedEmailOptions): Promise<SentEmail>;
97
162
  /**
@@ -99,27 +164,72 @@ export declare class EmailNamespace {
99
164
  * search for their quoted email address, not their name: a name only
100
165
  * matches where that display name appears. Resolve the address first, for
101
166
  * example with `macro.users.search(name)`.
167
+ *
168
+ * @readonly
102
169
  */
103
170
  search(query: string, opts?: SearchOpts): AsyncGenerator<EmailThread>;
104
- /** The threads in the inbox, most recent first, auto-paginated. */
171
+ /**
172
+ * The threads in the inbox, most recent first, auto-paginated; `maxItems` caps the total.
173
+ *
174
+ * @readonly
175
+ */
105
176
  inbox(opts?: InboxOptions): AsyncGenerator<EmailThread>;
106
- /** A handle to a label by id. */
177
+ /**
178
+ * A handle to a label by id.
179
+ *
180
+ * @readonly
181
+ */
107
182
  label(id: string): Label;
108
- /** All labels across the user's inboxes. */
183
+ /**
184
+ * All labels across the user's inboxes.
185
+ *
186
+ * @readonly
187
+ */
109
188
  labels(): Promise<Label[]>;
110
- /** Create a user label. Returns the created label. */
189
+ /**
190
+ * Create a user label. Returns the created label.
191
+ *
192
+ * @write
193
+ * @openworld
194
+ */
111
195
  createLabel(name: string): Promise<Label>;
112
196
  /**
113
197
  * Archive many threads (or unarchive with `false`). Resolves to the threads
114
198
  * whose state could not change.
199
+ *
200
+ * @write
201
+ * @openworld
202
+ * @idempotent
115
203
  */
116
204
  archive(threads: EmailThread[], archived?: boolean): Promise<EmailThread[]>;
117
- /** Delete a label. */
205
+ /**
206
+ * Delete a label.
207
+ *
208
+ * @destructive
209
+ * @openworld
210
+ * @idempotent
211
+ */
118
212
  deleteLabel(label: Label): Promise<void>;
119
- /** Block an email sender. */
213
+ /**
214
+ * Block an email sender.
215
+ *
216
+ * @write
217
+ * @openworld
218
+ * @idempotent
219
+ */
120
220
  blockSender(email: string): Promise<void>;
121
- /** Unblock a previously blocked sender. */
221
+ /**
222
+ * Unblock a previously blocked sender.
223
+ *
224
+ * @write
225
+ * @openworld
226
+ * @idempotent
227
+ */
122
228
  unblockSender(email: string): Promise<void>;
123
- /** The email addresses currently blocked. */
229
+ /**
230
+ * The email addresses currently blocked.
231
+ *
232
+ * @readonly
233
+ */
124
234
  blockedSenders(): Promise<string[]>;
125
235
  }
@@ -1,13 +1,15 @@
1
- import type { ApiContactInfo, ApiDraftContactInfo, CalendarInvitation, GetThreadResponses, MailboxOperation, UpdateThreadStateRequest } from '../../../generated/email/types.gen';
1
+ import type { ApiContactInfo, ApiDraftContactInfo, ApiThreadPreviewCursorInner, CalendarInvitation, GetThreadResponses, MailboxOperation, UpdateThreadStateRequest } from '../../../generated/email/types.gen';
2
2
  import type { EmailFollowupCommand } from '../../../generated/storage/types.gen';
3
3
  import type { MacroClient } from '../../utils/client';
4
4
  import type { Calendar } from '../calendar/calendar';
5
5
  import { CalendarEvent } from '../calendar/event';
6
+ import type { Channel } from '../channels/channel';
6
7
  import { PropertiedEntity } from '../entity';
7
8
  import { Project } from '../projects/project';
8
9
  import { EntityAccess } from '../sharing/access';
9
10
  import { type SharePermissionOptions } from '../sharing/permissions';
10
11
  import { EmailAttachment } from './attachment';
12
+ import { EmailDraft } from './draft';
11
13
  import type { Label } from './label';
12
14
  import { Link } from './link';
13
15
  import { EmailMessage } from './message';
@@ -45,11 +47,24 @@ export interface EmailReadReceipt {
45
47
  export declare class EmailThread extends PropertiedEntity<ThreadDetail> {
46
48
  /** Access requests and direct user grants. */
47
49
  readonly access: EntityAccess;
48
- /** Read follow-up state for this thread. */
50
+ /**
51
+ * Read follow-up state for this thread.
52
+ *
53
+ * @readonly
54
+ */
49
55
  followup(): Promise<import("../../../generated/storage").EmailFollowupResponse>;
50
- /** Set or remove a follow-up using a persisted operation id and revision. */
56
+ /**
57
+ * Set or remove a follow-up using a persisted operation id and revision.
58
+ *
59
+ * @write
60
+ * @idempotent
61
+ */
51
62
  setFollowup(command: EmailFollowupCommand): Promise<import("../../../generated/storage").EmailFollowup>;
52
- /** Calendar invitations resolved from this thread's messages. */
63
+ /**
64
+ * Calendar invitations resolved from this thread's messages.
65
+ *
66
+ * @readonly
67
+ */
53
68
  calendarInvitations(): Promise<{
54
69
  [key: string]: import("../../../generated/email").InvitationResolution;
55
70
  }>;
@@ -64,7 +79,11 @@ export declare class EmailThread extends PropertiedEntity<ThreadDetail> {
64
79
  * instead, `already_on_calendar` when the meeting is already on one of
65
80
  * their calendars, whichever calendar is named (it cannot be added to
66
81
  * another of theirs either), and `copy_refused` when Google will not
67
- * import it. */
82
+ * import it.
83
+ *
84
+ * @write
85
+ * @openworld
86
+ */
68
87
  addEventToCalendar(message: EmailMessage, invitation: CalendarInvitation, options?: {
69
88
  calendar?: Calendar;
70
89
  }): Promise<CalendarEvent>;
@@ -72,19 +91,39 @@ export declare class EmailThread extends PropertiedEntity<ThreadDetail> {
72
91
  * Opens recorded for messages sent from the caller's own or delegated
73
92
  * inboxes with read receipts on, newest message first. Counts are
74
93
  * approximate: some mail apps prefetch images and others block them.
94
+ *
95
+ * @readonly
75
96
  */
76
97
  readReceipts(): Promise<EmailReadReceipt[]>;
77
- /** Change project membership or share permissions for this thread. */
98
+ /**
99
+ * Change project membership or share permissions for this thread.
100
+ *
101
+ * @write
102
+ * @idempotent
103
+ */
78
104
  update(options: {
79
105
  project?: Project | null;
80
106
  sharePermission?: SharePermissionOptions;
81
107
  }): Promise<void>;
82
108
  /** Favorites identify email threads as `email_thread`. */
83
109
  readonly entityType = "email_thread";
110
+ /**
111
+ * Share this email thread with a channel's current members, as posting it in the
112
+ * channel does. The caller must be in the channel and able to share the
113
+ * email thread; sharing again changes nothing.
114
+ *
115
+ * @write
116
+ * @idempotent
117
+ */
118
+ shareWithChannel(channel: Channel): Promise<void>;
84
119
  /** The properties service identifies email threads as `THREAD`. */
85
120
  protected readonly propertyEntityType = "THREAD";
86
121
  protected fetch(): Promise<ThreadDetail>;
87
- /** The thread's URL in the Macro web app; hand it to users as the link. */
122
+ /**
123
+ * The thread's URL in the Macro web app; hand it to users as the link.
124
+ *
125
+ * @readonly
126
+ */
88
127
  webUrl(): string;
89
128
  /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
90
129
  toJSON(): {
@@ -94,6 +133,12 @@ export declare class EmailThread extends PropertiedEntity<ThreadDetail> {
94
133
  };
95
134
  /** A handle to a thread by id. Details load on first access. */
96
135
  static byId(client: MacroClient, id: string): EmailThread;
136
+ /**
137
+ * A handle seeded from an inbox preview with the thread columns it carries.
138
+ * Its subject is the latest message's and its times are inbox sort times,
139
+ * so `subject()` and the timestamps still read the thread.
140
+ */
141
+ static fromPreview(client: MacroClient, preview: ApiThreadPreviewCursorInner): EmailThread;
97
142
  /** When the thread was created. */
98
143
  readonly createdAt: () => Promise<string>;
99
144
  /** When the thread was last updated. */
@@ -116,47 +161,108 @@ export declare class EmailThread extends PropertiedEntity<ThreadDetail> {
116
161
  readonly latestOutboundAt: () => Promise<string | undefined>;
117
162
  /** Timestamp of the latest non-spam message, if any. */
118
163
  readonly latestNonSpamAt: () => Promise<string | undefined>;
119
- /** The thread's subject, from its first message with one. */
164
+ /**
165
+ * The thread's subject, from its first message with one.
166
+ *
167
+ * @readonly
168
+ */
120
169
  subject(): Promise<string | undefined>;
121
170
  /**
122
171
  * Everyone on the thread (senders and recipients), deduped by email.
123
172
  * Derived from the thread's first 100 messages.
173
+ *
174
+ * @readonly
124
175
  */
125
176
  participants(): Promise<ApiContactInfo[]>;
126
- /** The messages in this thread, pre-seeded from the list endpoint. */
177
+ /**
178
+ * The messages in this thread, pre-seeded from the list endpoint.
179
+ *
180
+ * @readonly
181
+ */
127
182
  messages(opts?: {
128
183
  since?: string;
129
184
  limit?: number;
130
185
  }): Promise<EmailMessage[]>;
131
- /** The attachments across this thread's first 100 messages, pre-seeded from the thread detail. */
186
+ /**
187
+ * The unsent drafts among this thread's first 100 messages, from the thread detail.
188
+ *
189
+ * @readonly
190
+ */
191
+ drafts(): Promise<EmailDraft[]>;
192
+ /**
193
+ * The attachments across this thread's first 100 messages, pre-seeded from the thread detail.
194
+ *
195
+ * @readonly
196
+ */
132
197
  attachments(): Promise<EmailAttachment[]>;
133
198
  /**
134
199
  * Send a plain-text reply in this thread; an agent's program is refused
135
200
  * (403) and replies through a review or `email.sendConfirmed` with
136
201
  * `replyingTo` instead. Returns a handle when the API reports the created
137
202
  * message's id.
203
+ *
204
+ * @send
205
+ * @openworld
138
206
  */
139
207
  reply(opts: ReplyEmailOptions): Promise<EmailMessage | undefined>;
140
- /** Archive the thread (or unarchive with `false`). */
208
+ /**
209
+ * Archive the thread (or unarchive with `false`).
210
+ *
211
+ * @write
212
+ * @openworld
213
+ * @idempotent
214
+ */
141
215
  archive(archived?: boolean): Promise<void>;
142
216
  /**
143
217
  * Archive many threads (or unarchive with `false`), sending one request per
144
218
  * 100 threads. Resolves to the threads whose state could not change.
145
219
  */
146
220
  static archiveMany(client: MacroClient, threads: EmailThread[], archived?: boolean): Promise<EmailThread[]>;
147
- /** Update provider-neutral read, trash, spam, or star state. */
221
+ /**
222
+ * Update provider-neutral read, trash, spam, or star state.
223
+ *
224
+ * @destructive
225
+ * @openworld
226
+ * @idempotent
227
+ */
148
228
  updateState(request: UpdateThreadStateRequest): Promise<void>;
149
- /** Read pending or failed mailbox changes without initiating a retry. */
229
+ /**
230
+ * Read pending or failed mailbox changes without initiating a retry.
231
+ *
232
+ * @readonly
233
+ */
150
234
  operations(): Promise<MailboxOperation[]>;
151
- /** Mark the thread as seen. */
235
+ /**
236
+ * Mark the thread as seen.
237
+ *
238
+ * @write
239
+ * @idempotent
240
+ */
152
241
  markSeen(): Promise<void>;
153
- /** Add a label to every message in the thread. */
242
+ /**
243
+ * Add a label to every message in the thread.
244
+ *
245
+ * @write
246
+ * @openworld
247
+ * @idempotent
248
+ */
154
249
  addLabel(label: Label): Promise<void>;
155
- /** Remove a label from every message in the thread. */
250
+ /**
251
+ * Remove a label from every message in the thread.
252
+ *
253
+ * @write
254
+ * @openworld
255
+ * @idempotent
256
+ */
156
257
  removeLabel(label: Label): Promise<void>;
157
- /** Attach the thread to a project, or clear the project with `null`. */
258
+ /**
259
+ * Attach the thread to a project, or clear the project with `null`.
260
+ *
261
+ * @write
262
+ * @idempotent
263
+ */
158
264
  moveToProject(project: Project | null): Promise<void>;
159
- /** Search email threads by subject and content, most relevant first, auto-paginated. */
265
+ /** Search email threads by subject and content, most relevant first, auto-paginated; `maxItems` caps the total. */
160
266
  static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<EmailThread, any, any>;
161
267
  }
162
268
  export {};
@@ -7,7 +7,12 @@ export declare class EntityMention {
7
7
  private constructor();
8
8
  /** Construct a mention handle for removal. */
9
9
  static byId(client: MacroClient, id: string): EntityMention;
10
- /** Remove this mention. */
10
+ /**
11
+ * Remove this mention.
12
+ *
13
+ * @destructive
14
+ * @idempotent
15
+ */
11
16
  delete(): Promise<void>;
12
17
  /** Serialize identity only. */
13
18
  toJSON(): {
@@ -11,6 +11,10 @@ export declare class EntityMentionNamespace {
11
11
  constructor(client: MacroClient);
12
12
  /** Construct a stored mention handle. */
13
13
  byId(id: string): EntityMention;
14
- /** Create a mention from a source resource to a target resource. */
14
+ /**
15
+ * Create a mention from a source resource to a target resource.
16
+ *
17
+ * @write
18
+ */
15
19
  create(source: EntityReference, target: EntityReference): Promise<EntityMention>;
16
20
  }
@@ -41,6 +41,13 @@ export declare abstract class MacroEntity<Detail> {
41
41
  readonly id: string;
42
42
  protected readonly detail: Lazy<Detail>;
43
43
  protected constructor(client: MacroClient, id: string, seed?: Detail);
44
+ /**
45
+ * Seed fields a listing returned, so {@link field} and {@link mappedField}
46
+ * read them without loading the detail. Map listing fields onto detail keys
47
+ * only where both mean the same thing; leave out anything the listing
48
+ * leaves empty or reports differently. Returns this handle.
49
+ */
50
+ protected withListed(fields: Partial<Detail>): this;
44
51
  /** Load the detail record backing {@link field} accessors. */
45
52
  protected abstract fetch(): Promise<Detail>;
46
53
  /** A lazy accessor for one detail field, `null` normalized to `undefined`. */
@@ -51,6 +58,7 @@ export declare abstract class MacroEntity<Detail> {
51
58
  * `this.mappedField('owner', (id) => User.byId(this.client, id))`.
52
59
  */
53
60
  protected mappedField<K extends keyof Detail, T>(key: K, map: (value: Normalized<Detail[K]>) => T): () => Promise<T>;
61
+ private readDetailField;
54
62
  toJSON(): {
55
63
  id: string;
56
64
  detail?: Detail;
@@ -66,7 +74,11 @@ export declare abstract class MacroEntity<Detail> {
66
74
  export declare abstract class FavoritableEntity<Detail> extends MacroEntity<Detail> implements Favoritable {
67
75
  /** How the entity-addressed APIs (favorites) identify this entity's type. */
68
76
  abstract readonly entityType: MacroEntityType;
69
- /** Read the caller's effective permission on this entity. */
77
+ /**
78
+ * Read the caller's effective permission on this entity.
79
+ *
80
+ * @readonly
81
+ */
70
82
  permission(): Promise<{
71
83
  permission: import("../../generated/storage").EntityPermission;
72
84
  status: "access";
@@ -77,9 +89,33 @@ export declare abstract class FavoritableEntity<Detail> extends MacroEntity<Deta
77
89
  * Add this entity to the user's favorites. Returns this handle for chaining.
78
90
  * Plain unwrap: favoriting alters the user's favorites collection, not this
79
91
  * entity's own detail, so there's nothing cached to invalidate.
92
+ *
93
+ * @write
94
+ * @idempotent
80
95
  */
81
96
  favorite(): Promise<this>;
82
- /** Remove this entity from the user's favorites. Returns this handle for chaining. */
97
+ /**
98
+ * Mute notifications about this item for the user only, as Mute in the app
99
+ * does; with `until`, a snooze that ends then. Nobody else's notifications
100
+ * change. Returns this handle for chaining.
101
+ *
102
+ * @write
103
+ */
104
+ muteNotifications(opts?: {
105
+ /** When notifications resume; must be in the future. Omit to mute until unmuted. */
106
+ until?: Date;
107
+ }): Promise<this>;
108
+ /** Resume notifications about this item, ending a mute or snooze. Returns this handle for chaining.
109
+ *
110
+ * @write
111
+ */
112
+ unmuteNotifications(): Promise<this>;
113
+ /**
114
+ * Remove this entity from the user's favorites. Returns this handle for chaining.
115
+ *
116
+ * @write
117
+ * @idempotent
118
+ */
83
119
  unfavorite(): Promise<this>;
84
120
  }
85
121
  /** A favoritable entity that also carries user-defined properties. */
@@ -89,20 +125,43 @@ export declare abstract class PropertiedEntity<Detail> extends FavoritableEntity
89
125
  * differently from {@link entityType} (e.g. `THREAD` for `email_thread`).
90
126
  */
91
127
  protected abstract readonly propertyEntityType: PropertyEntityType;
92
- /** This entity's reference for bulk property operations. */
128
+ /**
129
+ * This entity's reference for bulk property operations.
130
+ *
131
+ * @readonly
132
+ */
93
133
  propertyReference(): PropertyTargetReference;
94
- /** The properties set on this entity, each with its definition, value, and options. */
134
+ /**
135
+ * The properties set on this entity, each with its definition, value, and options.
136
+ *
137
+ * @readonly
138
+ */
95
139
  properties(opts?: {
96
140
  includeMetadata?: boolean;
97
141
  }): Promise<EntityPropertyWithDefinition[]>;
98
142
  /**
99
143
  * Set a property value on this entity, or attach the property without a
100
144
  * value when `value` is omitted.
145
+ *
146
+ * @write
147
+ * @idempotent
101
148
  */
102
149
  setProperty(property: PropertyDefinition, value?: SetPropertyValue): Promise<void>;
103
- /** Apply multi-select option deltas atomically across this entity's properties. */
150
+ /**
151
+ * Apply multi-select option deltas atomically across this entity's properties.
152
+ *
153
+ * @write
154
+ * @idempotent
155
+ * @mcp-exclude Takes a handle built from a listing record, which an MCP call can't reference.
156
+ */
104
157
  updatePropertyOptions(changes: PropertyOptionDelta[]): Promise<BulkUpdateEntityPropertyOptionsResponse>;
105
- /** Remove a property from this entity, given its {@link properties} entry. */
158
+ /**
159
+ * Clear one property's value on this item, given its {@link properties}
160
+ * entry; the item itself and the property's definition are kept.
161
+ *
162
+ * @destructive
163
+ * @idempotent
164
+ */
106
165
  deleteProperty(assignment: EntityPropertyWithDefinition): Promise<void>;
107
166
  }
108
167
  export {};