@macro-inc/sdk 0.4.0 → 0.5.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 (193) hide show
  1. package/CALLS.md +82 -0
  2. package/README.md +176 -7
  3. package/dist/chunk-2IVGAIGQ.js +80 -0
  4. package/dist/{chunk-PTX2RV2N.js → chunk-3SW6QVDV.js} +33 -0
  5. package/dist/{chunk-XFA7NCJ5.js → chunk-GT5EUYOR.js} +13 -15
  6. package/dist/{chunk-ZLBDES7U.js → chunk-HIW6KU2I.js} +490 -4
  7. package/dist/{chunk-AZJUIUIV.js → chunk-J2VK3NOR.js} +56 -0
  8. package/dist/{chunk-PZPTJI6F.js → chunk-UVJLWLSJ.js} +41 -2
  9. package/dist/generated/agent-fold/index.d.ts +8 -6
  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 +17 -1
  13. package/dist/generated/agent-harness/types.gen.d.ts +188 -3
  14. package/dist/generated/auth/index.js +1 -1
  15. package/dist/generated/auth/sdk.gen.d.ts +13 -15
  16. package/dist/generated/auth/types.gen.d.ts +36 -17
  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 +38 -1
  20. package/dist/generated/cognition/types.gen.d.ts +473 -4
  21. package/dist/generated/connection/types.gen.d.ts +1 -1
  22. package/dist/generated/notification/index.d.ts +1 -1
  23. package/dist/generated/notification/types.gen.d.ts +36 -1
  24. package/dist/generated/scheduled-action/index.d.ts +1 -1
  25. package/dist/generated/scheduled-action/index.js +1 -1
  26. package/dist/generated/scheduled-action/sdk.gen.d.ts +17 -2
  27. package/dist/generated/scheduled-action/types.gen.d.ts +642 -104
  28. package/dist/generated/storage/index.d.ts +1 -1
  29. package/dist/generated/storage/index.js +1 -1
  30. package/dist/generated/storage/sdk.gen.d.ts +204 -5
  31. package/dist/generated/storage/types.gen.d.ts +3969 -374
  32. package/dist/src/calls/browser.d.ts +14 -0
  33. package/dist/src/calls/browser.js +102 -0
  34. package/dist/src/calls/common.d.ts +18 -0
  35. package/dist/src/calls/node.d.ts +24 -0
  36. package/dist/src/calls/node.js +145 -0
  37. package/dist/src/calls/telemetry.d.ts +5 -0
  38. package/dist/src/entities/account-managers/grant.d.ts +28 -5
  39. package/dist/src/entities/account-managers/namespace.d.ts +15 -3
  40. package/dist/src/entities/activity/entity.d.ts +7 -0
  41. package/dist/src/entities/activity/namespace.d.ts +58 -0
  42. package/dist/src/entities/activity/namespace.test.d.ts +1 -0
  43. package/dist/src/entities/agent-sessions/activity.d.ts +10 -2
  44. package/dist/src/entities/agent-sessions/agent-session.d.ts +193 -18
  45. package/dist/src/entities/agent-sessions/code-execution.d.ts +15 -3
  46. package/dist/src/entities/agent-sessions/conversation.d.ts +46 -9
  47. package/dist/src/entities/agent-sessions/namespace.d.ts +71 -16
  48. package/dist/src/entities/agent-sessions/origin.d.ts +1 -1
  49. package/dist/src/entities/agent-sessions/queued-action.d.ts +17 -3
  50. package/dist/src/entities/agent-sessions/review.d.ts +55 -4
  51. package/dist/src/entities/agent-sessions/tool-approval.d.ts +5 -1
  52. package/dist/src/entities/agents/agent.d.ts +98 -3
  53. package/dist/src/entities/agents/namespace.d.ts +52 -8
  54. package/dist/src/entities/ai/namespace.d.ts +9 -1
  55. package/dist/src/entities/api-keys/api-key.d.ts +6 -1
  56. package/dist/src/entities/api-keys/namespace.d.ts +15 -3
  57. package/dist/src/entities/bots/bot.d.ts +38 -6
  58. package/dist/src/entities/bots/namespace.d.ts +13 -1
  59. package/dist/src/entities/bots/token.d.ts +6 -1
  60. package/dist/src/entities/calendar/booking-link.d.ts +7 -1
  61. package/dist/src/entities/calendar/booking-namespace.d.ts +13 -0
  62. package/dist/src/entities/calendar/booking.d.ts +15 -0
  63. package/dist/src/entities/calendar/calendar.d.ts +7 -1
  64. package/dist/src/entities/calendar/event.d.ts +59 -9
  65. package/dist/src/entities/calendar/namespace.d.ts +88 -10
  66. package/dist/src/entities/calendar/replacement.d.ts +19 -3
  67. package/dist/src/entities/calls/call-record.d.ts +90 -14
  68. package/dist/src/entities/calls/connection.d.ts +7 -1
  69. package/dist/src/entities/calls/message.d.ts +27 -5
  70. package/dist/src/entities/calls/namespace.d.ts +15 -3
  71. package/dist/src/entities/canvases/canvas.d.ts +324 -0
  72. package/dist/src/entities/channels/access-request.d.ts +10 -2
  73. package/dist/src/entities/channels/activity.d.ts +20 -4
  74. package/dist/src/entities/channels/channel.d.ts +130 -23
  75. package/dist/src/entities/channels/labels.d.ts +41 -7
  76. package/dist/src/entities/channels/message.d.ts +41 -7
  77. package/dist/src/entities/channels/namespace.d.ts +28 -3
  78. package/dist/src/entities/channels/post.test.d.ts +1 -0
  79. package/dist/src/entities/channels/thread.d.ts +19 -3
  80. package/dist/src/entities/chats/chat.d.ts +56 -6
  81. package/dist/src/entities/chats/generation.d.ts +11 -2
  82. package/dist/src/entities/chats/namespace.d.ts +10 -2
  83. package/dist/src/entities/connected-apps/connected-app.d.ts +14 -1
  84. package/dist/src/entities/connected-apps/connector.d.ts +3 -0
  85. package/dist/src/entities/connected-apps/namespace.d.ts +16 -0
  86. package/dist/src/entities/crm/company.d.ts +63 -15
  87. package/dist/src/entities/crm/contact.d.ts +60 -13
  88. package/dist/src/entities/crm/namespace.d.ts +85 -11
  89. package/dist/src/entities/crm/pipeline-entry.d.ts +102 -0
  90. package/dist/src/entities/crm/pipeline.d.ts +271 -27
  91. package/dist/src/entities/crm/pipelines.d.ts +39 -2
  92. package/dist/src/entities/databases/column.d.ts +54 -7
  93. package/dist/src/entities/databases/database.d.ts +126 -12
  94. package/dist/src/entities/databases/namespace.d.ts +16 -4
  95. package/dist/src/entities/databases/row.d.ts +2 -0
  96. package/dist/src/entities/databases/saved-query.d.ts +145 -0
  97. package/dist/src/entities/databases/table.d.ts +64 -10
  98. package/dist/src/entities/databases/view.d.ts +27 -5
  99. package/dist/src/entities/databases/webhook.d.ts +8 -1
  100. package/dist/src/entities/documents/ai-edit.d.ts +2 -0
  101. package/dist/src/entities/documents/anchor.d.ts +12 -2
  102. package/dist/src/entities/documents/comment.d.ts +29 -5
  103. package/dist/src/entities/documents/document.d.ts +243 -20
  104. package/dist/src/entities/documents/markdown.d.ts +25 -0
  105. package/dist/src/entities/documents/namespace.d.ts +132 -13
  106. package/dist/src/entities/documents/skills.test.d.ts +1 -0
  107. package/dist/src/entities/documents/system-skill.d.ts +21 -1
  108. package/dist/src/entities/documents/text-comment.d.ts +41 -0
  109. package/dist/src/entities/documents/text-comment.test.d.ts +1 -0
  110. package/dist/src/entities/documents/version.d.ts +5 -1
  111. package/dist/src/entities/email/attachment.d.ts +3 -0
  112. package/dist/src/entities/email/draft.d.ts +61 -9
  113. package/dist/src/entities/email/filter.d.ts +12 -2
  114. package/dist/src/entities/email/label.d.ts +7 -1
  115. package/dist/src/entities/email/link.d.ts +5 -1
  116. package/dist/src/entities/email/message.d.ts +55 -8
  117. package/dist/src/entities/email/namespace.d.ts +127 -21
  118. package/dist/src/entities/email/thread.d.ts +99 -16
  119. package/dist/src/entities/entity-mentions/mention.d.ts +6 -1
  120. package/dist/src/entities/entity-mentions/namespace.d.ts +5 -1
  121. package/dist/src/entities/entity.d.ts +56 -6
  122. package/dist/src/entities/external-chat/chat.d.ts +62 -11
  123. package/dist/src/entities/external-chat/message.d.ts +1 -1
  124. package/dist/src/entities/external-chat/namespace.d.ts +5 -1
  125. package/dist/src/entities/external-chat/send.d.ts +10 -2
  126. package/dist/src/entities/favorites/namespace.d.ts +20 -3
  127. package/dist/src/entities/foreign/foreign-entity.d.ts +5 -1
  128. package/dist/src/entities/foreign/namespace.d.ts +4 -0
  129. package/dist/src/entities/forms/form.d.ts +71 -13
  130. package/dist/src/entities/forms/namespace.d.ts +10 -2
  131. package/dist/src/entities/forms/question.d.ts +35 -7
  132. package/dist/src/entities/forms/response.d.ts +25 -5
  133. package/dist/src/entities/forms/section.d.ts +15 -3
  134. package/dist/src/entities/github-pull-requests/namespace.d.ts +5 -1
  135. package/dist/src/entities/github-pull-requests/pull-request.d.ts +15 -3
  136. package/dist/src/entities/harnesses/harness.d.ts +51 -3
  137. package/dist/src/entities/harnesses/namespace.d.ts +53 -7
  138. package/dist/src/entities/harnesses/pairing.d.ts +12 -2
  139. package/dist/src/entities/images/image.d.ts +16 -5
  140. package/dist/src/entities/images/namespace.d.ts +8 -1
  141. package/dist/src/entities/initiatives/initiative.d.ts +117 -3
  142. package/dist/src/entities/initiatives/initiative.test.d.ts +1 -0
  143. package/dist/src/entities/initiatives/namespace.d.ts +69 -7
  144. package/dist/src/entities/me/namespace.d.ts +27 -2
  145. package/dist/src/entities/meetings/meeting.d.ts +45 -8
  146. package/dist/src/entities/meetings/namespace.d.ts +20 -4
  147. package/dist/src/entities/memory/namespace.d.ts +49 -0
  148. package/dist/src/entities/memory/namespace.test.d.ts +1 -0
  149. package/dist/src/entities/messages/discussion.d.ts +84 -0
  150. package/dist/src/entities/messages/thread.d.ts +19 -5
  151. package/dist/src/entities/notifications/namespace.d.ts +40 -7
  152. package/dist/src/entities/notifications/notification.d.ts +29 -5
  153. package/dist/src/entities/pins/namespace.d.ts +23 -4
  154. package/dist/src/entities/projects/namespace.d.ts +29 -0
  155. package/dist/src/entities/projects/project.d.ts +47 -6
  156. package/dist/src/entities/properties/namespace.d.ts +67 -11
  157. package/dist/src/entities/properties/namespace.test.d.ts +1 -0
  158. package/dist/src/entities/properties/property-definition.d.ts +30 -5
  159. package/dist/src/entities/properties/property-option.d.ts +14 -2
  160. package/dist/src/entities/referrals/namespace.d.ts +8 -1
  161. package/dist/src/entities/routines/namespace.d.ts +128 -7
  162. package/dist/src/entities/routines/routine.d.ts +111 -25
  163. package/dist/src/entities/saved-views/namespace.d.ts +57 -0
  164. package/dist/src/entities/saved-views/saved-view.d.ts +78 -0
  165. package/dist/src/entities/search/namespace.d.ts +5 -1
  166. package/dist/src/entities/sharing/access.d.ts +50 -9
  167. package/dist/src/entities/spreadsheets/spreadsheet.d.ts +201 -0
  168. package/dist/src/entities/tasks/namespace.d.ts +13 -1
  169. package/dist/src/entities/tasks/task.d.ts +7 -1
  170. package/dist/src/entities/teams/invite.d.ts +3 -0
  171. package/dist/src/entities/teams/namespace.d.ts +10 -2
  172. package/dist/src/entities/teams/team.d.ts +7 -0
  173. package/dist/src/entities/unfurls/namespace.d.ts +12 -2
  174. package/dist/src/entities/users/namespace.d.ts +19 -1
  175. package/dist/src/entities/users/profile-picture.d.ts +29 -0
  176. package/dist/src/entities/users/profile-picture.test.d.ts +1 -0
  177. package/dist/src/entities/users/user.d.ts +52 -1
  178. package/dist/src/entities/web/namespace.d.ts +6 -0
  179. package/dist/src/entities/webhooks/namespace.d.ts +5 -0
  180. package/dist/src/entities/webhooks/webhook.d.ts +47 -7
  181. package/dist/src/entities/whatsapp/account.d.ts +5 -1
  182. package/dist/src/entities/whatsapp/chat.d.ts +9 -1
  183. package/dist/src/entities/whatsapp/namespace.d.ts +7 -1
  184. package/dist/src/entities/workspace/namespace.d.ts +7 -1
  185. package/dist/src/entities/workspace/query.d.ts +5 -1
  186. package/dist/src/events/hydrate/user.d.ts +14 -0
  187. package/dist/src/events/receiver.d.ts +2 -0
  188. package/dist/src/events/types.d.ts +2 -1
  189. package/dist/src/macro.d.ts +33 -5
  190. package/dist/src/macro.js +15635 -10132
  191. package/dist/src/utils/lazy.d.ts +7 -1
  192. package/package.json +32 -5
  193. package/dist/src/entities/crm/comment.d.ts +0 -64
@@ -24,6 +24,8 @@ export declare class TaskNamespace {
24
24
  /**
25
25
  * Create a task, with its initiative, assignees and due date in the same
26
26
  * request. The task starts Not started.
27
+ *
28
+ * @write
27
29
  */
28
30
  create(opts: {
29
31
  name: string;
@@ -43,6 +45,8 @@ export declare class TaskNamespace {
43
45
  /**
44
46
  * Names and state of many tasks in one request, in the order given. Tasks
45
47
  * that no longer exist are left out.
48
+ *
49
+ * @readonly
46
50
  */
47
51
  summaries(tasks: Task[]): Promise<TaskSummary[]>;
48
52
  /**
@@ -50,6 +54,8 @@ export declare class TaskNamespace {
50
54
  * task with this title and body, most similar first. Call it in the same
51
55
  * program as `create`: create only when nothing is a likely duplicate, and
52
56
  * otherwise return the matches and ask the user instead of creating.
57
+ *
58
+ * @readonly
53
59
  */
54
60
  findSimilar(opts: {
55
61
  title: string;
@@ -57,8 +63,14 @@ export declare class TaskNamespace {
57
63
  }): Promise<SimilarTask[]>;
58
64
  /**
59
65
  * The tasks the GitHub pull request at `url` references, oldest link first.
66
+ *
67
+ * @readonly
60
68
  */
61
69
  forPullRequest(url: string): Promise<Task[]>;
62
- /** Search tasks by name and content, most relevant first, auto-paginated. */
70
+ /**
71
+ * Search tasks by name and content, most relevant first, auto-paginated.
72
+ *
73
+ * @readonly
74
+ */
63
75
  search(query: string, opts?: SearchOpts): AsyncGenerator<Task>;
64
76
  }
@@ -72,9 +72,15 @@ export declare class Task extends Document {
72
72
  /**
73
73
  * Whether the task is completed (its Status property is "Completed");
74
74
  * `undefined` if the document is not a task.
75
+ *
76
+ * @readonly
75
77
  */
76
78
  completed(): Promise<boolean | undefined>;
77
- /** The task's URL in the Macro web app. */
79
+ /**
80
+ * The task's URL in the Macro web app.
81
+ *
82
+ * @readonly
83
+ */
78
84
  webUrl(): string;
79
85
  /** Search tasks by name and content, most relevant first, auto-paginated. */
80
86
  static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<Task, any, any>;
@@ -25,6 +25,9 @@ export declare class TeamInvite extends MacroEntity<TeamInviteDetails> {
25
25
  /**
26
26
  * Revoke this invite so it can no longer be accepted; only a team admin or
27
27
  * owner may revoke.
28
+ *
29
+ * @destructive
30
+ * @idempotent
28
31
  */
29
32
  revoke(): Promise<void>;
30
33
  }
@@ -8,8 +8,16 @@ export declare class TeamNamespace {
8
8
  constructor(client: MacroClient);
9
9
  /** A handle to a team by id. */
10
10
  byId(id: string): Team;
11
- /** The caller's current team. */
11
+ /**
12
+ * The caller's current team.
13
+ *
14
+ * @readonly
15
+ */
12
16
  current(): Promise<Team>;
13
- /** The teams the caller belongs to. */
17
+ /**
18
+ * The teams the caller belongs to.
19
+ *
20
+ * @readonly
21
+ */
14
22
  list(): Promise<Team[]>;
15
23
  }
@@ -36,6 +36,8 @@ export declare class Team extends MacroEntity<TeamRecord> {
36
36
  /**
37
37
  * The team's members, with their roles. The API only exposes members for
38
38
  * the caller's current team, so this rejects for any other team.
39
+ *
40
+ * @readonly
39
41
  */
40
42
  members(): Promise<TeamMembership[]>;
41
43
  /**
@@ -62,6 +64,9 @@ export declare class Team extends MacroEntity<TeamRecord> {
62
64
  * @param options - `agent` invites the addresses as agents.
63
65
  * @returns `true` when at least one new invite was sent, `false` when every
64
66
  * address was already a member or already invited.
67
+ *
68
+ * @destructive
69
+ * @openworld
65
70
  */
66
71
  invite(emails: string | readonly string[], options?: {
67
72
  agent?: boolean;
@@ -70,6 +75,8 @@ export declare class Team extends MacroEntity<TeamRecord> {
70
75
  * Pending invites to this team; only a team admin or owner may list them.
71
76
  * Only the caller's current team lists invites (see `Team.current`); the
72
77
  * API refuses any other team with a 409.
78
+ *
79
+ * @readonly
73
80
  */
74
81
  invites(): Promise<TeamInvite[]>;
75
82
  /** The caller's current team record, rejecting when this is another team. */
@@ -7,8 +7,18 @@ import type { MacroClient } from '../../utils/client';
7
7
  export declare class UnfurlNamespace {
8
8
  private readonly client;
9
9
  constructor(client: MacroClient);
10
- /** Read title, description and preview metadata for a URL. */
10
+ /**
11
+ * Read title, description and preview metadata for a URL.
12
+ *
13
+ * @readonly
14
+ * @openworld
15
+ */
11
16
  get(url: string): Promise<import("../../../generated/unfurl").GetUnfurlResponse>;
12
- /** Read metadata for multiple URLs in one request. */
17
+ /**
18
+ * Read metadata for multiple URLs in one request.
19
+ *
20
+ * @readonly
21
+ * @openworld
22
+ */
13
23
  bulk(urls: string[]): Promise<import("../../../generated/unfurl").GetUnfurlBulkResponse>;
14
24
  }
@@ -1,4 +1,5 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
+ import { type ProfilePicture } from './profile-picture';
2
3
  import { User } from './user';
3
4
  /**
4
5
  * @routing Use when looking up people or their profiles; not team membership, or changing the user's own profile (`macro.me`).
@@ -8,12 +9,29 @@ export declare class UserNamespace {
8
9
  constructor(client: MacroClient);
9
10
  /** A handle to a user by id. */
10
11
  byId(id: string): User;
11
- /** The current authenticated user. */
12
+ /**
13
+ * The current authenticated user.
14
+ *
15
+ * @readonly
16
+ */
12
17
  me(): Promise<User>;
18
+ /**
19
+ * Current profile pictures for several users in one request. Users without
20
+ * a picture are absent from the map.
21
+ *
22
+ * @example
23
+ * const pictures = await macro.users.profilePictures(teammates);
24
+ * const mine = pictures.get(teammates[0]);
25
+ *
26
+ * @readonly
27
+ */
28
+ profilePictures(users: User[]): Promise<Map<User, ProfilePicture>>;
13
29
  /**
14
30
  * Find people in your existing Macro contacts by name or email, as in the
15
31
  * mention picker. This is not a global directory. Returns every matching
16
32
  * contact so callers can disambiguate; it never chooses a person for you.
33
+ *
34
+ * @readonly
17
35
  */
18
36
  search(query: string): Promise<User[]>;
19
37
  }
@@ -0,0 +1,29 @@
1
+ import type { UserProfilePicture } from '../../../generated/auth/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { StaticImage } from '../images/image';
4
+ /**
5
+ * A profile picture that is not in static file storage: an older picture
6
+ * stored as a plain URL (such as a sign-in provider's avatar). It can be shown
7
+ * but not passed to `macro.me.update()`.
8
+ */
9
+ export declare class ExternalProfilePicture {
10
+ /** URL of the image bytes. */
11
+ readonly url: string;
12
+ /** @internal */
13
+ constructor(
14
+ /** URL of the image bytes. */
15
+ url: string);
16
+ /** Serialize the picture URL. */
17
+ toJSON(): {
18
+ url: string;
19
+ };
20
+ }
21
+ /**
22
+ * A user's profile picture. Pictures set through Macro are a
23
+ * {@link StaticImage}; older pictures stored as a bare URL are an
24
+ * {@link ExternalProfilePicture}. Narrow with `instanceof StaticImage`; both
25
+ * have a `url`.
26
+ */
27
+ export type ProfilePicture = StaticImage | ExternalProfilePicture;
28
+ /** Read a picture row; an empty URL means the user has no picture. */
29
+ export declare function toProfilePicture(client: MacroClient, row: UserProfilePicture | undefined): ProfilePicture | undefined;
@@ -0,0 +1 @@
1
+ export {};
@@ -1,8 +1,12 @@
1
1
  import type { UserName } from '../../../generated/auth/types.gen';
2
+ import type { Activity } from '../../../generated/cognition/types.gen';
2
3
  import { type Mentionable, type MentionPart } from '../../mentions';
3
4
  import type { MacroClient } from '../../utils/client';
4
5
  import { Channel } from '../channels/channel';
5
6
  import { PropertiedEntity } from '../entity';
7
+ import { type ProfilePicture } from './profile-picture';
8
+ /** A privacy-reviewed summary of a user's professional work over one period. */
9
+ export type ActivityReport = Activity;
6
10
  /**
7
11
  * A Macro user. Identity lives in the auth service, so details like the
8
12
  * display name are fetched on demand. Can be dropped into a {@link msg}
@@ -25,12 +29,29 @@ export declare class User extends PropertiedEntity<UserName> implements Mentiona
25
29
  * your email contacts when the Macro profile has none).
26
30
  *
27
31
  * @returns The full name, or `undefined` if the user has no name on record.
32
+ *
33
+ * @readonly
28
34
  */
29
35
  name(): Promise<string | undefined>;
36
+ /**
37
+ * This user's current profile picture. Reads the auth service every time,
38
+ * so it reflects a recent change.
39
+ *
40
+ * A picture set through Macro is a `StaticImage`; an older picture stored as
41
+ * a bare URL is an `ExternalProfilePicture`. For many users at once use
42
+ * `macro.users.profilePictures`.
43
+ *
44
+ * @returns The picture, or `undefined` if the user has none.
45
+ *
46
+ * @readonly
47
+ */
48
+ profilePicture(): Promise<ProfilePicture | undefined>;
30
49
  /**
31
50
  * Whether this user is an agent account rather than a person.
32
51
  *
33
52
  * @returns `true` for an agent account.
53
+ *
54
+ * @readonly
34
55
  */
35
56
  isAgent(): Promise<boolean>;
36
57
  /**
@@ -39,13 +60,43 @@ export declare class User extends PropertiedEntity<UserName> implements Mentiona
39
60
  * emails for arbitrary users.
40
61
  *
41
62
  * @returns The email, or `undefined` if the id is not email-derived.
63
+ *
64
+ * @readonly
42
65
  */
43
66
  email(): string | undefined;
44
67
  /**
45
- * Open (or create) your direct-message channel with this user.
68
+ * Open (or create) your 1:1 direct-message channel with this user. For a
69
+ * group DM, use `macro.channels.private(users)`.
46
70
  *
47
71
  * @returns The DM `Channel`.
72
+ *
73
+ * @write
74
+ * @idempotent
48
75
  */
49
76
  dm(): Promise<Channel>;
77
+ /**
78
+ * Privacy-reviewed summaries of this user's work in an inclusive UTC date
79
+ * range, for yourself or a current teammate; at most 366 days.
80
+ *
81
+ * Reports are daily, Monday-start weekly, monthly and a running summary.
82
+ * An empty list means nothing was summarized yet, not that no work happened.
83
+ * Anyone outside the caller's current teams fails with 403.
84
+ *
85
+ * @example
86
+ * const me = await macro.users.me();
87
+ * const reports = await me.activity({ start: '2026-10-01', end: '2026-10-31' });
88
+ * const weeks = reports.filter((report) => report.granularity === 'week');
89
+ *
90
+ * @readonly
91
+ */
92
+ activity(range: {
93
+ start: Date | string;
94
+ end: Date | string;
95
+ }): Promise<ActivityReport[]>;
96
+ /**
97
+ * This user as an @-mention part for a message template.
98
+ *
99
+ * @readonly
100
+ */
50
101
  toMention(): MentionPart;
51
102
  }
@@ -45,6 +45,9 @@ export declare class WebNamespace {
45
45
  * maxResults: 3,
46
46
  * });
47
47
  * for (const result of results) console.log(result.title, result.url, result.snippet);
48
+ *
49
+ * @write
50
+ * @openworld
48
51
  */
49
52
  search(query: string, options?: WebSearchOptions): Promise<{
50
53
  results: WebSearchResult[];
@@ -56,6 +59,9 @@ export declare class WebNamespace {
56
59
  * @example
57
60
  * const page = await macro.web.fetch('https://tokio.rs/blog/2025-10-tokio-1-48');
58
61
  * console.log(page.content);
62
+ *
63
+ * @write
64
+ * @openworld
59
65
  */
60
66
  fetch(url: string, options?: WebFetchOptions): Promise<WebFetchResponse>;
61
67
  }
@@ -14,6 +14,9 @@ export declare class WebhooksNamespace {
14
14
  * workspace's webhooks (the endpoint returns 409 on a clash) and cannot be
15
15
  * changed later. `filters` must be non-empty (each entry matches event
16
16
  * names, optionally narrowed to entity ids); `scope` defaults to `'user'`.
17
+ *
18
+ * @write
19
+ * @openworld
17
20
  */
18
21
  create(opts: {
19
22
  url: string;
@@ -28,6 +31,8 @@ export declare class WebhooksNamespace {
28
31
  /**
29
32
  * The caller's webhooks across their personal and team workspaces, newest
30
33
  * first. Each returned handle already holds its record.
34
+ *
35
+ * @readonly
31
36
  */
32
37
  list(): Promise<Webhook[]>;
33
38
  }
@@ -65,26 +65,66 @@ export declare class Webhook extends MacroEntity<WebhookRecord> {
65
65
  * their team (`team`). Derived from ownership: a personal webhook's owning
66
66
  * workspace is the creator's own user id, whereas a team webhook's workspace
67
67
  * is a distinct team id.
68
+ *
69
+ * @readonly
68
70
  */
69
71
  scope(): Promise<WebhookScope>;
70
- /** Update the webhook. */
72
+ /**
73
+ * Update the webhook.
74
+ *
75
+ * @write
76
+ * @idempotent
77
+ */
71
78
  update(body: PatchWebhookRequest): Promise<void>;
72
- /** Rename the webhook. */
79
+ /**
80
+ * Rename the webhook.
81
+ *
82
+ * @write
83
+ * @idempotent
84
+ */
73
85
  rename(name: string): Promise<void>;
74
- /** Point the webhook at a new HTTPS endpoint URL. */
86
+ /**
87
+ * Point the webhook at a new HTTPS endpoint URL.
88
+ *
89
+ * @write
90
+ * @idempotent
91
+ */
75
92
  setUrl(url: string): Promise<void>;
76
- /** Replace the webhook's delivery filters (must be non-empty). */
93
+ /**
94
+ * Replace the webhook's delivery filters (must be non-empty).
95
+ *
96
+ * @write
97
+ * @idempotent
98
+ */
77
99
  setFilters(filters: WebhookFilter[]): Promise<void>;
78
- /** Pause deliveries. */
100
+ /**
101
+ * Pause deliveries.
102
+ *
103
+ * @write
104
+ * @idempotent
105
+ */
79
106
  pause(): Promise<void>;
80
- /** Resume deliveries. */
107
+ /**
108
+ * Resume deliveries.
109
+ *
110
+ * @write
111
+ * @idempotent
112
+ */
81
113
  resume(): Promise<void>;
82
- /** Delete the webhook. */
114
+ /**
115
+ * Delete the webhook.
116
+ *
117
+ * @destructive
118
+ * @idempotent
119
+ */
83
120
  delete(): Promise<void>;
84
121
  /**
85
122
  * Send a signed validation test delivery to the endpoint and report whether
86
123
  * it was accepted. Drops the cached detail so a subsequent {@link isValid}
87
124
  * read reflects the new validation state.
125
+ *
126
+ * @write
127
+ * @openworld
88
128
  */
89
129
  validate(): Promise<ValidateWebhookResponse>;
90
130
  }
@@ -15,6 +15,10 @@ export declare class WhatsAppAccount extends MacroEntity<WhatsAppAccountRecord>
15
15
  readonly identity: () => Promise<string | undefined>;
16
16
  /** The Macro user who owns this account. */
17
17
  readonly owner: () => Promise<User>;
18
- /** Discard cached connection state and load its current value. */
18
+ /**
19
+ * Discard cached connection state and load its current value.
20
+ *
21
+ * @readonly
22
+ */
19
23
  refresh(): Promise<this>;
20
24
  }
@@ -47,8 +47,16 @@ export declare class WhatsAppChat extends MacroEntity<WhatsAppChatRecord> {
47
47
  * own external chat; its earlier messages are imported from the phone.
48
48
  * Adding it again returns the same chat. Only the owner sends in a direct
49
49
  * chat.
50
+ *
51
+ * @write
52
+ * @idempotent
53
+ * @openworld
50
54
  */
51
55
  add(): Promise<ExternalChat>;
52
- /** Reload the chat's list entry. */
56
+ /**
57
+ * Reload the chat's list entry.
58
+ *
59
+ * @readonly
60
+ */
53
61
  refresh(): Promise<this>;
54
62
  }
@@ -12,12 +12,18 @@ export declare class WhatsAppNamespace {
12
12
  private readonly client;
13
13
  /** Bind existing-account operations to this authenticated client. */
14
14
  constructor(client: MacroClient);
15
- /** Current owner's account, or undefined when no account has been connected. */
15
+ /**
16
+ * Current owner's account, or undefined when no account has been connected.
17
+ *
18
+ * @readonly
19
+ */
16
20
  account(): Promise<WhatsAppAccount | undefined>;
17
21
  /**
18
22
  * The caller's WhatsApp chat list (groups and direct chats), newest
19
23
  * activity first: each chat says whether it is added, shared with the caller
20
24
  * or addable, and `chat.add()` adds it.
25
+ *
26
+ * @readonly
21
27
  */
22
28
  chats(): Promise<WhatsAppChat[]>;
23
29
  }
@@ -75,13 +75,19 @@ import type { WorkspaceItem, WorkspaceListOptions, WorkspacePage, WorkspacePageO
75
75
  export declare class WorkspaceNamespace {
76
76
  private readonly client;
77
77
  constructor(client: MacroClient);
78
- /** One bounded page of recent items, newest first by default; resume using nextCursor and the same options. */
78
+ /**
79
+ * One bounded page of recent items, newest first by default; resume using nextCursor and the same options.
80
+ *
81
+ * @readonly
82
+ */
79
83
  page(options?: WorkspacePageOptions): Promise<WorkspacePage>;
80
84
  /**
81
85
  * Every matching item, newest first by default, auto-paginated. `limit` is a
82
86
  * page size, not a total result limit.
83
87
  * Break a `for await` loop to stop; no speculative next page is fetched.
84
88
  * Tag/inbox resolution is reused within this iterator.
89
+ *
90
+ * @readonly
85
91
  */
86
92
  list(options?: WorkspaceListOptions): AsyncGenerator<WorkspaceItem>;
87
93
  private fetch;
@@ -12,7 +12,11 @@ type ResolvedTag = WorkspaceTag & {
12
12
  id: string;
13
13
  definitionId: string;
14
14
  };
15
- /** @internal */
15
+ /**
16
+ * @internal
17
+ *
18
+ * @mcp-exclude Internal query-building helper, not reachable from the `Macro` client.
19
+ */
16
20
  export declare class WorkspaceQuery {
17
21
  private readonly client;
18
22
  private tagSets?;
@@ -0,0 +1,14 @@
1
+ import { StaticImage } from '../../entities/images/image';
2
+ import { User } from '../../entities/users/user';
3
+ import type { MacroClient } from '../../utils/client';
4
+ import type { MacroEvent } from '../types';
5
+ export type UserEvent = Extract<MacroEvent, {
6
+ event_type: `user.${string}`;
7
+ }>;
8
+ /** Attach SDK entity handles to a user webhook event. */
9
+ export declare function hydrateUserEvent(client: MacroClient, event: UserEvent): {
10
+ event_type: "user.picture_changed";
11
+ metadata: import("../../../generated/storage").UserPictureChangedMetadata;
12
+ user: User;
13
+ image: StaticImage | undefined;
14
+ } | undefined;
@@ -23,6 +23,8 @@ export interface ListenOptions {
23
23
  * {@link MacroEvents.webhook} at a persisted webhook URL.
24
24
  *
25
25
  * Obtain via `macro.events` — do not construct directly.
26
+ *
27
+ * @mcp-exclude Registers live event handlers and listeners; MCP calls carry JSON only.
26
28
  */
27
29
  export declare class MacroEvents {
28
30
  private readonly client;
@@ -4,6 +4,7 @@ import type { hydrateCallEvent } from './hydrate/call';
4
4
  import type { hydrateChannelEvent } from './hydrate/channel';
5
5
  import type { hydrateDocumentEvent } from './hydrate/document';
6
6
  import type { hydrateMessageEvent } from './hydrate/message';
7
+ import type { hydrateUserEvent } from './hydrate/user';
7
8
  /** A webhook delivery body, exactly as Macro serializes it. */
8
9
  export type MacroEvent = WebhookEvent;
9
10
  /** Every entity event name Macro can deliver. */
@@ -19,7 +20,7 @@ export type EventPayload<E extends EventName> = Extract<MacroEvent, {
19
20
  * ride along with which event — this reads their inferred return types back
20
21
  * rather than restating the mapping.
21
22
  */
22
- type HydratedEvent = ReturnType<typeof hydrateAgentSessionEvent> | ReturnType<typeof hydrateChannelEvent> | ReturnType<typeof hydrateCallEvent> | ReturnType<typeof hydrateDocumentEvent> | ReturnType<typeof hydrateMessageEvent>;
23
+ type HydratedEvent = ReturnType<typeof hydrateAgentSessionEvent> | ReturnType<typeof hydrateChannelEvent> | ReturnType<typeof hydrateCallEvent> | ReturnType<typeof hydrateDocumentEvent> | ReturnType<typeof hydrateMessageEvent> | ReturnType<typeof hydrateUserEvent>;
23
24
  /**
24
25
  * What a handler receives, per event: the raw `metadata` plus the ORM handles
25
26
  * named by that event's ids.