@macro-inc/sdk 0.3.0 → 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 (100) hide show
  1. package/README.md +45 -0
  2. package/dist/{chunk-Y4HQV7EL.js → chunk-AZJUIUIV.js} +26 -0
  3. package/dist/{chunk-KPR5JIGY.js → chunk-G43PLP2U.js} +95 -0
  4. package/dist/{chunk-IIICUUWY.js → chunk-PPR7IWZ7.js} +51 -51
  5. package/dist/{chunk-PTMBRVEK.js → chunk-PTX2RV2N.js} +84 -0
  6. package/dist/{chunk-OEHZOKGE.js → chunk-PZPTJI6F.js} +16 -0
  7. package/dist/{chunk-HR32RQGP.js → chunk-ZLBDES7U.js} +307 -1
  8. package/dist/generated/agent-fold/index.d.ts +6 -1
  9. package/dist/generated/agent-harness/index.d.ts +1 -1
  10. package/dist/generated/agent-harness/index.js +1 -1
  11. package/dist/generated/agent-harness/sdk.gen.d.ts +44 -1
  12. package/dist/generated/agent-harness/types.gen.d.ts +699 -0
  13. package/dist/generated/calendar/index.d.ts +1 -1
  14. package/dist/generated/calendar/index.js +1 -1
  15. package/dist/generated/calendar/sdk.gen.d.ts +41 -1
  16. package/dist/generated/calendar/types.gen.d.ts +904 -2
  17. package/dist/generated/cognition/index.d.ts +1 -1
  18. package/dist/generated/cognition/index.js +1 -1
  19. package/dist/generated/cognition/sdk.gen.d.ts +9 -1
  20. package/dist/generated/cognition/types.gen.d.ts +79 -0
  21. package/dist/generated/email/types.gen.d.ts +11 -1
  22. package/dist/generated/notification/index.js +1 -1
  23. package/dist/generated/notification/sdk.gen.d.ts +20 -20
  24. package/dist/generated/notification/types.gen.d.ts +77 -72
  25. package/dist/generated/scheduled-action/index.d.ts +1 -1
  26. package/dist/generated/scheduled-action/index.js +1 -1
  27. package/dist/generated/scheduled-action/sdk.gen.d.ts +4 -1
  28. package/dist/generated/scheduled-action/types.gen.d.ts +388 -7
  29. package/dist/generated/storage/index.d.ts +1 -1
  30. package/dist/generated/storage/index.js +1 -1
  31. package/dist/generated/storage/sdk.gen.d.ts +151 -1
  32. package/dist/generated/storage/types.gen.d.ts +3888 -139
  33. package/dist/src/entities/account-managers/grant.d.ts +39 -0
  34. package/dist/src/entities/account-managers/namespace.d.ts +17 -0
  35. package/dist/src/entities/agent-sessions/activity.d.ts +39 -0
  36. package/dist/src/entities/agent-sessions/agent-session.d.ts +42 -0
  37. package/dist/src/entities/agent-sessions/namespace.d.ts +7 -1
  38. package/dist/src/entities/agent-sessions/origin.d.ts +94 -0
  39. package/dist/src/entities/ai/namespace.d.ts +1 -1
  40. package/dist/src/entities/bots/bot.d.ts +108 -0
  41. package/dist/src/entities/bots/namespace.d.ts +15 -4
  42. package/dist/src/entities/bots/token.d.ts +34 -0
  43. package/dist/src/entities/calendar/booking-link.d.ts +49 -0
  44. package/dist/src/entities/calendar/booking-namespace.d.ts +130 -0
  45. package/dist/src/entities/calendar/booking-namespace.test.d.ts +1 -0
  46. package/dist/src/entities/calendar/booking.d.ts +77 -0
  47. package/dist/src/entities/calendar/create-confirmed.test.d.ts +1 -0
  48. package/dist/src/entities/calendar/namespace.d.ts +63 -15
  49. package/dist/src/entities/calls/call-record.d.ts +25 -3
  50. package/dist/src/entities/calls/connection.d.ts +53 -0
  51. package/dist/src/entities/calls/errors.d.ts +15 -0
  52. package/dist/src/entities/calls/namespace.d.ts +19 -2
  53. package/dist/src/entities/calls/participant.d.ts +22 -0
  54. package/dist/src/entities/channels/channel.d.ts +21 -3
  55. package/dist/src/entities/channels/namespace.d.ts +3 -3
  56. package/dist/src/entities/channels/post.d.ts +10 -2
  57. package/dist/src/entities/channels/thread.d.ts +4 -0
  58. package/dist/src/entities/chats/chat.d.ts +1 -1
  59. package/dist/src/entities/chats/namespace.d.ts +14 -1
  60. package/dist/src/entities/connected-apps/connected-app.d.ts +107 -0
  61. package/dist/src/entities/connected-apps/connector.d.ts +56 -0
  62. package/dist/src/entities/connected-apps/namespace.d.ts +74 -0
  63. package/dist/src/entities/crm/company.d.ts +1 -1
  64. package/dist/src/entities/crm/pipeline.d.ts +1 -1
  65. package/dist/src/entities/documents/document.d.ts +156 -7
  66. package/dist/src/entities/documents/namespace.d.ts +41 -2
  67. package/dist/src/entities/documents/office-files.d.ts +47 -0
  68. package/dist/src/entities/email/draft.d.ts +26 -4
  69. package/dist/src/entities/email/message.d.ts +91 -1
  70. package/dist/src/entities/email/namespace.d.ts +26 -3
  71. package/dist/src/entities/email/namespace.test.d.ts +1 -0
  72. package/dist/src/entities/email/thread.d.ts +7 -2
  73. package/dist/src/entities/external-chat/namespace.d.ts +2 -0
  74. package/dist/src/entities/favorites/namespace.d.ts +1 -1
  75. package/dist/src/entities/harnesses/namespace.d.ts +5 -1
  76. package/dist/src/entities/images/namespace.d.ts +5 -1
  77. package/dist/src/entities/me/namespace.d.ts +5 -1
  78. package/dist/src/entities/meetings/meeting.d.ts +5 -0
  79. package/dist/src/entities/messages/thread.d.ts +1 -1
  80. package/dist/src/entities/pins/namespace.d.ts +1 -1
  81. package/dist/src/entities/projects/namespace.d.ts +1 -1
  82. package/dist/src/entities/projects/project.d.ts +1 -1
  83. package/dist/src/entities/search/namespace.d.ts +65 -0
  84. package/dist/src/entities/search/options.d.ts +29 -0
  85. package/dist/src/entities/search/types.d.ts +90 -0
  86. package/dist/src/entities/tasks/namespace.d.ts +1 -1
  87. package/dist/src/entities/tasks/task.d.ts +4 -3
  88. package/dist/src/entities/users/namespace.d.ts +1 -1
  89. package/dist/src/entities/whatsapp/namespace.d.ts +2 -0
  90. package/dist/src/entities/workspace/items.d.ts +7 -0
  91. package/dist/src/entities/workspace/namespace.d.ts +14 -9
  92. package/dist/src/entities/workspace/query.d.ts +23 -0
  93. package/dist/src/entities/workspace/types.d.ts +6 -3
  94. package/dist/src/events/hydrate/call.d.ts +101 -0
  95. package/dist/src/events/types.d.ts +2 -1
  96. package/dist/src/macro.d.ts +33 -1
  97. package/dist/src/macro.js +6423 -4265
  98. package/dist/src/utils/activity.d.ts +23 -2
  99. package/package.json +1 -1
  100. package/dist/src/entities/search.d.ts +0 -53
@@ -0,0 +1,77 @@
1
+ import type { BookingAttendance, Booking as BookingRecord, BookingSlot } from '../../../generated/calendar/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { MacroEntity } from '../entity';
4
+ import { User } from '../users/user';
5
+ /**
6
+ * A meeting someone booked through one of the user's or their team's booking
7
+ * links. Detail loads through the host's management view, so it needs the
8
+ * personal owner, a host of the meeting or a team administrator.
9
+ */
10
+ export declare class Booking extends MacroEntity<BookingRecord> {
11
+ protected fetch(): Promise<BookingRecord>;
12
+ /** A handle to a booking by id. Detail loads on first access. */
13
+ static byId(client: MacroClient, id: string): Booking;
14
+ /** A handle seeded with a booking record the service returned. */
15
+ static fromRecord(client: MacroClient, record: BookingRecord): Booking;
16
+ /** Meeting title, as it was when the meeting was booked. */
17
+ readonly title: () => Promise<string>;
18
+ /** The guest's name. */
19
+ readonly name: () => Promise<string>;
20
+ /** The guest's email. */
21
+ readonly email: () => Promise<string>;
22
+ /** Absolute start. */
23
+ readonly startsAt: () => Promise<string>;
24
+ /** Absolute end. */
25
+ readonly endsAt: () => Promise<string>;
26
+ /** The guest's IANA display time zone. */
27
+ readonly timeZone: () => Promise<string>;
28
+ /** Lifecycle state. `failed` and `processing` need reconciliation, never a blind retry. */
29
+ readonly status: () => Promise<import("../../../generated/calendar").BookingStatus>;
30
+ /** Recorded attendance; `unknown` until a host records it. */
31
+ readonly attendance: () => Promise<NonNullable<BookingAttendance | undefined> | undefined>;
32
+ /** How many times the meeting moved to another start. */
33
+ readonly rescheduleCount: () => Promise<number | undefined>;
34
+ /** When the meeting last moved, if it ever did. */
35
+ readonly rescheduledAt: () => Promise<string | undefined>;
36
+ /** Final location or conference URL. */
37
+ readonly location: () => Promise<string>;
38
+ /** The guest's answers, keyed by question id; {@link questionLabels} names each question. */
39
+ readonly answers: () => Promise<{
40
+ [key: string]: string;
41
+ }>;
42
+ /** Question labels as they were when the meeting was booked, keyed by question id. */
43
+ readonly questionLabels: () => Promise<{
44
+ [key: string]: string;
45
+ } | undefined>;
46
+ /** The hosts assigned to the meeting. */
47
+ readonly hosts: () => Promise<User[]>;
48
+ /**
49
+ * Available replacement starts on one date (`YYYY-MM-DD`, in the booking
50
+ * schedule's time zone), for {@link reschedule}. Availability is checked
51
+ * again when the meeting moves.
52
+ */
53
+ rescheduleSlots(date: string): Promise<BookingSlot[]>;
54
+ /**
55
+ * Move the meeting to a start returned by {@link rescheduleSlots}; only on
56
+ * the user's go-ahead, since the guest and hosts are notified. Returns the
57
+ * saved booking.
58
+ */
59
+ reschedule(startsAt: string): Promise<Booking>;
60
+ /**
61
+ * Cancel the meeting; only on the user's go-ahead, since the guest and
62
+ * hosts are notified. The booking link stays as it is. Returns the saved
63
+ * booking.
64
+ */
65
+ cancel(): Promise<Booking>;
66
+ /**
67
+ * Approve a legacy pending booking and send its invitations; only on the
68
+ * user's go-ahead. Returns the saved booking.
69
+ */
70
+ approve(): Promise<Booking>;
71
+ /**
72
+ * Record or clear attendance once a confirmed meeting has ended. Returns
73
+ * the saved booking.
74
+ */
75
+ setAttendance(attendance: BookingAttendance): Promise<Booking>;
76
+ private change;
77
+ }
@@ -1,8 +1,10 @@
1
+ import type { CreateCalendarEvent_Deserialize } from '../../../generated/agent-reviews';
1
2
  import type { CalendarAttendeeInputBody, ConferenceChange, EventReminders, EventTime, EventTransparency, EventVisibility, GuestPolicy, OutOfOfficeProperties, TeamCalendarSharing } from '../../../generated/calendar/types.gen';
2
3
  import type { ListOccurrencesData, ListTeamCalendarData, ListTeamOutOfOfficeData } from '../../../generated/storage/types.gen';
3
4
  import type { MacroClient } from '../../utils/client';
4
5
  import type { Link } from '../email/link';
5
6
  import { User } from '../users/user';
7
+ import { BookingNamespace } from './booking-namespace';
6
8
  import { Calendar } from './calendar';
7
9
  import { CalendarEvent } from './event';
8
10
  import { CalendarReplacement } from './replacement';
@@ -90,20 +92,32 @@ export type CalendarEventRole = 'organizer' | 'guest';
90
92
  * @agent
91
93
  * ## Booking links
92
94
  *
93
- * - Booking links use conversational confirmation in every surface. First use `ListBookingLinks`
94
- * to find existing links and reusable availability. Resolve team and host identities with tools;
95
- * never ask for IDs, revisions or JSON. Default to personal ownership unless a team is requested.
96
- * Explain the complete proposal in readable prose: ownership and named hosts, who attends,
97
- * meeting name and description, duration, location or Google Meet, time zone, weekly hours and
98
- * date exceptions, link name, buffers, minimum notice, booking window, slot interval, daily limit,
99
- * guest questions, and whether bookings are enabled. Group related settings so it is easy to
100
- * review. Ask whether to proceed, and end the turn. Only after the user's reply approving that
101
- * proposal, call `CreateBookingLink` or `EditBookingLink`, quoting the reply verbatim in
102
- * `userConfirmation`. Do not quote the original request or invent approval. These tools save
103
- * immediately, with no booking review form. Do not use `AskUser` or an elicitation for booking
104
- * details. For edits preserve unrequested settings, and re-read and reconfirm if the revision
105
- * conflicts. Share the saved URL with an `<m-booking-link-mention>` chip (see Mentions), not a
106
- * bare URL. If the same proposal is already approved, do not ask again.
95
+ * - Booking links live under `macro.calendar.booking`. They are reusable booking pages, not
96
+ * calendar meetings; the meetings guests book through them are `Booking`s.
97
+ * - Booking links use conversational confirmation in every surface. First list
98
+ * `macro.calendar.booking.links()` to find existing links and reusable availability. Resolve
99
+ * teams and hosts from what it returns; never ask for IDs, revisions or JSON. Default to
100
+ * personal ownership unless a team is requested. Explain the complete proposal in readable
101
+ * prose: ownership and named hosts, who attends, meeting name and description, duration,
102
+ * location, Macro call or Google Meet, time zone, weekly hours and date exceptions, link name,
103
+ * buffers, minimum notice, booking window, slot interval, daily limit, guest questions, and
104
+ * whether bookings are enabled. Group related settings so it is easy to review. Ask whether to
105
+ * proceed, and end the turn. Only after the user's reply approving that proposal, call
106
+ * `booking.createLink` or `BookingLink.edit`, quoting the reply verbatim in `userConfirmation`.
107
+ * Do not quote the original request or invent approval. These save immediately, with no
108
+ * review card. For edits preserve unrequested settings, and re-read and reconfirm if the
109
+ * revision conflicts. Share the saved `webUrl()` with an `<m-booking-link-mention>` chip (see
110
+ * Mentions), not a bare URL. If the same proposal is already approved, do not ask again.
111
+ * - `booking.saveSettings` changes shared schedules, page settings and many links at once: explain
112
+ * the changes and the links they affect, and save only on the user's approving reply.
113
+ * - Cancelling, approving or rescheduling a `Booking` notifies its guest and hosts; do it only on
114
+ * the user's go-ahead. Reschedule to a start from `rescheduleSlots`.
115
+ *
116
+ * ## Creating events
117
+ *
118
+ * - Nothing lands on a calendar, and no invitation goes out, without the user seeing the event. A program cannot call `createEvent`; it is refused.
119
+ * - In an agent session, present the event as a review: `execution.reviews.create({kind: 'calendar', title, drafts})`, each draft with the same fields as `createConfirmed` (`calendarId` in place of `calendar`), then return `reviews: [await review.reference()]`. The user creates it from the card.
120
+ * - For a prompt from a channel or document thread, where no card is seen: write the whole event into your reply (title, date and time with its time zone, duration, guests, location, conference or Macro call, recurrence), ask whether to create it, and stop. Only once the user replies approving that event, call `createConfirmed` with their reply quoted in `userConfirmation`. Being asked to schedule something is a request to draft the event, never the approval.
107
121
  */
108
122
  export declare class CalendarNamespace {
109
123
  private readonly client;
@@ -193,6 +207,8 @@ export declare class CalendarNamespace {
193
207
  }[];
194
208
  hasMore: boolean;
195
209
  }>;
210
+ /** Booking links, their settings, booked meetings and booking statistics. */
211
+ readonly booking: BookingNamespace;
196
212
  constructor(client: MacroClient);
197
213
  /** The calendars the caller can see, some possibly not theirs, primaries and writable first. */
198
214
  calendars(): Promise<Calendar[]>;
@@ -202,6 +218,38 @@ export declare class CalendarNamespace {
202
218
  event(id: string): CalendarEvent;
203
219
  /** Recover a saved replacement, including after its original event was retired. */
204
220
  replacement(operationId: string): CalendarReplacement;
205
- /** Create a calendar event and return a handle to its synced record. */
221
+ /**
222
+ * Create a calendar event and return a handle to its synced record; an
223
+ * agent's program is refused (403) and creates through a review or
224
+ * {@link createConfirmed} instead.
225
+ */
206
226
  createEvent(options: CreateEventOptions): Promise<CalendarEvent>;
227
+ /**
228
+ * Create a calendar event only after the user replied approving it, quoting that reply in `userConfirmation`; never on the request that asked for the event.
229
+ *
230
+ * For a prompt from a channel or document thread: write the event out
231
+ * there, ask whether to create it, and call this in a later turn on the
232
+ * user's approving reply. In the agent session view, present a review
233
+ * (`execution.reviews.create({kind: 'calendar', ...})`) instead; its card
234
+ * is the confirmation. Takes what the CreateCalendarEvent tool takes:
235
+ * guests, recurrence, reminders, a provider conference or a Macro call,
236
+ * out-of-office and guest policy, and the calendar to write to. The event
237
+ * is written to the provider at once and guests receive invitations; on an
238
+ * error, look for the event before creating it again.
239
+ */
240
+ createConfirmed(options: ConfirmedEventOptions): Promise<CalendarEvent>;
207
241
  }
242
+ /** An event the user has approved in conversation, for `calendar.createConfirmed`. */
243
+ export type ConfirmedEventOptions = EventFields<CreateCalendarEvent_Deserialize> & {
244
+ /** The calendar to write to; omit for the user's primary calendar. */
245
+ calendar?: Calendar;
246
+ /**
247
+ * The user's own reply approving this specific event, quoted verbatim, such
248
+ * as their "yes, go ahead" after you wrote the event out for them. Never the
249
+ * request that asked you to schedule it, and never your own words.
250
+ */
251
+ userConfirmation: string;
252
+ };
253
+ /** The tool's event fields, with the calendar taken as a handle instead. */
254
+ type EventFields<Event> = Event extends unknown ? Omit<Event, 'calendarId'> : never;
255
+ export {};
@@ -1,15 +1,37 @@
1
- import type { EditCallTranscriptRequest, GetCallRecordResponses } from '../../../generated/storage/types.gen';
1
+ import type { EditCallTranscriptRequest, GetCallRecordResponses, LiveCallSummary, RingStatus } from '../../../generated/storage/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import { Channel } from '../channels/channel';
4
+ import { Thread } from '../channels/thread';
4
5
  import { FavoritableEntity } from '../entity';
5
6
  import { Meeting } from '../meetings/meeting';
6
7
  import { MessageThread, type TimelineOptions } from '../messages/thread';
7
8
  import { EntityAccess } from '../sharing/access';
8
9
  import { User } from '../users/user';
10
+ import { CallConnection, type JoinOptions } from './connection';
9
11
  import { CallMessage } from './message';
12
+ import { CallParticipant } from './participant';
10
13
  type CallRecordDetail = GetCallRecordResponses[200];
11
14
  /** A Macro call record (an archived or still active call). */
12
15
  export declare class CallRecord extends FavoritableEntity<CallRecordDetail> {
16
+ /** Kind is available immediately on handles returned by the live list. */
17
+ readonly kind?: LiveCallSummary['kind'];
18
+ private constructor();
19
+ /** Build a live call handle without fetching its archived detail. */
20
+ static fromLive(client: MacroClient, summary: LiveCallSummary): CallRecord;
21
+ /** Join only while this call is live; never start a replacement call. */
22
+ join(opts?: JoinOptions): Promise<CallConnection>;
23
+ /** Read the current ring state for this account. */
24
+ ringState(): Promise<RingStatus>;
25
+ /** Read the connected room roster without joining. */
26
+ participants(): Promise<CallParticipant[]>;
27
+ /** Decline this call's ring for the current account. */
28
+ decline(): Promise<void>;
29
+ /** Read the persistent discussion, which may be a channel thread. */
30
+ discussion(): Promise<MessageThread | Thread>;
31
+ /** Download recording bytes through the Macro host. */
32
+ readonly recording: {
33
+ bytes: () => Promise<Uint8Array>;
34
+ };
13
35
  /** A shared message thread scoped to this resource. */
14
36
  messageThreadById(id: string): MessageThread;
15
37
  /** A mixed message and activity timeline page. */
@@ -81,7 +103,7 @@ export declare class CallRecord extends FavoritableEntity<CallRecordDetail> {
81
103
  /** Transcript segments, ordered by sequence number. */
82
104
  readonly transcript: () => Promise<import("../../../generated/storage").CallRecordTranscriptSegment[]>;
83
105
  /** Macro-account participants, both active and historic. */
84
- readonly participants: () => Promise<import("../../../generated/storage").CallRecordParticipant[]>;
106
+ readonly historicParticipants: () => Promise<import("../../../generated/storage").CallRecordParticipant[]>;
85
107
  /** Current and past guests; each id matches its transcript speaker id. */
86
108
  readonly guests: () => Promise<import("../../../generated/storage").CallRecordGuest[]>;
87
109
  /**
@@ -114,6 +136,6 @@ export declare class CallRecord extends FavoritableEntity<CallRecordDetail> {
114
136
  /** Delete the call record. */
115
137
  delete(): Promise<void>;
116
138
  /** Search calls by name and transcript, most relevant first, auto-paginated. */
117
- static search: (client: MacroClient, query: string, searchOpts?: import("../search").SearchOpts) => AsyncGenerator<CallRecord, any, any>;
139
+ static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<CallRecord, any, any>;
118
140
  }
119
141
  export {};
@@ -0,0 +1,53 @@
1
+ import type { CallTokenResponse, JoinCallRequest } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { CallRecord } from './call-record';
4
+ declare const inspectSymbol: unique symbol;
5
+ /** Options for entering a call. The default is to fail if already in another call. */
6
+ export type JoinOptions = JoinCallRequest;
7
+ /** A room credential. Keep `token` out of logs and serialized values. */
8
+ export declare class CallConnection {
9
+ private readonly client;
10
+ /** The call this credential enters. */
11
+ readonly call: CallRecord;
12
+ /** LiveKit server URL. */
13
+ readonly url: string;
14
+ /** Short-lived LiveKit token; never serialize or log it. */
15
+ readonly token: string;
16
+ /** RTC participant identity. */
17
+ readonly identity: string;
18
+ /** RTC room name. */
19
+ readonly roomName: string;
20
+ /** Whether this request created the call. */
21
+ readonly started: boolean;
22
+ /** Construct a connection from the server's admission response. */
23
+ constructor(client: MacroClient, response: CallTokenResponse);
24
+ /** Leave this exact call; safe to invoke after another call has started. */
25
+ leave(): Promise<{
26
+ callEnded: boolean;
27
+ }>;
28
+ /** Serialize connection metadata without the room credential. */
29
+ toJSON(): {
30
+ call: {
31
+ url: string;
32
+ id: string;
33
+ detail?: import("../../../generated/storage").CallRecord | undefined;
34
+ };
35
+ url: string;
36
+ identity: string;
37
+ roomName: string;
38
+ started: boolean;
39
+ };
40
+ /** Keep the credential out of Node's console inspection. */
41
+ [inspectSymbol](): {
42
+ call: {
43
+ url: string;
44
+ id: string;
45
+ detail?: import("../../../generated/storage").CallRecord | undefined;
46
+ };
47
+ url: string;
48
+ identity: string;
49
+ roomName: string;
50
+ started: boolean;
51
+ };
52
+ }
53
+ export {};
@@ -0,0 +1,15 @@
1
+ import { MacroApiError } from '../../utils/unwrap';
2
+ /** The account is participating in another call. */
3
+ export declare class InOtherCallError extends MacroApiError {
4
+ constructor(data: unknown);
5
+ }
6
+ /** This identity already has a room connection. */
7
+ export declare class AlreadyConnectedError extends MacroApiError {
8
+ constructor(data: unknown);
9
+ }
10
+ /** The call ended before this join completed. */
11
+ export declare class CallEndedError extends MacroApiError {
12
+ constructor(data: unknown);
13
+ }
14
+ /** Preserve the server's branchable call admission codes. */
15
+ export declare function callAdmissionError(error: unknown): never;
@@ -1,12 +1,29 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
- import type { SearchOpts } from '../search';
2
+ import { Channel } from '../channels/channel';
3
+ import type { SearchOpts } from '../search/options';
3
4
  import { CallRecord } from './call-record';
5
+ /** A lightweight preview of an existing call record. */
6
+ export type CallSummary = {
7
+ call: CallRecord;
8
+ channel?: Channel;
9
+ channelName?: string;
10
+ customName?: string;
11
+ startedAt: string;
12
+ endedAt?: string;
13
+ };
4
14
  /**
5
- * @routing Use when the request names a recorded call or its transcript, such as what was said on yesterday's call; not email, messages, tables or scheduling.
15
+ * @routing Use when finding live or recorded calls, entering a room, reading a transcript, or downloading a recording; not email, messages, tables or scheduling.
16
+ * @agent A program uses an agent account's own API key to enter a call. Use active() to reconcile missed events. Join an existing call with call.join(); start a channel call only when intending to ring its members. Calls with only programs end after the server timeout. Keep room tokens private and connect with a LiveKit client outside code mode.
6
17
  */
7
18
  export declare class CallRecordNamespace {
8
19
  private readonly client;
9
20
  constructor(client: MacroClient);
21
+ /** Get a lazy call handle; joining it never creates a call. */
10
22
  byId(id: string): CallRecord;
23
+ /** Search archived calls by name and transcript, not the live room roster. */
11
24
  search(query: string, opts?: SearchOpts): AsyncGenerator<CallRecord>;
25
+ /** List joinable live calls; use after an event stream reconnects. */
26
+ active(): Promise<CallRecord[]>;
27
+ /** Preview these calls in input order; missing records are omitted. */
28
+ summaries(calls: CallRecord[]): Promise<CallSummary[]>;
12
29
  }
@@ -0,0 +1,22 @@
1
+ import type { LiveCallParticipant } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { User } from '../users/user';
4
+ /** A connected participant and their published track state. */
5
+ export declare class CallParticipant {
6
+ /** RTC participant identity. */
7
+ readonly identity: string;
8
+ /** Display name in the room. */
9
+ readonly displayName: string;
10
+ /** Account, guest, or bot participant. */
11
+ readonly kind: LiveCallParticipant['kind'];
12
+ /** Whether this participant is a program. */
13
+ readonly isProgram: boolean;
14
+ /** When this RTC connection began. */
15
+ readonly joinedAt?: string;
16
+ /** Published tracks and mute state. */
17
+ readonly tracks: LiveCallParticipant['tracks'];
18
+ /** Macro account handle, when one is present. */
19
+ readonly user?: User;
20
+ /** Build a roster handle from a live participant record. */
21
+ constructor(client: MacroClient, record: LiveCallParticipant);
22
+ }
@@ -2,6 +2,10 @@ 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';
6
10
  import type { StaticImage } from '../images/image';
7
11
  import { MessageThread, type TimelineOptions } from '../messages/thread';
@@ -21,6 +25,10 @@ export type ChannelAttachment = GetChannelAttachmentsResponses[200]['items'][num
21
25
  * A channel.
22
26
  */
23
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>;
24
32
  /** Record a view or interaction in this channel. */
25
33
  recordActivity(type: ActivityType): Promise<ChannelActivity>;
26
34
  /** Set an uploaded profile picture, or clear it. */
@@ -77,15 +85,23 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
77
85
  /**
78
86
  * Post a message. Plain text, or a rich body composed with `msg`.
79
87
  * `images` attaches static images, such as one from
80
- * `macro.images.generate()`, below the text.
88
+ * `macro.images.generate()`, below the text; `documents` attaches Macro
89
+ * documents as file chips, such as a file from `macro.documents.upload()`.
81
90
  *
82
91
  * Works with a channel webhook token as well as a normal one — see
83
92
  * {@link postToChannel} for which endpoint that picks and what it costs.
84
- * The webhook endpoint takes no images.
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
+ * ```
85
100
  */
86
101
  send(body: string | RichMessage, opts?: {
87
102
  thread?: Thread;
88
103
  images?: StaticImage[];
104
+ documents?: Document[];
89
105
  }): Promise<Message>;
90
106
  /** Root messages in this channel, most recent first, auto-paginated. */
91
107
  messages(opts?: {
@@ -129,6 +145,8 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
129
145
  leave(): Promise<void>;
130
146
  /** The channel's members, with their roles and join times. */
131
147
  participants(): Promise<ChannelParticipant[]>;
148
+ /** Bots that can post to the channel. */
149
+ bots(): Promise<Bot[]>;
132
150
  /** Add users to the channel. */
133
151
  addParticipants(users: User[]): Promise<void>;
134
152
  /** Remove users from the channel. */
@@ -152,6 +170,6 @@ export declare class Channel extends PropertiedEntity<ChannelDetail> {
152
170
  detail?: import("../../../generated/storage").ApiChannelDetail | undefined;
153
171
  };
154
172
  /** Search channels by content, most relevant first, auto-paginated. */
155
- 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>;
156
174
  }
157
175
  export {};
@@ -1,18 +1,18 @@
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
9
  /**
10
- * @routing Use when reading or sending channel and direct messages, posting a poll, reacting, managing members, or WhatsApp and external chats; not email.
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
11
  *
12
12
  * @agent
13
13
  * ## Polls
14
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` unless asked to hide results, and `channelGrants: []`. Post it as one message with its live card on its own line:
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
16
  *
17
17
  * `<m-document-card>{"documentId":"{form_id}","documentName":"{question}","blockName":"form","previewData":{"poll":{"optionCount":2}}}</m-document-card>`
18
18
  *
@@ -1,8 +1,16 @@
1
1
  import type { RichMessage } from '../../mentions';
2
2
  import type { MacroClient } from '../../utils/client';
3
+ import type { Document } from '../documents/document';
3
4
  import type { StaticImage } from '../images/image';
4
5
  import type { Channel } from './channel';
5
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
+ };
6
14
  /**
7
15
  * Post a message using the endpoint supported by the caller's credentials.
8
16
  *
@@ -12,7 +20,7 @@ import type { Thread } from './thread';
12
20
  * cached by the client.
13
21
  *
14
22
  * The webhook endpoint takes content only: the `mentions` list, threads and
15
- * images are dropped. `<m-*>` mention tags in the content still render and
23
+ * attachments are dropped. `<m-*>` mention tags in the content still render and
16
24
  * notify, because the server extracts a bot's mentions from its content. A
17
25
  * user-owned bot gets the full API by acting as its owner with `requestedAs`.
18
26
  *
@@ -20,4 +28,4 @@ import type { Thread } from './thread';
20
28
  * channel root. One target rather than a channel plus a thread id, so the two
21
29
  * can't disagree.
22
30
  */
23
- export declare function postToChannel(client: MacroClient, target: Channel | Thread, body: RichMessage, images?: StaticImage[]): Promise<string>;
31
+ export declare function postToChannel(client: MacroClient, target: Channel | Thread, body: RichMessage, { images, documents }?: MessageAttachments): Promise<string>;
@@ -1,5 +1,6 @@
1
1
  import { type RichMessage } from '../../mentions';
2
2
  import type { MacroClient } from '../../utils/client';
3
+ import type { Document } from '../documents/document';
3
4
  import type { StaticImage } from '../images/image';
4
5
  import { Channel } from './channel';
5
6
  import { Message } from './message';
@@ -32,9 +33,12 @@ export declare class Thread {
32
33
  * @param body - Plain text, or a rich body composed with {@link msg}.
33
34
  * @param opts.images - Static images to attach, such as one from
34
35
  * `macro.images.generate()`.
36
+ * @param opts.documents - Macro documents to attach as file chips, such as
37
+ * a file from `macro.documents.upload()`.
35
38
  * @returns The created reply.
36
39
  */
37
40
  reply(body: string | RichMessage, opts?: {
38
41
  images?: StaticImage[];
42
+ documents?: Document[];
39
43
  }): Promise<Message>;
40
44
  }
@@ -65,7 +65,7 @@ export declare class Chat extends PropertiedEntity<ChatDetail> implements Mentio
65
65
  detail?: import("../../../generated/cognition").ChatResponse | undefined;
66
66
  };
67
67
  /** Search chats by name and content, most relevant first, auto-paginated. */
68
- 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>;
69
69
  toMention(): MentionPart;
70
70
  }
71
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
  }