@macro-inc/sdk 0.2.2 → 0.4.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 (175) hide show
  1. package/README.md +177 -3
  2. package/dist/{chunk-OGE7WXJE.js → chunk-AZJUIUIV.js} +177 -23
  3. package/dist/{chunk-PRUFPW3B.js → chunk-G43PLP2U.js} +144 -0
  4. package/dist/{chunk-7LVVPVNT.js → chunk-K4G5VO4P.js} +76 -1
  5. package/dist/{chunk-PAAFJYGO.js → chunk-PPR7IWZ7.js} +77 -51
  6. package/dist/{chunk-QVBNNMQS.js → chunk-PTX2RV2N.js} +169 -20
  7. package/dist/{chunk-SUINKDXF.js → chunk-PZPTJI6F.js} +42 -0
  8. package/dist/{chunk-7YJ6Y7HJ.js → chunk-XFA7NCJ5.js} +207 -0
  9. package/dist/{chunk-ZQXOHNDB.js → chunk-ZLBDES7U.js} +789 -12
  10. package/dist/generated/agent-fold/index.d.ts +4332 -0
  11. package/dist/generated/agent-fold/index.js +0 -0
  12. package/dist/generated/agent-harness/index.d.ts +1 -1
  13. package/dist/generated/agent-harness/index.js +1 -1
  14. package/dist/generated/agent-harness/sdk.gen.d.ts +83 -9
  15. package/dist/generated/agent-harness/types.gen.d.ts +1504 -160
  16. package/dist/generated/agent-reviews/index.d.ts +893 -0
  17. package/dist/generated/agent-reviews/index.js +0 -0
  18. package/dist/generated/auth/index.d.ts +1 -1
  19. package/dist/generated/auth/index.js +1 -1
  20. package/dist/generated/auth/sdk.gen.d.ts +108 -2
  21. package/dist/generated/auth/types.gen.d.ts +799 -6
  22. package/dist/generated/calendar/index.d.ts +1 -1
  23. package/dist/generated/calendar/index.js +1 -1
  24. package/dist/generated/calendar/sdk.gen.d.ts +63 -1
  25. package/dist/generated/calendar/types.gen.d.ts +1234 -5
  26. package/dist/generated/cognition/index.d.ts +1 -1
  27. package/dist/generated/cognition/index.js +1 -1
  28. package/dist/generated/cognition/sdk.gen.d.ts +85 -20
  29. package/dist/generated/cognition/types.gen.d.ts +1040 -121
  30. package/dist/generated/connection/index.d.ts +1 -1
  31. package/dist/generated/connection/index.js +15 -0
  32. package/dist/generated/connection/sdk.gen.d.ts +6 -1
  33. package/dist/generated/connection/types.gen.d.ts +18 -1
  34. package/dist/generated/email/index.d.ts +1 -1
  35. package/dist/generated/email/index.js +1 -1
  36. package/dist/generated/email/sdk.gen.d.ts +44 -2
  37. package/dist/generated/email/types.gen.d.ts +475 -10
  38. package/dist/generated/notification/index.d.ts +1 -1
  39. package/dist/generated/notification/index.js +1 -1
  40. package/dist/generated/notification/sdk.gen.d.ts +29 -21
  41. package/dist/generated/notification/types.gen.d.ts +267 -73
  42. package/dist/generated/properties/index.d.ts +1 -1
  43. package/dist/generated/properties/types.gen.d.ts +21 -1
  44. package/dist/generated/scheduled-action/index.d.ts +1 -1
  45. package/dist/generated/scheduled-action/index.js +1 -1
  46. package/dist/generated/scheduled-action/sdk.gen.d.ts +8 -1
  47. package/dist/generated/scheduled-action/types.gen.d.ts +669 -19
  48. package/dist/generated/search/index.d.ts +1 -1
  49. package/dist/generated/search/types.gen.d.ts +87 -7
  50. package/dist/generated/static-files/types.gen.d.ts +6 -0
  51. package/dist/generated/storage/index.d.ts +1 -1
  52. package/dist/generated/storage/index.js +1 -1
  53. package/dist/generated/storage/sdk.gen.d.ts +376 -13
  54. package/dist/generated/storage/types.gen.d.ts +12038 -5562
  55. package/dist/src/entities/account-managers/grant.d.ts +39 -0
  56. package/dist/src/entities/account-managers/namespace.d.ts +17 -0
  57. package/dist/src/entities/agent-sessions/activity.d.ts +39 -0
  58. package/dist/src/entities/agent-sessions/agent-session.d.ts +148 -6
  59. package/dist/src/entities/agent-sessions/code-execution.d.ts +5 -0
  60. package/dist/src/entities/agent-sessions/namespace.d.ts +54 -4
  61. package/dist/src/entities/agent-sessions/origin.d.ts +94 -0
  62. package/dist/src/entities/agent-sessions/review.d.ts +18 -62
  63. package/dist/src/entities/agent-sessions/view.d.ts +11 -0
  64. package/dist/src/entities/agents/namespace.d.ts +11 -2
  65. package/dist/src/entities/ai/namespace.d.ts +5 -1
  66. package/dist/src/entities/api-keys/namespace.d.ts +5 -1
  67. package/dist/src/entities/bots/bot.d.ts +108 -0
  68. package/dist/src/entities/bots/namespace.d.ts +17 -4
  69. package/dist/src/entities/bots/token.d.ts +34 -0
  70. package/dist/src/entities/calendar/booking-link.d.ts +49 -0
  71. package/dist/src/entities/calendar/booking-namespace.d.ts +130 -0
  72. package/dist/src/entities/calendar/booking-namespace.test.d.ts +1 -0
  73. package/dist/src/entities/calendar/booking.d.ts +77 -0
  74. package/dist/src/entities/calendar/calendar.d.ts +11 -4
  75. package/dist/src/entities/calendar/create-confirmed.test.d.ts +1 -0
  76. package/dist/src/entities/calendar/event.d.ts +104 -3
  77. package/dist/src/entities/calendar/namespace.d.ts +151 -7
  78. package/dist/src/entities/calendar/namespace.test.d.ts +1 -0
  79. package/dist/src/entities/calls/call-record.d.ts +34 -4
  80. package/dist/src/entities/calls/connection.d.ts +53 -0
  81. package/dist/src/entities/calls/errors.d.ts +15 -0
  82. package/dist/src/entities/calls/namespace.d.ts +21 -1
  83. package/dist/src/entities/calls/participant.d.ts +22 -0
  84. package/dist/src/entities/channels/access-request.d.ts +34 -0
  85. package/dist/src/entities/channels/channel.d.ts +47 -1
  86. package/dist/src/entities/channels/namespace.d.ts +21 -5
  87. package/dist/src/entities/channels/namespace.test.d.ts +1 -0
  88. package/dist/src/entities/channels/post.d.ts +14 -3
  89. package/dist/src/entities/channels/thread.d.ts +10 -1
  90. package/dist/src/entities/chats/chat.d.ts +7 -1
  91. package/dist/src/entities/chats/namespace.d.ts +14 -1
  92. package/dist/src/entities/connected-apps/connected-app.d.ts +107 -0
  93. package/dist/src/entities/connected-apps/connector.d.ts +56 -0
  94. package/dist/src/entities/connected-apps/namespace.d.ts +74 -0
  95. package/dist/src/entities/crm/company.d.ts +7 -3
  96. package/dist/src/entities/crm/contact.d.ts +4 -4
  97. package/dist/src/entities/crm/namespace.d.ts +34 -1
  98. package/dist/src/entities/crm/pipeline.d.ts +43 -2
  99. package/dist/src/entities/databases/database.d.ts +17 -0
  100. package/dist/src/entities/databases/namespace.d.ts +56 -0
  101. package/dist/src/entities/documents/ai-edit.d.ts +52 -0
  102. package/dist/src/entities/documents/document.d.ts +244 -5
  103. package/dist/src/entities/documents/namespace.d.ts +89 -4
  104. package/dist/src/entities/documents/office-files.d.ts +47 -0
  105. package/dist/src/entities/email/draft.d.ts +36 -7
  106. package/dist/src/entities/email/message.d.ts +99 -3
  107. package/dist/src/entities/email/namespace.d.ts +47 -4
  108. package/dist/src/entities/email/namespace.test.d.ts +1 -0
  109. package/dist/src/entities/email/thread.d.ts +55 -3
  110. package/dist/src/entities/entity-mentions/namespace.d.ts +5 -1
  111. package/dist/src/entities/external-chat/chat.d.ts +105 -0
  112. package/dist/src/entities/external-chat/message.d.ts +54 -0
  113. package/dist/src/entities/external-chat/namespace.d.ts +18 -0
  114. package/dist/src/entities/external-chat/participant.d.ts +28 -0
  115. package/dist/src/entities/external-chat/send.d.ts +32 -0
  116. package/dist/src/entities/external-chat/upload.d.ts +25 -0
  117. package/dist/src/entities/favorites/namespace.d.ts +5 -1
  118. package/dist/src/entities/foreign/namespace.d.ts +3 -0
  119. package/dist/src/entities/forms/form.d.ts +17 -2
  120. package/dist/src/entities/forms/namespace.d.ts +5 -1
  121. package/dist/src/entities/github-pull-requests/namespace.d.ts +5 -1
  122. package/dist/src/entities/harnesses/harness.d.ts +9 -0
  123. package/dist/src/entities/harnesses/namespace.d.ts +5 -1
  124. package/dist/src/entities/images/image.d.ts +77 -0
  125. package/dist/src/entities/images/namespace.d.ts +48 -0
  126. package/dist/src/entities/images/namespace.test.d.ts +1 -0
  127. package/dist/src/entities/initiatives/initiative.d.ts +12 -1
  128. package/dist/src/entities/initiatives/namespace.d.ts +15 -2
  129. package/dist/src/entities/me/namespace.d.ts +43 -0
  130. package/dist/src/entities/meetings/meeting.d.ts +5 -0
  131. package/dist/src/entities/meetings/namespace.d.ts +5 -1
  132. package/dist/src/entities/messages/thread.d.ts +1 -1
  133. package/dist/src/entities/notifications/namespace.d.ts +3 -0
  134. package/dist/src/entities/pins/namespace.d.ts +5 -1
  135. package/dist/src/entities/projects/namespace.d.ts +4 -1
  136. package/dist/src/entities/projects/project.d.ts +9 -1
  137. package/dist/src/entities/properties/namespace.d.ts +2 -0
  138. package/dist/src/entities/referrals/namespace.d.ts +33 -0
  139. package/dist/src/entities/routines/namespace.d.ts +42 -2
  140. package/dist/src/entities/routines/routine.d.ts +84 -5
  141. package/dist/src/entities/search/namespace.d.ts +65 -0
  142. package/dist/src/entities/{search.d.ts → search/options.d.ts} +8 -2
  143. package/dist/src/entities/search/types.d.ts +90 -0
  144. package/dist/src/entities/sharing/access.d.ts +14 -0
  145. package/dist/src/entities/tasks/namespace.d.ts +42 -3
  146. package/dist/src/entities/tasks/task.d.ts +47 -6
  147. package/dist/src/entities/teams/invite.d.ts +30 -0
  148. package/dist/src/entities/teams/namespace.d.ts +3 -0
  149. package/dist/src/entities/teams/team.d.ts +37 -0
  150. package/dist/src/entities/unfurls/namespace.d.ts +5 -1
  151. package/dist/src/entities/users/namespace.d.ts +9 -0
  152. package/dist/src/entities/users/user.d.ts +8 -0
  153. package/dist/src/entities/web/namespace.d.ts +61 -0
  154. package/dist/src/entities/web/namespace.test.d.ts +1 -0
  155. package/dist/src/entities/webhooks/namespace.d.ts +2 -0
  156. package/dist/src/entities/whatsapp/account.d.ts +20 -0
  157. package/dist/src/entities/whatsapp/chat.d.ts +54 -0
  158. package/dist/src/entities/whatsapp/namespace.d.ts +23 -0
  159. package/dist/src/entities/workspace/items.d.ts +7 -0
  160. package/dist/src/entities/workspace/namespace.d.ts +14 -9
  161. package/dist/src/entities/workspace/query.d.ts +23 -0
  162. package/dist/src/entities/workspace/types.d.ts +6 -3
  163. package/dist/src/events/hydrate/agentSession.d.ts +1 -1
  164. package/dist/src/events/hydrate/call.d.ts +101 -0
  165. package/dist/src/events/hydrate/channel.d.ts +8 -1
  166. package/dist/src/events/hydrate/document.d.ts +1 -1
  167. package/dist/src/events/hydrate/message.d.ts +1 -1
  168. package/dist/src/events/types.d.ts +2 -1
  169. package/dist/src/macro.d.ts +73 -4
  170. package/dist/src/macro.js +8235 -3701
  171. package/dist/src/mentions.d.ts +6 -1
  172. package/dist/src/utils/activity.d.ts +23 -2
  173. package/dist/src/utils/index.d.ts +1 -1
  174. package/dist/src/utils/unwrap.d.ts +27 -2
  175. package/package.json +2 -2
@@ -2,10 +2,16 @@ import type { ActivityType, ChannelType, GetChannelAttachmentsResponses, GetChan
2
2
  import { type RichMessage } from '../../mentions';
3
3
  import type { MacroClient } from '../../utils/client';
4
4
  import { AgentConversation } from '../agent-sessions/conversation';
5
+ import { Bot } from '../bots/bot';
6
+ import { CallRecord } from '../calls/call-record';
7
+ import { CallConnection, type JoinOptions } from '../calls/connection';
8
+ import type { Document } from '../documents/document';
5
9
  import { PropertiedEntity } from '../entity';
10
+ import type { StaticImage } from '../images/image';
6
11
  import { MessageThread, type TimelineOptions } from '../messages/thread';
7
12
  import type { Team } from '../teams/team';
8
13
  import type { User } from '../users/user';
14
+ import { ChannelAccessRequest } from './access-request';
9
15
  import { ChannelActivity } from './activity';
10
16
  import { Message } from './message';
11
17
  import type { ChannelPicture } from './picture';
@@ -19,6 +25,10 @@ export type ChannelAttachment = GetChannelAttachmentsResponses[200]['items'][num
19
25
  * A channel.
20
26
  */
21
27
  export declare class Channel extends PropertiedEntity<ChannelDetail> {
28
+ /** Start or join this channel's call, ringing members if a new call starts. */
29
+ startCall(opts?: JoinOptions): Promise<CallConnection>;
30
+ /** Check the current call without creating one; undefined means no call. */
31
+ activeCall(): Promise<CallRecord | undefined>;
22
32
  /** Record a view or interaction in this channel. */
23
33
  recordActivity(type: ActivityType): Promise<ChannelActivity>;
24
34
  /** Set an uploaded profile picture, or clear it. */
@@ -74,12 +84,24 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
74
84
  readonly type: () => Promise<ChannelType>;
75
85
  /**
76
86
  * Post a message. Plain text, or a rich body composed with `msg`.
87
+ * `images` attaches static images, such as one from
88
+ * `macro.images.generate()`, below the text; `documents` attaches Macro
89
+ * documents as file chips, such as a file from `macro.documents.upload()`.
77
90
  *
78
91
  * Works with a channel webhook token as well as a normal one — see
79
92
  * {@link postToChannel} for which endpoint that picks and what it costs.
93
+ * The webhook endpoint takes no attachments.
94
+ *
95
+ * @example Share a generated CSV.
96
+ * ```js
97
+ * const file = await macro.documents.upload({ name: 'q3.csv', content: csv });
98
+ * await channel.send('Q3 numbers attached.', { documents: [file] });
99
+ * ```
80
100
  */
81
101
  send(body: string | RichMessage, opts?: {
82
102
  thread?: Thread;
103
+ images?: StaticImage[];
104
+ documents?: Document[];
83
105
  }): Promise<Message>;
84
106
  /** Root messages in this channel, most recent first, auto-paginated. */
85
107
  messages(opts?: {
@@ -103,10 +125,28 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
103
125
  join(): Promise<void>;
104
126
  /** A reusable code that lets a user join this channel. */
105
127
  joinCode(): Promise<string>;
128
+ /**
129
+ * Read the current user's join request, eligibility, and retry time.
130
+ * Works without channel access. Denial or withdrawal may delay retries.
131
+ */
132
+ myAccessRequest(): Promise<{
133
+ request?: ChannelAccessRequest;
134
+ canRequest: boolean;
135
+ retryAfter?: string;
136
+ }>;
137
+ /**
138
+ * Ask to join a private or team channel.
139
+ * Repeated calls return the pending request.
140
+ */
141
+ requestAccess(): Promise<ChannelAccessRequest>;
142
+ /** Withdraw the current user's pending join request. */
143
+ cancelAccessRequest(): Promise<void>;
106
144
  /** Leave the channel as the current user. */
107
145
  leave(): Promise<void>;
108
146
  /** The channel's members, with their roles and join times. */
109
147
  participants(): Promise<ChannelParticipant[]>;
148
+ /** Bots that can post to the channel. */
149
+ bots(): Promise<Bot[]>;
110
150
  /** Add users to the channel. */
111
151
  addParticipants(users: User[]): Promise<void>;
112
152
  /** Remove users from the channel. */
@@ -123,7 +163,13 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
123
163
  }): AsyncGenerator<ChannelAttachment>;
124
164
  /** The channel's URL in the Macro web app. */
125
165
  webUrl(): string;
166
+ /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
167
+ toJSON(): {
168
+ url: string;
169
+ id: string;
170
+ detail?: import("../../../generated/storage").ApiChannelDetail | undefined;
171
+ };
126
172
  /** Search channels by content, most relevant first, auto-paginated. */
127
- static search: (client: MacroClient, query: string, searchOpts?: import("../search").SearchOpts) => AsyncGenerator<Channel, any, any>;
173
+ static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<Channel, any, any>;
128
174
  }
129
175
  export {};
@@ -1,11 +1,23 @@
1
1
  import type { ChannelType } from '../../../generated/storage/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
- import type { SearchOpts } from '../search';
3
+ import type { SearchOpts } from '../search/options';
4
4
  import type { Team } from '../teams/team';
5
5
  import type { User } from '../users/user';
6
6
  import { ChannelActivity } from './activity';
7
7
  import { Channel } from './channel';
8
8
  import { ChannelLabelsNamespace } from './labels';
9
+ /**
10
+ * @routing Use when reading or sending channel and direct messages, posting a poll, reacting or managing members; not email, or WhatsApp and other external chats (`macro.externalChats`).
11
+ *
12
+ * @agent
13
+ * ## Polls
14
+ *
15
+ * A form for a channel is a poll: one required single- or multi-select question (`widget: "choice"`, or `"checkboxes"` for several answers), `status: "open"`, `tallyVisible: true`, and `channelGrants: []`. Post it as one message with its live card on its own line:
16
+ *
17
+ * `<m-document-card>{"documentId":"{form_id}","documentName":"{question}","blockName":"form","previewData":{"poll":{"optionCount":2}}}</m-document-card>`
18
+ *
19
+ * That message is the poll, and the card shares it with the channel. Never add a form chip, `/respond` link, `form:` link, or a second copy.
20
+ */
9
21
  export declare class ChannelNamespace {
10
22
  private readonly client;
11
23
  /** Recent channel activity, with channel and user handles. */
@@ -26,11 +38,15 @@ export declare class ChannelNamespace {
26
38
  /** Team, for team channels. */
27
39
  team?: Team;
28
40
  }): Promise<Channel>;
29
- /** All channels the authenticated user is a member of. */
30
- list(): Promise<Channel[]>;
31
41
  /**
32
- * Search channels by name (client-side fuzzy filter on the full channel list)
33
- * or by content (server-side unified search).
42
+ * Every channel the authenticated user is a member of, auto-paginated.
43
+ * Iterate with `for await`; collect with `Array.fromAsync`.
44
+ */
45
+ list(): AsyncGenerator<Channel>;
46
+ /**
47
+ * Search channels by name (case-insensitive substring match over every
48
+ * channel the user is a member of) or by content (server-side unified search).
34
49
  */
35
50
  search(query: string, opts?: SearchOpts): AsyncGenerator<Channel>;
51
+ private records;
36
52
  }
@@ -0,0 +1 @@
1
+ export {};
@@ -1,7 +1,16 @@
1
1
  import type { RichMessage } from '../../mentions';
2
2
  import type { MacroClient } from '../../utils/client';
3
+ import type { Document } from '../documents/document';
4
+ import type { StaticImage } from '../images/image';
3
5
  import type { Channel } from './channel';
4
6
  import type { Thread } from './thread';
7
+ /** What a posted message carries below its text. */
8
+ export type MessageAttachments = {
9
+ /** Static images, shown inline. */
10
+ images?: StaticImage[];
11
+ /** Macro documents, shown as file chips. */
12
+ documents?: Document[];
13
+ };
5
14
  /**
6
15
  * Post a message using the endpoint supported by the caller's credentials.
7
16
  *
@@ -10,11 +19,13 @@ import type { Thread } from './thread';
10
19
  * through channel membership. The bot owner is read from `GET /bots/me` and
11
20
  * cached by the client.
12
21
  *
13
- * The webhook endpoint supports content only. Mentions in `<m-*>` tags still
14
- * work, but threads and attachments are not supported.
22
+ * The webhook endpoint takes content only: the `mentions` list, threads and
23
+ * attachments are dropped. `<m-*>` mention tags in the content still render and
24
+ * notify, because the server extracts a bot's mentions from its content. A
25
+ * user-owned bot gets the full API by acting as its owner with `requestedAs`.
15
26
  *
16
27
  * Posting to a `Thread` puts the message in that thread; to a `Channel`, at the
17
28
  * channel root. One target rather than a channel plus a thread id, so the two
18
29
  * can't disagree.
19
30
  */
20
- export declare function postToChannel(client: MacroClient, target: Channel | Thread, body: RichMessage): Promise<string>;
31
+ export declare function postToChannel(client: MacroClient, target: Channel | Thread, body: RichMessage, { images, documents }?: MessageAttachments): Promise<string>;
@@ -1,5 +1,7 @@
1
1
  import { type RichMessage } from '../../mentions';
2
2
  import type { MacroClient } from '../../utils/client';
3
+ import type { Document } from '../documents/document';
4
+ import type { StaticImage } from '../images/image';
3
5
  import { Channel } from './channel';
4
6
  import { Message } from './message';
5
7
  /**
@@ -29,7 +31,14 @@ export declare class Thread {
29
31
  * Post a reply in this thread.
30
32
  *
31
33
  * @param body - Plain text, or a rich body composed with {@link msg}.
34
+ * @param opts.images - Static images to attach, such as one from
35
+ * `macro.images.generate()`.
36
+ * @param opts.documents - Macro documents to attach as file chips, such as
37
+ * a file from `macro.documents.upload()`.
32
38
  * @returns The created reply.
33
39
  */
34
- reply(body: string | RichMessage): Promise<Message>;
40
+ reply(body: string | RichMessage, opts?: {
41
+ images?: StaticImage[];
42
+ documents?: Document[];
43
+ }): Promise<Message>;
35
44
  }
@@ -58,8 +58,14 @@ export declare class Chat extends PropertiedEntity<ChatDetail> implements Mentio
58
58
  history(): Promise<ChatHistory>;
59
59
  /** The chat's URL in the Macro web app. */
60
60
  webUrl(): string;
61
+ /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
62
+ toJSON(): {
63
+ url: string;
64
+ id: string;
65
+ detail?: import("../../../generated/cognition").ChatResponse | undefined;
66
+ };
61
67
  /** Search chats by name and content, most relevant first, auto-paginated. */
62
- static search: (client: MacroClient, query: string, searchOpts?: import("../search").SearchOpts) => AsyncGenerator<Chat, any, any>;
68
+ static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<Chat, any, any>;
63
69
  toMention(): MentionPart;
64
70
  }
65
71
  export {};
@@ -1,14 +1,27 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
2
  import type { Project } from '../projects/project';
3
- import type { SearchOpts } from '../search';
3
+ import type { SearchOpts } from '../search/options';
4
4
  import { Chat } from './chat';
5
+ /**
6
+ * The user's AI chats: earlier conversations with Macro's assistant, each
7
+ * with its message history. Find one with {@link ChatNamespace.search},
8
+ * `macro.search.all(query, {types: ['chat']})` or
9
+ * `macro.workspace.list({includeTypes: ['ai_chat']})`, then read it with
10
+ * `chat.history()`. Agent work and coding sessions are agent sessions, not
11
+ * chats.
12
+ *
13
+ * @routing Use when reading or continuing one of the user's AI chats with Macro's assistant; not agent sessions or channels.
14
+ */
5
15
  export declare class ChatNamespace {
6
16
  private readonly client;
7
17
  constructor(client: MacroClient);
18
+ /** A handle to an AI chat by id; read its messages with `history()`. */
8
19
  byId(id: string): Chat;
20
+ /** Create an empty AI chat, optionally named and in a project. */
9
21
  create(opts?: {
10
22
  name?: string;
11
23
  project?: Project;
12
24
  }): Promise<Chat>;
25
+ /** Search AI chats by name and content, most relevant first, auto-paginated. */
13
26
  search(query: string, opts?: SearchOpts): AsyncGenerator<Chat>;
14
27
  }
@@ -0,0 +1,107 @@
1
+ import type { ConnectedAppKind, ConnectedApp as ConnectedAppRecord, ConnectedTool as ConnectedToolRecord } from '../../../generated/agent-harness/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import type { CodeExecution } from '../agent-sessions/code-execution';
4
+ export type { ConnectedAppKind };
5
+ /** A connected tool's answer, MCP's `CallToolResult`. */
6
+ export type ConnectedToolResult = {
7
+ /** The tool failed or could not run; `content` says why. */
8
+ isError: boolean;
9
+ /** MCP content blocks, e.g. `{type: 'text', text}`. */
10
+ content: Array<Record<string, unknown>>;
11
+ /** Structured output, for tools that declare an output schema. */
12
+ structuredContent?: Record<string, unknown>;
13
+ };
14
+ /**
15
+ * An app the session's agent was given: one the user connected through
16
+ * Macro Connect (Slack, Linear, GitHub, Notion, Gmail, ...) or a custom MCP
17
+ * server they added. Read its tools, then call one.
18
+ */
19
+ export declare class ConnectedApp {
20
+ private readonly client;
21
+ /** The running execution this app is reached through. */
22
+ readonly execution: CodeExecution;
23
+ /** `app` for a connected app, `custom` for a custom MCP server. */
24
+ readonly kind: ConnectedAppKind;
25
+ /** The app's slug, e.g. `slack`, or the custom server's key. */
26
+ readonly key: string;
27
+ /** Display name, e.g. `Slack`. */
28
+ readonly name: string;
29
+ private constructor();
30
+ /** The apps `execution`'s session agent was given. */
31
+ static list(client: MacroClient, execution: CodeExecution): Promise<ConnectedApp[]>;
32
+ /** @internal A handle for an app record the harness answered. */
33
+ static fromRecord(client: MacroClient, execution: CodeExecution, record: ConnectedAppRecord): ConnectedApp;
34
+ /**
35
+ * Find tools across every app the execution's agent was given, by
36
+ * keywords matched against tool names and descriptions, best first (at
37
+ * most 20). `unsearched` lists apps whose tools could not be read.
38
+ */
39
+ static searchTools(client: MacroClient, execution: CodeExecution, query: string): Promise<{
40
+ matches: ConnectedTool[];
41
+ unsearched: ConnectedApp[];
42
+ }>;
43
+ /**
44
+ * The tools this app serves, with each one's description and argument
45
+ * schema. Read a tool's `inputSchema` before calling it.
46
+ */
47
+ tools(): Promise<ConnectedTool[]>;
48
+ /** @internal The harness route that names this app. */
49
+ path(): {
50
+ session_id: string;
51
+ execution_id: string;
52
+ kind: ConnectedAppKind;
53
+ key: string;
54
+ };
55
+ /** Serialize identity only. */
56
+ toJSON(): {
57
+ kind: ConnectedAppKind;
58
+ key: string;
59
+ name: string;
60
+ };
61
+ }
62
+ /** One tool a connected app serves. */
63
+ export declare class ConnectedTool {
64
+ private readonly client;
65
+ /** The app serving this tool. */
66
+ readonly app: ConnectedApp;
67
+ /** The tool's name on its server. */
68
+ readonly name: string;
69
+ /** What the server says the tool does. */
70
+ readonly description: string | undefined;
71
+ /** JSON Schema for the tool's arguments. */
72
+ readonly inputSchema: Record<string, unknown>;
73
+ /** @internal */
74
+ constructor(client: MacroClient,
75
+ /** The app serving this tool. */
76
+ app: ConnectedApp,
77
+ /** The tool's name on its server. */
78
+ name: string,
79
+ /** What the server says the tool does. */
80
+ description: string | undefined,
81
+ /** JSON Schema for the tool's arguments. */
82
+ inputSchema: Record<string, unknown>);
83
+ /** @internal A handle for a tool record the harness answered. */
84
+ static fromRecord(client: MacroClient, app: ConnectedApp, record: ConnectedToolRecord): ConnectedTool;
85
+ /**
86
+ * Call the tool as the execution's account, with arguments matching
87
+ * `inputSchema`. Writes take effect immediately, in the user's real
88
+ * account. In a turn someone other than the session's owner prompted, a
89
+ * call as the owner waits for the owner to approve it, and a declined or
90
+ * unanswered call comes back with `isError`. Check `isError` on the result: an app that is not connected,
91
+ * or whose connection expired, answers with `isError` and text telling you
92
+ * what to say to the user, including any connect markup to put in your
93
+ * reply verbatim.
94
+ */
95
+ call(args?: Record<string, unknown>): Promise<ConnectedToolResult>;
96
+ /** Serialize the tool's description, not its client. */
97
+ toJSON(): {
98
+ app: {
99
+ kind: ConnectedAppKind;
100
+ key: string;
101
+ name: string;
102
+ };
103
+ name: string;
104
+ description: string | undefined;
105
+ inputSchema: Record<string, unknown>;
106
+ };
107
+ }
@@ -0,0 +1,56 @@
1
+ import type { MacroClient } from '../../utils/client';
2
+ import type { CodeExecution } from '../agent-sessions/code-execution';
3
+ /** One action a connectable app advertises; not callable until connected. */
4
+ export type ConnectorAction = {
5
+ /** The upstream tool name. */
6
+ name: string;
7
+ /** What the action supports. */
8
+ description: string;
9
+ };
10
+ /** A connector's verified capabilities and the account's connection status. */
11
+ export type ConnectorInspection = {
12
+ /** Whether the execution's account has the app connected and enabled. */
13
+ connected: boolean;
14
+ /** The actions the app advertises. */
15
+ actions: ConnectorAction[];
16
+ /** True when some advertised actions were left out. */
17
+ actionsTruncated: boolean;
18
+ /**
19
+ * Markup that gives the user a button to connect the app, present only for
20
+ * an unconnected app with advertised actions. Put it in your reply
21
+ * verbatim, and only when one of `actions` supports the user's task.
22
+ */
23
+ connectMarkup: string | undefined;
24
+ };
25
+ /**
26
+ * An app the user could connect, found in the connector catalog. Its
27
+ * description is the catalog's; inspect it to see what it can actually do.
28
+ */
29
+ export declare class Connector {
30
+ private readonly client;
31
+ /** The running execution the catalog is read through. */
32
+ readonly execution: CodeExecution;
33
+ /** The app's catalog slug, e.g. `linear`. */
34
+ readonly slug: string;
35
+ /** Display name, e.g. `Linear`. */
36
+ readonly name: string;
37
+ /** The catalog's description. */
38
+ readonly description: string | undefined;
39
+ private constructor();
40
+ /** Search the connector catalog by app name. */
41
+ static search(client: MacroClient, execution: CodeExecution, appName: string): Promise<{
42
+ connectors: Connector[];
43
+ moreResults: boolean;
44
+ }>;
45
+ /**
46
+ * Read the actions this app advertises and whether the execution's account
47
+ * has it connected. Inspection never calls the app or changes a connection.
48
+ */
49
+ inspect(): Promise<ConnectorInspection>;
50
+ /** Serialize the catalog entry, not its client. */
51
+ toJSON(): {
52
+ slug: string;
53
+ name: string;
54
+ description: string | undefined;
55
+ };
56
+ }
@@ -0,0 +1,74 @@
1
+ import type { ConnectMcpServerResponse } from '../../../generated/agent-harness/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import type { CodeExecution } from '../agent-sessions/code-execution';
4
+ import { ConnectedApp, type ConnectedTool } from './connected-app';
5
+ import { Connector } from './connector';
6
+ export type { ConnectMcpServerResponse };
7
+ /**
8
+ * The apps the user connected for their agents (Slack, Linear, GitHub,
9
+ * Notion, Gmail and others through Macro Connect) and the custom MCP servers
10
+ * they added, reached from a session's code execution.
11
+ *
12
+ * @routing Use when the work needs a connected third-party app or MCP server (Slack, Linear, GitHub, Notion, Jira, Google Sheets, a custom MCP server): reading or changing data in it, or calling one of its tools; not Macro's own documents, email, channels or calendar.
13
+ *
14
+ * @agent
15
+ * ## Connected apps
16
+ *
17
+ * Connected apps are reached only from an agent session's ExecuteCode program: pass the `execution` that `main` receives. `macro.connectedApps.list(execution)` returns the apps this agent was given (every app the user connected, or the agent's own selection); an app missing from it is not connected for this agent. Find a tool across every app with `macro.connectedApps.searchTools(execution, 'linear issue')`, or read one app's tools with `app.tools()`; pick one by name and description, read its `inputSchema`, then `tool.call(args)`.
18
+ *
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
+ *
21
+ * 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
+ *
23
+ * ```javascript
24
+ * export async function main({macro, execution}) {
25
+ * const apps = await macro.connectedApps.list(execution);
26
+ * const linear = apps.find((app) => app.key === 'linear');
27
+ * if (!linear) return {data: {error: 'Linear is not connected', available: apps.map((app) => app.name)}};
28
+ * const tools = await linear.tools();
29
+ * const search = tools.find((tool) => tool.name === 'list_issues');
30
+ * const result = await search.call({query: 'login bug', limit: 5});
31
+ * return {data: result.isError ? {error: result.content} : result.structuredContent ?? result.content};
32
+ * }
33
+ * ```
34
+ */
35
+ export declare class ConnectedAppNamespace {
36
+ private readonly client;
37
+ constructor(client: MacroClient);
38
+ /**
39
+ * List the apps a running code execution's session agent may use; pass the
40
+ * `execution` given to `main`. Fails outside a running execution of the
41
+ * session's current turn.
42
+ */
43
+ list(execution: CodeExecution): Promise<ConnectedApp[]>;
44
+ /**
45
+ * Find tools across every connected app the execution's agent was given,
46
+ * by keywords matched against tool names and descriptions (e.g. `linear
47
+ * issue`), best first, at most 20. Apps whose tools could not be read come
48
+ * back in `unsearched`, not as an error.
49
+ */
50
+ searchTools(execution: CodeExecution, query: string): Promise<{
51
+ matches: ConnectedTool[];
52
+ unsearched: ConnectedApp[];
53
+ }>;
54
+ /**
55
+ * Search the catalog of apps the user could connect, by app name (e.g.
56
+ * `Linear`, not a task description). Inspect a result before recommending
57
+ * it: its description alone does not show what it can do.
58
+ */
59
+ discover(execution: CodeExecution, appName: string): Promise<{
60
+ connectors: Connector[];
61
+ moreResults: boolean;
62
+ }>;
63
+ /**
64
+ * Add a remote MCP server to the execution account's connections by its
65
+ * URL: only one the user gave you, or an official URL you are sure of;
66
+ * never guess. Most servers then need the user to sign in under
67
+ * Settings → Connections, which the result's `summary` says. A URL the
68
+ * user already has is left as it is.
69
+ */
70
+ addServer(execution: CodeExecution, server: {
71
+ url: string;
72
+ serverName: string;
73
+ }): Promise<ConnectMcpServerResponse>;
74
+ }
@@ -62,7 +62,7 @@ export declare class Company extends PropertiedEntity<CompanyDetail> {
62
62
  /** The contacts attached to this company (hidden ones filtered for non-admins). */
63
63
  contacts(): Promise<Contact[]>;
64
64
  /** Search CRM companies by name/domain, most relevant first, auto-paginated. */
65
- static search: (client: MacroClient, query: string, searchOpts?: import("../search").SearchOpts) => AsyncGenerator<Company, any, any>;
65
+ static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<Company, any, any>;
66
66
  /**
67
67
  * Hide the company from CRM listings: disables email sync and soft-hides
68
68
  * its contacts. Reversible with {@link unhide}.
@@ -78,9 +78,13 @@ export declare class Company extends PropertiedEntity<CompanyDetail> {
78
78
  setEmailSync(enabled: boolean): Promise<void>;
79
79
  /** Rename the company for the caller's current team. */
80
80
  rename(name: string): Promise<void>;
81
- /** Create a contact under this company. */
81
+ /**
82
+ * Create a contact under this company. The email is optional and need not
83
+ * match the company's domains, so personal addresses work too; omitting it
84
+ * adds the contact by name alone.
85
+ */
82
86
  createContact(opts: {
83
- email: string;
87
+ email?: string;
84
88
  name: string;
85
89
  }): Promise<Contact>;
86
90
  /** The CRM record this company's discussions hang off. */
@@ -40,10 +40,10 @@ export declare class Contact extends FavoritableEntity<ContactDetail> {
40
40
  static from(client: MacroClient, data: ContactDetail): Contact;
41
41
  /** The contact's display name, if one has been observed. */
42
42
  readonly name: () => Promise<string | undefined>;
43
- /** The contact's email address. */
44
- readonly email: () => Promise<string>;
45
- /** The CRM company this contact belongs to. */
46
- readonly company: () => Promise<Company>;
43
+ /** The contact's email address; absent for a contact added by name alone. */
44
+ readonly email: () => Promise<string | undefined>;
45
+ /** The CRM company this contact belongs to, if it has one. */
46
+ readonly company: () => Promise<Company | undefined>;
47
47
  /** Whether the contact is hidden from CRM listings. */
48
48
  readonly hidden: () => Promise<boolean>;
49
49
  /** When the contact was first created in the CRM. */
@@ -1,8 +1,18 @@
1
- import type { CreateCrmCompanyRequest, CrmStagesResponse, CrmTeamSettingsResponse, ReplaceCrmStagesRequest, UpdateCrmTeamSettingsRequest } from '../../../generated/storage/types.gen';
1
+ import type { CreateCrmCompanyRequest, CreateCrmTeamContactRequest, CrmStagesResponse, CrmTeamSettingsResponse, ReplaceCrmStagesRequest, UpdateCrmTeamSettingsRequest } from '../../../generated/storage/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import { Company } from './company';
4
4
  import { Contact } from './contact';
5
5
  import { PipelineNamespace } from './pipelines';
6
+ /**
7
+ * @routing Use when working with CRM deals, pipelines, stages, companies or contacts; not generic databases, and not a search that merely names a company.
8
+ *
9
+ * @agent
10
+ * ## How CRM pipelines work
11
+ *
12
+ * A pipeline is a board of deals. Each entry tracks one CRM company or contact and has its own fields: usually Stage, Owner and Revenue, plus any the team added. "Deal", "opportunity", "lead", "the pipeline", "move Acme to Negotiation" and "who's in Demo" all refer to pipeline entries. A pipeline is not a Macro database: work with it through the CRM pipeline methods, never database queries or SQL.
13
+ *
14
+ * A company also has its own Stage, Owner and Revenue properties on its CRM page. They are separate from every pipeline and not kept in sync with it. When the user has pipelines, deal and stage requests mean pipeline entries; change the company's own properties only when the user asks for those properties specifically.
15
+ */
6
16
  export declare class CrmNamespace {
7
17
  private readonly client;
8
18
  /** Pipelines, their records and sharing settings. */
@@ -26,6 +36,29 @@ export declare class CrmNamespace {
26
36
  }): Promise<Contact[]>;
27
37
  /** Create a CRM company for the caller's current team. */
28
38
  createCompany(opts: CreateCrmCompanyRequest): Promise<Company>;
39
+ /**
40
+ * Create a contact without a company for the caller's current team. The
41
+ * email is optional and may be at any domain. To add someone to a company,
42
+ * use {@link Company.createContact}.
43
+ */
44
+ createContact(opts: CreateCrmTeamContactRequest): Promise<Contact>;
45
+ /** The domains the caller's current team keeps out of email sync. */
46
+ blockedDomains(): Promise<string[]>;
47
+ /**
48
+ * Block a domain (like `acme.com`): email sync skips it, and the company
49
+ * that owns it, that company's contacts, and contacts without a company at
50
+ * the domain are hidden. A contact attached to another company follows that
51
+ * company's domains. Requires a team admin or owner.
52
+ */
53
+ blockDomain(domain: string): Promise<void>;
54
+ /**
55
+ * Unblock a domain: email sync resumes for addresses the team's
56
+ * personal-email and generic-provider filters allow. Contacts without a
57
+ * company at this domain are shown again. Its company and attached contacts
58
+ * stay hidden until the company's last blocked domain is removed, then are
59
+ * shown even if hidden by hand before blocking. Requires a team admin or owner.
60
+ */
61
+ unblockDomain(domain: string): Promise<void>;
29
62
  /** The caller's current team's CRM settings. */
30
63
  settings(): Promise<CrmTeamSettingsResponse>;
31
64
  /** Partially update the caller's current team's CRM settings. */