@macro-inc/sdk 0.4.1 → 0.5.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 (185) hide show
  1. package/README.md +169 -7
  2. package/dist/{chunk-PTX2RV2N.js → chunk-3SW6QVDV.js} +33 -0
  3. package/dist/{chunk-XFA7NCJ5.js → chunk-GT5EUYOR.js} +13 -15
  4. package/dist/{chunk-ZLBDES7U.js → chunk-HIW6KU2I.js} +490 -4
  5. package/dist/{chunk-AZJUIUIV.js → chunk-J2VK3NOR.js} +56 -0
  6. package/dist/{chunk-PZPTJI6F.js → chunk-UVJLWLSJ.js} +41 -2
  7. package/dist/generated/agent-fold/index.d.ts +8 -6
  8. package/dist/generated/agent-harness/index.d.ts +1 -1
  9. package/dist/generated/agent-harness/index.js +1 -1
  10. package/dist/generated/agent-harness/sdk.gen.d.ts +17 -1
  11. package/dist/generated/agent-harness/types.gen.d.ts +188 -3
  12. package/dist/generated/auth/index.js +1 -1
  13. package/dist/generated/auth/sdk.gen.d.ts +13 -15
  14. package/dist/generated/auth/types.gen.d.ts +36 -17
  15. package/dist/generated/cognition/index.d.ts +1 -1
  16. package/dist/generated/cognition/index.js +1 -1
  17. package/dist/generated/cognition/sdk.gen.d.ts +38 -1
  18. package/dist/generated/cognition/types.gen.d.ts +473 -4
  19. package/dist/generated/connection/types.gen.d.ts +1 -1
  20. package/dist/generated/notification/index.d.ts +1 -1
  21. package/dist/generated/notification/types.gen.d.ts +36 -1
  22. package/dist/generated/scheduled-action/index.d.ts +1 -1
  23. package/dist/generated/scheduled-action/index.js +1 -1
  24. package/dist/generated/scheduled-action/sdk.gen.d.ts +17 -2
  25. package/dist/generated/scheduled-action/types.gen.d.ts +642 -104
  26. package/dist/generated/storage/index.d.ts +1 -1
  27. package/dist/generated/storage/index.js +1 -1
  28. package/dist/generated/storage/sdk.gen.d.ts +204 -5
  29. package/dist/generated/storage/types.gen.d.ts +3969 -374
  30. package/dist/src/entities/account-managers/grant.d.ts +28 -5
  31. package/dist/src/entities/account-managers/namespace.d.ts +15 -3
  32. package/dist/src/entities/activity/entity.d.ts +7 -0
  33. package/dist/src/entities/activity/namespace.d.ts +58 -0
  34. package/dist/src/entities/activity/namespace.test.d.ts +1 -0
  35. package/dist/src/entities/agent-sessions/activity.d.ts +10 -2
  36. package/dist/src/entities/agent-sessions/agent-session.d.ts +193 -18
  37. package/dist/src/entities/agent-sessions/code-execution.d.ts +15 -3
  38. package/dist/src/entities/agent-sessions/conversation.d.ts +46 -9
  39. package/dist/src/entities/agent-sessions/namespace.d.ts +71 -16
  40. package/dist/src/entities/agent-sessions/origin.d.ts +1 -1
  41. package/dist/src/entities/agent-sessions/queued-action.d.ts +17 -3
  42. package/dist/src/entities/agent-sessions/review.d.ts +55 -4
  43. package/dist/src/entities/agent-sessions/tool-approval.d.ts +5 -1
  44. package/dist/src/entities/agents/agent.d.ts +98 -3
  45. package/dist/src/entities/agents/namespace.d.ts +52 -8
  46. package/dist/src/entities/ai/namespace.d.ts +9 -1
  47. package/dist/src/entities/api-keys/api-key.d.ts +6 -1
  48. package/dist/src/entities/api-keys/namespace.d.ts +15 -3
  49. package/dist/src/entities/bots/bot.d.ts +38 -6
  50. package/dist/src/entities/bots/namespace.d.ts +13 -1
  51. package/dist/src/entities/bots/token.d.ts +6 -1
  52. package/dist/src/entities/calendar/booking-link.d.ts +7 -1
  53. package/dist/src/entities/calendar/booking-namespace.d.ts +13 -0
  54. package/dist/src/entities/calendar/booking.d.ts +15 -0
  55. package/dist/src/entities/calendar/calendar.d.ts +7 -1
  56. package/dist/src/entities/calendar/event.d.ts +59 -9
  57. package/dist/src/entities/calendar/namespace.d.ts +88 -10
  58. package/dist/src/entities/calendar/replacement.d.ts +19 -3
  59. package/dist/src/entities/calls/call-record.d.ts +90 -14
  60. package/dist/src/entities/calls/connection.d.ts +7 -1
  61. package/dist/src/entities/calls/message.d.ts +27 -5
  62. package/dist/src/entities/calls/namespace.d.ts +15 -3
  63. package/dist/src/entities/canvases/canvas.d.ts +324 -0
  64. package/dist/src/entities/channels/access-request.d.ts +10 -2
  65. package/dist/src/entities/channels/activity.d.ts +20 -4
  66. package/dist/src/entities/channels/channel.d.ts +130 -23
  67. package/dist/src/entities/channels/labels.d.ts +41 -7
  68. package/dist/src/entities/channels/message.d.ts +41 -7
  69. package/dist/src/entities/channels/namespace.d.ts +28 -3
  70. package/dist/src/entities/channels/post.test.d.ts +1 -0
  71. package/dist/src/entities/channels/thread.d.ts +19 -3
  72. package/dist/src/entities/chats/chat.d.ts +56 -6
  73. package/dist/src/entities/chats/generation.d.ts +11 -2
  74. package/dist/src/entities/chats/namespace.d.ts +10 -2
  75. package/dist/src/entities/connected-apps/connected-app.d.ts +14 -1
  76. package/dist/src/entities/connected-apps/connector.d.ts +3 -0
  77. package/dist/src/entities/connected-apps/namespace.d.ts +16 -0
  78. package/dist/src/entities/crm/company.d.ts +63 -15
  79. package/dist/src/entities/crm/contact.d.ts +60 -13
  80. package/dist/src/entities/crm/namespace.d.ts +85 -11
  81. package/dist/src/entities/crm/pipeline-entry.d.ts +102 -0
  82. package/dist/src/entities/crm/pipeline.d.ts +271 -27
  83. package/dist/src/entities/crm/pipelines.d.ts +39 -2
  84. package/dist/src/entities/databases/column.d.ts +54 -7
  85. package/dist/src/entities/databases/database.d.ts +126 -12
  86. package/dist/src/entities/databases/namespace.d.ts +16 -4
  87. package/dist/src/entities/databases/row.d.ts +2 -0
  88. package/dist/src/entities/databases/saved-query.d.ts +145 -0
  89. package/dist/src/entities/databases/table.d.ts +64 -10
  90. package/dist/src/entities/databases/view.d.ts +27 -5
  91. package/dist/src/entities/databases/webhook.d.ts +8 -1
  92. package/dist/src/entities/documents/ai-edit.d.ts +2 -0
  93. package/dist/src/entities/documents/anchor.d.ts +12 -2
  94. package/dist/src/entities/documents/comment.d.ts +29 -5
  95. package/dist/src/entities/documents/document.d.ts +243 -20
  96. package/dist/src/entities/documents/markdown.d.ts +25 -0
  97. package/dist/src/entities/documents/namespace.d.ts +132 -13
  98. package/dist/src/entities/documents/skills.test.d.ts +1 -0
  99. package/dist/src/entities/documents/system-skill.d.ts +21 -1
  100. package/dist/src/entities/documents/text-comment.d.ts +41 -0
  101. package/dist/src/entities/documents/text-comment.test.d.ts +1 -0
  102. package/dist/src/entities/documents/version.d.ts +5 -1
  103. package/dist/src/entities/email/attachment.d.ts +3 -0
  104. package/dist/src/entities/email/draft.d.ts +61 -9
  105. package/dist/src/entities/email/filter.d.ts +12 -2
  106. package/dist/src/entities/email/label.d.ts +7 -1
  107. package/dist/src/entities/email/link.d.ts +5 -1
  108. package/dist/src/entities/email/message.d.ts +55 -8
  109. package/dist/src/entities/email/namespace.d.ts +127 -21
  110. package/dist/src/entities/email/thread.d.ts +99 -16
  111. package/dist/src/entities/entity-mentions/mention.d.ts +6 -1
  112. package/dist/src/entities/entity-mentions/namespace.d.ts +5 -1
  113. package/dist/src/entities/entity.d.ts +56 -6
  114. package/dist/src/entities/external-chat/chat.d.ts +62 -11
  115. package/dist/src/entities/external-chat/message.d.ts +1 -1
  116. package/dist/src/entities/external-chat/namespace.d.ts +5 -1
  117. package/dist/src/entities/external-chat/send.d.ts +10 -2
  118. package/dist/src/entities/favorites/namespace.d.ts +20 -3
  119. package/dist/src/entities/foreign/foreign-entity.d.ts +5 -1
  120. package/dist/src/entities/foreign/namespace.d.ts +4 -0
  121. package/dist/src/entities/forms/form.d.ts +71 -13
  122. package/dist/src/entities/forms/namespace.d.ts +10 -2
  123. package/dist/src/entities/forms/question.d.ts +35 -7
  124. package/dist/src/entities/forms/response.d.ts +25 -5
  125. package/dist/src/entities/forms/section.d.ts +15 -3
  126. package/dist/src/entities/github-pull-requests/namespace.d.ts +5 -1
  127. package/dist/src/entities/github-pull-requests/pull-request.d.ts +15 -3
  128. package/dist/src/entities/harnesses/harness.d.ts +51 -3
  129. package/dist/src/entities/harnesses/namespace.d.ts +53 -7
  130. package/dist/src/entities/harnesses/pairing.d.ts +12 -2
  131. package/dist/src/entities/images/image.d.ts +16 -5
  132. package/dist/src/entities/images/namespace.d.ts +8 -1
  133. package/dist/src/entities/initiatives/initiative.d.ts +117 -3
  134. package/dist/src/entities/initiatives/initiative.test.d.ts +1 -0
  135. package/dist/src/entities/initiatives/namespace.d.ts +69 -7
  136. package/dist/src/entities/me/namespace.d.ts +27 -2
  137. package/dist/src/entities/meetings/meeting.d.ts +45 -8
  138. package/dist/src/entities/meetings/namespace.d.ts +20 -4
  139. package/dist/src/entities/memory/namespace.d.ts +49 -0
  140. package/dist/src/entities/memory/namespace.test.d.ts +1 -0
  141. package/dist/src/entities/messages/discussion.d.ts +84 -0
  142. package/dist/src/entities/messages/thread.d.ts +19 -5
  143. package/dist/src/entities/notifications/namespace.d.ts +40 -7
  144. package/dist/src/entities/notifications/notification.d.ts +29 -5
  145. package/dist/src/entities/pins/namespace.d.ts +23 -4
  146. package/dist/src/entities/projects/namespace.d.ts +29 -0
  147. package/dist/src/entities/projects/project.d.ts +47 -6
  148. package/dist/src/entities/properties/namespace.d.ts +67 -11
  149. package/dist/src/entities/properties/namespace.test.d.ts +1 -0
  150. package/dist/src/entities/properties/property-definition.d.ts +30 -5
  151. package/dist/src/entities/properties/property-option.d.ts +14 -2
  152. package/dist/src/entities/referrals/namespace.d.ts +8 -1
  153. package/dist/src/entities/routines/namespace.d.ts +128 -7
  154. package/dist/src/entities/routines/routine.d.ts +111 -25
  155. package/dist/src/entities/saved-views/namespace.d.ts +57 -0
  156. package/dist/src/entities/saved-views/saved-view.d.ts +78 -0
  157. package/dist/src/entities/search/namespace.d.ts +5 -1
  158. package/dist/src/entities/sharing/access.d.ts +50 -9
  159. package/dist/src/entities/spreadsheets/spreadsheet.d.ts +201 -0
  160. package/dist/src/entities/tasks/namespace.d.ts +13 -1
  161. package/dist/src/entities/tasks/task.d.ts +7 -1
  162. package/dist/src/entities/teams/invite.d.ts +3 -0
  163. package/dist/src/entities/teams/namespace.d.ts +10 -2
  164. package/dist/src/entities/teams/team.d.ts +7 -0
  165. package/dist/src/entities/unfurls/namespace.d.ts +12 -2
  166. package/dist/src/entities/users/namespace.d.ts +19 -1
  167. package/dist/src/entities/users/profile-picture.d.ts +29 -0
  168. package/dist/src/entities/users/profile-picture.test.d.ts +1 -0
  169. package/dist/src/entities/users/user.d.ts +52 -1
  170. package/dist/src/entities/web/namespace.d.ts +6 -0
  171. package/dist/src/entities/webhooks/namespace.d.ts +5 -0
  172. package/dist/src/entities/webhooks/webhook.d.ts +47 -7
  173. package/dist/src/entities/whatsapp/account.d.ts +5 -1
  174. package/dist/src/entities/whatsapp/chat.d.ts +9 -1
  175. package/dist/src/entities/whatsapp/namespace.d.ts +7 -1
  176. package/dist/src/entities/workspace/namespace.d.ts +7 -1
  177. package/dist/src/entities/workspace/query.d.ts +5 -1
  178. package/dist/src/events/hydrate/user.d.ts +14 -0
  179. package/dist/src/events/receiver.d.ts +2 -0
  180. package/dist/src/events/types.d.ts +2 -1
  181. package/dist/src/macro.d.ts +33 -5
  182. package/dist/src/macro.js +15635 -10132
  183. package/dist/src/utils/lazy.d.ts +7 -1
  184. package/package.json +1 -1
  185. package/dist/src/entities/crm/comment.d.ts +0 -64
package/README.md CHANGED
@@ -69,6 +69,13 @@ 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
@@ -176,6 +183,18 @@ await doc.setTeamShare(true);
176
183
  await doc.delete(); // soft delete; doc.restore() brings it back
177
184
  ```
178
185
 
186
+ Documents, projects, calls and chats change their link and channel sharing with
187
+ `updateSharePermissions`; omitted fields are left as they are. A calendar event
188
+ is shared with a channel's members through `shareWithChannel`:
189
+
190
+ ```ts
191
+ await project.updateSharePermissions({
192
+ linkShareAccessLevel: 'view',
193
+ channelSharePermissions: [{ channel, accessLevel: 'comment', operation: 'add' }],
194
+ });
195
+ await event.shareWithChannel(channel);
196
+ ```
197
+
179
198
  ### Listing and searching
180
199
 
181
200
  List/search methods that can page return a genreator that auto-paginates:
@@ -235,6 +254,22 @@ nonempty means a read hit the row cap and aggregates may be partial. SQL schemas
235
254
  are dynamic, so result cells use a generated tagged union rather than an inferred
236
255
  TypeScript interface for each table. The HTTP route is `POST /databases/query`.
237
256
 
257
+ To show a live answer in a document, save the `SELECT` as a question. The
258
+ server refuses anything but one `SELECT` that compiles, and chart columns the
259
+ `SELECT` does not return (`POST /databases/queries`). `toBlock()` is the
260
+ `<m-db-query>` block to put in a document's Markdown; it re-runs for whoever
261
+ views it. `withView()` restyles the answer without saving a new question.
262
+
263
+ ```ts
264
+ const question = await database.saveQuery({
265
+ sql: 'SELECT "Party", COUNT(*) AS invites FROM "Guests" GROUP BY "Party"',
266
+ title: 'Invites per party',
267
+ display: { mode: 'bar', chart: { x: 'Party', y: ['invites'] } },
268
+ });
269
+ await macro.documents.create({ name: 'Invites', markdown: question.toBlock() });
270
+ const pie = question.withView({ displayMode: 'pie' }).toBlock();
271
+ ```
272
+
238
273
  The SDK's schema methods write typed ops through one endpoint,
239
274
  `POST /databases/{id}/ops`. The methods below each send a one-op batch: the
240
275
  SDK mints the new table, column, and option ids (UUIDv7) itself and builds the
@@ -373,7 +408,9 @@ These will render as @mentions in the Macro UI.
373
408
  `macro.images.generate()` makes an image with Google's Nano Banana model, charged
374
409
  to the acting user's AI allowance, and stores it as a static file. Attach it to a
375
410
  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
411
+ the image loads. `image.toMarkdown()` is the `<m-image>` tag that shows it inline
412
+ in Markdown, such as an agent's reply; a static image is not a document, so never
413
+ mention its id as one. Pass up to three image documents or earlier images as
377
414
  `referenceImages` to edit or combine them. `examples/generate-image.ts` runs this
378
415
  end to end.
379
416
 
@@ -422,6 +459,29 @@ const transcript = await routine.execute(); // Chat or AgentSession, if availabl
422
459
  const executions = await routine.history(); // Each retains its parent routine
423
460
  ```
424
461
 
462
+ A routine can instead run `steps` in order: `code` steps run TypeScript against
463
+ this SDK as the owner, type-checked when saved, and an `agent` ("Ask AI") step
464
+ hands the run to a model or agent. Code steps' writes are attributed to Macro's
465
+ agent acting for the owner; set `dangerouslyOperateAsUser: true` only when the
466
+ user explicitly asks for the routine to act, send or post as them:
467
+
468
+ ```ts
469
+ await macro.routines.create({
470
+ name: 'Say hello',
471
+ trigger: { type: 'once', at: '2027-11-03T14:30:00Z' },
472
+ steps: [
473
+ {
474
+ type: 'code',
475
+ title: 'Post hello',
476
+ source: `export async function main({ macro }: StepContext) {
477
+ await macro.channels.byId(channelId).send('Hello');
478
+ }`,
479
+ },
480
+ ],
481
+ dangerouslyOperateAsUser: true,
482
+ });
483
+ ```
484
+
425
485
  Event triggers use `{ type: 'events', filters: [{ events, entities, condition }] }`;
426
486
  `entities` takes typed references such as `{ type: 'document', entity: doc }`.
427
487
  Use `{ type: 'multiple', triggers: [...] }` to combine schedules and events.
@@ -460,8 +520,13 @@ await routine.update({
460
520
 
461
521
  ### Agents, conversations and hosts
462
522
 
463
- `macro.agents.list/create/byId` manage agent configuration. `AgentOptions` takes
464
- channel, team and host handles. Updates replace the configuration.
523
+ `macro.agents.list/create/byId` manage agent configuration; listed agents read
524
+ their runtime, coding/chat choice, apps, channel scope and permission settings.
525
+ `agent.update(patch)` changes only the settings it names (`PATCH /agents/{id}`);
526
+ `agent.replace(options)` replaces everything, including the owning team, and
527
+ `AgentOptions` takes channel, team and host handles. `macro.agents.coding()` lists the coding personas the caller can
528
+ start right now, built-in ones such as Cursor included; pass an entry's `agent`
529
+ to `macro.agentSessions.createManaged`.
465
530
  `channel.agentConversations()` returns conversations with session and turn handles;
466
531
  `conversation.startFresh(session)` and `turn.retry(actionId)` expose explicit
467
532
  conversation controls. `session.toolApprovalById(id).answer(answer)` answers a
@@ -506,6 +571,44 @@ with `setImportant` and `delete`. Omit the inbox to select the caller's primary.
506
571
  caller-persisted operation IDs. `email.reminders({ inboxes })` auto-paginates and
507
572
  returns thread handles alongside reminder snapshots.
508
573
 
574
+ ### Saved views
575
+
576
+ ```ts
577
+ const view = await macro.savedViews.create({
578
+ name: 'Invoices',
579
+ config: {
580
+ kind: 'email',
581
+ version: 1,
582
+ filters: {
583
+ inboxIds: [], participants: [{ type: 'domain', domain: 'example.com' }],
584
+ participantFields: ['from'], subject: ['invoice'], starred: false,
585
+ attachments: [], calendarInvite: false, tags: [],
586
+ },
587
+ },
588
+ });
589
+ await view.edit({ name: 'Bills', team: macro.teams.byId(teamId) });
590
+ for await (const each of macro.savedViews.list({ kind: 'email' })) {
591
+ console.log(await each.name());
592
+ }
593
+ await macro.savedViews.reorder('email', [view]);
594
+ await view.remove();
595
+ ```
596
+
597
+ A saved view is a named filter definition the app shows in a surface's sidebar
598
+ (`kind` picks the surface, such as Email). `edit` and `remove` are checked
599
+ against the revision the handle last saw: a write made elsewhere since then
600
+ fails with a 409 conflict instead of being overwritten, and `view.refresh()`
601
+ picks up the current revision. Order is personal; `reorder` sets yours for one
602
+ kind.
603
+
604
+ ### CRM contact fields
605
+
606
+ `macro.crm.contactById(id).setEmail(address)` adds an address only when absent;
607
+ an identical retry is safe. Existing addresses cannot be replaced or cleared.
608
+ `setCompany(company)` links or switches a known personal-provider contact to a
609
+ Company handle in the same team. Unlinking is not supported. Both preserve
610
+ identity and reject same-team email conflicts without merging records.
611
+
509
612
  ### CRM pipelines and initiatives
510
613
 
511
614
  `macro.crm.pipelines.create/list/byId` returns pipeline handles. Rename, sharing,
@@ -520,9 +623,17 @@ atomic database operation contract, including batch-local UUIDs, like
520
623
  `Database.applyOps`. Table and column reads share a schema cache invalidated by
521
624
  successful batches. Call `row.refresh()` to reload a row after a batch changes it.
522
625
 
523
- `macro.initiatives.create/list/byId` groups tasks and members. Relations return user
626
+ `macro.initiatives.create/byId` groups tasks and members. Relations return user
524
627
  and task handles; `initiative.update({ name, members, sharePermission })` and
525
- `delete()` manage it.
628
+ `delete()` manage it. `initiatives.list({ query, status, priority, assignee,
629
+ dueAfter, dueBefore, sort })` iterates the matching initiatives with their Status,
630
+ Priority, assignees, due date and progress over the tasks the caller can view;
631
+ `initiatives.summaries()` reads every name in one request.
632
+ `initiative.description()` returns its description as Markdown, and
633
+ `comments()`, `comment(body)` and `commentById(id)` read and write its
634
+ discussion; `comment.reply(body)` answers a thread. Its comments are the same
635
+ `DiscussionComment` handles CRM companies and contacts use (formerly
636
+ `CrmComment`).
526
637
 
527
638
  ### Access requests and message threads
528
639
 
@@ -605,6 +716,53 @@ It returns the new revision, not a diff; read `content()` to see what changed.
605
716
  refused edit throws `DocumentEditRefusedError` with the editor's reason;
606
717
  `EditOutcomeUnknownError` means read the document before retrying.
607
718
 
719
+ ### Canvases
720
+
721
+ `document.canvas()` reads and edits a native canvas's live, shared scene:
722
+
723
+ ```ts
724
+ const canvas = document.canvas();
725
+ const scene = await canvas.scene(); // stable item ids, geometry, text, revision
726
+ await canvas.apply(
727
+ "editor.move(['box'], 0, 40); editor.text('box', snippets.label)",
728
+ { expectedRevision: scene.revision, snippets: { label: 'Shipped' } },
729
+ );
730
+ await canvas.edit('Arrange the boxes left to right as a flowchart.');
731
+ const image = await canvas.render({ items: ['box'] }); // a StaticImage
732
+ ```
733
+
734
+ `apply` runs CanvasEditor code without a model and commits the batch whole or
735
+ not at all: `CanvasRevisionConflictError` (the scene changed since
736
+ `expectedRevision`) and `CanvasEditRejectedError` (the code failed) mean nothing
737
+ changed; `EditOutcomeUnknownError` means read the scene before retrying. `edit`
738
+ takes natural-language instructions, like `document.edit`, and is billed as an
739
+ AI edit. `render` keeps the PNG as a static file you own, ready to attach to a
740
+ message. A canvas links to `canvas.webUrl()` (`/app/canvas/<id>`).
741
+
742
+ ### Spreadsheets
743
+
744
+ `documents.createSpreadsheet({ name })` creates a blank native spreadsheet, and
745
+ `documents.spreadsheet(document)` addresses an existing one. `read()` returns
746
+ every sheet's summary and the cells of the requested ranges with the revision,
747
+ `calculate(formulas, { overrides })` evaluates scratch formulas without saving,
748
+ and `applyEdits(operations, { expectedRevision })` saves one atomic batch:
749
+
750
+ ```ts
751
+ const sheet = macro.documents.spreadsheet(document);
752
+ const { revision, sheets } = await sheet.read({ ranges: ['A1:D20'] });
753
+ await sheet.applyEdits(
754
+ [{ type: 'set_cells', sheetId: sheets[0].id, cells: [{ address: 'D21', value: '=SUM(D2:D20)' }] }],
755
+ { expectedRevision: revision },
756
+ );
757
+ ```
758
+
759
+ A workbook that changed since the read throws `RevisionConflictError` and
760
+ saves nothing: read again and rebuild the batch.
761
+
762
+ `sheet.edit(instructions)` hands the change to an AI writer instead, which reads
763
+ what it needs and saves one batch the same way. It is billed as an AI edit and
764
+ throws `DocumentEditRefusedError` with the writer's reason when it can't do it.
765
+
608
766
  ### Document lifecycle and other resources
609
767
 
610
768
  `documents.createUpload(options)` reserves a binary document and returns upload
@@ -662,13 +820,17 @@ replay if you disconnect.
662
820
  Handlers receive the same hydrated payloads as webhook deliveries — ORM
663
821
  handles for every entity the event names.
664
822
 
665
- Four families are delivered: `document.*`, `channel.*`, `message.*`, and
666
- `agent_session.*`. Message events (`posted`, `patched`, `deleted`, `mentioned`,
823
+ Five families are delivered: `document.*`, `channel.*`, `message.*`, `user.*`,
824
+ and `agent_session.*`. Message events (`posted`, `patched`, `deleted`, `mentioned`,
667
825
  `attachment_created`, `attachment_removed`) cover channel messages and document
668
826
  comments alike: `metadata.parent` names the channel or document, and the
669
827
  hydrated `target` carries a `Channel` plus `Message` (and the `Thread` for a
670
828
  reply) or a `Document` plus `Comment`. `macro.events.onSelfMention` subscribes to
671
829
  `message.mentioned` deliveries that name the caller.
830
+ `user.picture_changed` tells you a user's own profile picture changed (set or
831
+ removed) and is delivered only to the changed user's own workspaces; it hydrates
832
+ to the `User` and, when the picture is a static file, its `StaticImage` (`image`
833
+ is undefined when the picture was removed or set by URL).
672
834
  Agent-session events describe a coding agent's life: `opened`, `turn_started`,
673
835
  `turn_ended`, `settled` (a turn ended with nothing queued behind it),
674
836
  `waiting_for_input` (the agent asked its owner a question), `input_received`,
@@ -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,6 +1385,20 @@ 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
@@ -1427,6 +1448,18 @@ var Sdk = class _Sdk extends HeyApiClient {
1427
1448
  listAgentWorkRegistrations(options) {
1428
1449
  return (options?.client ?? this.client).get({ url: "/agent-work-registrations", ...options });
1429
1450
  }
1451
+ /**
1452
+ * List the coding agents the caller can start a session as: the same
1453
+ * personas the `ListCodingAgents` tool offers, including built-in ones whose
1454
+ * runtime the caller has connected (Cursor once its key is saved).
1455
+ */
1456
+ listCodingAgents(options) {
1457
+ return (options?.client ?? this.client).get({
1458
+ security: [{ scheme: "bearer", type: "http" }],
1459
+ url: "/coding-agents",
1460
+ ...options
1461
+ });
1462
+ }
1430
1463
  /**
1431
1464
  * Classify a draft for the authenticated user.
1432
1465
  */
@@ -971,13 +971,16 @@ var Sdk = class _Sdk extends HeyApiClient {
971
971
  });
972
972
  }
973
973
  /**
974
- * Choose the model this user's `@cursor` sessions start on.
974
+ * Choose the model, and optionally the effort, this user's `@cursor` sessions
975
+ * start on.
975
976
  *
976
- * Stores the id only; its parameters are resolved from Cursor's own default
977
- * variant at session start. Not validated against the live model list here —
978
- * the settings dropdown offers only real ids, and a stale id degrades to the
979
- * deployment default at spawn rather than failing, so a round trip to Cursor
980
- * on every save would buy nothing.
977
+ * Stores the id and effort value only; the other parameters are resolved from
978
+ * Cursor's own variants at session start. Saving a model without an effort
979
+ * clears the previous effort, which belonged to the previous model. Not
980
+ * validated against the live model list here — the settings controls offer
981
+ * only real values, and a stale id or effort degrades to the deployment or
982
+ * model default at spawn rather than failing, so a round trip to Cursor on
983
+ * every save would buy nothing.
981
984
  */
982
985
  putCursorDefaultModel(options) {
983
986
  return (options.client ?? this.client).put({
@@ -1480,15 +1483,10 @@ var Sdk = class _Sdk extends HeyApiClient {
1480
1483
  return (options?.client ?? this.client).post({ url: "/team/auto-join-domain/toggle", ...options });
1481
1484
  }
1482
1485
  /**
1483
- * Enables or disables CRM for the team. On enable with `backfill`
1484
- * (the default), kicks off a best-effort backfill that enqueues a
1485
- * `PopulateCrmForUser` message per team member (no-op if CRM is
1486
- * already enabled); without `backfill` the CRM starts empty and fills
1487
- * from new activity only. On disable,
1488
- * flips the flag and purges the team's CRM data (cascading through
1489
- * `crm_companies` → `crm_domains` / `crm_contacts` /
1490
- * `crm_contact_sources`). Requires the caller to be an Admin or
1491
- * Owner of the team.
1486
+ * Legacy compatibility endpoint for team admins and owners. Enabling
1487
+ * is a no-op; disabling is rejected. CRM records remain available.
1488
+ * Each member manages mailbox contribution through `/crm/email-privacy`;
1489
+ * this endpoint does not enroll mailboxes, backfill emails, or purge records.
1492
1490
  */
1493
1491
  patchTeamCrmSettings(options) {
1494
1492
  return (options.client ?? this.client).patch({