@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.
- package/README.md +169 -7
- package/dist/{chunk-PTX2RV2N.js → chunk-3SW6QVDV.js} +33 -0
- package/dist/{chunk-XFA7NCJ5.js → chunk-GT5EUYOR.js} +13 -15
- package/dist/{chunk-ZLBDES7U.js → chunk-HIW6KU2I.js} +490 -4
- package/dist/{chunk-AZJUIUIV.js → chunk-J2VK3NOR.js} +56 -0
- package/dist/{chunk-PZPTJI6F.js → chunk-UVJLWLSJ.js} +41 -2
- package/dist/generated/agent-fold/index.d.ts +8 -6
- package/dist/generated/agent-harness/index.d.ts +1 -1
- package/dist/generated/agent-harness/index.js +1 -1
- package/dist/generated/agent-harness/sdk.gen.d.ts +17 -1
- package/dist/generated/agent-harness/types.gen.d.ts +188 -3
- package/dist/generated/auth/index.js +1 -1
- package/dist/generated/auth/sdk.gen.d.ts +13 -15
- package/dist/generated/auth/types.gen.d.ts +36 -17
- package/dist/generated/cognition/index.d.ts +1 -1
- package/dist/generated/cognition/index.js +1 -1
- package/dist/generated/cognition/sdk.gen.d.ts +38 -1
- package/dist/generated/cognition/types.gen.d.ts +473 -4
- package/dist/generated/connection/types.gen.d.ts +1 -1
- package/dist/generated/notification/index.d.ts +1 -1
- package/dist/generated/notification/types.gen.d.ts +36 -1
- package/dist/generated/scheduled-action/index.d.ts +1 -1
- package/dist/generated/scheduled-action/index.js +1 -1
- package/dist/generated/scheduled-action/sdk.gen.d.ts +17 -2
- package/dist/generated/scheduled-action/types.gen.d.ts +642 -104
- package/dist/generated/storage/index.d.ts +1 -1
- package/dist/generated/storage/index.js +1 -1
- package/dist/generated/storage/sdk.gen.d.ts +204 -5
- package/dist/generated/storage/types.gen.d.ts +3969 -374
- package/dist/src/entities/account-managers/grant.d.ts +28 -5
- package/dist/src/entities/account-managers/namespace.d.ts +15 -3
- package/dist/src/entities/activity/entity.d.ts +7 -0
- package/dist/src/entities/activity/namespace.d.ts +58 -0
- package/dist/src/entities/activity/namespace.test.d.ts +1 -0
- package/dist/src/entities/agent-sessions/activity.d.ts +10 -2
- package/dist/src/entities/agent-sessions/agent-session.d.ts +193 -18
- package/dist/src/entities/agent-sessions/code-execution.d.ts +15 -3
- package/dist/src/entities/agent-sessions/conversation.d.ts +46 -9
- package/dist/src/entities/agent-sessions/namespace.d.ts +71 -16
- package/dist/src/entities/agent-sessions/origin.d.ts +1 -1
- package/dist/src/entities/agent-sessions/queued-action.d.ts +17 -3
- package/dist/src/entities/agent-sessions/review.d.ts +55 -4
- package/dist/src/entities/agent-sessions/tool-approval.d.ts +5 -1
- package/dist/src/entities/agents/agent.d.ts +98 -3
- package/dist/src/entities/agents/namespace.d.ts +52 -8
- package/dist/src/entities/ai/namespace.d.ts +9 -1
- package/dist/src/entities/api-keys/api-key.d.ts +6 -1
- package/dist/src/entities/api-keys/namespace.d.ts +15 -3
- package/dist/src/entities/bots/bot.d.ts +38 -6
- package/dist/src/entities/bots/namespace.d.ts +13 -1
- package/dist/src/entities/bots/token.d.ts +6 -1
- package/dist/src/entities/calendar/booking-link.d.ts +7 -1
- package/dist/src/entities/calendar/booking-namespace.d.ts +13 -0
- package/dist/src/entities/calendar/booking.d.ts +15 -0
- package/dist/src/entities/calendar/calendar.d.ts +7 -1
- package/dist/src/entities/calendar/event.d.ts +59 -9
- package/dist/src/entities/calendar/namespace.d.ts +88 -10
- package/dist/src/entities/calendar/replacement.d.ts +19 -3
- package/dist/src/entities/calls/call-record.d.ts +90 -14
- package/dist/src/entities/calls/connection.d.ts +7 -1
- package/dist/src/entities/calls/message.d.ts +27 -5
- package/dist/src/entities/calls/namespace.d.ts +15 -3
- package/dist/src/entities/canvases/canvas.d.ts +324 -0
- package/dist/src/entities/channels/access-request.d.ts +10 -2
- package/dist/src/entities/channels/activity.d.ts +20 -4
- package/dist/src/entities/channels/channel.d.ts +130 -23
- package/dist/src/entities/channels/labels.d.ts +41 -7
- package/dist/src/entities/channels/message.d.ts +41 -7
- package/dist/src/entities/channels/namespace.d.ts +28 -3
- package/dist/src/entities/channels/post.test.d.ts +1 -0
- package/dist/src/entities/channels/thread.d.ts +19 -3
- package/dist/src/entities/chats/chat.d.ts +56 -6
- package/dist/src/entities/chats/generation.d.ts +11 -2
- package/dist/src/entities/chats/namespace.d.ts +10 -2
- package/dist/src/entities/connected-apps/connected-app.d.ts +14 -1
- package/dist/src/entities/connected-apps/connector.d.ts +3 -0
- package/dist/src/entities/connected-apps/namespace.d.ts +16 -0
- package/dist/src/entities/crm/company.d.ts +63 -15
- package/dist/src/entities/crm/contact.d.ts +60 -13
- package/dist/src/entities/crm/namespace.d.ts +85 -11
- package/dist/src/entities/crm/pipeline-entry.d.ts +102 -0
- package/dist/src/entities/crm/pipeline.d.ts +271 -27
- package/dist/src/entities/crm/pipelines.d.ts +39 -2
- package/dist/src/entities/databases/column.d.ts +54 -7
- package/dist/src/entities/databases/database.d.ts +126 -12
- package/dist/src/entities/databases/namespace.d.ts +16 -4
- package/dist/src/entities/databases/row.d.ts +2 -0
- package/dist/src/entities/databases/saved-query.d.ts +145 -0
- package/dist/src/entities/databases/table.d.ts +64 -10
- package/dist/src/entities/databases/view.d.ts +27 -5
- package/dist/src/entities/databases/webhook.d.ts +8 -1
- package/dist/src/entities/documents/ai-edit.d.ts +2 -0
- package/dist/src/entities/documents/anchor.d.ts +12 -2
- package/dist/src/entities/documents/comment.d.ts +29 -5
- package/dist/src/entities/documents/document.d.ts +243 -20
- package/dist/src/entities/documents/markdown.d.ts +25 -0
- package/dist/src/entities/documents/namespace.d.ts +132 -13
- package/dist/src/entities/documents/skills.test.d.ts +1 -0
- package/dist/src/entities/documents/system-skill.d.ts +21 -1
- package/dist/src/entities/documents/text-comment.d.ts +41 -0
- package/dist/src/entities/documents/text-comment.test.d.ts +1 -0
- package/dist/src/entities/documents/version.d.ts +5 -1
- package/dist/src/entities/email/attachment.d.ts +3 -0
- package/dist/src/entities/email/draft.d.ts +61 -9
- package/dist/src/entities/email/filter.d.ts +12 -2
- package/dist/src/entities/email/label.d.ts +7 -1
- package/dist/src/entities/email/link.d.ts +5 -1
- package/dist/src/entities/email/message.d.ts +55 -8
- package/dist/src/entities/email/namespace.d.ts +127 -21
- package/dist/src/entities/email/thread.d.ts +99 -16
- package/dist/src/entities/entity-mentions/mention.d.ts +6 -1
- package/dist/src/entities/entity-mentions/namespace.d.ts +5 -1
- package/dist/src/entities/entity.d.ts +56 -6
- package/dist/src/entities/external-chat/chat.d.ts +62 -11
- package/dist/src/entities/external-chat/message.d.ts +1 -1
- package/dist/src/entities/external-chat/namespace.d.ts +5 -1
- package/dist/src/entities/external-chat/send.d.ts +10 -2
- package/dist/src/entities/favorites/namespace.d.ts +20 -3
- package/dist/src/entities/foreign/foreign-entity.d.ts +5 -1
- package/dist/src/entities/foreign/namespace.d.ts +4 -0
- package/dist/src/entities/forms/form.d.ts +71 -13
- package/dist/src/entities/forms/namespace.d.ts +10 -2
- package/dist/src/entities/forms/question.d.ts +35 -7
- package/dist/src/entities/forms/response.d.ts +25 -5
- package/dist/src/entities/forms/section.d.ts +15 -3
- package/dist/src/entities/github-pull-requests/namespace.d.ts +5 -1
- package/dist/src/entities/github-pull-requests/pull-request.d.ts +15 -3
- package/dist/src/entities/harnesses/harness.d.ts +51 -3
- package/dist/src/entities/harnesses/namespace.d.ts +53 -7
- package/dist/src/entities/harnesses/pairing.d.ts +12 -2
- package/dist/src/entities/images/image.d.ts +16 -5
- package/dist/src/entities/images/namespace.d.ts +8 -1
- package/dist/src/entities/initiatives/initiative.d.ts +117 -3
- package/dist/src/entities/initiatives/initiative.test.d.ts +1 -0
- package/dist/src/entities/initiatives/namespace.d.ts +69 -7
- package/dist/src/entities/me/namespace.d.ts +27 -2
- package/dist/src/entities/meetings/meeting.d.ts +45 -8
- package/dist/src/entities/meetings/namespace.d.ts +20 -4
- package/dist/src/entities/memory/namespace.d.ts +49 -0
- package/dist/src/entities/memory/namespace.test.d.ts +1 -0
- package/dist/src/entities/messages/discussion.d.ts +84 -0
- package/dist/src/entities/messages/thread.d.ts +19 -5
- package/dist/src/entities/notifications/namespace.d.ts +40 -7
- package/dist/src/entities/notifications/notification.d.ts +29 -5
- package/dist/src/entities/pins/namespace.d.ts +23 -4
- package/dist/src/entities/projects/namespace.d.ts +29 -0
- package/dist/src/entities/projects/project.d.ts +47 -6
- package/dist/src/entities/properties/namespace.d.ts +67 -11
- package/dist/src/entities/properties/namespace.test.d.ts +1 -0
- package/dist/src/entities/properties/property-definition.d.ts +30 -5
- package/dist/src/entities/properties/property-option.d.ts +14 -2
- package/dist/src/entities/referrals/namespace.d.ts +8 -1
- package/dist/src/entities/routines/namespace.d.ts +128 -7
- package/dist/src/entities/routines/routine.d.ts +111 -25
- package/dist/src/entities/saved-views/namespace.d.ts +57 -0
- package/dist/src/entities/saved-views/saved-view.d.ts +78 -0
- package/dist/src/entities/search/namespace.d.ts +5 -1
- package/dist/src/entities/sharing/access.d.ts +50 -9
- package/dist/src/entities/spreadsheets/spreadsheet.d.ts +201 -0
- package/dist/src/entities/tasks/namespace.d.ts +13 -1
- package/dist/src/entities/tasks/task.d.ts +7 -1
- package/dist/src/entities/teams/invite.d.ts +3 -0
- package/dist/src/entities/teams/namespace.d.ts +10 -2
- package/dist/src/entities/teams/team.d.ts +7 -0
- package/dist/src/entities/unfurls/namespace.d.ts +12 -2
- package/dist/src/entities/users/namespace.d.ts +19 -1
- package/dist/src/entities/users/profile-picture.d.ts +29 -0
- package/dist/src/entities/users/profile-picture.test.d.ts +1 -0
- package/dist/src/entities/users/user.d.ts +52 -1
- package/dist/src/entities/web/namespace.d.ts +6 -0
- package/dist/src/entities/webhooks/namespace.d.ts +5 -0
- package/dist/src/entities/webhooks/webhook.d.ts +47 -7
- package/dist/src/entities/whatsapp/account.d.ts +5 -1
- package/dist/src/entities/whatsapp/chat.d.ts +9 -1
- package/dist/src/entities/whatsapp/namespace.d.ts +7 -1
- package/dist/src/entities/workspace/namespace.d.ts +7 -1
- package/dist/src/entities/workspace/query.d.ts +5 -1
- package/dist/src/events/hydrate/user.d.ts +14 -0
- package/dist/src/events/receiver.d.ts +2 -0
- package/dist/src/events/types.d.ts +2 -1
- package/dist/src/macro.d.ts +33 -5
- package/dist/src/macro.js +15635 -10132
- package/dist/src/utils/lazy.d.ts +7 -1
- package/package.json +1 -1
- 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.
|
|
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
|
|
464
|
-
|
|
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/
|
|
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
|
-
|
|
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
|
|
974
|
+
* Choose the model, and optionally the effort, this user's `@cursor` sessions
|
|
975
|
+
* start on.
|
|
975
976
|
*
|
|
976
|
-
* Stores the id only;
|
|
977
|
-
*
|
|
978
|
-
* the
|
|
979
|
-
*
|
|
980
|
-
*
|
|
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
|
-
*
|
|
1484
|
-
*
|
|
1485
|
-
*
|
|
1486
|
-
*
|
|
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({
|