@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
@@ -1,4 +1,4 @@
1
- import type { ActivityType, ChannelType, GetChannelAttachmentsResponses, GetChannelParticipantsResponses, GetChannelResponses, MessageCursor } from '../../../generated/storage/types.gen';
1
+ import type { ActivityType, ApiChannelWithLatest, ChannelType, GetChannelAttachmentsResponses, GetChannelParticipantsResponses, GetChannelResponses, MessageCursor } from '../../../generated/storage/types.gen';
2
2
  import { type RichMessage } from '../../mentions';
3
3
  import type { MacroClient } from '../../utils/client';
4
4
  import { AgentConversation } from '../agent-sessions/conversation';
@@ -25,17 +25,44 @@ export type ChannelAttachment = GetChannelAttachmentsResponses[200]['items'][num
25
25
  * A channel.
26
26
  */
27
27
  export declare class Channel extends PropertiedEntity<ChannelDetail> {
28
- /** Start or join this channel's call, ringing members if a new call starts. */
28
+ /**
29
+ * Start or join this channel's call, ringing members if a new call starts;
30
+ * refused to an agent's program (ExecuteCode, a routine).
31
+ *
32
+ * @write
33
+ * @mcp-exclude Returns a live call room credential; MCP calls carry JSON only.
34
+ */
29
35
  startCall(opts?: JoinOptions): Promise<CallConnection>;
30
- /** Check the current call without creating one; undefined means no call. */
36
+ /**
37
+ * Check the current call without creating one; undefined means no call.
38
+ *
39
+ * @readonly
40
+ */
31
41
  activeCall(): Promise<CallRecord | undefined>;
32
- /** Record a view or interaction in this channel. */
42
+ /**
43
+ * Record a view or interaction in this channel.
44
+ *
45
+ * @write
46
+ */
33
47
  recordActivity(type: ActivityType): Promise<ChannelActivity>;
34
- /** Set an uploaded profile picture, or clear it. */
48
+ /**
49
+ * Set an uploaded profile picture, or clear it.
50
+ *
51
+ * @write
52
+ * @idempotent
53
+ */
35
54
  setPicture(picture?: ChannelPicture): Promise<void>;
36
- /** A shared message thread scoped to this resource. */
55
+ /**
56
+ * A shared message thread scoped to this resource.
57
+ *
58
+ * @readonly
59
+ */
37
60
  messageThreadById(id: string): MessageThread;
38
- /** A mixed message and activity timeline page. */
61
+ /**
62
+ * A mixed message and activity timeline page.
63
+ *
64
+ * @readonly
65
+ */
39
66
  timelinePage(selection?: TimelineOptions<Message>): Promise<{
40
67
  entries: ({
41
68
  type: "activity";
@@ -56,7 +83,11 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
56
83
  nextCursor: MessageCursor | undefined;
57
84
  previousCursor: MessageCursor | undefined;
58
85
  }>;
59
- /** Conversations maintained by agents in this channel. */
86
+ /**
87
+ * Conversations maintained by agents in this channel.
88
+ *
89
+ * @readonly
90
+ */
60
91
  agentConversations(): Promise<AgentConversation[]>;
61
92
  /** Favorites identify channels as `channel`. */
62
93
  readonly entityType = "channel";
@@ -65,9 +96,15 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
65
96
  protected fetch(): Promise<ChannelDetail>;
66
97
  /** A handle to a channel by id. Details load on first access. */
67
98
  static byId(client: MacroClient, id: string): Channel;
99
+ /**
100
+ * A handle seeded from a `GET /comms/channels` record. The listed name is
101
+ * the stored one, which the detail shows as is except on direct messages and
102
+ * unnamed private channels; those are named after the members, so they load.
103
+ */
104
+ static fromListing(client: MacroClient, record: ApiChannelWithLatest): Channel;
68
105
  /** Open (creating if needed) the DM channel with a user. */
69
106
  static dm(client: MacroClient, recipient: User): Promise<Channel>;
70
- /** Open (creating if needed) the private group channel with a set of users. */
107
+ /** Open (creating if needed) the group direct message with exactly these people, excluding the caller. */
71
108
  static private(client: MacroClient, recipients: User[]): Promise<Channel>;
72
109
  /** Create a channel. The caller becomes the owner. */
73
110
  static create(client: MacroClient, opts: {
@@ -83,10 +120,13 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
83
120
  /** The channel's type (e.g. `public`, `dm`, `private`). */
84
121
  readonly type: () => Promise<ChannelType>;
85
122
  /**
86
- * Post a message. Plain text, or a rich body composed with `msg`.
123
+ * Post a message; pass `silent: true` for a routine update that should
124
+ * notify nobody. Plain text, or a rich body composed with `msg`.
87
125
  * `images` attaches static images, such as one from
88
126
  * `macro.images.generate()`, below the text; `documents` attaches Macro
89
127
  * documents as file chips, such as a file from `macro.documents.upload()`.
128
+ * `silent` sends no push, email or inbox entry to anyone, mentioned people
129
+ * included; the message still appears in the channel.
90
130
  *
91
131
  * Works with a channel webhook token as well as a normal one — see
92
132
  * {@link postToChannel} for which endpoint that picks and what it costs.
@@ -97,37 +137,78 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
97
137
  * const file = await macro.documents.upload({ name: 'q3.csv', content: csv });
98
138
  * await channel.send('Q3 numbers attached.', { documents: [file] });
99
139
  * ```
140
+ *
141
+ * @example Post a routine status update without notifying anyone.
142
+ * ```js
143
+ * await channel.send('Nightly sync finished: 42 records.', { silent: true });
144
+ * ```
145
+ *
146
+ * @write
100
147
  */
101
148
  send(body: string | RichMessage, opts?: {
102
149
  thread?: Thread;
103
150
  images?: StaticImage[];
104
151
  documents?: Document[];
152
+ silent?: boolean;
105
153
  }): Promise<Message>;
106
- /** Root messages in this channel, most recent first, auto-paginated. */
154
+ /**
155
+ * Root messages in this channel, most recent first, auto-paginated; `maxItems` caps the total.
156
+ *
157
+ * @readonly
158
+ */
107
159
  messages(opts?: {
108
160
  pageSize?: number;
161
+ maxItems?: number;
109
162
  }): AsyncGenerator<Message>;
110
163
  /**
111
164
  * Root messages created or replied to at or after `after`, most recent
112
- * first, auto-paginated. Use it to catch up after a disconnect.
165
+ * first, auto-paginated; `maxItems` caps the total. Use it to catch up after a disconnect.
166
+ *
167
+ * @readonly
113
168
  */
114
169
  messagesAfter(after: Date | string, opts?: {
115
170
  pageSize?: number;
171
+ maxItems?: number;
116
172
  }): AsyncGenerator<Message>;
117
173
  private timeline;
118
- /** A handle to a message in this channel by id. */
174
+ /**
175
+ * A handle to a message in this channel by id.
176
+ *
177
+ * @readonly
178
+ */
119
179
  message(id: string): Message;
120
- /** Rename the channel. */
180
+ /**
181
+ * Rename the channel.
182
+ *
183
+ * @write
184
+ * @idempotent
185
+ */
121
186
  rename(name: string): Promise<void>;
122
- /** Delete the channel. This is not reversible. */
187
+ /**
188
+ * Delete the channel. This is not reversible.
189
+ *
190
+ * @destructive
191
+ * @idempotent
192
+ */
123
193
  delete(): Promise<void>;
124
- /** Join the channel as the current user. */
194
+ /**
195
+ * Join the channel as the current user.
196
+ *
197
+ * @write
198
+ * @idempotent
199
+ */
125
200
  join(): Promise<void>;
126
- /** A reusable code that lets a user join this channel. */
201
+ /**
202
+ * A reusable code that lets a user join this channel.
203
+ *
204
+ * @readonly
205
+ */
127
206
  joinCode(): Promise<string>;
128
207
  /**
129
208
  * Read the current user's join request, eligibility, and retry time.
130
209
  * Works without channel access. Denial or withdrawal may delay retries.
210
+ *
211
+ * @readonly
131
212
  */
132
213
  myAccessRequest(): Promise<{
133
214
  request?: ChannelAccessRequest;
@@ -137,31 +218,77 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
137
218
  /**
138
219
  * Ask to join a private or team channel.
139
220
  * Repeated calls return the pending request.
221
+ *
222
+ * @write
223
+ * @idempotent
140
224
  */
141
225
  requestAccess(): Promise<ChannelAccessRequest>;
142
- /** Withdraw the current user's pending join request. */
226
+ /**
227
+ * Withdraw the current user's pending join request.
228
+ *
229
+ * @destructive
230
+ * @idempotent
231
+ */
143
232
  cancelAccessRequest(): Promise<void>;
144
- /** Leave the channel as the current user. */
233
+ /**
234
+ * Leave the channel as the current user.
235
+ *
236
+ * @destructive
237
+ * @idempotent
238
+ */
145
239
  leave(): Promise<void>;
146
- /** The channel's members, with their roles and join times. */
240
+ /**
241
+ * The channel's members, with their roles and join times.
242
+ *
243
+ * @readonly
244
+ */
147
245
  participants(): Promise<ChannelParticipant[]>;
148
- /** Bots that can post to the channel. */
246
+ /**
247
+ * Bots that can post to the channel.
248
+ *
249
+ * @readonly
250
+ */
149
251
  bots(): Promise<Bot[]>;
150
- /** Add users to the channel. */
252
+ /**
253
+ * Add users to the channel.
254
+ *
255
+ * @write
256
+ * @idempotent
257
+ */
151
258
  addParticipants(users: User[]): Promise<void>;
152
- /** Remove users from the channel. */
259
+ /**
260
+ * Remove users from the channel.
261
+ *
262
+ * @destructive
263
+ * @idempotent
264
+ */
153
265
  removeParticipants(users: User[]): Promise<void>;
154
- /** Broadcast a typing indicator, optionally scoped to a thread. */
266
+ /**
267
+ * Broadcast a typing indicator, optionally scoped to a thread.
268
+ *
269
+ * @write
270
+ * @idempotent
271
+ */
155
272
  typing(action: 'start' | 'stop', opts?: {
156
273
  thread?: Thread;
157
274
  }): Promise<void>;
158
- /** The attachments posted in this channel, auto-paginated. */
275
+ /**
276
+ * The attachments posted in this channel, auto-paginated; `maxItems` caps the total.
277
+ *
278
+ * @readonly
279
+ */
159
280
  attachments(opts?: {
160
281
  pageSize?: number;
161
282
  /** Filter by type: `static` for images/videos, `dss` for documents. */
162
283
  type?: string;
284
+ maxItems?: number;
163
285
  }): AsyncGenerator<ChannelAttachment>;
164
- /** The channel's URL in the Macro web app. */
286
+ private attachmentPages;
287
+ /**
288
+ * The channel's URL in the Macro web app.
289
+ *
290
+ * @readonly
291
+ */
165
292
  webUrl(): string;
166
293
  /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
167
294
  toJSON(): {
@@ -169,7 +296,7 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
169
296
  id: string;
170
297
  detail?: import("../../../generated/storage").ApiChannelDetail | undefined;
171
298
  };
172
- /** Search channels by content, most relevant first, auto-paginated. */
299
+ /** Search channels by content, most relevant first, auto-paginated; `maxItems` caps the total. */
173
300
  static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<Channel, any, any>;
174
301
  }
175
302
  export {};
@@ -17,23 +17,57 @@ export type { ChannelLabel, ChannelLabelRule, SmartTagPreview };
17
17
  export declare class ChannelLabelsNamespace {
18
18
  private readonly client;
19
19
  constructor(client: MacroClient);
20
- /** Every label in the authenticated user's shared or private scope. */
20
+ /**
21
+ * Every label in the authenticated user's shared or private scope.
22
+ *
23
+ * @readonly
24
+ */
21
25
  list(): Promise<ChannelLabel[]>;
22
26
  /**
23
27
  * Create a label and atomically move `channels` into it. Names are unique
24
28
  * within the team or account, case-insensitively.
29
+ *
30
+ * @write
25
31
  */
26
32
  create(name: string, channels?: Channel[]): Promise<ChannelLabel>;
27
- /** Create a smart tag whose membership follows an attribute rule automatically. */
33
+ /**
34
+ * Create a smart tag whose membership follows an attribute rule automatically.
35
+ *
36
+ * @write
37
+ */
28
38
  createSmartTag(name: string, rule: ChannelLabelRule): Promise<ChannelLabel>;
29
- /** Preview the first matches and total visible count without creating a tag. */
39
+ /**
40
+ * Preview the first matches and total visible count without creating a tag.
41
+ *
42
+ * @readonly
43
+ */
30
44
  previewSmartTag(rule: ChannelLabelRule): Promise<SmartTagPreview>;
31
- /** Update the name and matching rule of an existing smart tag. */
45
+ /**
46
+ * Update the name and matching rule of an existing smart tag.
47
+ *
48
+ * @write
49
+ * @idempotent
50
+ */
32
51
  updateSmartTag(label: ChannelLabel, name: string, rule: ChannelLabelRule): Promise<ChannelLabel>;
33
- /** Rename a label for the whole team. */
52
+ /**
53
+ * Rename a label for the whole team.
54
+ *
55
+ * @write
56
+ * @idempotent
57
+ */
34
58
  rename(label: ChannelLabel, name: string): Promise<ChannelLabel>;
35
- /** Delete a label for the whole team; its channels return to the plain list. */
59
+ /**
60
+ * Delete a label for the whole team; its channels return to the plain list.
61
+ *
62
+ * @destructive
63
+ * @idempotent
64
+ */
36
65
  delete(label: ChannelLabel): Promise<void>;
37
- /** Move a channel into `label`, or out of any label when `label` is `undefined`. */
66
+ /**
67
+ * Move a channel into `label`, or out of any label when `label` is `undefined`.
68
+ *
69
+ * @write
70
+ * @idempotent
71
+ */
38
72
  setLabel(channel: Channel, label: ChannelLabel | undefined): Promise<void>;
39
73
  }
@@ -7,6 +7,41 @@ import { Channel } from './channel';
7
7
  import { Thread } from './thread';
8
8
  /** The API's representation of a message; the same record the document comment API returns. */
9
9
  export type MessageData = MessageRecord;
10
+ /** How much surrounds a message in {@link Message.context}. */
11
+ export interface MessageContextOptions {
12
+ /** Top-level messages before the root; defaults to 3, at most 25. */
13
+ channelBefore?: number;
14
+ /** Top-level messages after the root; defaults to 3, at most 25. */
15
+ channelAfter?: number;
16
+ /** For a reply, replies before it; defaults to 10, at most 50. */
17
+ threadBefore?: number;
18
+ /** For a reply, replies after it; defaults to 10, at most 50. */
19
+ threadAfter?: number;
20
+ }
21
+ /** The replies around a reply, in {@link MessageContext}. */
22
+ export interface ReplyContext {
23
+ /** Replies before the message, oldest first. */
24
+ before: Message[];
25
+ /** Replies after the message, oldest first. */
26
+ after: Message[];
27
+ /** Earlier replies left out. */
28
+ omittedBefore: number;
29
+ /** Later replies left out. */
30
+ omittedAfter: number;
31
+ }
32
+ /** A channel message with the conversation around it. */
33
+ export interface MessageContext {
34
+ /** The message asked about. */
35
+ message: Message;
36
+ /** Its top-level message: the message itself, or the root of the thread it replies in. */
37
+ root: Message;
38
+ /** Top-level messages before `root`, oldest first. */
39
+ before: Message[];
40
+ /** Top-level messages after `root`, oldest first. */
41
+ after: Message[];
42
+ /** For a reply, the replies around it; absent for a top-level message. */
43
+ thread?: ReplyContext;
44
+ }
10
45
  /**
11
46
  * A message in a channel. A thin handle: `id` and `channelId` are known up
12
47
  * front, and record-backed fields (`content`, `author`) load lazily on first
@@ -33,24 +68,86 @@ export declare class Message extends FavoritableEntity<MessageRecord> {
33
68
  readonly editedAt: () => Promise<string | undefined>;
34
69
  /** When the message was last updated. */
35
70
  readonly updatedAt: () => Promise<string>;
36
- /** The user who sent this message. */
71
+ /**
72
+ * The user who sent this message.
73
+ *
74
+ * @readonly
75
+ */
37
76
  author(): Promise<User>;
38
- /** The channel this message is in. */
77
+ /**
78
+ * The message's URL in the Macro web app: its channel, scrolled to it. Pass
79
+ * the message to `macro.ui.open` to show it to the user.
80
+ *
81
+ * @readonly
82
+ */
83
+ webUrl(): string;
84
+ /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
85
+ toJSON(): {
86
+ url: string;
87
+ id: string;
88
+ detail?: MessageRecord | undefined;
89
+ };
90
+ /**
91
+ * The channel this message is in.
92
+ *
93
+ * @readonly
94
+ */
39
95
  channel(): Channel;
40
- /** The thread rooted at this message. */
96
+ /**
97
+ * The thread rooted at this message.
98
+ *
99
+ * @readonly
100
+ */
41
101
  thread(): Thread;
42
- /** Add an emoji reaction to this message. */
102
+ /**
103
+ * The conversation around this message: nearby top-level messages and, when
104
+ * it is a thread reply, its thread's root and the replies around it. Use it
105
+ * to read what a message (from a mention, search hit or notification)
106
+ * answers before acting on it.
107
+ *
108
+ * @readonly
109
+ */
110
+ context(options?: MessageContextOptions): Promise<MessageContext>;
111
+ /**
112
+ * Add an emoji reaction to this message.
113
+ *
114
+ * @write
115
+ * @idempotent
116
+ */
43
117
  react(emoji: string): Promise<this>;
44
- /** Remove one of your emoji reactions from this message. */
118
+ /**
119
+ * Remove one of your emoji reactions from this message.
120
+ *
121
+ * @write
122
+ * @idempotent
123
+ */
45
124
  unreact(emoji: string): Promise<this>;
46
125
  /**
47
126
  * Replace this message's body.
48
127
  *
49
128
  * @param body - Plain text, or a rich body composed with {@link msg}.
129
+ *
130
+ * @destructive
131
+ * @idempotent
50
132
  */
51
133
  edit(body: string | RichMessage): Promise<this>;
52
- /** Delete this message. */
134
+ /**
135
+ * Delete this message.
136
+ *
137
+ * @destructive
138
+ * @idempotent
139
+ */
53
140
  delete(): Promise<void>;
54
- /** Post a reply in this message's thread. */
55
- reply(body: string | RichMessage): Promise<Message>;
141
+ /**
142
+ * Post a reply in this message's thread; pass `silent: true` for a routine
143
+ * update that should notify nobody.
144
+ *
145
+ * @param opts.silent - Send no push, email or inbox entry to anyone,
146
+ * mentioned people included; the reply still appears in the thread.
147
+ *
148
+ * @write
149
+ */
150
+ reply(body: string | RichMessage, opts?: {
151
+ silent?: boolean;
152
+ }): Promise<Message>;
56
153
  }
@@ -0,0 +1 @@
1
+ export {};
@@ -1,4 +1,5 @@
1
1
  import type { ChannelType } from '../../../generated/storage/types.gen';
2
+ import { type IterationOptions } from '../../utils';
2
3
  import type { MacroClient } from '../../utils/client';
3
4
  import type { SearchOpts } from '../search/options';
4
5
  import type { Team } from '../teams/team';
@@ -20,16 +21,37 @@ import { ChannelLabelsNamespace } from './labels';
20
21
  */
21
22
  export declare class ChannelNamespace {
22
23
  private readonly client;
23
- /** Recent channel activity, with channel and user handles. */
24
+ /**
25
+ * Recent channel activity, with channel and user handles.
26
+ *
27
+ * @readonly
28
+ */
24
29
  activity(): Promise<ChannelActivity[]>;
25
30
  /** Team-shared labels that group channels in the Chat sidebar. */
26
31
  readonly labels: ChannelLabelsNamespace;
27
32
  constructor(client: MacroClient);
28
33
  byId(id: string): Channel;
34
+ /**
35
+ * Open (creating if needed) the user's 1:1 direct message with one person.
36
+ * For several people, use {@link private}.
37
+ *
38
+ * @write
39
+ * @idempotent
40
+ */
29
41
  dm(recipient: User): Promise<Channel>;
30
- /** Open (creating if needed) the private group channel with a set of users. */
42
+ /**
43
+ * Open (creating if needed) the group direct message with exactly these
44
+ * people, excluding the user. For one person, use {@link dm}.
45
+ *
46
+ * @write
47
+ * @idempotent
48
+ */
31
49
  private(recipients: User[]): Promise<Channel>;
32
- /** Create a channel. The caller becomes the owner. */
50
+ /**
51
+ * Create a channel. The caller becomes the owner.
52
+ *
53
+ * @write
54
+ */
33
55
  create(opts: {
34
56
  type: ChannelType;
35
57
  name?: string;
@@ -39,13 +61,21 @@ export declare class ChannelNamespace {
39
61
  team?: Team;
40
62
  }): Promise<Channel>;
41
63
  /**
42
- * Every channel the authenticated user is a member of, auto-paginated.
64
+ * Every channel the authenticated user is a member of, auto-paginated; `maxItems` caps the total.
43
65
  * Iterate with `for await`; collect with `Array.fromAsync`.
66
+ *
67
+ * @readonly
44
68
  */
45
- list(): AsyncGenerator<Channel>;
69
+ list(opts?: IterationOptions): AsyncGenerator<Channel>;
70
+ private listed;
46
71
  /**
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).
72
+ * Search the user's channels by name (the default) or by content; `maxItems`
73
+ * caps the total. A name search matches, case-insensitively, channels whose
74
+ * name or other members' names contain every word of `query`; the server runs
75
+ * it, one request per page of matches, newest first. A blank query lists
76
+ * every channel.
77
+ *
78
+ * @readonly
49
79
  */
50
80
  search(query: string, opts?: SearchOpts): AsyncGenerator<Channel>;
51
81
  private records;
@@ -4,12 +4,17 @@ import type { Document } from '../documents/document';
4
4
  import type { StaticImage } from '../images/image';
5
5
  import type { Channel } from './channel';
6
6
  import type { Thread } from './thread';
7
- /** What a posted message carries below its text. */
8
- export type MessageAttachments = {
7
+ /** What a posted message carries below its text, and who hears about it. */
8
+ export type PostOptions = {
9
9
  /** Static images, shown inline. */
10
10
  images?: StaticImage[];
11
11
  /** Macro documents, shown as file chips. */
12
12
  documents?: Document[];
13
+ /**
14
+ * Post without notifying anyone, mentioned people included: no push, email
15
+ * or inbox entry. The message still appears in the channel for everyone.
16
+ */
17
+ silent?: boolean;
13
18
  };
14
19
  /**
15
20
  * Post a message using the endpoint supported by the caller's credentials.
@@ -19,13 +24,14 @@ export type MessageAttachments = {
19
24
  * through channel membership. The bot owner is read from `GET /bots/me` and
20
25
  * cached by the client.
21
26
  *
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`.
27
+ * The webhook endpoint takes content and `silent` only: the `mentions` list,
28
+ * threads and attachments are dropped. `<m-*>` mention tags in the content
29
+ * still render and notify, because the server extracts a bot's mentions from
30
+ * its content. A user-owned bot gets the full API by acting as its owner with
31
+ * `requestedAs`.
26
32
  *
27
33
  * Posting to a `Thread` puts the message in that thread; to a `Channel`, at the
28
34
  * channel root. One target rather than a channel plus a thread id, so the two
29
35
  * can't disagree.
30
36
  */
31
- export declare function postToChannel(client: MacroClient, target: Channel | Thread, body: RichMessage, { images, documents }?: MessageAttachments): Promise<string>;
37
+ export declare function postToChannel(client: MacroClient, target: Channel | Thread, body: RichMessage, { images, documents, silent }?: PostOptions): Promise<string>;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,9 @@
1
+ import type { ChannelShareEntityType } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import type { Channel } from './channel';
4
+ /**
5
+ * Grant a channel's current members access to one item, as posting it in the
6
+ * channel does. The caller must be in the channel and able to share the item;
7
+ * sharing again changes nothing.
8
+ */
9
+ export declare function shareWithChannel(client: MacroClient, channel: Channel, entityType: ChannelShareEntityType, entityId: string): Promise<void>;
@@ -0,0 +1 @@
1
+ import '../../macro';
@@ -16,29 +16,49 @@ export declare class Thread {
16
16
  constructor(client: MacroClient, channelId: string,
17
17
  /** The id of the message this thread hangs off. */
18
18
  rootId: string);
19
+ /** A handle to the thread under the message `rootId` in `channel`. */
20
+ static byId(client: MacroClient, channel: Channel, rootId: string): Thread;
19
21
  /** Serialize the thread identity without its authenticated client. */
20
22
  toJSON(): {
21
23
  channelId: string;
22
24
  rootId: string;
23
25
  };
24
- /** The channel this thread is in. */
26
+ /**
27
+ * The channel this thread is in.
28
+ *
29
+ * @readonly
30
+ */
25
31
  channel(): Channel;
26
- /** The message this thread hangs off. */
32
+ /**
33
+ * The message this thread hangs off.
34
+ *
35
+ * @readonly
36
+ */
27
37
  root(): Message;
28
- /** List the replies in this thread, oldest first. */
38
+ /**
39
+ * List the replies in this thread, oldest first.
40
+ *
41
+ * @readonly
42
+ */
29
43
  replies(): Promise<Message[]>;
30
44
  /**
31
- * Post a reply in this thread.
45
+ * Post a reply in this thread; pass `silent: true` for a routine update
46
+ * that should notify nobody.
32
47
  *
33
48
  * @param body - Plain text, or a rich body composed with {@link msg}.
34
49
  * @param opts.images - Static images to attach, such as one from
35
50
  * `macro.images.generate()`.
36
51
  * @param opts.documents - Macro documents to attach as file chips, such as
37
52
  * a file from `macro.documents.upload()`.
53
+ * @param opts.silent - Send no push, email or inbox entry to anyone,
54
+ * mentioned people included; the reply still appears in the thread.
38
55
  * @returns The created reply.
56
+ *
57
+ * @write
39
58
  */
40
59
  reply(body: string | RichMessage, opts?: {
41
60
  images?: StaticImage[];
42
61
  documents?: Document[];
62
+ silent?: boolean;
43
63
  }): Promise<Message>;
44
64
  }