@macro-inc/sdk 0.5.0 → 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 (138) hide show
  1. package/README.md +156 -23
  2. package/dist/{chunk-3SW6QVDV.js → chunk-4MI52GWV.js} +60 -1
  3. package/dist/{chunk-GT5EUYOR.js → chunk-HO75UE4Z.js} +133 -0
  4. package/dist/{chunk-P4DTO6VD.js → chunk-MCSQNZ4E.js} +6 -0
  5. package/dist/{chunk-HIW6KU2I.js → chunk-SJ6S2GAT.js} +712 -14
  6. package/dist/{chunk-J2VK3NOR.js → chunk-SK5CMXRV.js} +44 -14
  7. package/dist/{chunk-UVJLWLSJ.js → chunk-TMTYN2UK.js} +190 -2
  8. package/dist/{chunk-PPR7IWZ7.js → chunk-ZYBAKW25.js} +2 -1
  9. package/dist/generated/agent-fold/index.d.ts +194 -8
  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 +33 -2
  13. package/dist/generated/agent-harness/types.gen.d.ts +341 -8
  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 +69 -1
  18. package/dist/generated/auth/types.gen.d.ts +734 -3
  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 +23 -6
  23. package/dist/generated/cognition/types.gen.d.ts +202 -114
  24. package/dist/generated/contacts/index.d.ts +1 -1
  25. package/dist/generated/contacts/index.js +1 -1
  26. package/dist/generated/contacts/sdk.gen.d.ts +5 -1
  27. package/dist/generated/contacts/types.gen.d.ts +56 -0
  28. package/dist/generated/email/types.gen.d.ts +8 -2
  29. package/dist/generated/notification/index.d.ts +1 -1
  30. package/dist/generated/notification/index.js +1 -1
  31. package/dist/generated/notification/sdk.gen.d.ts +2 -1
  32. package/dist/generated/notification/types.gen.d.ts +138 -0
  33. package/dist/generated/scheduled-action/index.d.ts +1 -1
  34. package/dist/generated/scheduled-action/index.js +1 -1
  35. package/dist/generated/scheduled-action/sdk.gen.d.ts +92 -2
  36. package/dist/generated/scheduled-action/types.gen.d.ts +1455 -21
  37. package/dist/generated/search/index.d.ts +1 -1
  38. package/dist/generated/search/types.gen.d.ts +50 -11
  39. package/dist/generated/storage/index.d.ts +1 -1
  40. package/dist/generated/storage/index.js +1 -1
  41. package/dist/generated/storage/sdk.gen.d.ts +309 -15
  42. package/dist/generated/storage/types.gen.d.ts +12437 -8899
  43. package/dist/src/entities/agent-sessions/activity.d.ts +3 -2
  44. package/dist/src/entities/agent-sessions/agent-session.d.ts +17 -5
  45. package/dist/src/entities/agent-sessions/namespace.d.ts +5 -4
  46. package/dist/src/entities/agent-sessions/review.d.ts +1 -1
  47. package/dist/src/entities/ai/namespace.d.ts +2 -2
  48. package/dist/src/entities/api-keys/namespace.d.ts +5 -2
  49. package/dist/src/entities/bots/bot.d.ts +6 -3
  50. package/dist/src/entities/calendar/booking-namespace.d.ts +1 -1
  51. package/dist/src/entities/calendar/calendar.d.ts +3 -2
  52. package/dist/src/entities/calendar/event.d.ts +9 -0
  53. package/dist/src/entities/calendar/namespace.d.ts +3 -2
  54. package/dist/src/entities/calls/call-record.d.ts +19 -5
  55. package/dist/src/entities/canvases/canvas.d.ts +5 -0
  56. package/dist/src/entities/channels/channel.d.ts +27 -7
  57. package/dist/src/entities/channels/message.d.ts +65 -2
  58. package/dist/src/entities/channels/message.test.d.ts +1 -0
  59. package/dist/src/entities/channels/namespace.d.ts +9 -4
  60. package/dist/src/entities/channels/post.d.ts +13 -7
  61. package/dist/src/entities/channels/share.d.ts +9 -0
  62. package/dist/src/entities/channels/share.test.d.ts +1 -0
  63. package/dist/src/entities/channels/thread.d.ts +5 -1
  64. package/dist/src/entities/chats/chat.d.ts +1 -1
  65. package/dist/src/entities/chats/namespace.d.ts +1 -1
  66. package/dist/src/entities/connected-apps/connected-app.d.ts +2 -1
  67. package/dist/src/entities/connected-apps/namespace.d.ts +2 -0
  68. package/dist/src/entities/crm/company.d.ts +1 -1
  69. package/dist/src/entities/crm/contact.d.ts +44 -3
  70. package/dist/src/entities/crm/namespace.d.ts +30 -13
  71. package/dist/src/entities/crm/pipeline-entry.d.ts +10 -3
  72. package/dist/src/entities/crm/pipeline.d.ts +39 -20
  73. package/dist/src/entities/crm/pipelines.d.ts +33 -5
  74. package/dist/src/entities/crm-email-privacy/email-privacy.d.ts +238 -0
  75. package/dist/src/entities/crm-email-privacy/email-rule-preview.d.ts +55 -0
  76. package/dist/src/entities/crm-email-privacy/email-rule-revision.d.ts +27 -0
  77. package/dist/src/entities/crm-email-privacy/email-rules.d.ts +32 -0
  78. package/dist/src/entities/databases/database.d.ts +34 -6
  79. package/dist/src/entities/databases/namespace.d.ts +26 -6
  80. package/dist/src/entities/databases/saved-query.d.ts +7 -1
  81. package/dist/src/entities/databases/table.d.ts +9 -0
  82. package/dist/src/entities/databases/view.d.ts +10 -0
  83. package/dist/src/entities/documents/create.test.d.ts +1 -0
  84. package/dist/src/entities/documents/document.d.ts +41 -6
  85. package/dist/src/entities/documents/namespace.d.ts +17 -3
  86. package/dist/src/entities/email/draft.d.ts +2 -2
  87. package/dist/src/entities/email/message.d.ts +18 -7
  88. package/dist/src/entities/email/namespace.d.ts +11 -7
  89. package/dist/src/entities/email/thread.d.ts +26 -3
  90. package/dist/src/entities/entity.d.ts +10 -1
  91. package/dist/src/entities/external-chat/chat.d.ts +19 -2
  92. package/dist/src/entities/foreign/namespace.d.ts +1 -1
  93. package/dist/src/entities/forms/form.d.ts +20 -1
  94. package/dist/src/entities/harnesses/namespace.d.ts +1 -1
  95. package/dist/src/entities/harnesses/pairing.d.ts +2 -1
  96. package/dist/src/entities/imports/entry.d.ts +65 -0
  97. package/dist/src/entities/imports/namespace.d.ts +103 -0
  98. package/dist/src/entities/imports/namespace.test.d.ts +1 -0
  99. package/dist/src/entities/initiatives/initiative.d.ts +14 -4
  100. package/dist/src/entities/initiatives/namespace.d.ts +4 -2
  101. package/dist/src/entities/me/namespace.d.ts +1 -1
  102. package/dist/src/entities/meetings/meeting.d.ts +2 -1
  103. package/dist/src/entities/notifications/namespace.d.ts +2 -1
  104. package/dist/src/entities/notifications/notification.d.ts +2 -1
  105. package/dist/src/entities/passwords/item.d.ts +118 -0
  106. package/dist/src/entities/passwords/namespace.d.ts +45 -0
  107. package/dist/src/entities/projects/namespace.d.ts +1 -1
  108. package/dist/src/entities/projects/project.d.ts +11 -1
  109. package/dist/src/entities/referrals/namespace.d.ts +1 -1
  110. package/dist/src/entities/routines/namespace.d.ts +81 -18
  111. package/dist/src/entities/routines/routine.d.ts +65 -4
  112. package/dist/src/entities/routines/suggestion.d.ts +38 -0
  113. package/dist/src/entities/saved-views/namespace.d.ts +2 -1
  114. package/dist/src/entities/search/exclusions.d.ts +6 -0
  115. package/dist/src/entities/search/namespace.d.ts +4 -2
  116. package/dist/src/entities/search/options.d.ts +3 -2
  117. package/dist/src/entities/suggestions/namespace.d.ts +118 -0
  118. package/dist/src/entities/suggestions/suggestion.d.ts +172 -0
  119. package/dist/src/entities/suggestions/suggestion.test.d.ts +1 -0
  120. package/dist/src/entities/tasks/namespace.d.ts +6 -5
  121. package/dist/src/entities/tasks/task.d.ts +14 -2
  122. package/dist/src/entities/teams/team.d.ts +16 -3
  123. package/dist/src/entities/ui/app-link.d.ts +24 -0
  124. package/dist/src/entities/ui/namespace.d.ts +75 -0
  125. package/dist/src/entities/users/namespace.d.ts +7 -3
  126. package/dist/src/entities/web/namespace.d.ts +2 -2
  127. package/dist/src/entities/workspace/namespace.d.ts +5 -3
  128. package/dist/src/entities/workspace/query.test.d.ts +1 -0
  129. package/dist/src/events/hydrate/document.d.ts +5 -0
  130. package/dist/src/macro.d.ts +26 -1
  131. package/dist/src/macro.js +4086 -1234
  132. package/dist/src/utils/activity.d.ts +2 -0
  133. package/dist/src/utils/index.d.ts +1 -1
  134. package/dist/src/utils/lazy.d.ts +13 -0
  135. package/dist/src/utils/options.d.ts +7 -0
  136. package/dist/src/utils/pagination.d.ts +16 -0
  137. package/dist/src/utils/verbs.d.ts +3 -0
  138. package/package.json +1 -1
@@ -1,8 +1,9 @@
1
1
  import type { ActivityWireRow } from '../../../generated/agent-harness/types.gen';
2
+ import { type IterationOptions } from '../../utils';
2
3
  import type { MacroClient } from '../../utils/client';
3
4
  import type { AgentSession } from './agent-session';
4
5
  /** Page options for recorded session activity, newest first. */
5
- export type AgentActivityOptions = {
6
+ export type AgentActivityOptions = IterationOptions & {
6
7
  /** Page size, from 1 to 100; defaults to 50. */
7
8
  limit?: number;
8
9
  /** Restrict to one code-mode invocation belonging to this session. */
@@ -23,7 +24,7 @@ export declare class AgentInvocation {
23
24
  */
24
25
  session(): AgentSession;
25
26
  /**
26
- * Recorded activity caused by this invocation, lazily paginated.
27
+ * Recorded activity caused by this invocation, lazily paginated; `maxItems` caps the total.
27
28
  *
28
29
  * @readonly
29
30
  */
@@ -2,6 +2,7 @@ import type { FoldedMessage } from '../../../generated/agent-fold';
2
2
  import type { AgentAction, AgentMode, AgentSessionChangesResponse, AgentSessionLogResponse, AgentSessionResponse, AgentUpdateKind, ArchiveCause, AutoArchivePreferencesBody, CodingPreferencesBody, ControlResponse, PromptAttachment, PullRequestLinkSource, SandboxSize, SessionBot } from '../../../generated/agent-harness/types.gen';
3
3
  import type { MacroClient } from '../../utils/client';
4
4
  import type { Agent } from '../agents/agent';
5
+ import type { Channel } from '../channels/channel';
5
6
  import { MacroEntity } from '../entity';
6
7
  import { EntityAccess } from '../sharing/access';
7
8
  import { type SharePermissionOptions } from '../sharing/permissions';
@@ -172,6 +173,15 @@ export type CreateManagedSessionOptions = {
172
173
  export declare class AgentSession extends MacroEntity<AgentSessionResponse> {
173
174
  /** Access requests and direct user grants. */
174
175
  readonly access: EntityAccess;
176
+ /**
177
+ * Share this agent session with a channel's current members, as posting it in the
178
+ * channel does. The caller must be in the channel and able to share the
179
+ * agent session; sharing again changes nothing.
180
+ *
181
+ * @write
182
+ * @idempotent
183
+ */
184
+ shareWithChannel(channel: Channel): Promise<void>;
175
185
  /**
176
186
  * Construct an approval handle scoped to this session.
177
187
  *
@@ -215,8 +225,9 @@ export declare class AgentSession extends MacroEntity<AgentSessionResponse> {
215
225
  */
216
226
  static createManaged(client: MacroClient, opts?: CreateManagedSessionOptions): Promise<AgentSession>;
217
227
  /**
218
- * The GitHub repositories the caller can hand a managed session: every
219
- * repository under an installation of Macro's GitHub App they or their
228
+ * List repositories available for managed sessions.
229
+ *
230
+ * Includes every repository under an installation of Macro's GitHub App they or their
220
231
  * teams made, sorted by `owner/name`. Empty when the App is installed
221
232
  * nowhere they reach.
222
233
  */
@@ -457,8 +468,9 @@ export declare class AgentSession extends MacroEntity<AgentSessionResponse> {
457
468
  */
458
469
  refreshChanges(): Promise<AgentSessionChangesResponse>;
459
470
  /**
460
- * Read this session's whole history as the conversation the app renders:
461
- * each user prompt and agent reply, oldest first, with tool calls and their
471
+ * Read this session's full conversation as the app renders it.
472
+ *
473
+ * Includes each user prompt and agent reply, oldest first, with tool calls and their
462
474
  * results, plans, permission requests and how each turn ended. Works on any
463
475
  * session the caller can view, live or finished, so it is the way to read
464
476
  * what another agent session did. Prefer it to {@link log}, which returns
@@ -487,7 +499,7 @@ export declare class AgentSession extends MacroEntity<AgentSessionResponse> {
487
499
  byId: (id: string) => CodeExecution;
488
500
  };
489
501
  /**
490
- * Recorded activity caused by this session, lazily paginated newest first.
502
+ * Recorded activity caused by this session, lazily paginated newest first; `maxItems` caps the total.
491
503
  *
492
504
  * @readonly
493
505
  */
@@ -31,7 +31,7 @@ import { AgentSession, type AgentSessionUpdates, type CreateManagedSessionOption
31
31
  *
32
32
  * ## Sessions waiting for the user
33
33
  *
34
- * macro.agentSessions.updates() lists the user's sessions waiting on them (permission requests, questions, held tool approvals) or stalled. A session's held tool calls come from session.pendingApprovals(); approve or deny one only when the user said so for that call. session.linkTask(task) links a session the user owns to its Macro task, and the session's pull request with it.
34
+ * macro.agentSessions.updates() lists the user's sessions waiting on them (permission requests, questions, held tool approvals) or stalled. The user answers them only on cards: in ExecuteCode, whenever it returns items, present them with execution.views.present({widgets: [{type: "agentUpdates", items: updates.items}]}). A session's held tool calls come from session.pendingApprovals(); approve or deny one only when the user said so for that call. session.linkTask(task) links a session the user owns to its Macro task, and the session's pull request with it.
35
35
  */
36
36
  export declare class AgentSessionNamespace {
37
37
  private readonly client;
@@ -84,9 +84,10 @@ export declare class AgentSessionNamespace {
84
84
  */
85
85
  repositoryBranches(repoUrl: string): Promise<string[]>;
86
86
  /**
87
- * The caller's coding sessions waiting for them: permission requests,
88
- * questions and held tool approvals to answer, and sessions stalled for
89
- * over 20 minutes, newest activity first. Read a session's held approvals
87
+ * List coding sessions awaiting the caller or stalled over 20 minutes.
88
+ *
89
+ * Includes permission requests, questions and held tool approvals to
90
+ * answer, and stalled sessions, newest activity first. Read a session's held approvals
90
91
  * with {@link AgentSession.pendingApprovals}.
91
92
  *
92
93
  * @readonly
@@ -16,7 +16,7 @@ export declare class SessionReview extends MacroEntity<ReviewRecord> {
16
16
  static list(client: MacroClient, execution: CodeExecution): Promise<SessionReview[]>;
17
17
  protected fetch(): Promise<ReviewRecord>;
18
18
  readonly title: () => Promise<string>;
19
- readonly kind: () => Promise<"email" | "calendar" | "import">;
19
+ readonly kind: () => Promise<"calendar" | "email" | "import">;
20
20
  /**
21
21
  * The session this review belongs to.
22
22
  *
@@ -5,7 +5,7 @@ export type { DecisionRequest, DecisionResponse, StructuredCompletionRequest, St
5
5
  /**
6
6
  * Shared cognition endpoints, charged to the authenticated acting user.
7
7
  *
8
- * @routing Use when generating structured objects or classifying supplied content with Jev; not generating images (`macro.images`) or answering the user yourself.
8
+ * @routing Use when asking a model to answer named yes/no questions or fill a JSON Schema from content you supply, or when reading AI usage; not generating images (`macro.images`) or answering the user yourself.
9
9
  */
10
10
  export declare class AiNamespace {
11
11
  private readonly client;
@@ -30,7 +30,7 @@ export declare class AiNamespace {
30
30
  * Ask named yes/no questions about JSON input. Each probability estimates
31
31
  * yes, from 0 to 1. This classifies supplied data without running tools.
32
32
  *
33
- * @write
33
+ * @readonly
34
34
  */
35
35
  decide(request: DecisionRequest): Promise<DecisionResponse>;
36
36
  }
@@ -17,7 +17,9 @@ export declare class ApiKeyNamespace {
17
17
  */
18
18
  list(): Promise<UserApiKey[]>;
19
19
  /**
20
- * Create a key. Save the secret now; it cannot be retrieved later.
20
+ * Create a key; refused to an agent's program (ExecuteCode, a routine), so
21
+ * there have the user create one in Macro's settings. Save the secret now;
22
+ * it cannot be retrieved later.
21
23
  *
22
24
  * @write
23
25
  */
@@ -26,7 +28,8 @@ export declare class ApiKeyNamespace {
26
28
  secret: string;
27
29
  }>;
28
30
  /**
29
- * Exchange an email address for a Macro API token, subject to server authorization.
31
+ * Exchange an email address for a Macro API token, subject to server
32
+ * authorization; refused to an agent's program (ExecuteCode, a routine).
30
33
  *
31
34
  * @write
32
35
  */
@@ -124,9 +124,12 @@ export declare class Bot extends MacroEntity<BotRecord> {
124
124
  */
125
125
  tokens(): Promise<BotToken[]>;
126
126
  /**
127
- * Mint a bearer token for the bot's webhooks and API. The secret is returned
128
- * once and cannot be read again; never write it into chat, documents or
129
- * results. To hand a user a token, have them mint it in bot settings.
127
+ * Mint a bearer token for the bot's webhooks and API; refused to an agent's
128
+ * program (ExecuteCode, a routine), so there present a card that mints it,
129
+ * `execution.views.present({widgets: [{type: 'botCredential', botId}]})` in
130
+ * an agent session, or have the user mint it in bot settings. The secret is
131
+ * returned once and cannot be read again; never write it into chat,
132
+ * documents or results.
130
133
  *
131
134
  * @write
132
135
  */
@@ -81,7 +81,7 @@ export declare class BookingNamespace {
81
81
  * real hosts: a personal link names {@link BookingLinkListing.host} with
82
82
  * mode `individual`; a team link uses `collective` or `roundRobin`.
83
83
  * `requiresConfirmation` must be false. For video set `macroCall`
84
- * (preferred) or `googleMeet`, never both. Creating sends no invitations.
84
+ * or `googleMeet`, as the user asks, never both. Creating sends no invitations.
85
85
  * Replaying an identical draft at the same slug returns the saved link; a
86
86
  * different draft at that slug conflicts (409). Share the link's
87
87
  * {@link BookingLink.webUrl} as an `<m-booking-link-mention>` chip.
@@ -34,8 +34,9 @@ export declare class Calendar extends MacroEntity<VisibleCalendar> {
34
34
  /** Whether the grant can create and modify events on this calendar. People
35
35
  * can hold that on someone else's calendar, so it does not mean it is theirs. */
36
36
  readonly isWritable: () => Promise<boolean>;
37
- /** Whether this calendar counts toward the caller's busy time: their
38
- * setting, by default only the primary calendars of inboxes they own. */
37
+ /** Whether this calendar counts toward the caller's busy time: their Busy
38
+ * switch in Settings → Calendar, on for every calendar until they turn it
39
+ * off. Booking links, team availability and agents all read it. */
39
40
  readonly contributesToAvailability: () => Promise<NonNullable<boolean | undefined> | undefined>;
40
41
  /** Whether this is a subscribed system calendar (holidays, birthdays). */
41
42
  readonly isSubscription: () => Promise<boolean>;
@@ -27,6 +27,11 @@ export interface UpdateEventOptions {
27
27
  /** Provider conference change; omit to retain it. Outlook removal requires a
28
28
  * separately confirmed replacement via prepareReplacement(). */
29
29
  conference?: ConferenceChange;
30
+ /** Switch the event to a Macro call in this update: create one, write its
31
+ * join link into the description and location, and remove any Google Meet or
32
+ * other conference. An event already holding a Macro call keeps it. Cannot be
33
+ * combined with `conference`. */
34
+ macroCall?: boolean;
30
35
  /** Replacement out-of-office properties, applied only to an event that is
31
36
  * already out-of-office. */
32
37
  outOfOffice?: OutOfOfficeProperties;
@@ -161,6 +166,10 @@ export declare class CalendarEvent extends MacroEntity<CalendarEventRecord> {
161
166
  * copy and say which inbox you used. Without `inbox` the call is refused
162
167
  * with `copy_choice_required`, listing each copy and the question to ask.
163
168
  *
169
+ * To change a meeting's link to a Macro call pass `macroCall: true`; never
170
+ * delete and recreate the event for it. The Teams meeting of an Outlook event
171
+ * cannot be removed this way: use {@link CalendarEvent.prepareReplacement}.
172
+ *
164
173
  * @destructive
165
174
  * @openworld
166
175
  * @idempotent
@@ -1,6 +1,7 @@
1
1
  import type { CreateCalendarEvent_Deserialize } from '../../../generated/agent-reviews';
2
2
  import type { CalendarAttendeeInputBody, ConferenceChange, EventReminders, EventTime, EventTransparency, EventVisibility, GuestPolicy, OutOfOfficeProperties, TeamCalendarSharing } from '../../../generated/calendar/types.gen';
3
3
  import type { ListOccurrencesData, ListTeamCalendarData, ListTeamOutOfOfficeData } from '../../../generated/storage/types.gen';
4
+ import { type IterationOptions } from '../../utils';
4
5
  import type { MacroClient } from '../../utils/client';
5
6
  import type { Link } from '../email/link';
6
7
  import { User } from '../users/user';
@@ -147,7 +148,7 @@ export declare class CalendarNamespace {
147
148
  setTeamSharing(sharing: TeamCalendarSharing): Promise<TeamCalendarSharing>;
148
149
  /** Occurrences on every calendar the user can see: their schedule is only
149
150
  * `contributesToAvailability` rows and meetings they attend; call the rest
150
- * by `calendarName`. Automatically paginated within the viewport. Each names
151
+ * by `calendarName`. Automatically paginated within the viewport; `maxItems` caps the total. Each names
151
152
  * its calendar (`calendarName`), whether a calendar holding it is on the
152
153
  * user's schedule (`contributesToAvailability`), the address of the
153
154
  * connected inbox holding that copy of the event (`inbox`) and whether the
@@ -181,7 +182,7 @@ export declare class CalendarNamespace {
181
182
  *
182
183
  * @readonly
183
184
  */
184
- occurrences(options: Omit<ListOccurrencesData['query'], 'cursor'>): AsyncGenerator<{
185
+ occurrences(options: Omit<ListOccurrencesData['query'], 'cursor'> & IterationOptions): AsyncGenerator<{
185
186
  event: CalendarEvent;
186
187
  occurrence: import("../../../generated/storage").CalendarOccurrence;
187
188
  calendarName: string | undefined;
@@ -20,7 +20,8 @@ export declare class CallRecord extends FavoritableEntity<CallRecordDetail> {
20
20
  /** Build a live call handle without fetching its archived detail. */
21
21
  static fromLive(client: MacroClient, summary: LiveCallSummary): CallRecord;
22
22
  /**
23
- * Join only while this call is live; never start a replacement call.
23
+ * Join only while this call is live, never starting a replacement call;
24
+ * refused to an agent's program (ExecuteCode, a routine).
24
25
  *
25
26
  * @write
26
27
  * @mcp-exclude Returns a live call room credential; MCP calls carry JSON only.
@@ -89,7 +90,8 @@ export declare class CallRecord extends FavoritableEntity<CallRecordDetail> {
89
90
  /** Access requests and direct user grants. */
90
91
  readonly access: EntityAccess;
91
92
  /**
92
- * Get or create a shareable meeting for this call.
93
+ * Get or create a shareable meeting for this call; refused to an agent's
94
+ * program (ExecuteCode, a routine), so there ask the user to share it.
93
95
  *
94
96
  * @write
95
97
  * @idempotent
@@ -110,6 +112,15 @@ export declare class CallRecord extends FavoritableEntity<CallRecordDetail> {
110
112
  toggleTeamShare(): Promise<boolean>;
111
113
  /** Favorites identify call records as `call`. */
112
114
  readonly entityType = "call";
115
+ /**
116
+ * Share this call record with a channel's current members, as posting it in the
117
+ * channel does. The caller must be in the channel and able to share the
118
+ * call record; sharing again changes nothing.
119
+ *
120
+ * @write
121
+ * @idempotent
122
+ */
123
+ shareWithChannel(channel: Channel): Promise<void>;
113
124
  protected fetch(): Promise<CallRecordDetail>;
114
125
  /**
115
126
  * The call's URL in the Macro web app; hand it to users as the link.
@@ -171,9 +182,12 @@ export declare class CallRecord extends FavoritableEntity<CallRecordDetail> {
171
182
  * while the call is live, the canonical grant once it is archived.
172
183
  */
173
184
  readonly shareWithTeam: () => Promise<boolean>;
174
- /** URL of the call recording, once available. */
185
+ /**
186
+ * URL of the call recording, once available; empty for an agent's program
187
+ * (ExecuteCode, a routine), which reads the bytes with `recording.bytes()`.
188
+ */
175
189
  readonly recordingUrl: () => Promise<string | undefined>;
176
- /** URL of the recording preview (thumbnail), once available. */
190
+ /** URL of the recording preview (thumbnail), once available; empty for an agent's program. */
177
191
  readonly recordingPreviewUrl: () => Promise<string | undefined>;
178
192
  /** When the recording started, if it was recorded. */
179
193
  readonly recordingStartedAt: () => Promise<string | undefined>;
@@ -211,7 +225,7 @@ export declare class CallRecord extends FavoritableEntity<CallRecordDetail> {
211
225
  * @idempotent
212
226
  */
213
227
  delete(): Promise<void>;
214
- /** Search calls by name and transcript, most relevant first, auto-paginated. */
228
+ /** Search calls by name and transcript, most relevant first, auto-paginated; `maxItems` caps the total. */
215
229
  static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<CallRecord, any, any>;
216
230
  }
217
231
  export {};
@@ -307,6 +307,11 @@ export declare class Canvas {
307
307
  * await channel.send(`Current plan: ${canvas.webUrl()}`, { images: [image] });
308
308
  * ```
309
309
  *
310
+ * @example Look at the canvas yourself, in an agent session's ExecuteCode.
311
+ * ```js
312
+ * return { data: { link: canvas.webUrl() }, images: [await canvas.render()] };
313
+ * ```
314
+ *
310
315
  * @example Show the render in your reply.
311
316
  * ```js
312
317
  * const image = await canvas.render();
@@ -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';
@@ -26,7 +26,8 @@ export type ChannelAttachment = GetChannelAttachmentsResponses[200]['items'][num
26
26
  */
27
27
  export declare class Channel extends PropertiedEntity<ChannelDetail> {
28
28
  /**
29
- * Start or join this channel's call, ringing members if a new call starts.
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).
30
31
  *
31
32
  * @write
32
33
  * @mcp-exclude Returns a live call room credential; MCP calls carry JSON only.
@@ -95,6 +96,12 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
95
96
  protected fetch(): Promise<ChannelDetail>;
96
97
  /** A handle to a channel by id. Details load on first access. */
97
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;
98
105
  /** Open (creating if needed) the DM channel with a user. */
99
106
  static dm(client: MacroClient, recipient: User): Promise<Channel>;
100
107
  /** Open (creating if needed) the group direct message with exactly these people, excluding the caller. */
@@ -113,10 +120,13 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
113
120
  /** The channel's type (e.g. `public`, `dm`, `private`). */
114
121
  readonly type: () => Promise<ChannelType>;
115
122
  /**
116
- * 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`.
117
125
  * `images` attaches static images, such as one from
118
126
  * `macro.images.generate()`, below the text; `documents` attaches Macro
119
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.
120
130
  *
121
131
  * Works with a channel webhook token as well as a normal one — see
122
132
  * {@link postToChannel} for which endpoint that picks and what it costs.
@@ -128,29 +138,37 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
128
138
  * await channel.send('Q3 numbers attached.', { documents: [file] });
129
139
  * ```
130
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
+ *
131
146
  * @write
132
147
  */
133
148
  send(body: string | RichMessage, opts?: {
134
149
  thread?: Thread;
135
150
  images?: StaticImage[];
136
151
  documents?: Document[];
152
+ silent?: boolean;
137
153
  }): Promise<Message>;
138
154
  /**
139
- * Root messages in this channel, most recent first, auto-paginated.
155
+ * Root messages in this channel, most recent first, auto-paginated; `maxItems` caps the total.
140
156
  *
141
157
  * @readonly
142
158
  */
143
159
  messages(opts?: {
144
160
  pageSize?: number;
161
+ maxItems?: number;
145
162
  }): AsyncGenerator<Message>;
146
163
  /**
147
164
  * Root messages created or replied to at or after `after`, most recent
148
- * 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.
149
166
  *
150
167
  * @readonly
151
168
  */
152
169
  messagesAfter(after: Date | string, opts?: {
153
170
  pageSize?: number;
171
+ maxItems?: number;
154
172
  }): AsyncGenerator<Message>;
155
173
  private timeline;
156
174
  /**
@@ -255,7 +273,7 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
255
273
  thread?: Thread;
256
274
  }): Promise<void>;
257
275
  /**
258
- * The attachments posted in this channel, auto-paginated.
276
+ * The attachments posted in this channel, auto-paginated; `maxItems` caps the total.
259
277
  *
260
278
  * @readonly
261
279
  */
@@ -263,7 +281,9 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
263
281
  pageSize?: number;
264
282
  /** Filter by type: `static` for images/videos, `dss` for documents. */
265
283
  type?: string;
284
+ maxItems?: number;
266
285
  }): AsyncGenerator<ChannelAttachment>;
286
+ private attachmentPages;
267
287
  /**
268
288
  * The channel's URL in the Macro web app.
269
289
  *
@@ -276,7 +296,7 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
276
296
  id: string;
277
297
  detail?: import("../../../generated/storage").ApiChannelDetail | undefined;
278
298
  };
279
- /** Search channels by content, most relevant first, auto-paginated. */
299
+ /** Search channels by content, most relevant first, auto-paginated; `maxItems` caps the total. */
280
300
  static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<Channel, any, any>;
281
301
  }
282
302
  export {};
@@ -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
@@ -39,6 +74,19 @@ export declare class Message extends FavoritableEntity<MessageRecord> {
39
74
  * @readonly
40
75
  */
41
76
  author(): Promise<User>;
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
+ };
42
90
  /**
43
91
  * The channel this message is in.
44
92
  *
@@ -51,6 +99,15 @@ export declare class Message extends FavoritableEntity<MessageRecord> {
51
99
  * @readonly
52
100
  */
53
101
  thread(): Thread;
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>;
54
111
  /**
55
112
  * Add an emoji reaction to this message.
56
113
  *
@@ -82,9 +139,15 @@ export declare class Message extends FavoritableEntity<MessageRecord> {
82
139
  */
83
140
  delete(): Promise<void>;
84
141
  /**
85
- * Post a reply in this message's thread.
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.
86
147
  *
87
148
  * @write
88
149
  */
89
- reply(body: string | RichMessage): Promise<Message>;
150
+ reply(body: string | RichMessage, opts?: {
151
+ silent?: boolean;
152
+ }): Promise<Message>;
90
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';
@@ -60,15 +61,19 @@ export declare class ChannelNamespace {
60
61
  team?: Team;
61
62
  }): Promise<Channel>;
62
63
  /**
63
- * 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.
64
65
  * Iterate with `for await`; collect with `Array.fromAsync`.
65
66
  *
66
67
  * @readonly
67
68
  */
68
- list(): AsyncGenerator<Channel>;
69
+ list(opts?: IterationOptions): AsyncGenerator<Channel>;
70
+ private listed;
69
71
  /**
70
- * Search channels by name (case-insensitive substring match over every
71
- * 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.
72
77
  *
73
78
  * @readonly
74
79
  */
@@ -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,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';
@@ -42,13 +42,16 @@ export declare class Thread {
42
42
  */
43
43
  replies(): Promise<Message[]>;
44
44
  /**
45
- * 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.
46
47
  *
47
48
  * @param body - Plain text, or a rich body composed with {@link msg}.
48
49
  * @param opts.images - Static images to attach, such as one from
49
50
  * `macro.images.generate()`.
50
51
  * @param opts.documents - Macro documents to attach as file chips, such as
51
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.
52
55
  * @returns The created reply.
53
56
  *
54
57
  * @write
@@ -56,5 +59,6 @@ export declare class Thread {
56
59
  reply(body: string | RichMessage, opts?: {
57
60
  images?: StaticImage[];
58
61
  documents?: Document[];
62
+ silent?: boolean;
59
63
  }): Promise<Message>;
60
64
  }