@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
package/README.md CHANGED
@@ -63,12 +63,19 @@ An API key always acts as the user who minted it. `requestedAs` is bot-only.
63
63
  #### Agent accounts
64
64
 
65
65
  An agent has its own account and seat. Invite one with
66
- `(await macro.teams.current()).invite('agent@example.com', { agent: true })`, or sign
67
- up at https://macro.com/app/signup/agent. After signing in, the agent sees its API key once in the
66
+ `(await macro.teams.current()).invite('agent@example.com', { agent: true })` from your own
67
+ key (an agent's program is refused), or sign up at https://macro.com/app/signup/agent. After signing in, the agent sees its API key once in the
68
68
  web app and uses it like any other key. It can set up its profile with
69
69
  `macro.me.update({ name, profilePicture: await macro.me.uploadProfilePicture(bytes, options) })`
70
70
  and mint more keys with `macro.apiKeys.create(name)`.
71
71
 
72
+ Switch between earlier uploads with `macro.me.update({ profilePicture: macro.images.byId(savedId) })`,
73
+ and read pictures with `macro.me.profilePicture()`, `user.profilePicture()` or
74
+ `macro.users.profilePictures(users)`. Pictures set through Macro are a
75
+ `StaticImage`; legacy URL pictures are an `ExternalProfilePicture` (`{ url }`).
76
+ Setting a picture is throttled to once a second per user and uploads to 20 an
77
+ hour; both fail with 429 beyond that.
78
+
72
79
  #### Account managers
73
80
 
74
81
  An agent account can manage a person's account: either side asks in their DM, and
@@ -81,7 +88,9 @@ const grant = await macro.accountManagers.askToManage(person);
81
88
  const token = await grant.claimToken();
82
89
  ```
83
90
 
84
- A person can ask instead, with `macro.accountManagers.askToBeManagedBy(agent)`. Only the
91
+ An agent's program (ExecuteCode, a routine) can't ask, approve or claim: those return 403,
92
+ so an agent account uses its own API key. A person can ask instead, with
93
+ `macro.accountManagers.askToBeManagedBy(agent)`. Only the
85
94
  manager can claim, so the agent approves and claims with its own client, using the grant id
86
95
  from the card in the DM: `macro.accountManagers.byId(id)`.
87
96
 
@@ -176,6 +185,41 @@ await doc.setTeamShare(true);
176
185
  await doc.delete(); // soft delete; doc.restore() brings it back
177
186
  ```
178
187
 
188
+ ### Entity appearance
189
+
190
+ Markdown documents, snippets, initiatives (task projects), forms, databases,
191
+ and routines expose `appearance()` and `setAppearance()`. Appearance is shared
192
+ with other viewers and requires edit access to change.
193
+
194
+ ```ts
195
+ await doc.setAppearance({
196
+ icon: { kind: 'emoji', value: '🌱' },
197
+ color: 'green',
198
+ });
199
+ const appearance = await doc.appearance();
200
+ await doc.setAppearance({}); // restore the default icon and color
201
+ ```
202
+
203
+ Writes replace both overrides without changing content timestamps. Omit an
204
+ override to restore its default. Colors use the same twelve-color palette as
205
+ tags and only tint Macro icons; native emoji keep their own colors.
206
+
207
+ ### Sharing permissions
208
+ Documents, projects, calls and chats change their link and channel sharing with
209
+ `updateSharePermissions`; omitted fields are left as they are. Any item a
210
+ channel message can carry (a document or task, project, database, form, call,
211
+ email thread, agent session, external chat or calendar event) is shared with a
212
+ channel's current members, as posting it there does, through `shareWithChannel`:
213
+
214
+ ```ts
215
+ await project.updateSharePermissions({
216
+ linkShareAccessLevel: 'view',
217
+ channelSharePermissions: [{ channel, accessLevel: 'comment', operation: 'add' }],
218
+ });
219
+ await doc.shareWithChannel(channel);
220
+ await event.shareWithChannel(channel);
221
+ ```
222
+
179
223
  ### Listing and searching
180
224
 
181
225
  List/search methods that can page return a genreator that auto-paginates:
@@ -235,6 +279,23 @@ nonempty means a read hit the row cap and aggregates may be partial. SQL schemas
235
279
  are dynamic, so result cells use a generated tagged union rather than an inferred
236
280
  TypeScript interface for each table. The HTTP route is `POST /databases/query`.
237
281
 
282
+ To show a live answer in a document, save the `SELECT` as a question. The
283
+ server refuses anything but one `SELECT` that compiles, and chart columns the
284
+ `SELECT` does not return (`POST /databases/queries`). `toBlock()` is the
285
+ `<m-db-query>` block to put in a document's Markdown; it re-runs for whoever
286
+ views it. `withView()` restyles the answer without saving a new question.
287
+ `macro.databases.saveQuery()` saves a question whose tables span databases.
288
+
289
+ ```ts
290
+ const question = await database.saveQuery({
291
+ sql: 'SELECT "Party", COUNT(*) AS invites FROM "Guests" GROUP BY "Party"',
292
+ title: 'Invites per party',
293
+ display: { mode: 'bar', chart: { x: 'Party', y: ['invites'] } },
294
+ });
295
+ await macro.documents.create({ name: 'Invites', markdown: question.toBlock() });
296
+ const pie = question.withView({ displayMode: 'pie' }).toBlock();
297
+ ```
298
+
238
299
  The SDK's schema methods write typed ops through one endpoint,
239
300
  `POST /databases/{id}/ops`. The methods below each send a one-op batch: the
240
301
  SDK mints the new table, column, and option ids (UUIDv7) itself and builds the
@@ -373,7 +434,9 @@ These will render as @mentions in the Macro UI.
373
434
  `macro.images.generate()` makes an image with Google's Nano Banana model, charged
374
435
  to the acting user's AI allowance, and stores it as a static file. Attach it to a
375
436
  message with `images`; its width and height let the message reserve space before
376
- the image loads. Pass up to three image documents or earlier images as
437
+ the image loads. `image.toMarkdown()` is the `<m-image>` tag that shows it inline
438
+ in Markdown, such as an agent's reply; a static image is not a document, so never
439
+ mention its id as one. Pass up to three image documents or earlier images as
377
440
  `referenceImages` to edit or combine them. `examples/generate-image.ts` runs this
378
441
  end to end.
379
442
 
@@ -405,23 +468,59 @@ await macro.channels
405
468
  .send(msg`Deploy ${sha} finished. ${here}`);
406
469
  ```
407
470
 
471
+ Pass `{ silent: true }` to `send` or `reply` for a routine update that should
472
+ notify nobody, mentioned people included; the message still appears in the
473
+ channel. It works with every credential.
474
+
408
475
  ### Routines
409
476
 
410
- Create scheduled or event-triggered agent tasks through `macro.routines`.
411
- Routine configuration takes typed agent and event resource handles:
477
+ Create scheduled or event-triggered routines through `macro.routines`. A
478
+ routine runs `steps` in order: an `agent` ("Ask AI") step hands the run to a
479
+ model or agent, and `code` steps run TypeScript against this SDK as the owner,
480
+ type-checked when saved. Routine configuration takes typed agent and event
481
+ resource handles:
412
482
 
413
483
  ```ts
414
484
  const routine = await macro.routines.create({
415
485
  name: 'Daily summary',
416
- prompt: 'Summarize my open tasks.',
417
- userPrompt: 'A daily task summary',
418
- trigger: { type: 'cron', schedule: '0 9 * * *', timezone: 'America/New_York' },
486
+ trigger: { type: 'cron', schedule: '0 0 9 * * *', timezone: 'America/New_York' },
487
+ steps: [
488
+ {
489
+ type: 'agent',
490
+ instructions: 'Summarize my open tasks.',
491
+ model: 'anthropic/claude-sonnet-5-5',
492
+ },
493
+ ],
419
494
  });
420
495
  await routine.setEnabled(false);
421
496
  const transcript = await routine.execute(); // Chat or AgentSession, if available
422
497
  const executions = await routine.history(); // Each retains its parent routine
423
498
  ```
424
499
 
500
+ A cron `schedule` has 6 fields (second minute hour day-of-month month
501
+ day-of-week) or 7 with a year. The older single agent task (`prompt` and
502
+ `userPrompt`, with `model`, `agent` or both, instead of `steps`) still saves
503
+ and runs as one Ask AI step. Code steps' writes are attributed to Macro's
504
+ agent acting for the owner; set `dangerouslyOperateAsUser: true` only when the
505
+ user explicitly asks for the routine to act, send or post as them:
506
+
507
+ ```ts
508
+ await macro.routines.create({
509
+ name: 'Say hello',
510
+ trigger: { type: 'once', at: '2027-11-03T14:30:00Z' },
511
+ steps: [
512
+ {
513
+ type: 'code',
514
+ title: 'Post hello',
515
+ source: `export async function main({ macro }: StepContext) {
516
+ await macro.channels.byId(channelId).send('Hello');
517
+ }`,
518
+ },
519
+ ],
520
+ dangerouslyOperateAsUser: true,
521
+ });
522
+ ```
523
+
425
524
  Event triggers use `{ type: 'events', filters: [{ events, entities, condition }] }`;
426
525
  `entities` takes typed references such as `{ type: 'document', entity: doc }`.
427
526
  Use `{ type: 'multiple', triggers: [...] }` to combine schedules and events.
@@ -460,8 +559,13 @@ await routine.update({
460
559
 
461
560
  ### Agents, conversations and hosts
462
561
 
463
- `macro.agents.list/create/byId` manage agent configuration. `AgentOptions` takes
464
- channel, team and host handles. Updates replace the configuration.
562
+ `macro.agents.list/create/byId` manage agent configuration; listed agents read
563
+ their runtime, coding/chat choice, apps, channel scope and permission settings.
564
+ `agent.update(patch)` changes only the settings it names (`PATCH /agents/{id}`);
565
+ `agent.replace(options)` replaces everything, including the owning team, and
566
+ `AgentOptions` takes channel, team and host handles. `macro.agents.coding()` lists the coding personas the caller can
567
+ start right now, built-in ones such as Cursor included; pass an entry's `agent`
568
+ to `macro.agentSessions.createManaged`.
465
569
  `channel.agentConversations()` returns conversations with session and turn handles;
466
570
  `conversation.startFresh(session)` and `turn.retry(actionId)` expose explicit
467
571
  conversation controls. `session.toolApprovalById(id).answer(answer)` answers a
@@ -506,6 +610,125 @@ with `setImportant` and `delete`. Omit the inbox to select the caller's primary.
506
610
  caller-persisted operation IDs. `email.reminders({ inboxes })` auto-paginates and
507
611
  returns thread handles alongside reminder snapshots.
508
612
 
613
+ ### Saved views
614
+
615
+ ```ts
616
+ const view = await macro.savedViews.create({
617
+ name: 'Invoices',
618
+ config: {
619
+ kind: 'email',
620
+ version: 1,
621
+ filters: {
622
+ inboxIds: [], participants: [{ type: 'domain', domain: 'example.com' }],
623
+ participantFields: ['from'], subject: ['invoice'], starred: false,
624
+ attachments: [], calendarInvite: false, tags: [],
625
+ },
626
+ },
627
+ });
628
+ await view.edit({ name: 'Bills', team: macro.teams.byId(teamId) });
629
+ for await (const each of macro.savedViews.list({ kind: 'email' })) {
630
+ console.log(await each.name());
631
+ }
632
+ await macro.savedViews.reorder('email', [view]);
633
+ await view.remove();
634
+ ```
635
+
636
+ A saved view is a named filter definition the app shows in a surface's sidebar
637
+ (`kind` picks the surface, such as Email). `edit` and `remove` are checked
638
+ against the revision the handle last saw: a write made elsewhere since then
639
+ fails with a 409 conflict instead of being overwritten, and `view.refresh()`
640
+ picks up the current revision. Order is personal; `reorder` sets yours for one
641
+ kind.
642
+
643
+ ### CRM email contribution
644
+
645
+ `macro.crm.emailPrivacy` manages only the authenticated member's contribution,
646
+ including when their CRM viewing permission is off. `get()` is read-only and
647
+ returns the current mode, selectors, mailbox handle and observed-state token.
648
+ `settings()` reads domain exclusions; `excludedThreads()` lazily lists private
649
+ thread exceptions. Existing team-wide domain methods remain on `macro.crm`;
650
+ `emailPrivacy.blockDomain` and `unblockDomain` edit personal exclusions.
651
+
652
+ Rules use `{ schemaVersion: 1, include: [...] }`. Selectors are `thread` with an
653
+ `EmailThread`, `contact` with a `Contact`, `company` with a `Company`, or
654
+ `address` / `domain` with the corresponding string. A participant match includes
655
+ the whole thread, across eligible past and future mail. Contact/company rules
656
+ follow live records. Private-thread, domain and personal-email exclusions always
657
+ win. Narrowing or withdrawal leaves CRM records in place; a teammate's eligible
658
+ copy remains independent.
659
+
660
+ ```ts
661
+ const privacy = macro.crm.emailPrivacy;
662
+ const state = await privacy.get();
663
+ if (!state.authoringAvailable || !state.token) {
664
+ throw new Error('Selective contribution is unavailable.');
665
+ }
666
+ const checked = await privacy.validateRules({
667
+ schemaVersion: 1,
668
+ include: [{ kind: 'domain', domain: 'example.com' }],
669
+ });
670
+ const idempotencyKey = crypto.randomUUID();
671
+ const result = await privacy.replaceRules(checked.rules, {
672
+ ifPolicy: state.token,
673
+ idempotencyKey,
674
+ });
675
+ ```
676
+
677
+ `replaceRules` directly activates the replacement; member-authorized agents need
678
+ no separate human confirmation. `enableAll` and `withdraw` take the same options.
679
+ Keep the exact token, key and command for retries. A 409 requires fresh inspection
680
+ and a new decision; the SDK never refreshes or retries automatically. A result
681
+ with `replayed: true` describes the original commit, not current sharing. Server
682
+ rollout and credential restrictions remain authoritative.
683
+
684
+ Optional counts use `preview()` to inspect the current slot, then
685
+ `previewRules(rules, { ifPolicy: state.token, ifPreview: previousPreview })`.
686
+ A preview handle's `get()` refreshes only that preview and `cancel()` names that
687
+ exact identity. Superseded handles cannot read or cancel newer work. Only
688
+ `status: 'complete'` means exact counts; running/partial counts are lower bounds,
689
+ and stale/cancelled results are not current estimates. Counts are mailbox-local,
690
+ limited to 10,000 scanned raw threads and five minutes. Previewing does not grant
691
+ contribution or schedule mail backfill.
692
+
693
+ `history()` iterates owner-only audit events in pages of fifty. Revision handles
694
+ on current state, mutation outcomes and history read immutable definitions with
695
+ `get()`; they never fetch target content or reapply rules. Verified agent/session
696
+ provenance is read from history, never supplied by the caller.
697
+
698
+ Legacy members without a policy token retain `setConsent(false)` for withdrawal.
699
+ `setConsent(true, inbox)` uses the existing all-mail opt-in, bound to the chosen
700
+ primary inbox; members with a policy token use `enableAll` / `withdraw` instead.
701
+ `setThreadExcluded(thread, excluded)` reuses the existing thread-exclusion API and
702
+ its rollout gate. The SDK changes no flags and adds no settings UI.
703
+
704
+ ### CRM member access
705
+
706
+ `macro.crm.access()` reads the caller's current team and effective CRM access,
707
+ even when access is denied. `team.members()` includes `crmAccess` for each member.
708
+ Admins and owners use `team.setMemberCrmAccess(user, enabled)` to deny or restore
709
+ an ordinary member; admins and owners cannot be denied. This never changes the
710
+ member's mailbox contribution consent. The mutation returns 503 until the
711
+ server rollout enables access changes; existing denials remain enforced while
712
+ changes are disabled. Record, search, email and tool requests
713
+ recheck access on the server. A separately shared pipeline still exposes its own
714
+ rows and cell values, while its CRM record references need separate access.
715
+
716
+ ### CRM contact fields
717
+
718
+ A contact holds several addresses, one of them primary: `contact.emails()` lists
719
+ them, primary first. `addEmail(address)` adds one, `setEmail(address)` makes one
720
+ the primary (adding it when the contact does not hold it), and
721
+ `removeEmail(address)` removes one; removing the primary promotes the oldest
722
+ address left. Removing an address deletes nothing else: the contact stops
723
+ showing that address's mail. An identical retry of any of them is safe.
724
+
725
+ `setCompany(company)` links or switches a contact with a personal-provider
726
+ primary to a Company handle in the same team, and `unlinkCompany()` removes the
727
+ link. A contact with an address on one of its company's domains
728
+ (`contact.companyDomain()`) can do neither, and the last of those addresses
729
+ (`contact.companyDomainEmails()`) cannot be removed. All of them preserve
730
+ identity and reject same-team email conflicts without merging records.
731
+
509
732
  ### CRM pipelines and initiatives
510
733
 
511
734
  `macro.crm.pipelines.create/list/byId` returns pipeline handles. Rename, sharing,
@@ -520,9 +743,25 @@ atomic database operation contract, including batch-local UUIDs, like
520
743
  `Database.applyOps`. Table and column reads share a schema cache invalidated by
521
744
  successful batches. Call `row.refresh()` to reload a row after a batch changes it.
522
745
 
523
- `macro.initiatives.create/list/byId` groups tasks and members. Relations return user
746
+ A pipeline that tracks companies or contacts has an **Outcome** field (`Open`,
747
+ `Won` or `Lost`, independent of Stage) and a currency field beside each
748
+ monetary field, such as `Revenue currency`; new entries default to `Open` and
749
+ `USD`, and neither field can be emptied. `listWithFields()` and `find()` name
750
+ each monetary field's `currencyField`, `find()` returns one total per
751
+ `currency` for it, never converted or combined, and an update's changes carry
752
+ `beforeCurrency` and `afterCurrency` for a monetary field.
753
+
754
+ `macro.initiatives.create/byId` groups tasks and members. Relations return user
524
755
  and task handles; `initiative.update({ name, members, sharePermission })` and
525
- `delete()` manage it.
756
+ `delete()` manage it. `initiatives.list({ query, status, priority, assignee,
757
+ dueAfter, dueBefore, sort })` iterates the matching initiatives with their Status,
758
+ Priority, assignees, due date and progress over the tasks the caller can view;
759
+ `initiatives.summaries()` reads every name in one request.
760
+ `initiative.description()` returns its description as Markdown, and
761
+ `comments()`, `comment(body)` and `commentById(id)` read and write its
762
+ discussion; `comment.reply(body)` answers a thread. Its comments are the same
763
+ `DiscussionComment` handles CRM companies and contacts use (formerly
764
+ `CrmComment`).
526
765
 
527
766
  ### Access requests and message threads
528
767
 
@@ -605,6 +844,53 @@ It returns the new revision, not a diff; read `content()` to see what changed.
605
844
  refused edit throws `DocumentEditRefusedError` with the editor's reason;
606
845
  `EditOutcomeUnknownError` means read the document before retrying.
607
846
 
847
+ ### Canvases
848
+
849
+ `document.canvas()` reads and edits a native canvas's live, shared scene:
850
+
851
+ ```ts
852
+ const canvas = document.canvas();
853
+ const scene = await canvas.scene(); // stable item ids, geometry, text, revision
854
+ await canvas.apply(
855
+ "editor.move(['box'], 0, 40); editor.text('box', snippets.label)",
856
+ { expectedRevision: scene.revision, snippets: { label: 'Shipped' } },
857
+ );
858
+ await canvas.edit('Arrange the boxes left to right as a flowchart.');
859
+ const image = await canvas.render({ items: ['box'] }); // a StaticImage
860
+ ```
861
+
862
+ `apply` runs CanvasEditor code without a model and commits the batch whole or
863
+ not at all: `CanvasRevisionConflictError` (the scene changed since
864
+ `expectedRevision`) and `CanvasEditRejectedError` (the code failed) mean nothing
865
+ changed; `EditOutcomeUnknownError` means read the scene before retrying. `edit`
866
+ takes natural-language instructions, like `document.edit`, and is billed as an
867
+ AI edit. `render` keeps the PNG as a static file you own, ready to attach to a
868
+ message. A canvas links to `canvas.webUrl()` (`/app/canvas/<id>`).
869
+
870
+ ### Spreadsheets
871
+
872
+ `documents.createSpreadsheet({ name })` creates a blank native spreadsheet, and
873
+ `documents.spreadsheet(document)` addresses an existing one. `read()` returns
874
+ every sheet's summary and the cells of the requested ranges with the revision,
875
+ `calculate(formulas, { overrides })` evaluates scratch formulas without saving,
876
+ and `applyEdits(operations, { expectedRevision })` saves one atomic batch:
877
+
878
+ ```ts
879
+ const sheet = macro.documents.spreadsheet(document);
880
+ const { revision, sheets } = await sheet.read({ ranges: ['A1:D20'] });
881
+ await sheet.applyEdits(
882
+ [{ type: 'set_cells', sheetId: sheets[0].id, cells: [{ address: 'D21', value: '=SUM(D2:D20)' }] }],
883
+ { expectedRevision: revision },
884
+ );
885
+ ```
886
+
887
+ A workbook that changed since the read throws `RevisionConflictError` and
888
+ saves nothing: read again and rebuild the batch.
889
+
890
+ `sheet.edit(instructions)` hands the change to an AI writer instead, which reads
891
+ what it needs and saves one batch the same way. It is billed as an AI edit and
892
+ throws `DocumentEditRefusedError` with the writer's reason when it can't do it.
893
+
608
894
  ### Document lifecycle and other resources
609
895
 
610
896
  `documents.createUpload(options)` reserves a binary document and returns upload
@@ -622,8 +908,10 @@ takes typed source/target references and returns a deletable mention handle.
622
908
  `macro.unfurls.get(url)` and `bulk(urls)` read URL preview metadata.
623
909
 
624
910
  `macro.apiKeys.create(name)` returns `{ key, secret }`. Save the secret immediately;
625
- the handle only retains metadata. `list()` and `key.delete()` manage keys.
626
- `tokenForEmail(email)` exchanges credentials subject to ordinary server authorization.
911
+ the handle only retains metadata. It and `bot.createToken()` are refused to an
912
+ agent's program (ExecuteCode, a routine), whose results reach the model. `list()` and `key.delete()` manage keys.
913
+ `tokenForEmail(email)` exchanges credentials subject to ordinary server authorization;
914
+ an agent's program is refused.
627
915
 
628
916
  `chat.send({ content, model, attachments, toolset })` starts a generation and returns
629
917
  its chat, response message and cancellable stream handle. Use
@@ -657,18 +945,24 @@ const stop = await macro.events.listen();
657
945
  model as persisted webhooks. If you omit `filters`, it derives one filter from
658
946
  the event names already registered with `.on()`. Pass `scope: 'team'` for a
659
947
  team workspace (defaults to `'user'`). Delivery is best-effort: there is no
660
- replay if you disconnect.
948
+ replay if you disconnect. Reconnecting sends `Last-Event-ID`, but the service
949
+ replays only for clients that also ask `resume=true`, which `listen()` does
950
+ not, so a reconnected listener gets the live stream as before.
661
951
 
662
952
  Handlers receive the same hydrated payloads as webhook deliveries — ORM
663
953
  handles for every entity the event names.
664
954
 
665
- Four families are delivered: `document.*`, `channel.*`, `message.*`, and
666
- `agent_session.*`. Message events (`posted`, `patched`, `deleted`, `mentioned`,
955
+ Five families are delivered: `document.*`, `channel.*`, `message.*`, `user.*`,
956
+ and `agent_session.*`. Message events (`posted`, `patched`, `deleted`, `mentioned`,
667
957
  `attachment_created`, `attachment_removed`) cover channel messages and document
668
958
  comments alike: `metadata.parent` names the channel or document, and the
669
959
  hydrated `target` carries a `Channel` plus `Message` (and the `Thread` for a
670
960
  reply) or a `Document` plus `Comment`. `macro.events.onSelfMention` subscribes to
671
961
  `message.mentioned` deliveries that name the caller.
962
+ `user.picture_changed` tells you a user's own profile picture changed (set or
963
+ removed) and is delivered only to the changed user's own workspaces; it hydrates
964
+ to the `User` and, when the picture is a static file, its `StaticImage` (`image`
965
+ is undefined when the picture was removed or set by URL).
672
966
  Agent-session events describe a coding agent's life: `opened`, `turn_started`,
673
967
  `turn_ended`, `settled` (a turn ended with nothing queued behind it),
674
968
  `waiting_for_input` (the agent asked its owner a question), `input_received`,
@@ -789,9 +1083,10 @@ the build.
789
1083
 
790
1084
  You can add exceptions for stuff OpenAPI covers that we don't want the sdk to
791
1085
  support by adding them to the `src/coverage/skipped.ts`. You can implement
792
- support by adding a wrapper to the appropriate model. There is CI to ensure that
793
- we don't forget to add coverage or explicitly skip coverage for new generated
794
- functions (endpoints).
1086
+ support by adding a wrapper to the appropriate model. Every wrapped generated
1087
+ method also needs a hand-assigned display verb in `src/utils/verbs.ts`; choose a
1088
+ read verb for a POST that only reads. Coverage fails for missing or stale verb
1089
+ entries as well as uncovered endpoints.
795
1090
 
796
1091
  ## Events
797
1092
 
@@ -1026,6 +1026,13 @@ var Sdk = class _Sdk extends HeyApiClient {
1026
1026
  }
1027
1027
  });
1028
1028
  }
1029
+ /**
1030
+ * The caller's coding sessions waiting for their answer, or stalled for over 20 minutes,
1031
+ * newest activity first.
1032
+ */
1033
+ listAgentSessionUpdates(options) {
1034
+ return (options?.client ?? this.client).get({ url: "/agent-sessions/updates", ...options });
1035
+ }
1029
1036
  /**
1030
1037
  * Prepare MCP connections without sending a prompt or creating a visible list row.
1031
1038
  */
@@ -1378,10 +1385,24 @@ var Sdk = class _Sdk extends HeyApiClient {
1378
1385
  }
1379
1386
  });
1380
1387
  }
1388
+ /**
1389
+ * Link a session the caller owns to a task they can view, replacing any earlier link. The
1390
+ * session's pull request, now or later, is linked to the task.
1391
+ */
1392
+ linkAgentSessionTask(options) {
1393
+ return (options.client ?? this.client).put({
1394
+ url: "/agent-sessions/{session_id}/task",
1395
+ ...options,
1396
+ headers: {
1397
+ "Content-Type": "application/json",
1398
+ ...options.headers
1399
+ }
1400
+ });
1401
+ }
1381
1402
  /**
1382
1403
  * Answer a tool call the agent made in a turn somebody other than the
1383
1404
  * session's owner prompted. Approve and deny are the owner's; cancel is
1384
- * anyone's with edit access.
1405
+ * anyone's with edit access. Agent runs may deny or cancel, but never approve.
1385
1406
  */
1386
1407
  answerAgentSessionToolApproval(options) {
1387
1408
  return (options.client ?? this.client).post({
@@ -1393,6 +1414,21 @@ var Sdk = class _Sdk extends HeyApiClient {
1393
1414
  }
1394
1415
  });
1395
1416
  }
1417
+ /**
1418
+ * Open an item in a new pane of the app tab the person who prompted the
1419
+ * running turn typed in. Only a running execution of the session's current
1420
+ * turn may send, as the account it acts as.
1421
+ */
1422
+ openInApp(options) {
1423
+ return (options.client ?? this.client).post({
1424
+ url: "/agent-sessions/{session_id}/ui-commands",
1425
+ ...options,
1426
+ headers: {
1427
+ "Content-Type": "application/json",
1428
+ ...options.headers
1429
+ }
1430
+ });
1431
+ }
1396
1432
  /**
1397
1433
  * Present a view in the session: a review with nothing saved.
1398
1434
  */
@@ -1427,6 +1463,49 @@ var Sdk = class _Sdk extends HeyApiClient {
1427
1463
  listAgentWorkRegistrations(options) {
1428
1464
  return (options?.client ?? this.client).get({ url: "/agent-work-registrations", ...options });
1429
1465
  }
1466
+ /**
1467
+ * List the coding agents the caller can start a session as: the same
1468
+ * personas the `ListCodingAgents` tool offers, including built-in ones whose
1469
+ * runtime the caller has connected (Cursor once its key is saved).
1470
+ */
1471
+ listCodingAgents(options) {
1472
+ return (options?.client ?? this.client).get({
1473
+ security: [{ scheme: "bearer", type: "http" }],
1474
+ url: "/coding-agents",
1475
+ ...options
1476
+ });
1477
+ }
1478
+ /**
1479
+ * How Claude Code on the computer is paid for.
1480
+ */
1481
+ getClaudeMode(options) {
1482
+ return (options.client ?? this.client).get({ url: "/harnesses/{harness_id}/claude-mode", ...options });
1483
+ }
1484
+ /**
1485
+ * Start a Claude sign-in on the computer and return its URL.
1486
+ */
1487
+ startClaudeSignIn(options) {
1488
+ return (options.client ?? this.client).post({ url: "/harnesses/{harness_id}/claude-sign-in", ...options });
1489
+ }
1490
+ /**
1491
+ * Finish the Claude sign-in with what the user pasted.
1492
+ */
1493
+ completeClaudeSignIn(options) {
1494
+ return (options.client ?? this.client).post({
1495
+ url: "/harnesses/{harness_id}/claude-sign-in/complete",
1496
+ ...options,
1497
+ headers: {
1498
+ "Content-Type": "application/json",
1499
+ ...options.headers
1500
+ }
1501
+ });
1502
+ }
1503
+ /**
1504
+ * Forget the computer's Claude credential and return it to Macro credits.
1505
+ */
1506
+ claudeSignOut(options) {
1507
+ return (options.client ?? this.client).post({ url: "/harnesses/{harness_id}/claude-sign-out", ...options });
1508
+ }
1430
1509
  /**
1431
1510
  * Classify a draft for the authenticated user.
1432
1511
  */
@@ -1453,6 +1532,19 @@ var Sdk = class _Sdk extends HeyApiClient {
1453
1532
  }
1454
1533
  });
1455
1534
  }
1535
+ /**
1536
+ * The voices an agent teammate can speak with on calls. Team admins only.
1537
+ */
1538
+ getAgentVoices(options) {
1539
+ return (options?.client ?? this.client).get({ url: "/voices", ...options });
1540
+ }
1541
+ /**
1542
+ * A catalog voice saying a fixed line, as WAV. Team admins only; the first
1543
+ * play of each voice is billed to the admin's team.
1544
+ */
1545
+ getAgentVoiceSample(options) {
1546
+ return (options.client ?? this.client).get({ url: "/voices/{model}/sample", ...options });
1547
+ }
1456
1548
  };
1457
1549
 
1458
1550
  export {