@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
@@ -32,6 +32,9 @@ export type FileContent = Uint8Array<ArrayBuffer> | ArrayBuffer | Blob | string;
32
32
  * Change the text of an existing Markdown document or task body in place, with `document.edit(instructions)` in code or the `EditDocument` tool where code isn't available. Never recreate the document or upload its Markdown to change its text. PDF, Word and other uploaded files can't be edited this way.
33
33
  *
34
34
  * When a program already holds the exact new Markdown, as an integration syncing from another system does, read `document.contentWithRevision()` and write with `document.setContent(markdown, {expectedRevision})`: the write lands only if nobody changed the document since the read, and throws `DocumentChangedError` otherwise, so read again and reapply instead of overwriting.
35
+ *
36
+ * `document.content()`, `contentWithRevision()` and `initiative.description()` return Macro's lossless Markdown: people, documents, dates and other chips, tables, images and equations are `<m-*>` tags with a JSON body, such as `<m-user-mention>{"userId":"…"}</m-user-mention>` for a person and `<m-table>` for a table. To write text back, take it and its revision from one `contentWithRevision()` read, and copy every tag you are not changing exactly as you read it: an edited tag changes its chip, and a dropped one deletes it.
37
+ *
35
38
  * ## Uploaded Office and design files
36
39
  *
37
40
  * Edit an uploaded Word file with `readWord()` then `editWord(operations)`, and a PowerPoint deck with `readPresentation()` then `editPresentation(operations)` (or `copyPresentation()` for a new deck): both address paragraphs, slides and shapes by the ids the read reports. Read Figma, Photoshop and Illustrator files with `readDesign()`, `readPhotoshop()` and `readIllustrator()`; they can't be edited. Never rebuild these files from `bytes()`.
@@ -254,24 +257,35 @@ export declare class DocumentNamespace {
254
257
  */
255
258
  systemSkills(): Promise<SystemSkill[]>;
256
259
  /**
257
- * Search documents by name and content, most relevant first, auto-paginated.
260
+ * Search documents by name and content, most relevant first, auto-paginated; `maxItems` caps the total.
258
261
  *
259
262
  * @readonly
260
263
  */
261
264
  search(query: string, opts?: SearchOpts): AsyncGenerator<Document>;
262
265
  /**
263
- * The user's recent documents, most recent first, auto-paginated.
266
+ * The user's recent documents, most recent first, auto-paginated; `maxItems` caps the total.
264
267
  *
265
268
  * @readonly
266
269
  */
267
270
  recent(opts?: {
268
271
  pageSize?: number;
269
272
  fileType?: string;
273
+ maxItems?: number;
270
274
  }): AsyncGenerator<Document>;
271
275
  /**
272
- * The user's recently soft-deleted documents.
276
+ * The documents among the user's 100 most recently trashed items; page
277
+ * through the whole trash with `trashed()`.
273
278
  *
274
279
  * @readonly
275
280
  */
276
281
  recentlyDeleted(): Promise<Document[]>;
282
+ /**
283
+ * The user's trashed documents, most recently trashed first, auto-paginated; `maxItems` caps the total.
284
+ *
285
+ * @readonly
286
+ */
287
+ trashed(opts?: {
288
+ pageSize?: number;
289
+ maxItems?: number;
290
+ }): AsyncGenerator<Document>;
277
291
  }
@@ -62,7 +62,7 @@ export declare class EmailDraft extends EmailMessage {
62
62
  * 8601, in the future). Write the draft out for the user and ask before
63
63
  * scheduling it; the request that asked for the email is not the approval.
64
64
  *
65
- * @destructive
65
+ * @send
66
66
  * @openworld
67
67
  */
68
68
  schedule(sendTime: string, options?: DraftSendOptions): Promise<void>;
@@ -73,7 +73,7 @@ export declare class EmailDraft extends EmailMessage {
73
73
  * about a minute; until then {@link unschedule} still stops it. Write the
74
74
  * draft out for the user and ask before sending it.
75
75
  *
76
- * @destructive
76
+ * @send
77
77
  * @openworld
78
78
  */
79
79
  send(options?: DraftSendOptions): Promise<void>;
@@ -21,6 +21,12 @@ export interface SendEmailOptions {
21
21
  subject: string;
22
22
  /** Plain-text body. */
23
23
  bodyText: string;
24
+ /**
25
+ * The address to send from: the primary inbox's own address or one of its
26
+ * verified Gmail send-as aliases, which sends under the alias's display
27
+ * name. An unverified or unknown address is refused.
28
+ */
29
+ from?: string;
24
30
  }
25
31
  /** An email the user has approved in conversation, for `email.sendConfirmed`. */
26
32
  export interface ConfirmedEmailOptions {
@@ -35,11 +41,13 @@ export interface ConfirmedEmailOptions {
35
41
  /** The body, written as Markdown; it is rendered to HTML on send. */
36
42
  body: string;
37
43
  /**
38
- * The connected inbox to send from. Omit it unless you know which inbox is
39
- * right: a reply then goes out from the inbox that received the message it
40
- * answers, and a new email from the user's primary inbox.
44
+ * The connected inbox to send from, or the address of a verified Gmail
45
+ * send-as alias of one, which then sends from that inbox under the alias's
46
+ * display name. Omit it unless you know which is right: a reply then goes
47
+ * out from the inbox that received the message it answers, and a new email
48
+ * from the user's primary inbox. An unverified alias is refused.
41
49
  */
42
- from?: Link;
50
+ from?: Link | string;
43
51
  /** The message this answers; the email is then sent as a reply in its thread. */
44
52
  replyingTo?: EmailMessage;
45
53
  /**
@@ -67,8 +75,11 @@ export interface ForwardEmailOptions {
67
75
  bcc?: EmailRecipient[];
68
76
  /** A note above the forwarded message, written as Markdown. */
69
77
  body?: string;
70
- /** The connected inbox to send from; defaults to the inbox holding the message. */
71
- from?: Link;
78
+ /**
79
+ * The connected inbox to send from, or a verified Gmail send-as alias of
80
+ * one; defaults to the inbox holding the message.
81
+ */
82
+ from?: Link | string;
72
83
  /** `false` leaves the inbox signature off this one email; omit for the inbox's default. */
73
84
  includeSignature?: boolean;
74
85
  }
@@ -125,7 +136,7 @@ export declare class EmailMessage extends MacroEntity<EmailMessageData> {
125
136
  * quotes this message and carries its attachments; it takes effect at once
126
137
  * and is never retried.
127
138
  *
128
- * @destructive
139
+ * @send
129
140
  * @openworld
130
141
  */
131
142
  forwardConfirmed(opts: ForwardEmailOptions & {
@@ -1,6 +1,7 @@
1
1
  import type { EmailConnectionProviders } from '../../../generated/auth/types.gen';
2
2
  import type { ApiSortMethod, TransferRecoveryResponse } from '../../../generated/email/types.gen';
3
3
  import type { ListEmailRemindersData } from '../../../generated/storage/types.gen';
4
+ import { type IterationOptions } from '../../utils';
4
5
  import type { MacroClient } from '../../utils/client';
5
6
  import type { SearchOpts } from '../search/options';
6
7
  import { EmailAttachment } from './attachment';
@@ -11,8 +12,8 @@ import { Link } from './link';
11
12
  import { type ConfirmedEmailOptions, EmailMessage, type SendEmailOptions, type SentEmail } from './message';
12
13
  import { EmailThread } from './thread';
13
14
  /** Options for listing inbox threads. */
14
- export interface InboxOptions {
15
- /** Page size (default 20, max 500). */
15
+ export interface InboxOptions extends IterationOptions {
16
+ /** Threads fetched per request (default 50, max 500). */
16
17
  pageSize?: number;
17
18
  /** Sort order. Defaults to `viewed_updated`. */
18
19
  sort?: ApiSortMethod;
@@ -30,7 +31,7 @@ export interface InboxOptions {
30
31
  * ## Sending email
31
32
  *
32
33
  * - Nothing leaves without the user seeing it. A program cannot call `send` or `EmailThread.reply`; they are refused, and so is a draft's `send` or `schedule` without `userConfirmation`.
33
- * - In an agent session, present the email as a review: `execution.reviews.create({kind: 'email', title, drafts})`, each draft with the same fields as `sendConfirmed` (Markdown `body`, `to`/`cc`/`bcc`, `from` as the inbox's address, `replyingToId`, `attachments: [{documentId}]`), then return `reviews: [await review.reference()]`. The user sends it from the card. For a forward, `await message.forwardDraft({to, body})` is the draft.
34
+ * - In an agent session, present the email as a review: `execution.reviews.create({kind: 'email', title, drafts})`, each draft with the same fields as `sendConfirmed` (Markdown `body`, `to`/`cc`/`bcc`, `from` as the inbox's address or a verified send-as alias of it, `replyingToId`, `attachments: [{documentId}]`), then return `reviews: [await review.reference()]`. The user sends it from the card. For a forward, `await message.forwardDraft({to, body})` is the draft.
34
35
  * - For a prompt from a channel or document thread, where no card is seen: write the whole email into your reply, ask whether to send it, and stop. Only once the user replies approving that email, send it with their reply quoted in `userConfirmation`: `sendConfirmed` for a new email or a reply, `EmailMessage.forwardConfirmed` for a forward, `EmailDraft.send` or `EmailDraft.schedule` for a saved draft. Being asked to send an email is a request to draft one, never the approval.
35
36
  */
36
37
  export declare class EmailNamespace {
@@ -56,7 +57,9 @@ export declare class EmailNamespace {
56
57
  scheduled(options?: {
57
58
  pageSize?: number;
58
59
  inbox?: Link;
60
+ maxItems?: number;
59
61
  }): AsyncGenerator<EmailDraft>;
62
+ private scheduledPages;
60
63
  /**
61
64
  * Importance filters.
62
65
  *
@@ -79,12 +82,13 @@ export declare class EmailNamespace {
79
82
  [key: string]: import("../../../generated/email").ContactInfoWithInteraction[];
80
83
  }>;
81
84
  /**
82
- * Follow-up reminders with thread handles, automatically paginated.
85
+ * Follow-up reminders with thread handles, automatically paginated; `maxItems` caps the total.
83
86
  *
84
87
  * @readonly
85
88
  */
86
89
  reminders(options?: Omit<NonNullable<ListEmailRemindersData['query']>, 'inboxIds' | 'cursor'> & {
87
90
  inboxes?: Link[];
91
+ maxItems?: number;
88
92
  }): AsyncGenerator<{
89
93
  thread: EmailThread;
90
94
  followup: import("../../../generated/storage").EmailFollowup;
@@ -134,7 +138,7 @@ export declare class EmailNamespace {
134
138
  * Send a new plain-text email; an agent's program is refused (403) and
135
139
  * sends through a review or {@link sendConfirmed} instead.
136
140
  *
137
- * @destructive
141
+ * @send
138
142
  * @openworld
139
143
  */
140
144
  send(opts: SendEmailOptions): Promise<EmailMessage | undefined>;
@@ -151,7 +155,7 @@ export declare class EmailNamespace {
151
155
  * is never retried; on an error, look for the message in the thread before
152
156
  * sending again.
153
157
  *
154
- * @destructive
158
+ * @send
155
159
  * @openworld
156
160
  */
157
161
  sendConfirmed(opts: ConfirmedEmailOptions): Promise<SentEmail>;
@@ -165,7 +169,7 @@ export declare class EmailNamespace {
165
169
  */
166
170
  search(query: string, opts?: SearchOpts): AsyncGenerator<EmailThread>;
167
171
  /**
168
- * The threads in the inbox, most recent first, auto-paginated.
172
+ * The threads in the inbox, most recent first, auto-paginated; `maxItems` caps the total.
169
173
  *
170
174
  * @readonly
171
175
  */
@@ -1,13 +1,15 @@
1
- import type { ApiContactInfo, ApiDraftContactInfo, CalendarInvitation, GetThreadResponses, MailboxOperation, UpdateThreadStateRequest } from '../../../generated/email/types.gen';
1
+ import type { ApiContactInfo, ApiDraftContactInfo, ApiThreadPreviewCursorInner, CalendarInvitation, GetThreadResponses, MailboxOperation, UpdateThreadStateRequest } from '../../../generated/email/types.gen';
2
2
  import type { EmailFollowupCommand } from '../../../generated/storage/types.gen';
3
3
  import type { MacroClient } from '../../utils/client';
4
4
  import type { Calendar } from '../calendar/calendar';
5
5
  import { CalendarEvent } from '../calendar/event';
6
+ import type { Channel } from '../channels/channel';
6
7
  import { PropertiedEntity } from '../entity';
7
8
  import { Project } from '../projects/project';
8
9
  import { EntityAccess } from '../sharing/access';
9
10
  import { type SharePermissionOptions } from '../sharing/permissions';
10
11
  import { EmailAttachment } from './attachment';
12
+ import { EmailDraft } from './draft';
11
13
  import type { Label } from './label';
12
14
  import { Link } from './link';
13
15
  import { EmailMessage } from './message';
@@ -105,6 +107,15 @@ export declare class EmailThread extends PropertiedEntity<ThreadDetail> {
105
107
  }): Promise<void>;
106
108
  /** Favorites identify email threads as `email_thread`. */
107
109
  readonly entityType = "email_thread";
110
+ /**
111
+ * Share this email thread with a channel's current members, as posting it in the
112
+ * channel does. The caller must be in the channel and able to share the
113
+ * email thread; sharing again changes nothing.
114
+ *
115
+ * @write
116
+ * @idempotent
117
+ */
118
+ shareWithChannel(channel: Channel): Promise<void>;
108
119
  /** The properties service identifies email threads as `THREAD`. */
109
120
  protected readonly propertyEntityType = "THREAD";
110
121
  protected fetch(): Promise<ThreadDetail>;
@@ -122,6 +133,12 @@ export declare class EmailThread extends PropertiedEntity<ThreadDetail> {
122
133
  };
123
134
  /** A handle to a thread by id. Details load on first access. */
124
135
  static byId(client: MacroClient, id: string): EmailThread;
136
+ /**
137
+ * A handle seeded from an inbox preview with the thread columns it carries.
138
+ * Its subject is the latest message's and its times are inbox sort times,
139
+ * so `subject()` and the timestamps still read the thread.
140
+ */
141
+ static fromPreview(client: MacroClient, preview: ApiThreadPreviewCursorInner): EmailThread;
125
142
  /** When the thread was created. */
126
143
  readonly createdAt: () => Promise<string>;
127
144
  /** When the thread was last updated. */
@@ -166,6 +183,12 @@ export declare class EmailThread extends PropertiedEntity<ThreadDetail> {
166
183
  since?: string;
167
184
  limit?: number;
168
185
  }): Promise<EmailMessage[]>;
186
+ /**
187
+ * The unsent drafts among this thread's first 100 messages, from the thread detail.
188
+ *
189
+ * @readonly
190
+ */
191
+ drafts(): Promise<EmailDraft[]>;
169
192
  /**
170
193
  * The attachments across this thread's first 100 messages, pre-seeded from the thread detail.
171
194
  *
@@ -178,7 +201,7 @@ export declare class EmailThread extends PropertiedEntity<ThreadDetail> {
178
201
  * `replyingTo` instead. Returns a handle when the API reports the created
179
202
  * message's id.
180
203
  *
181
- * @destructive
204
+ * @send
182
205
  * @openworld
183
206
  */
184
207
  reply(opts: ReplyEmailOptions): Promise<EmailMessage | undefined>;
@@ -239,7 +262,7 @@ export declare class EmailThread extends PropertiedEntity<ThreadDetail> {
239
262
  * @idempotent
240
263
  */
241
264
  moveToProject(project: Project | null): Promise<void>;
242
- /** Search email threads by subject and content, most relevant first, auto-paginated. */
265
+ /** Search email threads by subject and content, most relevant first, auto-paginated; `maxItems` caps the total. */
243
266
  static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<EmailThread, any, any>;
244
267
  }
245
268
  export {};
@@ -41,6 +41,13 @@ export declare abstract class MacroEntity<Detail> {
41
41
  readonly id: string;
42
42
  protected readonly detail: Lazy<Detail>;
43
43
  protected constructor(client: MacroClient, id: string, seed?: Detail);
44
+ /**
45
+ * Seed fields a listing returned, so {@link field} and {@link mappedField}
46
+ * read them without loading the detail. Map listing fields onto detail keys
47
+ * only where both mean the same thing; leave out anything the listing
48
+ * leaves empty or reports differently. Returns this handle.
49
+ */
50
+ protected withListed(fields: Partial<Detail>): this;
44
51
  /** Load the detail record backing {@link field} accessors. */
45
52
  protected abstract fetch(): Promise<Detail>;
46
53
  /** A lazy accessor for one detail field, `null` normalized to `undefined`. */
@@ -51,6 +58,7 @@ export declare abstract class MacroEntity<Detail> {
51
58
  * `this.mappedField('owner', (id) => User.byId(this.client, id))`.
52
59
  */
53
60
  protected mappedField<K extends keyof Detail, T>(key: K, map: (value: Normalized<Detail[K]>) => T): () => Promise<T>;
61
+ private readDetailField;
54
62
  toJSON(): {
55
63
  id: string;
56
64
  detail?: Detail;
@@ -148,7 +156,8 @@ export declare abstract class PropertiedEntity<Detail> extends FavoritableEntity
148
156
  */
149
157
  updatePropertyOptions(changes: PropertyOptionDelta[]): Promise<BulkUpdateEntityPropertyOptionsResponse>;
150
158
  /**
151
- * Remove a property from this entity, given its {@link properties} entry.
159
+ * Clear one property's value on this item, given its {@link properties}
160
+ * entry; the item itself and the property's definition are kept.
152
161
  *
153
162
  * @destructive
154
163
  * @idempotent
@@ -1,5 +1,6 @@
1
1
  import type { ExternalChatDetail, UpdateSharePermissionRequestV2 } from '../../../generated/storage/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
+ import type { Channel } from '../channels/channel';
3
4
  import { FavoritableEntity } from '../entity';
4
5
  import { User } from '../users/user';
5
6
  import { type WhatsAppCommunity } from '../whatsapp/chat';
@@ -30,6 +31,15 @@ export type ExternalChatContent = {
30
31
  export declare class ExternalChat extends FavoritableEntity<ExternalChatDetail> {
31
32
  /** Canonical sharing and favorites kind. */
32
33
  readonly entityType: "external_chat";
34
+ /**
35
+ * Share this chat with a channel's current members, as posting it in the
36
+ * channel does. The caller must be in the channel and able to share the
37
+ * chat; sharing again changes nothing.
38
+ *
39
+ * @write
40
+ * @idempotent
41
+ */
42
+ shareWithChannel(channel: Channel): Promise<void>;
33
43
  /** Reference an added chat; access is checked on each request. */
34
44
  static byId(client: MacroClient, id: string): ExternalChat;
35
45
  protected fetch(): Promise<ExternalChatDetail>;
@@ -66,12 +76,13 @@ export declare class ExternalChat extends FavoritableEntity<ExternalChatDetail>
66
76
  */
67
77
  community(): Promise<WhatsAppCommunity | undefined>;
68
78
  /**
69
- * Iterate newest-first timeline pages lazily.
79
+ * Iterate newest-first timeline pages lazily; `maxItems` caps the total.
70
80
  *
71
81
  * @readonly
72
82
  */
73
83
  messages(options?: {
74
84
  limit?: number;
85
+ maxItems?: number;
75
86
  }): AsyncGenerator<ExternalChatMessage>;
76
87
  /**
77
88
  * Advance the caller's own read cursor.
@@ -107,7 +118,11 @@ export declare class ExternalChat extends FavoritableEntity<ExternalChatDetail>
107
118
  * @mcp-exclude Takes file bytes; MCP calls carry JSON only.
108
119
  */
109
120
  upload(file: Blob | File): Promise<ExternalChatUpload>;
110
- /** Personal sessions and owner API credentials can send. Bots never send.
121
+ /** Send to the chat; an agent's program must quote the user's reply approving this send in `userConfirmation`, or it is refused (403).
122
+ *
123
+ * Write the message out, ask, and send only after the user says yes; the
124
+ * request that asked for the message is not the approval. Personal sessions
125
+ * and owner API credentials can send. Bots never send.
111
126
  * Preserve the idempotency key; uncertain outcomes are never automatically resent.
112
127
  * The server enforces one request per second per user.
113
128
  *
@@ -117,6 +132,8 @@ export declare class ExternalChat extends FavoritableEntity<ExternalChatDetail>
117
132
  send(content: ExternalChatContent, options: {
118
133
  idempotencyKey: string;
119
134
  replyTo?: ExternalChatMessage;
135
+ /** The user's own reply approving this send, quoted verbatim. Required from an agent's program. */
136
+ userConfirmation?: string;
120
137
  }): Promise<ExternalChatSend>;
121
138
  /**
122
139
  * Read only the caller's pending, uncertain or failed sends.
@@ -27,7 +27,7 @@ export interface GithubPullRequestFacets {
27
27
  labels: GithubLabelFacet[];
28
28
  }
29
29
  /**
30
- * @routing Use when resolving a linked external entity, such as an imported item; not Macro's own items.
30
+ * @routing Use when looking up, favoriting or muting an item linked into Macro from another system, such as a GitHub pull request, by its id in that system; not items created in Macro.
31
31
  */
32
32
  export declare class ForeignEntityNamespace {
33
33
  private readonly client;
@@ -1,5 +1,6 @@
1
- import type { BookingTarget, CellValue, EntityKind, FilterGroup, FilterTest, FormDetail, FormPublicationProblem, ResponseStatus, SharePermissionV2, UnlockedBooking, UpdateForm, UpdateSharePermissionRequestV2, Widget } from '../../../generated/storage/types.gen';
1
+ import type { BookingTarget, CellValue, EntityAppearance, EntityKind, FilterGroup, FilterTest, FormDetail, FormPublicationProblem, ResponseStatus, SharePermissionV2, UnlockedBooking, UpdateForm, UpdateSharePermissionRequestV2, Widget } from '../../../generated/storage/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
+ import type { Channel } from '../channels/channel';
3
4
  import type { DatabaseColumn } from '../databases/column';
4
5
  import { Database } from '../databases/database';
5
6
  import { DatabaseRow } from '../databases/row';
@@ -186,6 +187,15 @@ export declare class Form extends MacroEntity<FormDetail> {
186
187
  schema(): Promise<FormDetail>;
187
188
  /** The form's display name. */
188
189
  readonly name: () => Promise<string>;
190
+ /** Shared icon and color overrides. */
191
+ readonly appearance: () => Promise<EntityAppearance | null | undefined>;
192
+ /**
193
+ * Replace shared appearance. Pass {} to reset both overrides.
194
+ *
195
+ * @write
196
+ * @idempotent
197
+ */
198
+ setAppearance(appearance: EntityAppearance): Promise<EntityAppearance>;
189
199
  /** Introductory text shown to respondents. */
190
200
  readonly description: () => Promise<string>;
191
201
  /** The owning user. */
@@ -202,6 +212,15 @@ export declare class Form extends MacroEntity<FormDetail> {
202
212
  readonly closesAt: () => Promise<string | undefined>;
203
213
  /** The caller's access level. */
204
214
  readonly access: () => Promise<import("../../../generated/storage").FormAccess>;
215
+ /**
216
+ * Share this form with a channel's current members, as posting it in the
217
+ * channel does. The caller must be in the channel and able to share the
218
+ * form; sharing again changes nothing.
219
+ *
220
+ * @write
221
+ * @idempotent
222
+ */
223
+ shareWithChannel(channel: Channel): Promise<void>;
205
224
  /**
206
225
  * Sections in display order.
207
226
  *
@@ -7,7 +7,7 @@ import { DevicePairing, HarnessPairing } from './pairing';
7
7
  /**
8
8
  * Hosts and device pairing. Self operations require host credentials.
9
9
  *
10
- * @routing Use when listing, pairing or removing the machines (hosts) that run the user's agents; not changing an agent persona's setup (`macro.agents`).
10
+ * @routing Use when listing, pairing, renaming or sharing the machines (agent hosts) that run the user's agents, or the agents living on them; not changing an agent persona's setup (`macro.agents`).
11
11
  */
12
12
  export declare class HarnessNamespace {
13
13
  private readonly client;
@@ -13,7 +13,8 @@ export declare class HarnessPairing extends MacroEntity<PairingDetails> {
13
13
  /** Expiration time. */
14
14
  readonly expiresAt: () => Promise<string>;
15
15
  /**
16
- * Approve this pairing.
16
+ * Approve this pairing; refused to an agent's program (ExecuteCode, a
17
+ * routine), so there ask the user to approve it in Settings, Machines.
17
18
  *
18
19
  * @write
19
20
  */
@@ -0,0 +1,65 @@
1
+ import type { ImportEntity as ImportEntryRecord, ImportKind, ImportSource, ImportStatus } from '../../../generated/cognition/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { Channel } from '../channels/channel';
4
+ import { Database } from '../databases/database';
5
+ import { Document } from '../documents/document';
6
+ import { Initiative } from '../initiatives/initiative';
7
+ import { Project } from '../projects/project';
8
+ import { Task } from '../tasks/task';
9
+ import { User } from '../users/user';
10
+ /** The Macro item an import became. */
11
+ export type ImportedItem = Document | Task | Channel | Database | Project | Initiative;
12
+ /**
13
+ * One external item in the import ledger: a Linear or Jira issue, a Notion
14
+ * page or database, or a Slack channel, from the moment it is proposed
15
+ * (`staged`) through `importing` to `imported` (or `discarded`, declined).
16
+ *
17
+ * @mcp-exclude Built from a ledger listing or tracking response; no id-only reference an MCP call can pass.
18
+ */
19
+ export declare class ImportEntry {
20
+ private readonly client;
21
+ private readonly record;
22
+ private constructor();
23
+ /** Wrap a ledger row from an import response. */
24
+ static from(client: MacroClient, record: ImportEntryRecord): ImportEntry;
25
+ /** Ledger row id. */
26
+ get id(): string;
27
+ /** The external system the item comes from. */
28
+ get source(): ImportSource;
29
+ /** What the item is in its source system. */
30
+ get kind(): ImportKind;
31
+ /** The item's stable id in its source system. */
32
+ get foreignId(): string;
33
+ /** Where the entry is in its lifecycle. */
34
+ get status(): ImportStatus;
35
+ /** What the source said about the item (title, URL, …), by source. */
36
+ get metadata(): unknown;
37
+ /** Why the last attempt to import it failed, if one did. */
38
+ get lastError(): string | undefined;
39
+ /** When it was first proposed, RFC 3339. */
40
+ get createdAt(): string;
41
+ /**
42
+ * Who tracked the item: the caller, or the teammate whose import into the
43
+ * team this is.
44
+ *
45
+ * @readonly
46
+ */
47
+ importedBy(): User;
48
+ /**
49
+ * The Macro item the import became; `undefined` until it is imported, or
50
+ * for a kind of item this SDK has no handle for.
51
+ *
52
+ * @readonly
53
+ */
54
+ item(): ImportedItem | undefined;
55
+ /**
56
+ * Decline this staged candidate for the caller: it is remembered as
57
+ * declined and not proposed again. Only the caller's own staged entries can
58
+ * be declined; declining one again is refused.
59
+ *
60
+ * @destructive
61
+ */
62
+ decline(): Promise<void>;
63
+ /** The ledger row, without the authenticated client. */
64
+ toJSON(): ImportEntryRecord;
65
+ }
@@ -0,0 +1,103 @@
1
+ import type { ImportNotionPageResult, ImportSource, ImportStatus, TrackImportOutcome } from '../../../generated/cognition/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { ImportEntry, type ImportedItem } from './entry';
4
+ /** An external item to track in the import ledger. */
5
+ export interface ImportCandidate {
6
+ /** The external system the item comes from. */
7
+ source: ImportSource;
8
+ /**
9
+ * The item's stable id in its source: a Linear identifier such as
10
+ * `ENG-142`, a Notion page URL or id, or a Slack channel id.
11
+ */
12
+ foreignId: string;
13
+ /**
14
+ * What the source says about it. Linear: `{identifier, title,
15
+ * description?, status?, priority?, assignee?, assignee_email?, url?}`;
16
+ * Notion: `{title, url?, summary?}`, never the page content; Slack:
17
+ * `{name, channel_id?, purpose?, participants?}`.
18
+ */
19
+ metadata: Record<string, unknown>;
20
+ }
21
+ /** What tracking an item did, with its ledger entry. */
22
+ export interface TrackedImport {
23
+ /**
24
+ * `staged` or `recorded_imported` when the ledger took it;
25
+ * `already_imported` and `already_imported_by_teammate` mean it exists in
26
+ * Macro (`entry.item()`), so do not create a duplicate;
27
+ * `previously_declined` means skip it; `import_in_progress` means leave it.
28
+ */
29
+ outcome: TrackImportOutcome;
30
+ /** The ledger entry behind the outcome. */
31
+ entry: ImportEntry;
32
+ }
33
+ /** What importing one Notion page did. */
34
+ export interface NotionPageImport {
35
+ /**
36
+ * `imported`, or `already_imported` / `already_imported_by_teammate` when
37
+ * the page was a Macro document before; `previously_declined` and
38
+ * `import_in_progress` imported nothing.
39
+ */
40
+ outcome: ImportNotionPageResult;
41
+ /** The ledger entry; `entry.item()` is the document once imported. */
42
+ entry: ImportEntry;
43
+ }
44
+ /**
45
+ * The import ledger: the external items (Linear and Jira issues, Notion pages,
46
+ * Slack channels) the caller has proposed for import, imported, or declined,
47
+ * with the team's imports. Check it before copying an item into Macro, so
48
+ * nothing is imported twice.
49
+ *
50
+ * @routing Use when tracking one external item being copied into Macro, checking whether it was already imported, or importing one Notion page; not a whole Notion, Linear or Jira workspace, which goes through a reviewed import.
51
+ *
52
+ * @agent
53
+ * Stage an item with `track` before creating anything for it, and stop when
54
+ * the outcome says it already exists, was declined, or is being imported.
55
+ * After creating the Macro item yourself, record it with `recordImported`.
56
+ * Import a single Notion page with `importNotionPage`, never by fetching and
57
+ * recreating it.
58
+ */
59
+ export declare class ImportNamespace {
60
+ private readonly client;
61
+ constructor(client: MacroClient);
62
+ /**
63
+ * The caller's ledger entries, newest first: their staged candidates,
64
+ * running and finished imports (with ones teammates imported into the
65
+ * team), and declined items.
66
+ *
67
+ * @readonly
68
+ */
69
+ list(options?: {
70
+ source?: ImportSource;
71
+ status?: ImportStatus;
72
+ }): Promise<ImportEntry[]>;
73
+ /**
74
+ * Propose an external item for import, before creating anything for it.
75
+ * The outcome says when it was already imported, declined or is being
76
+ * imported; then do not create it.
77
+ *
78
+ * @write
79
+ * @idempotent
80
+ */
81
+ track(candidate: ImportCandidate): Promise<TrackedImport>;
82
+ /**
83
+ * Record that `item` was created in Macro from the external item, so it is
84
+ * not imported again. The ledger stores each source's kind of item: a task
85
+ * for Linear and Jira, a document for Notion and a channel for Slack, and
86
+ * any other handle is refused. An earlier mapping wins: the outcome is then
87
+ * `already_imported` and `entry.item()` is the item recorded first.
88
+ *
89
+ * @write
90
+ * @idempotent
91
+ */
92
+ recordImported(candidate: ImportCandidate, item: ImportedItem): Promise<TrackedImport>;
93
+ /**
94
+ * Import one Notion page as a Macro document through the caller's Notion
95
+ * connection, deduplicated against the ledger. Notion databases are not
96
+ * imported; import a whole workspace through a reviewed import instead.
97
+ *
98
+ * @write
99
+ * @openworld
100
+ */
101
+ importNotionPage(page: string): Promise<NotionPageImport>;
102
+ private trackAs;
103
+ }
@@ -0,0 +1 @@
1
+ import '../../macro';