@macro-inc/sdk 0.4.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (228) hide show
  1. package/README.md +316 -21
  2. package/dist/{chunk-PTX2RV2N.js → chunk-4MI52GWV.js} +93 -1
  3. package/dist/{chunk-XFA7NCJ5.js → chunk-HO75UE4Z.js} +146 -15
  4. package/dist/{chunk-P4DTO6VD.js → chunk-MCSQNZ4E.js} +6 -0
  5. package/dist/{chunk-ZLBDES7U.js → chunk-SJ6S2GAT.js} +1271 -87
  6. package/dist/{chunk-AZJUIUIV.js → chunk-SK5CMXRV.js} +100 -14
  7. package/dist/{chunk-PZPTJI6F.js → chunk-TMTYN2UK.js} +229 -2
  8. package/dist/{chunk-PPR7IWZ7.js → chunk-ZYBAKW25.js} +2 -1
  9. package/dist/generated/agent-fold/index.d.ts +202 -14
  10. package/dist/generated/agent-harness/index.d.ts +1 -1
  11. package/dist/generated/agent-harness/index.js +1 -1
  12. package/dist/generated/agent-harness/sdk.gen.d.ts +49 -2
  13. package/dist/generated/agent-harness/types.gen.d.ts +527 -9
  14. package/dist/generated/agent-reviews/index.d.ts +11 -9
  15. package/dist/generated/auth/index.d.ts +1 -1
  16. package/dist/generated/auth/index.js +1 -1
  17. package/dist/generated/auth/sdk.gen.d.ts +82 -16
  18. package/dist/generated/auth/types.gen.d.ts +768 -18
  19. package/dist/generated/calendar/types.gen.d.ts +10 -3
  20. package/dist/generated/cognition/index.d.ts +1 -1
  21. package/dist/generated/cognition/index.js +1 -1
  22. package/dist/generated/cognition/sdk.gen.d.ts +60 -6
  23. package/dist/generated/cognition/types.gen.d.ts +663 -106
  24. package/dist/generated/connection/types.gen.d.ts +1 -1
  25. package/dist/generated/contacts/index.d.ts +1 -1
  26. package/dist/generated/contacts/index.js +1 -1
  27. package/dist/generated/contacts/sdk.gen.d.ts +5 -1
  28. package/dist/generated/contacts/types.gen.d.ts +56 -0
  29. package/dist/generated/email/types.gen.d.ts +8 -2
  30. package/dist/generated/notification/index.d.ts +1 -1
  31. package/dist/generated/notification/index.js +1 -1
  32. package/dist/generated/notification/sdk.gen.d.ts +2 -1
  33. package/dist/generated/notification/types.gen.d.ts +174 -1
  34. package/dist/generated/scheduled-action/index.d.ts +1 -1
  35. package/dist/generated/scheduled-action/index.js +1 -1
  36. package/dist/generated/scheduled-action/sdk.gen.d.ts +107 -2
  37. package/dist/generated/scheduled-action/types.gen.d.ts +2451 -479
  38. package/dist/generated/search/index.d.ts +1 -1
  39. package/dist/generated/search/types.gen.d.ts +50 -11
  40. package/dist/generated/storage/index.d.ts +1 -1
  41. package/dist/generated/storage/index.js +1 -1
  42. package/dist/generated/storage/sdk.gen.d.ts +511 -18
  43. package/dist/generated/storage/types.gen.d.ts +18528 -11395
  44. package/dist/src/entities/account-managers/grant.d.ts +28 -5
  45. package/dist/src/entities/account-managers/namespace.d.ts +15 -3
  46. package/dist/src/entities/activity/entity.d.ts +7 -0
  47. package/dist/src/entities/activity/namespace.d.ts +58 -0
  48. package/dist/src/entities/activity/namespace.test.d.ts +1 -0
  49. package/dist/src/entities/agent-sessions/activity.d.ts +12 -3
  50. package/dist/src/entities/agent-sessions/agent-session.d.ts +209 -22
  51. package/dist/src/entities/agent-sessions/code-execution.d.ts +15 -3
  52. package/dist/src/entities/agent-sessions/conversation.d.ts +46 -9
  53. package/dist/src/entities/agent-sessions/namespace.d.ts +72 -16
  54. package/dist/src/entities/agent-sessions/origin.d.ts +1 -1
  55. package/dist/src/entities/agent-sessions/queued-action.d.ts +17 -3
  56. package/dist/src/entities/agent-sessions/review.d.ts +56 -5
  57. package/dist/src/entities/agent-sessions/tool-approval.d.ts +5 -1
  58. package/dist/src/entities/agents/agent.d.ts +98 -3
  59. package/dist/src/entities/agents/namespace.d.ts +52 -8
  60. package/dist/src/entities/ai/namespace.d.ts +10 -2
  61. package/dist/src/entities/api-keys/api-key.d.ts +6 -1
  62. package/dist/src/entities/api-keys/namespace.d.ts +18 -3
  63. package/dist/src/entities/bots/bot.d.ts +44 -9
  64. package/dist/src/entities/bots/namespace.d.ts +13 -1
  65. package/dist/src/entities/bots/token.d.ts +6 -1
  66. package/dist/src/entities/calendar/booking-link.d.ts +7 -1
  67. package/dist/src/entities/calendar/booking-namespace.d.ts +14 -1
  68. package/dist/src/entities/calendar/booking.d.ts +15 -0
  69. package/dist/src/entities/calendar/calendar.d.ts +10 -3
  70. package/dist/src/entities/calendar/event.d.ts +68 -9
  71. package/dist/src/entities/calendar/namespace.d.ts +91 -12
  72. package/dist/src/entities/calendar/replacement.d.ts +19 -3
  73. package/dist/src/entities/calls/call-record.d.ts +107 -17
  74. package/dist/src/entities/calls/connection.d.ts +7 -1
  75. package/dist/src/entities/calls/message.d.ts +27 -5
  76. package/dist/src/entities/calls/namespace.d.ts +15 -3
  77. package/dist/src/entities/canvases/canvas.d.ts +329 -0
  78. package/dist/src/entities/channels/access-request.d.ts +10 -2
  79. package/dist/src/entities/channels/activity.d.ts +20 -4
  80. package/dist/src/entities/channels/channel.d.ts +154 -27
  81. package/dist/src/entities/channels/labels.d.ts +41 -7
  82. package/dist/src/entities/channels/message.d.ts +105 -8
  83. package/dist/src/entities/channels/message.test.d.ts +1 -0
  84. package/dist/src/entities/channels/namespace.d.ts +37 -7
  85. package/dist/src/entities/channels/post.d.ts +13 -7
  86. package/dist/src/entities/channels/post.test.d.ts +1 -0
  87. package/dist/src/entities/channels/share.d.ts +9 -0
  88. package/dist/src/entities/channels/share.test.d.ts +1 -0
  89. package/dist/src/entities/channels/thread.d.ts +24 -4
  90. package/dist/src/entities/chats/chat.d.ts +57 -7
  91. package/dist/src/entities/chats/generation.d.ts +11 -2
  92. package/dist/src/entities/chats/namespace.d.ts +10 -2
  93. package/dist/src/entities/connected-apps/connected-app.d.ts +16 -2
  94. package/dist/src/entities/connected-apps/connector.d.ts +3 -0
  95. package/dist/src/entities/connected-apps/namespace.d.ts +18 -0
  96. package/dist/src/entities/crm/company.d.ts +64 -16
  97. package/dist/src/entities/crm/contact.d.ts +102 -14
  98. package/dist/src/entities/crm/namespace.d.ts +113 -22
  99. package/dist/src/entities/crm/pipeline-entry.d.ts +109 -0
  100. package/dist/src/entities/crm/pipeline.d.ts +292 -29
  101. package/dist/src/entities/crm/pipelines.d.ts +69 -4
  102. package/dist/src/entities/crm-email-privacy/email-privacy.d.ts +238 -0
  103. package/dist/src/entities/crm-email-privacy/email-rule-preview.d.ts +55 -0
  104. package/dist/src/entities/crm-email-privacy/email-rule-revision.d.ts +27 -0
  105. package/dist/src/entities/crm-email-privacy/email-rules.d.ts +32 -0
  106. package/dist/src/entities/databases/column.d.ts +54 -7
  107. package/dist/src/entities/databases/database.d.ts +160 -18
  108. package/dist/src/entities/databases/namespace.d.ts +40 -8
  109. package/dist/src/entities/databases/row.d.ts +2 -0
  110. package/dist/src/entities/databases/saved-query.d.ts +151 -0
  111. package/dist/src/entities/databases/table.d.ts +73 -10
  112. package/dist/src/entities/databases/view.d.ts +37 -5
  113. package/dist/src/entities/databases/webhook.d.ts +8 -1
  114. package/dist/src/entities/documents/ai-edit.d.ts +2 -0
  115. package/dist/src/entities/documents/anchor.d.ts +12 -2
  116. package/dist/src/entities/documents/comment.d.ts +29 -5
  117. package/dist/src/entities/documents/create.test.d.ts +1 -0
  118. package/dist/src/entities/documents/document.d.ts +284 -26
  119. package/dist/src/entities/documents/markdown.d.ts +25 -0
  120. package/dist/src/entities/documents/namespace.d.ts +146 -13
  121. package/dist/src/entities/documents/skills.test.d.ts +1 -0
  122. package/dist/src/entities/documents/system-skill.d.ts +21 -1
  123. package/dist/src/entities/documents/text-comment.d.ts +41 -0
  124. package/dist/src/entities/documents/text-comment.test.d.ts +1 -0
  125. package/dist/src/entities/documents/version.d.ts +5 -1
  126. package/dist/src/entities/email/attachment.d.ts +3 -0
  127. package/dist/src/entities/email/draft.d.ts +61 -9
  128. package/dist/src/entities/email/filter.d.ts +12 -2
  129. package/dist/src/entities/email/label.d.ts +7 -1
  130. package/dist/src/entities/email/link.d.ts +5 -1
  131. package/dist/src/entities/email/message.d.ts +72 -14
  132. package/dist/src/entities/email/namespace.d.ts +134 -24
  133. package/dist/src/entities/email/thread.d.ts +124 -18
  134. package/dist/src/entities/entity-mentions/mention.d.ts +6 -1
  135. package/dist/src/entities/entity-mentions/namespace.d.ts +5 -1
  136. package/dist/src/entities/entity.d.ts +65 -6
  137. package/dist/src/entities/external-chat/chat.d.ts +80 -12
  138. package/dist/src/entities/external-chat/message.d.ts +1 -1
  139. package/dist/src/entities/external-chat/namespace.d.ts +5 -1
  140. package/dist/src/entities/external-chat/send.d.ts +10 -2
  141. package/dist/src/entities/favorites/namespace.d.ts +20 -3
  142. package/dist/src/entities/foreign/foreign-entity.d.ts +5 -1
  143. package/dist/src/entities/foreign/namespace.d.ts +5 -1
  144. package/dist/src/entities/forms/form.d.ts +91 -14
  145. package/dist/src/entities/forms/namespace.d.ts +10 -2
  146. package/dist/src/entities/forms/question.d.ts +35 -7
  147. package/dist/src/entities/forms/response.d.ts +25 -5
  148. package/dist/src/entities/forms/section.d.ts +15 -3
  149. package/dist/src/entities/github-pull-requests/namespace.d.ts +5 -1
  150. package/dist/src/entities/github-pull-requests/pull-request.d.ts +15 -3
  151. package/dist/src/entities/harnesses/harness.d.ts +51 -3
  152. package/dist/src/entities/harnesses/namespace.d.ts +54 -8
  153. package/dist/src/entities/harnesses/pairing.d.ts +13 -2
  154. package/dist/src/entities/images/image.d.ts +16 -5
  155. package/dist/src/entities/images/namespace.d.ts +8 -1
  156. package/dist/src/entities/imports/entry.d.ts +65 -0
  157. package/dist/src/entities/imports/namespace.d.ts +103 -0
  158. package/dist/src/entities/imports/namespace.test.d.ts +1 -0
  159. package/dist/src/entities/initiatives/initiative.d.ts +128 -4
  160. package/dist/src/entities/initiatives/initiative.test.d.ts +1 -0
  161. package/dist/src/entities/initiatives/namespace.d.ts +71 -7
  162. package/dist/src/entities/me/namespace.d.ts +28 -3
  163. package/dist/src/entities/meetings/meeting.d.ts +46 -8
  164. package/dist/src/entities/meetings/namespace.d.ts +20 -4
  165. package/dist/src/entities/memory/namespace.d.ts +49 -0
  166. package/dist/src/entities/memory/namespace.test.d.ts +1 -0
  167. package/dist/src/entities/messages/discussion.d.ts +84 -0
  168. package/dist/src/entities/messages/thread.d.ts +19 -5
  169. package/dist/src/entities/notifications/namespace.d.ts +41 -7
  170. package/dist/src/entities/notifications/notification.d.ts +31 -6
  171. package/dist/src/entities/passwords/item.d.ts +118 -0
  172. package/dist/src/entities/passwords/namespace.d.ts +45 -0
  173. package/dist/src/entities/pins/namespace.d.ts +23 -4
  174. package/dist/src/entities/projects/namespace.d.ts +29 -0
  175. package/dist/src/entities/projects/project.d.ts +58 -7
  176. package/dist/src/entities/properties/namespace.d.ts +67 -11
  177. package/dist/src/entities/properties/namespace.test.d.ts +1 -0
  178. package/dist/src/entities/properties/property-definition.d.ts +30 -5
  179. package/dist/src/entities/properties/property-option.d.ts +14 -2
  180. package/dist/src/entities/referrals/namespace.d.ts +8 -1
  181. package/dist/src/entities/routines/namespace.d.ts +198 -14
  182. package/dist/src/entities/routines/routine.d.ts +174 -27
  183. package/dist/src/entities/routines/suggestion.d.ts +38 -0
  184. package/dist/src/entities/saved-views/namespace.d.ts +58 -0
  185. package/dist/src/entities/saved-views/saved-view.d.ts +78 -0
  186. package/dist/src/entities/search/exclusions.d.ts +6 -0
  187. package/dist/src/entities/search/namespace.d.ts +9 -3
  188. package/dist/src/entities/search/options.d.ts +3 -2
  189. package/dist/src/entities/sharing/access.d.ts +50 -9
  190. package/dist/src/entities/spreadsheets/spreadsheet.d.ts +201 -0
  191. package/dist/src/entities/suggestions/namespace.d.ts +118 -0
  192. package/dist/src/entities/suggestions/suggestion.d.ts +172 -0
  193. package/dist/src/entities/suggestions/suggestion.test.d.ts +1 -0
  194. package/dist/src/entities/tasks/namespace.d.ts +18 -5
  195. package/dist/src/entities/tasks/task.d.ts +21 -3
  196. package/dist/src/entities/teams/invite.d.ts +3 -0
  197. package/dist/src/entities/teams/namespace.d.ts +10 -2
  198. package/dist/src/entities/teams/team.d.ts +22 -2
  199. package/dist/src/entities/ui/app-link.d.ts +24 -0
  200. package/dist/src/entities/ui/namespace.d.ts +75 -0
  201. package/dist/src/entities/unfurls/namespace.d.ts +12 -2
  202. package/dist/src/entities/users/namespace.d.ts +26 -4
  203. package/dist/src/entities/users/profile-picture.d.ts +29 -0
  204. package/dist/src/entities/users/profile-picture.test.d.ts +1 -0
  205. package/dist/src/entities/users/user.d.ts +52 -1
  206. package/dist/src/entities/web/namespace.d.ts +6 -0
  207. package/dist/src/entities/webhooks/namespace.d.ts +5 -0
  208. package/dist/src/entities/webhooks/webhook.d.ts +47 -7
  209. package/dist/src/entities/whatsapp/account.d.ts +5 -1
  210. package/dist/src/entities/whatsapp/chat.d.ts +9 -1
  211. package/dist/src/entities/whatsapp/namespace.d.ts +7 -1
  212. package/dist/src/entities/workspace/namespace.d.ts +12 -4
  213. package/dist/src/entities/workspace/query.d.ts +5 -1
  214. package/dist/src/entities/workspace/query.test.d.ts +1 -0
  215. package/dist/src/events/hydrate/document.d.ts +5 -0
  216. package/dist/src/events/hydrate/user.d.ts +14 -0
  217. package/dist/src/events/receiver.d.ts +2 -0
  218. package/dist/src/events/types.d.ts +2 -1
  219. package/dist/src/macro.d.ts +59 -6
  220. package/dist/src/macro.js +18710 -10355
  221. package/dist/src/utils/activity.d.ts +2 -0
  222. package/dist/src/utils/index.d.ts +1 -1
  223. package/dist/src/utils/lazy.d.ts +20 -1
  224. package/dist/src/utils/options.d.ts +7 -0
  225. package/dist/src/utils/pagination.d.ts +16 -0
  226. package/dist/src/utils/verbs.d.ts +3 -0
  227. package/package.json +1 -1
  228. package/dist/src/entities/crm/comment.d.ts +0 -64
@@ -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,18 @@ 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.
35
+ *
36
+ * `document.content()`, `contentWithRevision()` and `initiative.description()` return Macro's lossless Markdown: people, documents, dates and other chips, tables, images and equations are `<m-*>` tags with a JSON body, such as `<m-user-mention>{"userId":"…"}</m-user-mention>` for a person and `<m-table>` for a table. To write text back, take it and its revision from one `contentWithRevision()` read, and copy every tag you are not changing exactly as you read it: an edited tag changes its chip, and a dropped one deletes it.
37
+ *
19
38
  * ## Uploaded Office and design files
20
39
  *
21
40
  * 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
41
  *
42
+ * ## New spreadsheets
43
+ *
44
+ * `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.
45
+ *
23
46
  * ## Linking Macro items inside document content
24
47
  *
25
48
  * `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 +55,7 @@ export type FileContent = Uint8Array<ArrayBuffer> | ArrayBuffer | Blob | string;
32
55
  *
33
56
  * 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
57
  *
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.
58
+ * 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
59
  *
37
60
  * 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
61
  *
@@ -40,9 +63,17 @@ export type FileContent = Uint8Array<ArrayBuffer> | ArrayBuffer | Blob | string;
40
63
  */
41
64
  export declare class DocumentNamespace {
42
65
  private readonly client;
43
- /** Resolve a team task reference such as ENG-42. */
66
+ /**
67
+ * Resolve a team task reference such as ENG-42.
68
+ *
69
+ * @readonly
70
+ */
44
71
  byTeamSlug(slug: string): Promise<Document>;
45
- /** Validate a permissions token, returning its document and optional user handles. */
72
+ /**
73
+ * Validate a permissions token, returning its document and optional user handles.
74
+ *
75
+ * @readonly
76
+ */
46
77
  validatePermissionsToken(token: string): Promise<{
47
78
  document: Document;
48
79
  user: User | undefined;
@@ -70,6 +101,8 @@ export declare class DocumentNamespace {
70
101
  * });
71
102
  * await channel.send('Invoices attached.', { documents: [file] });
72
103
  * ```
104
+ *
105
+ * @write
73
106
  */
74
107
  upload(options: {
75
108
  name: string;
@@ -79,6 +112,8 @@ export declare class DocumentNamespace {
79
112
  /**
80
113
  * Reserve a binary document and return a presigned URL to PUT its content
81
114
  * to. The URL is outside the hosts code mode can reach; use `upload` there.
115
+ *
116
+ * @write
82
117
  */
83
118
  createUpload(options: {
84
119
  name: string;
@@ -99,18 +134,68 @@ export declare class DocumentNamespace {
99
134
  constructor(client: MacroClient);
100
135
  /** A handle to a document by id. Details load on first access. */
101
136
  byId(id: string): Document;
102
- /** Create a markdown document. */
137
+ /**
138
+ * Create a markdown document.
139
+ *
140
+ * @write
141
+ */
103
142
  create(opts: {
104
143
  name: string;
105
144
  markdown?: string;
106
145
  project?: Project;
107
146
  }): Promise<Document>;
108
- /** Create a native Canvas with shared content ready for reading and editing. */
147
+ /**
148
+ * Create a native Canvas with shared content ready for reading and editing;
149
+ * work on it with `document.canvas()`.
150
+ *
151
+ * @write
152
+ */
109
153
  createCanvas(opts: {
110
154
  name: string;
111
155
  project?: Project;
112
156
  }): Promise<Document>;
113
- /** Create a snippet: a reusable markdown document. */
157
+ /**
158
+ * Create a blank native spreadsheet, ready to read and edit; fill it with
159
+ * `applyEdits`. It is saved before this returns: keep its `id` even when
160
+ * filling it fails, and reopen it by id rather than creating another.
161
+ *
162
+ * @example Create and fill a budget, keeping the spreadsheet if a step fails.
163
+ * ```js
164
+ * const sheet = await macro.documents.createSpreadsheet({ name: 'Q4 budget' });
165
+ * try {
166
+ * const { revision, sheets } = await sheet.read();
167
+ * await sheet.applyEdits(
168
+ * [{ type: 'set_cells', sheetId: sheets[0].id, cells: [
169
+ * { address: 'A1', value: 'Item' }, { address: 'B1', value: 'Cost' },
170
+ * { address: 'A2', value: 'Laptops' }, { address: 'B2', value: 4200 },
171
+ * { address: 'A3', value: 'Total' }, { address: 'B3', value: '=SUM(B2:B2)' },
172
+ * ] }],
173
+ * { expectedRevision: revision },
174
+ * );
175
+ * return { data: { spreadsheet: sheet } };
176
+ * } catch (error) {
177
+ * return { data: { spreadsheet: sheet, error: String(error) } };
178
+ * }
179
+ * ```
180
+ *
181
+ * @write
182
+ */
183
+ createSpreadsheet(opts: {
184
+ name: string;
185
+ project?: Project;
186
+ }): Promise<Spreadsheet>;
187
+ /**
188
+ * Read, calculate and edit a document as a native spreadsheet, such as a
189
+ * search result or mention. Its methods refuse a document of another type.
190
+ *
191
+ * @readonly
192
+ */
193
+ spreadsheet(document: Document): Spreadsheet;
194
+ /**
195
+ * Create a snippet: a reusable markdown document.
196
+ *
197
+ * @write
198
+ */
114
199
  createSnippet(opts: {
115
200
  name: string;
116
201
  markdown?: string;
@@ -128,11 +213,12 @@ export declare class DocumentNamespace {
128
213
  * ```
129
214
  *
130
215
  * 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.
216
+ * that request only. Find skills, built-in ones included, with `skills()`.
133
217
  *
134
218
  * `description` says when to use the skill, in one line starting "Use when"
135
219
  * (at most 300 characters); agents load the skill for requests it describes.
220
+ *
221
+ * @write
136
222
  */
137
223
  createSkill(opts: {
138
224
  name: string;
@@ -140,19 +226,66 @@ export declare class DocumentNamespace {
140
226
  markdown?: string;
141
227
  project?: Project;
142
228
  }): Promise<Document>;
229
+ /**
230
+ * Find skills by name, or list them, built-in skills included; read the
231
+ * instructions of the one a request needs with `skill.content()` before
232
+ * doing the task, and follow them for that request only.
233
+ *
234
+ * With `query`, searches skill names: pass 1-3 words that literally appear
235
+ * in the name, matched as one adjacent phrase whose last word may be a
236
+ * prefix (`matchType: 'exact'` for whole words). Without it, lists the 100
237
+ * most recently updated skills. User skills come first, most recently
238
+ * updated first, then built-in skills.
239
+ *
240
+ * ```js
241
+ * const [match] = await macro.documents.skills({ query: 'deploy' });
242
+ * const instructions = match && (await match.skill.content());
243
+ * ```
244
+ *
245
+ * @readonly
246
+ */
247
+ skills(opts?: {
248
+ query?: string;
249
+ matchType?: 'partial' | 'exact';
250
+ }): Promise<SkillListing[]>;
143
251
  /**
144
252
  * 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()`.
253
+ * behind them. Unlike user skills they cannot be opened or edited; read
254
+ * their instructions with `content()`.
255
+ *
256
+ * @readonly
147
257
  */
148
258
  systemSkills(): Promise<SystemSkill[]>;
149
- /** Search documents by name and content, most relevant first, auto-paginated. */
259
+ /**
260
+ * Search documents by name and content, most relevant first, auto-paginated; `maxItems` caps the total.
261
+ *
262
+ * @readonly
263
+ */
150
264
  search(query: string, opts?: SearchOpts): AsyncGenerator<Document>;
151
- /** The user's recent documents, most recent first, auto-paginated. */
265
+ /**
266
+ * The user's recent documents, most recent first, auto-paginated; `maxItems` caps the total.
267
+ *
268
+ * @readonly
269
+ */
152
270
  recent(opts?: {
153
271
  pageSize?: number;
154
272
  fileType?: string;
273
+ maxItems?: number;
155
274
  }): AsyncGenerator<Document>;
156
- /** The user's recently soft-deleted documents. */
275
+ /**
276
+ * The documents among the user's 100 most recently trashed items; page
277
+ * through the whole trash with `trashed()`.
278
+ *
279
+ * @readonly
280
+ */
157
281
  recentlyDeleted(): Promise<Document[]>;
282
+ /**
283
+ * The user's trashed documents, most recently trashed first, auto-paginated; `maxItems` caps the total.
284
+ *
285
+ * @readonly
286
+ */
287
+ trashed(opts?: {
288
+ pageSize?: number;
289
+ maxItems?: number;
290
+ }): AsyncGenerator<Document>;
158
291
  }
@@ -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
+ * @send
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
+ * @send
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
  }
@@ -21,6 +21,12 @@ export interface SendEmailOptions {
21
21
  subject: string;
22
22
  /** Plain-text body. */
23
23
  bodyText: string;
24
+ /**
25
+ * The address to send from: the primary inbox's own address or one of its
26
+ * verified Gmail send-as aliases, which sends under the alias's display
27
+ * name. An unverified or unknown address is refused.
28
+ */
29
+ from?: string;
24
30
  }
25
31
  /** An email the user has approved in conversation, for `email.sendConfirmed`. */
26
32
  export interface ConfirmedEmailOptions {
@@ -35,11 +41,13 @@ export interface ConfirmedEmailOptions {
35
41
  /** The body, written as Markdown; it is rendered to HTML on send. */
36
42
  body: string;
37
43
  /**
38
- * The connected inbox to send from. Omit it unless you know which inbox is
39
- * right: a reply then goes out from the inbox that received the message it
40
- * answers, and a new email from the user's primary inbox.
44
+ * The connected inbox to send from, or the address of a verified Gmail
45
+ * send-as alias of one, which then sends from that inbox under the alias's
46
+ * display name. Omit it unless you know which is right: a reply then goes
47
+ * out from the inbox that received the message it answers, and a new email
48
+ * from the user's primary inbox. An unverified alias is refused.
41
49
  */
42
- from?: Link;
50
+ from?: Link | string;
43
51
  /** The message this answers; the email is then sent as a reply in its thread. */
44
52
  replyingTo?: EmailMessage;
45
53
  /**
@@ -67,8 +75,11 @@ export interface ForwardEmailOptions {
67
75
  bcc?: EmailRecipient[];
68
76
  /** A note above the forwarded message, written as Markdown. */
69
77
  body?: string;
70
- /** The connected inbox to send from; defaults to the inbox holding the message. */
71
- from?: Link;
78
+ /**
79
+ * The connected inbox to send from, or a verified Gmail send-as alias of
80
+ * one; defaults to the inbox holding the message.
81
+ */
82
+ from?: Link | string;
72
83
  /** `false` leaves the inbox signature off this one email; omit for the inbox's default. */
73
84
  includeSignature?: boolean;
74
85
  }
@@ -99,13 +110,20 @@ export declare class EmailMessage extends MacroEntity<EmailMessageData> {
99
110
  static sendConfirmed(client: MacroClient, opts: ConfirmedEmailOptions): Promise<SentEmail>;
100
111
  /** @internal Run the SendConfirmedEmail tool with a SendEmail draft and its approval. */
101
112
  private static sendReviewedDraft;
102
- /** The files attached to this message, from its thread's first 100 messages. */
113
+ /**
114
+ * The files attached to this message, from its thread's first 100 messages.
115
+ *
116
+ * @readonly
117
+ */
103
118
  attachments(): Promise<EmailAttachment[]>;
104
119
  /**
105
120
  * This message as a forward: a SendEmail draft with the note, the quoted
106
121
  * message under the forwarded-message header, and its attachments as
107
122
  * Macro documents. Pass it to `execution.reviews.create({kind: 'email'})`
108
123
  * in a session; in a thread, use {@link forwardConfirmed}.
124
+ *
125
+ * @write
126
+ * @idempotent
109
127
  */
110
128
  forwardDraft(opts: ForwardEmailOptions): Promise<SendEmail>;
111
129
  /**
@@ -117,6 +135,9 @@ export declare class EmailMessage extends MacroEntity<EmailMessageData> {
117
135
  * `forwardDraft` as a review instead. The forward is a new email that
118
136
  * quotes this message and carries its attachments; it takes effect at once
119
137
  * and is never retried.
138
+ *
139
+ * @send
140
+ * @openworld
120
141
  */
121
142
  forwardConfirmed(opts: ForwardEmailOptions & {
122
143
  userConfirmation: string;
@@ -139,27 +160,64 @@ export declare class EmailMessage extends MacroEntity<EmailMessageData> {
139
160
  readonly labels: () => Promise<import("../../../generated/email").LabelInfo[]>;
140
161
  /** The inbox (email link) this message belongs to. */
141
162
  readonly link: () => Promise<Link>;
142
- /** Read the draft's durable send, upload, or conflict status without retrying it. */
163
+ /**
164
+ * Read the draft's durable send, upload, or conflict status without retrying it.
165
+ *
166
+ * @readonly
167
+ */
143
168
  operationStatus(): Promise<MessageOperationResponse>;
144
169
  /** Resolve the displayed operation revision after the user chooses an action.
145
- * Retrying an uncertain send requires explicit duplicate-risk acceptance. */
170
+ * Retrying an uncertain send requires explicit duplicate-risk acceptance.
171
+ *
172
+ * @destructive
173
+ * @openworld
174
+ */
146
175
  resolveOperation(request: ResolveMessageOperationRequest): Promise<void>;
147
- /** Verify an uploaded attachment using the draft generation captured when its upload began. */
176
+ /**
177
+ * Verify an uploaded attachment using the draft generation captured when its upload began.
178
+ *
179
+ * @write
180
+ * @idempotent
181
+ */
148
182
  completeDraftAttachment(attachmentId: string, draftGeneration?: number): Promise<void>;
149
183
  /** Move a draft to another inbox using a caller-persisted operation UUID.
150
184
  * Continue editing the returned message_id; the original identity is retired.
151
- * On an interrupted response, use email.recoverDraftTransfer(operation_id). */
185
+ * On an interrupted response, use email.recoverDraftTransfer(operation_id).
186
+ *
187
+ * @write
188
+ * @openworld
189
+ * @idempotent
190
+ */
152
191
  transferDraft(request: TransferDraftRequest): Promise<TransferDraftResponse>;
153
- /** Add a label to this message. */
192
+ /**
193
+ * Add a label to this message.
194
+ *
195
+ * @write
196
+ * @openworld
197
+ * @idempotent
198
+ */
154
199
  addLabel(label: Label): Promise<void>;
155
- /** Remove a label from this message. */
200
+ /**
201
+ * Remove a label from this message.
202
+ *
203
+ * @write
204
+ * @openworld
205
+ * @idempotent
206
+ */
156
207
  removeLabel(label: Label): Promise<void>;
157
- /** The thread this message belongs to. */
208
+ /**
209
+ * The thread this message belongs to.
210
+ *
211
+ * @readonly
212
+ */
158
213
  thread(): Promise<EmailThread>;
159
214
  /**
160
215
  * The message's original source, exactly as Gmail or Outlook holds it, as
161
216
  * `message/rfc822` bytes for an `.eml` file. Drafts and messages still on
162
217
  * their way have no source yet and fail with a 404.
218
+ *
219
+ * @readonly
220
+ * @mcp-exclude Returns raw bytes only; MCP calls carry JSON.
163
221
  */
164
222
  downloadEml(): Promise<Blob>;
165
223
  }