@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
@@ -5,12 +5,18 @@ import { PropertiedEntity } from '../entity';
5
5
  import { Project } from '../projects/project';
6
6
  import type { EntityReference } from '../reference';
7
7
  import { EntityAccess } from '../sharing/access';
8
+ import { type SharePermissionOptions } from '../sharing/permissions';
8
9
  import { ChatGeneration } from './generation';
9
10
  type ChatDetail = GetChatResponses[200]['chat'];
10
11
  type ChatHistory = GetChatHistoryHandlerResponses[200]['conversation'];
11
12
  /** A Macro AI chat. */
12
13
  export declare class Chat extends PropertiedEntity<ChatDetail> implements Mentionable {
13
- /** Send a message and start a background generation. Tools may perform writes. */
14
+ /**
15
+ * Send a message and start a background generation. Tools may perform writes.
16
+ *
17
+ * @write
18
+ * @openworld
19
+ */
14
20
  send(options: Omit<HttpSendChatMessageRequest, 'chat_id' | 'attachments' | 'additional_instructions'> & {
15
21
  attachments?: EntityReference[];
16
22
  additionalInstructions?: string;
@@ -41,22 +47,61 @@ export declare class Chat extends PropertiedEntity<ChatDetail> implements Mentio
41
47
  readonly updatedAt: () => Promise<string | undefined>;
42
48
  /** The messages in the chat, with their attachments. */
43
49
  readonly messages: () => Promise<import("../../../generated/cognition").ChatMessageWithAttachments[]>;
44
- /** Rename the chat. */
50
+ /**
51
+ * Sharing configuration.
52
+ *
53
+ * @readonly
54
+ */
55
+ sharePermissions(): Promise<import("../../../generated/cognition").GetChatPermissionsResponse>;
56
+ /**
57
+ * Change who can open the chat: the link share and its access level, the
58
+ * owner's team, and channel grants. Omitted fields are left as they are.
59
+ *
60
+ * @write
61
+ * @idempotent
62
+ */
63
+ updateSharePermissions(options: SharePermissionOptions): Promise<void>;
64
+ /**
65
+ * Rename the chat.
66
+ *
67
+ * @write
68
+ * @idempotent
69
+ */
45
70
  rename(name: string): Promise<void>;
46
71
  /**
47
72
  * Delete the chat. Soft by default (reversible with {@link restore});
48
73
  * pass `permanent: true` to delete irreversibly.
74
+ *
75
+ * @destructive
76
+ * @idempotent
49
77
  */
50
78
  delete(opts?: {
51
79
  permanent?: boolean;
52
80
  }): Promise<void>;
53
- /** Copy the chat, returning a handle to the new copy. */
81
+ /**
82
+ * Copy the chat, returning a handle to the new copy.
83
+ *
84
+ * @write
85
+ */
54
86
  copy(): Promise<Chat>;
55
- /** Restore a soft-deleted chat. */
87
+ /**
88
+ * Restore a soft-deleted chat.
89
+ *
90
+ * @write
91
+ * @idempotent
92
+ */
56
93
  restore(): Promise<void>;
57
- /** The chat's conversation history: titled records of messages with attachment ids. */
94
+ /**
95
+ * The chat's conversation history: titled records of messages with attachment ids.
96
+ *
97
+ * @readonly
98
+ */
58
99
  history(): Promise<ChatHistory>;
59
- /** The chat's URL in the Macro web app. */
100
+ /**
101
+ * The chat's URL in the Macro web app.
102
+ *
103
+ * @readonly
104
+ */
60
105
  webUrl(): string;
61
106
  /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
62
107
  toJSON(): {
@@ -64,8 +109,13 @@ export declare class Chat extends PropertiedEntity<ChatDetail> implements Mentio
64
109
  id: string;
65
110
  detail?: import("../../../generated/cognition").ChatResponse | undefined;
66
111
  };
67
- /** Search chats by name and content, most relevant first, auto-paginated. */
112
+ /** Search chats by name and content, most relevant first, auto-paginated; `maxItems` caps the total. */
68
113
  static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<Chat, any, any>;
114
+ /**
115
+ * Render this chat as a mention for a message body.
116
+ *
117
+ * @readonly
118
+ */
69
119
  toMention(): MentionPart;
70
120
  }
71
121
  export {};
@@ -14,7 +14,12 @@ export declare class ChatGeneration {
14
14
  private constructor();
15
15
  /** Construct from a send receipt. */
16
16
  static byId(client: MacroClient, chat: Chat, id: string, message: ChatMessage): ChatGeneration;
17
- /** Request cancellation of this generation. */
17
+ /**
18
+ * Request cancellation of this generation.
19
+ *
20
+ * @destructive
21
+ * @idempotent
22
+ */
18
23
  stop(): Promise<void>;
19
24
  /** Serialize scoped identity. */
20
25
  toJSON(): {
@@ -35,7 +40,11 @@ export declare class ChatMessage extends MacroEntity<ChatMessageWithAttachments>
35
40
  readonly content: () => Promise<import("../../../generated/cognition").ChatMessageContent>;
36
41
  /** Role of the message author. */
37
42
  readonly role: () => Promise<import("../../../generated/cognition").Role>;
38
- /** Reload after a running generation changes or finishes. */
43
+ /**
44
+ * Reload after a running generation changes or finishes.
45
+ *
46
+ * @readonly
47
+ */
39
48
  refresh(): Promise<void>;
40
49
  /** Serialize scoped identity and any loaded message. */
41
50
  toJSON(): {
@@ -17,11 +17,19 @@ export declare class ChatNamespace {
17
17
  constructor(client: MacroClient);
18
18
  /** A handle to an AI chat by id; read its messages with `history()`. */
19
19
  byId(id: string): Chat;
20
- /** Create an empty AI chat, optionally named and in a project. */
20
+ /**
21
+ * Create an empty AI chat, optionally named and in a project.
22
+ *
23
+ * @write
24
+ */
21
25
  create(opts?: {
22
26
  name?: string;
23
27
  project?: Project;
24
28
  }): Promise<Chat>;
25
- /** Search AI chats by name and content, most relevant first, auto-paginated. */
29
+ /**
30
+ * Search AI chats by name and content, most relevant first, auto-paginated; `maxItems` caps the total.
31
+ *
32
+ * @readonly
33
+ */
26
34
  search(query: string, opts?: SearchOpts): AsyncGenerator<Chat>;
27
35
  }
@@ -43,9 +43,18 @@ export declare class ConnectedApp {
43
43
  /**
44
44
  * The tools this app serves, with each one's description and argument
45
45
  * schema. Read a tool's `inputSchema` before calling it.
46
+ *
47
+ * @readonly
48
+ * @openworld
49
+ * @mcp-exclude Needs the CodeExecution of a running program.
46
50
  */
47
51
  tools(): Promise<ConnectedTool[]>;
48
- /** @internal The harness route that names this app. */
52
+ /**
53
+ * @internal The harness route that names this app.
54
+ *
55
+ * @readonly
56
+ * @mcp-exclude Internal route helper.
57
+ */
49
58
  path(): {
50
59
  session_id: string;
51
60
  execution_id: string;
@@ -90,7 +99,12 @@ export declare class ConnectedTool {
90
99
  * unanswered call comes back with `isError`. Check `isError` on the result: an app that is not connected,
91
100
  * or whose connection expired, answers with `isError` and text telling you
92
101
  * what to say to the user, including any connect markup to put in your
93
- * reply verbatim.
102
+ * reply verbatim. Throws when the app is still rate limiting the account
103
+ * after Macro paced and retried the call; the call did not run.
104
+ *
105
+ * @destructive
106
+ * @openworld
107
+ * @mcp-exclude Needs the CodeExecution of a running program.
94
108
  */
95
109
  call(args?: Record<string, unknown>): Promise<ConnectedToolResult>;
96
110
  /** Serialize the tool's description, not its client. */
@@ -45,6 +45,9 @@ export declare class Connector {
45
45
  /**
46
46
  * Read the actions this app advertises and whether the execution's account
47
47
  * has it connected. Inspection never calls the app or changes a connection.
48
+ *
49
+ * @readonly
50
+ * @mcp-exclude Needs the CodeExecution of a running program.
48
51
  */
49
52
  inspect(): Promise<ConnectorInspection>;
50
53
  /** Serialize the catalog entry, not its client. */
@@ -18,6 +18,8 @@ export type { ConnectMcpServerResponse };
18
18
  *
19
19
  * Calls run in the user's real account through Macro's server, as the account this execution acts as, and take effect at once; the program never sees a credential. In a turn someone other than the session's owner prompted, each call that uses the owner's account waits for the owner to approve it, so make few such calls and expect a long wait or a refusal. Read before writing, and never repeat a write whose outcome is unknown: check the app's state first. A result with `isError` explains itself: when it says an app is not connected, tell the user and include the connect markup it gives you in your reply verbatim, then stop.
20
20
  *
21
+ * Each account's calls to one app share a budget across its running programs on the same Macro server: a few run at once, paced, and the rest queue. Narrow first with the app's search or list tools and their own limits and filters (e.g. open PRs updated this week), then call per item only for the few items you need, in small batches; never `Promise.all` a call per item over a whole list. A call the app keeps refusing with HTTP 429 is retried after its `Retry-After`; one still refused throws a rate-limit error and did not run, so stop and report partial results rather than retrying in a loop.
22
+ *
21
23
  * When an app the work needs is missing, find it with `macro.connectedApps.discover(execution, appName)` and `connector.inspect()` its advertised actions and connection status. Recommend connecting only when an advertised action supports the task; an app's name is not evidence. For a suitable unconnected app, put the inspection's `connectMarkup` in your reply verbatim and say what connecting enables. To add a remote MCP server the user gives you the URL of, use `macro.connectedApps.addServer(execution, {url, serverName})`; never guess a URL, and tell the user to sign in under Settings → Connections when its summary says so.
22
24
  *
23
25
  * ```javascript
@@ -39,6 +41,10 @@ export declare class ConnectedAppNamespace {
39
41
  * List the apps a running code execution's session agent may use; pass the
40
42
  * `execution` given to `main`. Fails outside a running execution of the
41
43
  * session's current turn.
44
+ *
45
+ * @readonly
46
+ * @openworld
47
+ * @mcp-exclude Needs the CodeExecution of a running program.
42
48
  */
43
49
  list(execution: CodeExecution): Promise<ConnectedApp[]>;
44
50
  /**
@@ -46,6 +52,10 @@ export declare class ConnectedAppNamespace {
46
52
  * by keywords matched against tool names and descriptions (e.g. `linear
47
53
  * issue`), best first, at most 20. Apps whose tools could not be read come
48
54
  * back in `unsearched`, not as an error.
55
+ *
56
+ * @readonly
57
+ * @openworld
58
+ * @mcp-exclude Needs the CodeExecution of a running program.
49
59
  */
50
60
  searchTools(execution: CodeExecution, query: string): Promise<{
51
61
  matches: ConnectedTool[];
@@ -55,6 +65,9 @@ export declare class ConnectedAppNamespace {
55
65
  * Search the catalog of apps the user could connect, by app name (e.g.
56
66
  * `Linear`, not a task description). Inspect a result before recommending
57
67
  * it: its description alone does not show what it can do.
68
+ *
69
+ * @readonly
70
+ * @mcp-exclude Needs the CodeExecution of a running program.
58
71
  */
59
72
  discover(execution: CodeExecution, appName: string): Promise<{
60
73
  connectors: Connector[];
@@ -66,6 +79,11 @@ export declare class ConnectedAppNamespace {
66
79
  * never guess. Most servers then need the user to sign in under
67
80
  * Settings → Connections, which the result's `summary` says. A URL the
68
81
  * user already has is left as it is.
82
+ *
83
+ * @write
84
+ * @idempotent
85
+ * @openworld
86
+ * @mcp-exclude Needs the CodeExecution of a running program.
69
87
  */
70
88
  addServer(execution: CodeExecution, server: {
71
89
  url: string;
@@ -2,17 +2,25 @@ import type { GetCompanyResponses } from '../../../generated/storage/types.gen';
2
2
  import type { RichMessage } from '../../mentions';
3
3
  import type { MacroClient } from '../../utils/client';
4
4
  import { PropertiedEntity } from '../entity';
5
+ import { DiscussionComment, type DiscussionThread } from '../messages/discussion';
5
6
  import { MessageThread, type TimelineOptions } from '../messages/thread';
6
7
  import { Team } from '../teams/team';
7
- import { CrmComment, type CrmCommentThread } from './comment';
8
8
  import { Contact } from './contact';
9
9
  type CompanyDetail = GetCompanyResponses[200];
10
10
  /** A CRM company: an organization the team has interacted with. */
11
11
  export declare class Company extends PropertiedEntity<CompanyDetail> {
12
- /** A shared message thread scoped to this resource. */
12
+ /**
13
+ * A shared message thread scoped to this resource.
14
+ *
15
+ * @readonly
16
+ */
13
17
  messageThreadById(id: string): MessageThread;
14
- /** A mixed message and activity timeline page. */
15
- timelinePage(selection?: TimelineOptions<CrmComment>): Promise<{
18
+ /**
19
+ * A mixed message and activity timeline page.
20
+ *
21
+ * @readonly
22
+ */
23
+ timelinePage(selection?: TimelineOptions<DiscussionComment>): Promise<{
16
24
  entries: ({
17
25
  type: "activity";
18
26
  activity: {
@@ -26,7 +34,7 @@ export declare class Company extends PropertiedEntity<CompanyDetail> {
26
34
  message?: undefined;
27
35
  } | {
28
36
  type: "message";
29
- message: CrmComment;
37
+ message: DiscussionComment;
30
38
  activity?: undefined;
31
39
  })[];
32
40
  nextCursor: import("../../../generated/storage").MessageCursor | undefined;
@@ -55,33 +63,63 @@ export declare class Company extends PropertiedEntity<CompanyDetail> {
55
63
  readonly createdAt: () => Promise<string>;
56
64
  /** When the company was last updated. */
57
65
  readonly updatedAt: () => Promise<string>;
58
- /** The company's primary domain (e.g. `acme.com`), if any. */
66
+ /**
67
+ * The company's primary domain (e.g. `acme.com`), if any.
68
+ *
69
+ * @readonly
70
+ */
59
71
  domain(): Promise<string | undefined>;
60
- /** All domains associated with the company, primary first. */
72
+ /**
73
+ * All domains associated with the company, primary first.
74
+ *
75
+ * @readonly
76
+ */
61
77
  domains(): Promise<string[]>;
62
- /** The contacts attached to this company (hidden ones filtered for non-admins). */
78
+ /**
79
+ * The contacts attached to this company (hidden ones filtered for non-admins).
80
+ *
81
+ * @readonly
82
+ */
63
83
  contacts(): Promise<Contact[]>;
64
- /** Search CRM companies by name/domain, most relevant first, auto-paginated. */
84
+ /** Search CRM companies by name/domain, most relevant first, auto-paginated; `maxItems` caps the total. */
65
85
  static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<Company, any, any>;
66
86
  /**
67
87
  * Hide the company from CRM listings: disables email sync and soft-hides
68
88
  * its contacts. Reversible with {@link unhide}.
89
+ *
90
+ * @write
91
+ * @idempotent
69
92
  */
70
93
  hide(): Promise<void>;
71
- /** Un-hide the company, restoring it and its contacts to CRM listings. */
94
+ /**
95
+ * Un-hide the company, restoring it and its contacts to CRM listings.
96
+ *
97
+ * @write
98
+ * @idempotent
99
+ */
72
100
  unhide(): Promise<void>;
73
101
  private setHidden;
74
102
  /**
75
103
  * Enable or disable team-wide email sync for this company. Rejects with 409
76
104
  * when enabling on a hidden company — {@link unhide} first.
105
+ *
106
+ * @write
107
+ * @idempotent
77
108
  */
78
109
  setEmailSync(enabled: boolean): Promise<void>;
79
- /** Rename the company for the caller's current team. */
110
+ /**
111
+ * Rename the company for the caller's current team.
112
+ *
113
+ * @write
114
+ * @idempotent
115
+ */
80
116
  rename(name: string): Promise<void>;
81
117
  /**
82
118
  * Create a contact under this company. The email is optional and need not
83
119
  * match the company's domains, so personal addresses work too; omitting it
84
120
  * adds the contact by name alone.
121
+ *
122
+ * @write
85
123
  */
86
124
  createContact(opts: {
87
125
  email?: string;
@@ -89,18 +127,28 @@ export declare class Company extends PropertiedEntity<CompanyDetail> {
89
127
  }): Promise<Contact>;
90
128
  /** The CRM record this company's discussions hang off. */
91
129
  private get commentParent();
92
- /** The comment threads on this company, newest thread first. */
93
- comments(): Promise<CrmCommentThread[]>;
130
+ /**
131
+ * The comment threads on this company, newest thread first.
132
+ *
133
+ * @readonly
134
+ */
135
+ comments(): Promise<DiscussionThread[]>;
94
136
  /**
95
137
  * Add a comment. Starts a new thread, or replies to an existing one when
96
138
  * `threadId` (the thread's root comment id) is given.
97
139
  *
98
140
  * @param body - Plain text, or a rich body composed with {@link msg}.
141
+ *
142
+ * @write
99
143
  */
100
144
  comment(body: string | RichMessage, opts?: {
101
145
  threadId?: string;
102
- }): Promise<CrmComment>;
103
- /** A handle to one of this company's comments by id. */
104
- commentById(id: string): CrmComment;
146
+ }): Promise<DiscussionComment>;
147
+ /**
148
+ * A handle to one of this company's comments by id.
149
+ *
150
+ * @readonly
151
+ */
152
+ commentById(id: string): DiscussionComment;
105
153
  }
106
154
  export {};
@@ -2,16 +2,24 @@ import type { GetContactResponses } from '../../../generated/storage/types.gen';
2
2
  import type { RichMessage } from '../../mentions';
3
3
  import type { MacroClient } from '../../utils/client';
4
4
  import { FavoritableEntity } from '../entity';
5
+ import { DiscussionComment, type DiscussionThread } from '../messages/discussion';
5
6
  import { MessageThread, type TimelineOptions } from '../messages/thread';
6
- import { CrmComment, type CrmCommentThread } from './comment';
7
7
  import { Company } from './company';
8
8
  type ContactDetail = GetContactResponses[200];
9
9
  /** A CRM contact: a person observed interacting with the team. */
10
10
  export declare class Contact extends FavoritableEntity<ContactDetail> {
11
- /** A shared message thread scoped to this resource. */
11
+ /**
12
+ * A shared message thread scoped to this resource.
13
+ *
14
+ * @readonly
15
+ */
12
16
  messageThreadById(id: string): MessageThread;
13
- /** A mixed message and activity timeline page. */
14
- timelinePage(selection?: TimelineOptions<CrmComment>): Promise<{
17
+ /**
18
+ * A mixed message and activity timeline page.
19
+ *
20
+ * @readonly
21
+ */
22
+ timelinePage(selection?: TimelineOptions<DiscussionComment>): Promise<{
15
23
  entries: ({
16
24
  type: "activity";
17
25
  activity: {
@@ -25,7 +33,7 @@ export declare class Contact extends FavoritableEntity<ContactDetail> {
25
33
  message?: undefined;
26
34
  } | {
27
35
  type: "message";
28
- message: CrmComment;
36
+ message: DiscussionComment;
29
37
  activity?: undefined;
30
38
  })[];
31
39
  nextCursor: import("../../../generated/storage").MessageCursor | undefined;
@@ -40,8 +48,20 @@ export declare class Contact extends FavoritableEntity<ContactDetail> {
40
48
  static from(client: MacroClient, data: ContactDetail): Contact;
41
49
  /** The contact's display name, if one has been observed. */
42
50
  readonly name: () => Promise<string | undefined>;
43
- /** The contact's email address; absent for a contact added by name alone. */
51
+ /** The contact's primary email address; absent for a contact added by name alone. */
44
52
  readonly email: () => Promise<string | undefined>;
53
+ /** Every address the contact is known by: the primary first, then the rest oldest first. */
54
+ readonly emails: () => Promise<string[]>;
55
+ /**
56
+ * Whether the contact has an address on one of its company's domains. Such a
57
+ * contact cannot be unlinked from the company or moved to another.
58
+ */
59
+ readonly companyDomain: () => Promise<NonNullable<boolean | undefined>>;
60
+ /**
61
+ * The addresses on one of the company's domains. The last one cannot be
62
+ * removed while the contact is linked to the company.
63
+ */
64
+ readonly companyDomainEmails: () => Promise<string[]>;
45
65
  /** The CRM company this contact belongs to, if it has one. */
46
66
  readonly company: () => Promise<Company | undefined>;
47
67
  /** Whether the contact is hidden from CRM listings. */
@@ -54,27 +74,95 @@ export declare class Contact extends FavoritableEntity<ContactDetail> {
54
74
  readonly firstInteraction: () => Promise<string>;
55
75
  /** When the team last interacted with this contact. */
56
76
  readonly lastInteraction: () => Promise<string>;
57
- /** Hide the contact from CRM listings. Display-only; reversible with {@link unhide}. */
77
+ /**
78
+ * Hide the contact from CRM listings. Display-only; reversible with {@link unhide}.
79
+ *
80
+ * @write
81
+ * @idempotent
82
+ */
58
83
  hide(): Promise<void>;
59
- /** Un-hide the contact, restoring it to CRM listings. */
84
+ /**
85
+ * Un-hide the contact, restoring it to CRM listings.
86
+ *
87
+ * @write
88
+ * @idempotent
89
+ */
60
90
  unhide(): Promise<void>;
61
91
  private setHidden;
62
- /** Rename the contact for the caller's current team. */
92
+ /**
93
+ * Rename the contact for the caller's current team.
94
+ *
95
+ * @write
96
+ * @idempotent
97
+ */
63
98
  rename(name: string): Promise<void>;
99
+ /**
100
+ * Make an address the contact's primary, adding it when the contact does not
101
+ * hold it yet. The previous primary stays on the contact.
102
+ *
103
+ * @write
104
+ * @idempotent
105
+ */
106
+ setEmail(email: string): Promise<void>;
107
+ /**
108
+ * Add a further address the contact is known by. It must not belong to
109
+ * another contact in the team, and becomes the primary only when the contact
110
+ * has none.
111
+ *
112
+ * @write
113
+ * @idempotent
114
+ */
115
+ addEmail(email: string): Promise<void>;
116
+ /**
117
+ * Remove one of the contact's addresses. Nothing else is deleted: the contact
118
+ * stops showing that address's email history. Removing the primary promotes
119
+ * the oldest address left. The last address on a domain of the contact's
120
+ * company cannot be removed while the contact is linked to it.
121
+ *
122
+ * @destructive
123
+ * @idempotent
124
+ */
125
+ removeEmail(email: string): Promise<void>;
126
+ /**
127
+ * Link or switch the company of a contact whose primary address is on a
128
+ * personal provider. Rejected for a contact on its company's domain.
129
+ *
130
+ * @write
131
+ * @idempotent
132
+ */
133
+ setCompany(company: Company): Promise<void>;
134
+ /**
135
+ * Remove the contact's company link, leaving a contact without a company.
136
+ * Rejected for a contact on its company's domain.
137
+ *
138
+ * @write
139
+ * @idempotent
140
+ */
141
+ unlinkCompany(): Promise<void>;
64
142
  /** The CRM record this contact's discussions hang off. */
65
143
  private get commentParent();
66
- /** The comment threads on this contact, newest thread first. */
67
- comments(): Promise<CrmCommentThread[]>;
144
+ /**
145
+ * The comment threads on this contact, newest thread first.
146
+ *
147
+ * @readonly
148
+ */
149
+ comments(): Promise<DiscussionThread[]>;
68
150
  /**
69
151
  * Add a comment. Starts a new thread, or replies to an existing one when
70
152
  * `threadId` (the thread's root comment id) is given.
71
153
  *
72
154
  * @param body - Plain text, or a rich body composed with {@link msg}.
155
+ *
156
+ * @write
73
157
  */
74
158
  comment(body: string | RichMessage, opts?: {
75
159
  threadId?: string;
76
- }): Promise<CrmComment>;
77
- /** A handle to one of this contact's comments by id. */
78
- commentById(id: string): CrmComment;
160
+ }): Promise<DiscussionComment>;
161
+ /**
162
+ * A handle to one of this contact's comments by id.
163
+ *
164
+ * @readonly
165
+ */
166
+ commentById(id: string): DiscussionComment;
79
167
  }
80
168
  export {};