@macro-inc/sdk 0.4.0 → 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 (193) hide show
  1. package/CALLS.md +82 -0
  2. package/README.md +176 -7
  3. package/dist/chunk-2IVGAIGQ.js +80 -0
  4. package/dist/{chunk-PTX2RV2N.js → chunk-3SW6QVDV.js} +33 -0
  5. package/dist/{chunk-XFA7NCJ5.js → chunk-GT5EUYOR.js} +13 -15
  6. package/dist/{chunk-ZLBDES7U.js → chunk-HIW6KU2I.js} +490 -4
  7. package/dist/{chunk-AZJUIUIV.js → chunk-J2VK3NOR.js} +56 -0
  8. package/dist/{chunk-PZPTJI6F.js → chunk-UVJLWLSJ.js} +41 -2
  9. package/dist/generated/agent-fold/index.d.ts +8 -6
  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 +17 -1
  13. package/dist/generated/agent-harness/types.gen.d.ts +188 -3
  14. package/dist/generated/auth/index.js +1 -1
  15. package/dist/generated/auth/sdk.gen.d.ts +13 -15
  16. package/dist/generated/auth/types.gen.d.ts +36 -17
  17. package/dist/generated/cognition/index.d.ts +1 -1
  18. package/dist/generated/cognition/index.js +1 -1
  19. package/dist/generated/cognition/sdk.gen.d.ts +38 -1
  20. package/dist/generated/cognition/types.gen.d.ts +473 -4
  21. package/dist/generated/connection/types.gen.d.ts +1 -1
  22. package/dist/generated/notification/index.d.ts +1 -1
  23. package/dist/generated/notification/types.gen.d.ts +36 -1
  24. package/dist/generated/scheduled-action/index.d.ts +1 -1
  25. package/dist/generated/scheduled-action/index.js +1 -1
  26. package/dist/generated/scheduled-action/sdk.gen.d.ts +17 -2
  27. package/dist/generated/scheduled-action/types.gen.d.ts +642 -104
  28. package/dist/generated/storage/index.d.ts +1 -1
  29. package/dist/generated/storage/index.js +1 -1
  30. package/dist/generated/storage/sdk.gen.d.ts +204 -5
  31. package/dist/generated/storage/types.gen.d.ts +3969 -374
  32. package/dist/src/calls/browser.d.ts +14 -0
  33. package/dist/src/calls/browser.js +102 -0
  34. package/dist/src/calls/common.d.ts +18 -0
  35. package/dist/src/calls/node.d.ts +24 -0
  36. package/dist/src/calls/node.js +145 -0
  37. package/dist/src/calls/telemetry.d.ts +5 -0
  38. package/dist/src/entities/account-managers/grant.d.ts +28 -5
  39. package/dist/src/entities/account-managers/namespace.d.ts +15 -3
  40. package/dist/src/entities/activity/entity.d.ts +7 -0
  41. package/dist/src/entities/activity/namespace.d.ts +58 -0
  42. package/dist/src/entities/activity/namespace.test.d.ts +1 -0
  43. package/dist/src/entities/agent-sessions/activity.d.ts +10 -2
  44. package/dist/src/entities/agent-sessions/agent-session.d.ts +193 -18
  45. package/dist/src/entities/agent-sessions/code-execution.d.ts +15 -3
  46. package/dist/src/entities/agent-sessions/conversation.d.ts +46 -9
  47. package/dist/src/entities/agent-sessions/namespace.d.ts +71 -16
  48. package/dist/src/entities/agent-sessions/origin.d.ts +1 -1
  49. package/dist/src/entities/agent-sessions/queued-action.d.ts +17 -3
  50. package/dist/src/entities/agent-sessions/review.d.ts +55 -4
  51. package/dist/src/entities/agent-sessions/tool-approval.d.ts +5 -1
  52. package/dist/src/entities/agents/agent.d.ts +98 -3
  53. package/dist/src/entities/agents/namespace.d.ts +52 -8
  54. package/dist/src/entities/ai/namespace.d.ts +9 -1
  55. package/dist/src/entities/api-keys/api-key.d.ts +6 -1
  56. package/dist/src/entities/api-keys/namespace.d.ts +15 -3
  57. package/dist/src/entities/bots/bot.d.ts +38 -6
  58. package/dist/src/entities/bots/namespace.d.ts +13 -1
  59. package/dist/src/entities/bots/token.d.ts +6 -1
  60. package/dist/src/entities/calendar/booking-link.d.ts +7 -1
  61. package/dist/src/entities/calendar/booking-namespace.d.ts +13 -0
  62. package/dist/src/entities/calendar/booking.d.ts +15 -0
  63. package/dist/src/entities/calendar/calendar.d.ts +7 -1
  64. package/dist/src/entities/calendar/event.d.ts +59 -9
  65. package/dist/src/entities/calendar/namespace.d.ts +88 -10
  66. package/dist/src/entities/calendar/replacement.d.ts +19 -3
  67. package/dist/src/entities/calls/call-record.d.ts +90 -14
  68. package/dist/src/entities/calls/connection.d.ts +7 -1
  69. package/dist/src/entities/calls/message.d.ts +27 -5
  70. package/dist/src/entities/calls/namespace.d.ts +15 -3
  71. package/dist/src/entities/canvases/canvas.d.ts +324 -0
  72. package/dist/src/entities/channels/access-request.d.ts +10 -2
  73. package/dist/src/entities/channels/activity.d.ts +20 -4
  74. package/dist/src/entities/channels/channel.d.ts +130 -23
  75. package/dist/src/entities/channels/labels.d.ts +41 -7
  76. package/dist/src/entities/channels/message.d.ts +41 -7
  77. package/dist/src/entities/channels/namespace.d.ts +28 -3
  78. package/dist/src/entities/channels/post.test.d.ts +1 -0
  79. package/dist/src/entities/channels/thread.d.ts +19 -3
  80. package/dist/src/entities/chats/chat.d.ts +56 -6
  81. package/dist/src/entities/chats/generation.d.ts +11 -2
  82. package/dist/src/entities/chats/namespace.d.ts +10 -2
  83. package/dist/src/entities/connected-apps/connected-app.d.ts +14 -1
  84. package/dist/src/entities/connected-apps/connector.d.ts +3 -0
  85. package/dist/src/entities/connected-apps/namespace.d.ts +16 -0
  86. package/dist/src/entities/crm/company.d.ts +63 -15
  87. package/dist/src/entities/crm/contact.d.ts +60 -13
  88. package/dist/src/entities/crm/namespace.d.ts +85 -11
  89. package/dist/src/entities/crm/pipeline-entry.d.ts +102 -0
  90. package/dist/src/entities/crm/pipeline.d.ts +271 -27
  91. package/dist/src/entities/crm/pipelines.d.ts +39 -2
  92. package/dist/src/entities/databases/column.d.ts +54 -7
  93. package/dist/src/entities/databases/database.d.ts +126 -12
  94. package/dist/src/entities/databases/namespace.d.ts +16 -4
  95. package/dist/src/entities/databases/row.d.ts +2 -0
  96. package/dist/src/entities/databases/saved-query.d.ts +145 -0
  97. package/dist/src/entities/databases/table.d.ts +64 -10
  98. package/dist/src/entities/databases/view.d.ts +27 -5
  99. package/dist/src/entities/databases/webhook.d.ts +8 -1
  100. package/dist/src/entities/documents/ai-edit.d.ts +2 -0
  101. package/dist/src/entities/documents/anchor.d.ts +12 -2
  102. package/dist/src/entities/documents/comment.d.ts +29 -5
  103. package/dist/src/entities/documents/document.d.ts +243 -20
  104. package/dist/src/entities/documents/markdown.d.ts +25 -0
  105. package/dist/src/entities/documents/namespace.d.ts +132 -13
  106. package/dist/src/entities/documents/skills.test.d.ts +1 -0
  107. package/dist/src/entities/documents/system-skill.d.ts +21 -1
  108. package/dist/src/entities/documents/text-comment.d.ts +41 -0
  109. package/dist/src/entities/documents/text-comment.test.d.ts +1 -0
  110. package/dist/src/entities/documents/version.d.ts +5 -1
  111. package/dist/src/entities/email/attachment.d.ts +3 -0
  112. package/dist/src/entities/email/draft.d.ts +61 -9
  113. package/dist/src/entities/email/filter.d.ts +12 -2
  114. package/dist/src/entities/email/label.d.ts +7 -1
  115. package/dist/src/entities/email/link.d.ts +5 -1
  116. package/dist/src/entities/email/message.d.ts +55 -8
  117. package/dist/src/entities/email/namespace.d.ts +127 -21
  118. package/dist/src/entities/email/thread.d.ts +99 -16
  119. package/dist/src/entities/entity-mentions/mention.d.ts +6 -1
  120. package/dist/src/entities/entity-mentions/namespace.d.ts +5 -1
  121. package/dist/src/entities/entity.d.ts +56 -6
  122. package/dist/src/entities/external-chat/chat.d.ts +62 -11
  123. package/dist/src/entities/external-chat/message.d.ts +1 -1
  124. package/dist/src/entities/external-chat/namespace.d.ts +5 -1
  125. package/dist/src/entities/external-chat/send.d.ts +10 -2
  126. package/dist/src/entities/favorites/namespace.d.ts +20 -3
  127. package/dist/src/entities/foreign/foreign-entity.d.ts +5 -1
  128. package/dist/src/entities/foreign/namespace.d.ts +4 -0
  129. package/dist/src/entities/forms/form.d.ts +71 -13
  130. package/dist/src/entities/forms/namespace.d.ts +10 -2
  131. package/dist/src/entities/forms/question.d.ts +35 -7
  132. package/dist/src/entities/forms/response.d.ts +25 -5
  133. package/dist/src/entities/forms/section.d.ts +15 -3
  134. package/dist/src/entities/github-pull-requests/namespace.d.ts +5 -1
  135. package/dist/src/entities/github-pull-requests/pull-request.d.ts +15 -3
  136. package/dist/src/entities/harnesses/harness.d.ts +51 -3
  137. package/dist/src/entities/harnesses/namespace.d.ts +53 -7
  138. package/dist/src/entities/harnesses/pairing.d.ts +12 -2
  139. package/dist/src/entities/images/image.d.ts +16 -5
  140. package/dist/src/entities/images/namespace.d.ts +8 -1
  141. package/dist/src/entities/initiatives/initiative.d.ts +117 -3
  142. package/dist/src/entities/initiatives/initiative.test.d.ts +1 -0
  143. package/dist/src/entities/initiatives/namespace.d.ts +69 -7
  144. package/dist/src/entities/me/namespace.d.ts +27 -2
  145. package/dist/src/entities/meetings/meeting.d.ts +45 -8
  146. package/dist/src/entities/meetings/namespace.d.ts +20 -4
  147. package/dist/src/entities/memory/namespace.d.ts +49 -0
  148. package/dist/src/entities/memory/namespace.test.d.ts +1 -0
  149. package/dist/src/entities/messages/discussion.d.ts +84 -0
  150. package/dist/src/entities/messages/thread.d.ts +19 -5
  151. package/dist/src/entities/notifications/namespace.d.ts +40 -7
  152. package/dist/src/entities/notifications/notification.d.ts +29 -5
  153. package/dist/src/entities/pins/namespace.d.ts +23 -4
  154. package/dist/src/entities/projects/namespace.d.ts +29 -0
  155. package/dist/src/entities/projects/project.d.ts +47 -6
  156. package/dist/src/entities/properties/namespace.d.ts +67 -11
  157. package/dist/src/entities/properties/namespace.test.d.ts +1 -0
  158. package/dist/src/entities/properties/property-definition.d.ts +30 -5
  159. package/dist/src/entities/properties/property-option.d.ts +14 -2
  160. package/dist/src/entities/referrals/namespace.d.ts +8 -1
  161. package/dist/src/entities/routines/namespace.d.ts +128 -7
  162. package/dist/src/entities/routines/routine.d.ts +111 -25
  163. package/dist/src/entities/saved-views/namespace.d.ts +57 -0
  164. package/dist/src/entities/saved-views/saved-view.d.ts +78 -0
  165. package/dist/src/entities/search/namespace.d.ts +5 -1
  166. package/dist/src/entities/sharing/access.d.ts +50 -9
  167. package/dist/src/entities/spreadsheets/spreadsheet.d.ts +201 -0
  168. package/dist/src/entities/tasks/namespace.d.ts +13 -1
  169. package/dist/src/entities/tasks/task.d.ts +7 -1
  170. package/dist/src/entities/teams/invite.d.ts +3 -0
  171. package/dist/src/entities/teams/namespace.d.ts +10 -2
  172. package/dist/src/entities/teams/team.d.ts +7 -0
  173. package/dist/src/entities/unfurls/namespace.d.ts +12 -2
  174. package/dist/src/entities/users/namespace.d.ts +19 -1
  175. package/dist/src/entities/users/profile-picture.d.ts +29 -0
  176. package/dist/src/entities/users/profile-picture.test.d.ts +1 -0
  177. package/dist/src/entities/users/user.d.ts +52 -1
  178. package/dist/src/entities/web/namespace.d.ts +6 -0
  179. package/dist/src/entities/webhooks/namespace.d.ts +5 -0
  180. package/dist/src/entities/webhooks/webhook.d.ts +47 -7
  181. package/dist/src/entities/whatsapp/account.d.ts +5 -1
  182. package/dist/src/entities/whatsapp/chat.d.ts +9 -1
  183. package/dist/src/entities/whatsapp/namespace.d.ts +7 -1
  184. package/dist/src/entities/workspace/namespace.d.ts +7 -1
  185. package/dist/src/entities/workspace/query.d.ts +5 -1
  186. package/dist/src/events/hydrate/user.d.ts +14 -0
  187. package/dist/src/events/receiver.d.ts +2 -0
  188. package/dist/src/events/types.d.ts +2 -1
  189. package/dist/src/macro.d.ts +33 -5
  190. package/dist/src/macro.js +15635 -10132
  191. package/dist/src/utils/lazy.d.ts +7 -1
  192. package/package.json +32 -5
  193. package/dist/src/entities/crm/comment.d.ts +0 -64
@@ -0,0 +1,25 @@
1
+ import type { DocumentMarkdown, DocumentMarkdownWritten } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { MacroApiError } from '../../utils/unwrap';
4
+ import type { Document } from './document';
5
+ export type { DocumentMarkdown, DocumentMarkdownWritten };
6
+ /** Options for `Document.setContent`. */
7
+ export interface SetContentOptions {
8
+ /**
9
+ * The `revision` from the `contentWithRevision()` read the new Markdown is
10
+ * based on. The write applies only while the document is still at it.
11
+ */
12
+ expectedRevision: string;
13
+ }
14
+ /**
15
+ * The document changed since the revision the write was based on (HTTP 409),
16
+ * so nothing was written. Read it again with `contentWithRevision()`, reapply
17
+ * your change to what it now says, and write against the new revision.
18
+ */
19
+ export declare class DocumentChangedError extends MacroApiError {
20
+ constructor(data: unknown);
21
+ }
22
+ /** Read the body and revision; `Document.contentWithRevision` calls this. */
23
+ export declare function readMarkdown(client: MacroClient, document: Document): Promise<DocumentMarkdown>;
24
+ /** Write the body at a revision; `Document.setContent` calls this. */
25
+ export declare function writeMarkdown(client: MacroClient, document: Document, markdown: string, options: SetContentOptions): Promise<DocumentMarkdownWritten>;
@@ -2,10 +2,25 @@ import type { MacroClient } from '../../utils/client';
2
2
  import type { EmailAttachment } from '../email/attachment';
3
3
  import type { Project } from '../projects/project';
4
4
  import type { SearchOpts } from '../search/options';
5
+ import { Spreadsheet } from '../spreadsheets/spreadsheet';
5
6
  import type { Team } from '../teams/team';
6
7
  import { User } from '../users/user';
7
8
  import { Document } from './document';
8
9
  import { SystemSkill } from './system-skill';
10
+ /** One skill found by {@link DocumentNamespace.skills}. */
11
+ export interface SkillListing {
12
+ /**
13
+ * The skill: a skill document, or a built-in skill with no document. Read
14
+ * either one's instructions with `content()`.
15
+ */
16
+ skill: Document | SystemSkill;
17
+ /** The skill's name. */
18
+ name: string;
19
+ /** When to use the skill, when it says. Built-in skills have none. */
20
+ description: string | undefined;
21
+ /** When the skill document was last updated (ISO 8601); built-in skills have none. */
22
+ updatedAt: string | undefined;
23
+ }
9
24
  /** A file's content: its bytes, or text stored as UTF-8. */
10
25
  export type FileContent = Uint8Array<ArrayBuffer> | ArrayBuffer | Blob | string;
11
26
  /**
@@ -16,10 +31,15 @@ export type FileContent = Uint8Array<ArrayBuffer> | ArrayBuffer | Blob | string;
16
31
  *
17
32
  * Change the text of an existing Markdown document or task body in place, with `document.edit(instructions)` in code or the `EditDocument` tool where code isn't available. Never recreate the document or upload its Markdown to change its text. PDF, Word and other uploaded files can't be edited this way.
18
33
  *
34
+ * When a program already holds the exact new Markdown, as an integration syncing from another system does, read `document.contentWithRevision()` and write with `document.setContent(markdown, {expectedRevision})`: the write lands only if nobody changed the document since the read, and throws `DocumentChangedError` otherwise, so read again and reapply instead of overwriting.
19
35
  * ## Uploaded Office and design files
20
36
  *
21
37
  * Edit an uploaded Word file with `readWord()` then `editWord(operations)`, and a PowerPoint deck with `readPresentation()` then `editPresentation(operations)` (or `copyPresentation()` for a new deck): both address paragraphs, slides and shapes by the ids the read reports. Read Figma, Photoshop and Illustrator files with `readDesign()`, `readPhotoshop()` and `readIllustrator()`; they can't be edited. Never rebuild these files from `bytes()`.
22
38
  *
39
+ * ## New spreadsheets
40
+ *
41
+ * `createSpreadsheet` saves the spreadsheet before it returns, so it exists even when a later step of the program throws. Keep its id across that failure: fill it inside `try`/`catch` and return `{ data: { spreadsheet: sheet, error } }` (the handle serializes as its `id` and `url`). To retry, reopen it with `macro.documents.spreadsheet(macro.documents.byId(id))`; never search recent documents for it or create another.
42
+ *
23
43
  * ## Linking Macro items inside document content
24
44
  *
25
45
  * `CreateDocument` content (the `fileContent` argument) is rendered with the same Markdown parser used for chat responses, channel messages, and email bodies inside the Macro app — but only for Markdown (`.md`) documents. Non-Markdown documents (e.g. PDF, CSV, PNG, XLSX, DOCX, created by passing a non-`md` `file_extension`) are stored as raw file bytes and must never contain Markdown syntax or mention tags.
@@ -32,7 +52,7 @@ export type FileContent = Uint8Array<ArrayBuffer> | ArrayBuffer | Blob | string;
32
52
  *
33
53
  * Reference a GitHub pull request with a PR chip rather than a Markdown link or bare URL: `<m-pr-mention>{"url":"https://github.com/{owner}/{repo}/pull/{number}","label":""}</m-pr-mention>`. Put the PR's github.com URL in `url`; no Macro id is needed. This applies to Markdown document content and to `SendChannelMessage` content, which uses the same Markdown syntax. The chip shows the PR's number, title, and live status and opens it in Macro, so leave `label` empty and do not repeat the number or title beside it. Issues, commits, and other GitHub pages stay Markdown links. Your own chat replies to the MCP client still link pull requests as plain Markdown URLs.
34
54
  *
35
- * Reference a Macro booking link with a booking-link chip rather than a Markdown link or bare URL: `<m-booking-link-mention>{"profileId":"{profile_id}","slug":"{slug}","url":"https://macro.com/app/book/{profile_id}/{slug}","label":""}</m-booking-link-mention>` (`slug` optional when linking the profile page). Put the shareable URL in `url` and the path's profile id (and slug when present) in `profileId`/`slug`. Leave `label` empty. Your own chat replies to the MCP client still link booking pages as plain Markdown URLs.
55
+ * Reference a Macro booking link with a booking-link chip rather than a Markdown link or bare URL: `<m-booking-link-mention>{"profileId":"{profile_id}","slug":"{slug}","url":"{booking_url}","label":""}</m-booking-link-mention>` (`slug` optional when linking the profile page). Put the shareable URL in `url` and the path's profile id (and slug when present) in `profileId`/`slug`. Leave `label` empty. Your own chat replies to the MCP client still link booking pages as plain Markdown URLs.
36
56
  *
37
57
  * This holds true even when `CreateDocument` is called through the MCP server, where you are otherwise told to link items in your own chat replies as plain Markdown URLs — that rule is about your conversational responses to the MCP client, not about content you write into a Macro document. Do NOT use plain Markdown links or bare URLs to reference other Macro items inside document content; only `<m-document-mention>` tags (and the other chip tags above) render as working links there.
38
58
  *
@@ -40,9 +60,17 @@ export type FileContent = Uint8Array<ArrayBuffer> | ArrayBuffer | Blob | string;
40
60
  */
41
61
  export declare class DocumentNamespace {
42
62
  private readonly client;
43
- /** Resolve a team task reference such as ENG-42. */
63
+ /**
64
+ * Resolve a team task reference such as ENG-42.
65
+ *
66
+ * @readonly
67
+ */
44
68
  byTeamSlug(slug: string): Promise<Document>;
45
- /** Validate a permissions token, returning its document and optional user handles. */
69
+ /**
70
+ * Validate a permissions token, returning its document and optional user handles.
71
+ *
72
+ * @readonly
73
+ */
46
74
  validatePermissionsToken(token: string): Promise<{
47
75
  document: Document;
48
76
  user: User | undefined;
@@ -70,6 +98,8 @@ export declare class DocumentNamespace {
70
98
  * });
71
99
  * await channel.send('Invoices attached.', { documents: [file] });
72
100
  * ```
101
+ *
102
+ * @write
73
103
  */
74
104
  upload(options: {
75
105
  name: string;
@@ -79,6 +109,8 @@ export declare class DocumentNamespace {
79
109
  /**
80
110
  * Reserve a binary document and return a presigned URL to PUT its content
81
111
  * to. The URL is outside the hosts code mode can reach; use `upload` there.
112
+ *
113
+ * @write
82
114
  */
83
115
  createUpload(options: {
84
116
  name: string;
@@ -99,18 +131,68 @@ export declare class DocumentNamespace {
99
131
  constructor(client: MacroClient);
100
132
  /** A handle to a document by id. Details load on first access. */
101
133
  byId(id: string): Document;
102
- /** Create a markdown document. */
134
+ /**
135
+ * Create a markdown document.
136
+ *
137
+ * @write
138
+ */
103
139
  create(opts: {
104
140
  name: string;
105
141
  markdown?: string;
106
142
  project?: Project;
107
143
  }): Promise<Document>;
108
- /** Create a native Canvas with shared content ready for reading and editing. */
144
+ /**
145
+ * Create a native Canvas with shared content ready for reading and editing;
146
+ * work on it with `document.canvas()`.
147
+ *
148
+ * @write
149
+ */
109
150
  createCanvas(opts: {
110
151
  name: string;
111
152
  project?: Project;
112
153
  }): Promise<Document>;
113
- /** Create a snippet: a reusable markdown document. */
154
+ /**
155
+ * Create a blank native spreadsheet, ready to read and edit; fill it with
156
+ * `applyEdits`. It is saved before this returns: keep its `id` even when
157
+ * filling it fails, and reopen it by id rather than creating another.
158
+ *
159
+ * @example Create and fill a budget, keeping the spreadsheet if a step fails.
160
+ * ```js
161
+ * const sheet = await macro.documents.createSpreadsheet({ name: 'Q4 budget' });
162
+ * try {
163
+ * const { revision, sheets } = await sheet.read();
164
+ * await sheet.applyEdits(
165
+ * [{ type: 'set_cells', sheetId: sheets[0].id, cells: [
166
+ * { address: 'A1', value: 'Item' }, { address: 'B1', value: 'Cost' },
167
+ * { address: 'A2', value: 'Laptops' }, { address: 'B2', value: 4200 },
168
+ * { address: 'A3', value: 'Total' }, { address: 'B3', value: '=SUM(B2:B2)' },
169
+ * ] }],
170
+ * { expectedRevision: revision },
171
+ * );
172
+ * return { data: { spreadsheet: sheet } };
173
+ * } catch (error) {
174
+ * return { data: { spreadsheet: sheet, error: String(error) } };
175
+ * }
176
+ * ```
177
+ *
178
+ * @write
179
+ */
180
+ createSpreadsheet(opts: {
181
+ name: string;
182
+ project?: Project;
183
+ }): Promise<Spreadsheet>;
184
+ /**
185
+ * Read, calculate and edit a document as a native spreadsheet, such as a
186
+ * search result or mention. Its methods refuse a document of another type.
187
+ *
188
+ * @readonly
189
+ */
190
+ spreadsheet(document: Document): Spreadsheet;
191
+ /**
192
+ * Create a snippet: a reusable markdown document.
193
+ *
194
+ * @write
195
+ */
114
196
  createSnippet(opts: {
115
197
  name: string;
116
198
  markdown?: string;
@@ -128,11 +210,12 @@ export declare class DocumentNamespace {
128
210
  * ```
129
211
  *
130
212
  * Read a skill the request names before doing the task, and follow it for
131
- * that request only. `systemSkills()` lists the built-in skills, whose
132
- * instructions have no document; read those with the ReadSkill tool.
213
+ * that request only. Find skills, built-in ones included, with `skills()`.
133
214
  *
134
215
  * `description` says when to use the skill, in one line starting "Use when"
135
216
  * (at most 300 characters); agents load the skill for requests it describes.
217
+ *
218
+ * @write
136
219
  */
137
220
  createSkill(opts: {
138
221
  name: string;
@@ -140,19 +223,55 @@ export declare class DocumentNamespace {
140
223
  markdown?: string;
141
224
  project?: Project;
142
225
  }): Promise<Document>;
226
+ /**
227
+ * Find skills by name, or list them, built-in skills included; read the
228
+ * instructions of the one a request needs with `skill.content()` before
229
+ * doing the task, and follow them for that request only.
230
+ *
231
+ * With `query`, searches skill names: pass 1-3 words that literally appear
232
+ * in the name, matched as one adjacent phrase whose last word may be a
233
+ * prefix (`matchType: 'exact'` for whole words). Without it, lists the 100
234
+ * most recently updated skills. User skills come first, most recently
235
+ * updated first, then built-in skills.
236
+ *
237
+ * ```js
238
+ * const [match] = await macro.documents.skills({ query: 'deploy' });
239
+ * const instructions = match && (await match.skill.content());
240
+ * ```
241
+ *
242
+ * @readonly
243
+ */
244
+ skills(opts?: {
245
+ query?: string;
246
+ matchType?: 'partial' | 'exact';
247
+ }): Promise<SkillListing[]>;
143
248
  /**
144
249
  * The built-in system skills: static AI instructions with no document
145
- * behind them. Unlike user skills they cannot be opened or edited, and
146
- * their instructions are read with the ReadSkill tool, not `content()`.
250
+ * behind them. Unlike user skills they cannot be opened or edited; read
251
+ * their instructions with `content()`.
252
+ *
253
+ * @readonly
147
254
  */
148
255
  systemSkills(): Promise<SystemSkill[]>;
149
- /** Search documents by name and content, most relevant first, auto-paginated. */
256
+ /**
257
+ * Search documents by name and content, most relevant first, auto-paginated.
258
+ *
259
+ * @readonly
260
+ */
150
261
  search(query: string, opts?: SearchOpts): AsyncGenerator<Document>;
151
- /** The user's recent documents, most recent first, auto-paginated. */
262
+ /**
263
+ * The user's recent documents, most recent first, auto-paginated.
264
+ *
265
+ * @readonly
266
+ */
152
267
  recent(opts?: {
153
268
  pageSize?: number;
154
269
  fileType?: string;
155
270
  }): AsyncGenerator<Document>;
156
- /** The user's recently soft-deleted documents. */
271
+ /**
272
+ * The user's recently soft-deleted documents.
273
+ *
274
+ * @readonly
275
+ */
157
276
  recentlyDeleted(): Promise<Document[]>;
158
277
  }
@@ -0,0 +1 @@
1
+ export {};
@@ -3,14 +3,34 @@ import type { MacroClient } from '../../utils/client';
3
3
  * A built-in system skill: static, code-defined AI instructions that surface
4
4
  * to AI like skill documents but have no document behind them. System skills
5
5
  * cannot be opened, edited, or deleted; reference them in AI inputs by id the
6
- * same way as skill documents.
6
+ * same way as skill documents, and read their instructions with `content()`.
7
+ *
8
+ * @mcp-exclude Built from a listing record; no id-only reference an MCP call can pass.
7
9
  */
8
10
  export declare class SystemSkill {
11
+ private readonly client;
9
12
  /** The well-known id the skill is referenced by in mentions and AI tools. */
10
13
  readonly id: string;
11
14
  /** The skill's display name. */
12
15
  readonly name: string;
13
16
  private constructor();
17
+ /**
18
+ * The skill's complete markdown instructions. Read them before doing the
19
+ * task the skill was named for, and follow them for that request only.
20
+ *
21
+ * @readonly
22
+ */
23
+ content(): Promise<string>;
24
+ /** Identity and name, without the authenticated client. */
25
+ toJSON(): {
26
+ id: string;
27
+ name: string;
28
+ };
14
29
  /** The built-in system skills, in display order. */
15
30
  static list(client: MacroClient): Promise<SystemSkill[]>;
31
+ /** Wrap a built-in skill from a record already in hand, such as a skill listing. */
32
+ static from(client: MacroClient, record: {
33
+ id: string;
34
+ name: string;
35
+ }): SystemSkill;
16
36
  }
@@ -0,0 +1,41 @@
1
+ import type { CommentOnTextRefused } from '../../../generated/storage/types.gen';
2
+ import { type RichMessage } from '../../mentions';
3
+ import type { MacroClient } from '../../utils/client';
4
+ import { MacroApiError } from '../../utils/unwrap';
5
+ import { Comment } from './comment';
6
+ import type { Document } from './document';
7
+ /** Where `Document.commentOnText` anchors its comment. */
8
+ export interface TextCommentOptions {
9
+ /**
10
+ * The passage to comment on, quoted exactly as the document reads: plain
11
+ * text without markdown syntax such as `**` or link brackets, within one
12
+ * paragraph, heading, list item or table cell. Keep it to the words the
13
+ * comment is about; a longer quote is more likely to be unique.
14
+ */
15
+ quote: string;
16
+ /**
17
+ * Which appearance of the quote, counting from 1 in document order. Only
18
+ * needed when it appears more than once; a Word document takes only the
19
+ * first.
20
+ */
21
+ occurrence?: number;
22
+ }
23
+ /** A comment anchored to text, and the text it is anchored to. */
24
+ export interface TextComment {
25
+ /** The posted comment, the root of a new thread. */
26
+ comment: Comment;
27
+ /** The text the comment is anchored to, as the document reads. */
28
+ markedText: string;
29
+ }
30
+ /**
31
+ * The quote appears more than once, or not at all (HTTP 422). Nothing was
32
+ * posted. `reason` lists each appearance to choose from with `occurrence`, or
33
+ * says the text was not found: read the document again rather than guessing.
34
+ */
35
+ export declare class CommentQuoteNotPlacedError extends MacroApiError {
36
+ /** Why the quote could not be anchored, in the document's words. */
37
+ readonly reason: string;
38
+ constructor(refusal: CommentOnTextRefused);
39
+ }
40
+ /** Post a comment on quoted text; `Document.commentOnText` calls this. */
41
+ export declare function commentOnText(client: MacroClient, document: Document, body: string | RichMessage, options: TextCommentOptions): Promise<TextComment>;
@@ -0,0 +1 @@
1
+ export {};
@@ -12,7 +12,11 @@ export declare class DocumentVersion {
12
12
  private constructor();
13
13
  /** Construct a version handle. */
14
14
  static byId(client: MacroClient, document: Document, id: number): DocumentVersion;
15
- /** Version metadata and the caller's access. */
15
+ /**
16
+ * Version metadata and the caller's access.
17
+ *
18
+ * @readonly
19
+ */
16
20
  read(): Promise<GetDocumentResponseData>;
17
21
  /** Serialize only scoped identity. */
18
22
  toJSON(): {
@@ -31,6 +31,9 @@ export declare class EmailAttachment extends MacroEntity<EmailAttachmentData> {
31
31
  * server returns the existing document's id, or downloads the attachment
32
32
  * from the provider and uploads it as a new document first (deduplicated
33
33
  * behind a server-side lock).
34
+ *
35
+ * @write
36
+ * @idempotent
34
37
  */
35
38
  toDocument(): Promise<Document>;
36
39
  }
@@ -39,9 +39,21 @@ export declare class EmailDraft extends EmailMessage {
39
39
  static byId(client: MacroClient, id: string): EmailDraft;
40
40
  /** Edit generation to capture with content before saving or transferring it. */
41
41
  readonly draftGeneration: () => Promise<number | undefined>;
42
- /** Replace draft content without changing its identity or sending it. */
42
+ /**
43
+ * Replace draft content without changing its identity or sending it.
44
+ *
45
+ * @destructive
46
+ * @openworld
47
+ * @idempotent
48
+ */
43
49
  update(options: DraftOptions): Promise<void>;
44
- /** Delete the draft. */
50
+ /**
51
+ * Delete the draft.
52
+ *
53
+ * @destructive
54
+ * @openworld
55
+ * @idempotent
56
+ */
45
57
  delete(): Promise<void>;
46
58
  /**
47
59
  * Schedule this draft for sending; an agent's program must quote the user's reply approving this send in `userConfirmation`, or it is refused (403).
@@ -49,6 +61,9 @@ export declare class EmailDraft extends EmailMessage {
49
61
  * The draft goes out as saved, attachments included, at `sendTime` (ISO
50
62
  * 8601, in the future). Write the draft out for the user and ask before
51
63
  * scheduling it; the request that asked for the email is not the approval.
64
+ *
65
+ * @destructive
66
+ * @openworld
52
67
  */
53
68
  schedule(sendTime: string, options?: DraftSendOptions): Promise<void>;
54
69
  /**
@@ -57,11 +72,24 @@ export declare class EmailDraft extends EmailMessage {
57
72
  * The draft is handed to the scheduled sender, which delivers it within
58
73
  * about a minute; until then {@link unschedule} still stops it. Write the
59
74
  * draft out for the user and ask before sending it.
75
+ *
76
+ * @destructive
77
+ * @openworld
60
78
  */
61
79
  send(options?: DraftSendOptions): Promise<void>;
62
- /** Remove a scheduled send. */
80
+ /**
81
+ * Remove a scheduled send.
82
+ *
83
+ * @write
84
+ * @openworld
85
+ * @idempotent
86
+ */
63
87
  unschedule(): Promise<void>;
64
- /** Reserve an attachment upload. Upload to the returned URL, then call complete(). */
88
+ /**
89
+ * Reserve an attachment upload. Upload to the returned URL, then call complete().
90
+ *
91
+ * @write
92
+ */
65
93
  addAttachment(options: {
66
94
  fileName: string;
67
95
  sha: string;
@@ -72,11 +100,25 @@ export declare class EmailDraft extends EmailMessage {
72
100
  uploadUrl: string;
73
101
  contentType: string;
74
102
  }>;
75
- /** Forward an existing attachment into this draft. */
103
+ /**
104
+ * Forward an existing attachment into this draft.
105
+ *
106
+ * @write
107
+ */
76
108
  forwardAttachment(attachment: EmailAttachment): Promise<DraftAttachment>;
77
- /** Remove a draft attachment. */
109
+ /**
110
+ * Remove a draft attachment.
111
+ *
112
+ * @destructive
113
+ * @idempotent
114
+ */
78
115
  removeAttachment(attachment: DraftAttachment): Promise<void>;
79
- /** Complete verification of an uploaded attachment. */
116
+ /**
117
+ * Complete verification of an uploaded attachment.
118
+ *
119
+ * @write
120
+ * @idempotent
121
+ */
80
122
  verifyAttachment(attachment: DraftAttachment): Promise<void>;
81
123
  }
82
124
  /** An uploaded or forwarded attachment belonging to a draft. */
@@ -92,9 +134,19 @@ export declare class DraftAttachment {
92
134
  private constructor();
93
135
  /** Construct a draft scoped attachment handle. */
94
136
  static byId(_client: MacroClient, draft: EmailDraft, id: string, forwarded?: boolean, draftGeneration?: number): DraftAttachment;
95
- /** Complete verification after uploading the file. */
137
+ /**
138
+ * Complete verification after uploading the file.
139
+ *
140
+ * @write
141
+ * @idempotent
142
+ */
96
143
  complete(): Promise<void>;
97
- /** Remove this attachment from its draft. */
144
+ /**
145
+ * Remove this attachment from its draft.
146
+ *
147
+ * @destructive
148
+ * @idempotent
149
+ */
98
150
  remove(): Promise<void>;
99
151
  /** Serialize identity without credentials. */
100
152
  toJSON(): {
@@ -27,8 +27,18 @@ export declare class EmailFilter extends MacroEntity<ApiEmailFilter> {
27
27
  readonly emailDomain: () => Promise<string | undefined>;
28
28
  /** Importance assigned by this filter. */
29
29
  readonly isImportant: () => Promise<boolean>;
30
- /** Change the importance for the same sender selector. */
30
+ /**
31
+ * Change the importance for the same sender selector.
32
+ *
33
+ * @write
34
+ * @idempotent
35
+ */
31
36
  setImportant(isImportant: boolean): Promise<void>;
32
- /** Delete this filter. */
37
+ /**
38
+ * Delete this filter.
39
+ *
40
+ * @destructive
41
+ * @idempotent
42
+ */
33
43
  delete(): Promise<void>;
34
44
  }
@@ -14,7 +14,13 @@ export declare class Label extends MacroEntity<ApiLabel> {
14
14
  static list(client: MacroClient): Promise<Label[]>;
15
15
  /** Create a user label. */
16
16
  static create(client: MacroClient, name: string): Promise<Label>;
17
- /** Delete this label. */
17
+ /**
18
+ * Delete this label.
19
+ *
20
+ * @destructive
21
+ * @openworld
22
+ * @idempotent
23
+ */
18
24
  delete(): Promise<void>;
19
25
  /** The label's display name. */
20
26
  readonly name: () => Promise<string>;
@@ -26,6 +26,10 @@ export declare class Link extends MacroEntity<LinkRecord> {
26
26
  readonly needsReauth: () => Promise<boolean>;
27
27
  /** The inbox's avatar URL, if any. */
28
28
  readonly photoUrl: () => Promise<string | undefined>;
29
- /** Read category and sender-policy changes for this inbox. */
29
+ /**
30
+ * Read category and sender-policy changes for this inbox.
31
+ *
32
+ * @readonly
33
+ */
30
34
  settingsOperations(): Promise<MailboxSettingsOperation[]>;
31
35
  }
@@ -99,13 +99,20 @@ export declare class EmailMessage extends MacroEntity<EmailMessageData> {
99
99
  static sendConfirmed(client: MacroClient, opts: ConfirmedEmailOptions): Promise<SentEmail>;
100
100
  /** @internal Run the SendConfirmedEmail tool with a SendEmail draft and its approval. */
101
101
  private static sendReviewedDraft;
102
- /** The files attached to this message, from its thread's first 100 messages. */
102
+ /**
103
+ * The files attached to this message, from its thread's first 100 messages.
104
+ *
105
+ * @readonly
106
+ */
103
107
  attachments(): Promise<EmailAttachment[]>;
104
108
  /**
105
109
  * This message as a forward: a SendEmail draft with the note, the quoted
106
110
  * message under the forwarded-message header, and its attachments as
107
111
  * Macro documents. Pass it to `execution.reviews.create({kind: 'email'})`
108
112
  * in a session; in a thread, use {@link forwardConfirmed}.
113
+ *
114
+ * @write
115
+ * @idempotent
109
116
  */
110
117
  forwardDraft(opts: ForwardEmailOptions): Promise<SendEmail>;
111
118
  /**
@@ -117,6 +124,9 @@ export declare class EmailMessage extends MacroEntity<EmailMessageData> {
117
124
  * `forwardDraft` as a review instead. The forward is a new email that
118
125
  * quotes this message and carries its attachments; it takes effect at once
119
126
  * and is never retried.
127
+ *
128
+ * @destructive
129
+ * @openworld
120
130
  */
121
131
  forwardConfirmed(opts: ForwardEmailOptions & {
122
132
  userConfirmation: string;
@@ -139,27 +149,64 @@ export declare class EmailMessage extends MacroEntity<EmailMessageData> {
139
149
  readonly labels: () => Promise<import("../../../generated/email").LabelInfo[]>;
140
150
  /** The inbox (email link) this message belongs to. */
141
151
  readonly link: () => Promise<Link>;
142
- /** Read the draft's durable send, upload, or conflict status without retrying it. */
152
+ /**
153
+ * Read the draft's durable send, upload, or conflict status without retrying it.
154
+ *
155
+ * @readonly
156
+ */
143
157
  operationStatus(): Promise<MessageOperationResponse>;
144
158
  /** Resolve the displayed operation revision after the user chooses an action.
145
- * Retrying an uncertain send requires explicit duplicate-risk acceptance. */
159
+ * Retrying an uncertain send requires explicit duplicate-risk acceptance.
160
+ *
161
+ * @destructive
162
+ * @openworld
163
+ */
146
164
  resolveOperation(request: ResolveMessageOperationRequest): Promise<void>;
147
- /** Verify an uploaded attachment using the draft generation captured when its upload began. */
165
+ /**
166
+ * Verify an uploaded attachment using the draft generation captured when its upload began.
167
+ *
168
+ * @write
169
+ * @idempotent
170
+ */
148
171
  completeDraftAttachment(attachmentId: string, draftGeneration?: number): Promise<void>;
149
172
  /** Move a draft to another inbox using a caller-persisted operation UUID.
150
173
  * Continue editing the returned message_id; the original identity is retired.
151
- * On an interrupted response, use email.recoverDraftTransfer(operation_id). */
174
+ * On an interrupted response, use email.recoverDraftTransfer(operation_id).
175
+ *
176
+ * @write
177
+ * @openworld
178
+ * @idempotent
179
+ */
152
180
  transferDraft(request: TransferDraftRequest): Promise<TransferDraftResponse>;
153
- /** Add a label to this message. */
181
+ /**
182
+ * Add a label to this message.
183
+ *
184
+ * @write
185
+ * @openworld
186
+ * @idempotent
187
+ */
154
188
  addLabel(label: Label): Promise<void>;
155
- /** Remove a label from this message. */
189
+ /**
190
+ * Remove a label from this message.
191
+ *
192
+ * @write
193
+ * @openworld
194
+ * @idempotent
195
+ */
156
196
  removeLabel(label: Label): Promise<void>;
157
- /** The thread this message belongs to. */
197
+ /**
198
+ * The thread this message belongs to.
199
+ *
200
+ * @readonly
201
+ */
158
202
  thread(): Promise<EmailThread>;
159
203
  /**
160
204
  * The message's original source, exactly as Gmail or Outlook holds it, as
161
205
  * `message/rfc822` bytes for an `.eml` file. Drafts and messages still on
162
206
  * their way have no source yet and fail with a 404.
207
+ *
208
+ * @readonly
209
+ * @mcp-exclude Returns raw bytes only; MCP calls carry JSON.
163
210
  */
164
211
  downloadEml(): Promise<Blob>;
165
212
  }