@macro-inc/sdk 0.4.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (228) hide show
  1. package/README.md +316 -21
  2. package/dist/{chunk-PTX2RV2N.js → chunk-4MI52GWV.js} +93 -1
  3. package/dist/{chunk-XFA7NCJ5.js → chunk-HO75UE4Z.js} +146 -15
  4. package/dist/{chunk-P4DTO6VD.js → chunk-MCSQNZ4E.js} +6 -0
  5. package/dist/{chunk-ZLBDES7U.js → chunk-SJ6S2GAT.js} +1271 -87
  6. package/dist/{chunk-AZJUIUIV.js → chunk-SK5CMXRV.js} +100 -14
  7. package/dist/{chunk-PZPTJI6F.js → chunk-TMTYN2UK.js} +229 -2
  8. package/dist/{chunk-PPR7IWZ7.js → chunk-ZYBAKW25.js} +2 -1
  9. package/dist/generated/agent-fold/index.d.ts +202 -14
  10. package/dist/generated/agent-harness/index.d.ts +1 -1
  11. package/dist/generated/agent-harness/index.js +1 -1
  12. package/dist/generated/agent-harness/sdk.gen.d.ts +49 -2
  13. package/dist/generated/agent-harness/types.gen.d.ts +527 -9
  14. package/dist/generated/agent-reviews/index.d.ts +11 -9
  15. package/dist/generated/auth/index.d.ts +1 -1
  16. package/dist/generated/auth/index.js +1 -1
  17. package/dist/generated/auth/sdk.gen.d.ts +82 -16
  18. package/dist/generated/auth/types.gen.d.ts +768 -18
  19. package/dist/generated/calendar/types.gen.d.ts +10 -3
  20. package/dist/generated/cognition/index.d.ts +1 -1
  21. package/dist/generated/cognition/index.js +1 -1
  22. package/dist/generated/cognition/sdk.gen.d.ts +60 -6
  23. package/dist/generated/cognition/types.gen.d.ts +663 -106
  24. package/dist/generated/connection/types.gen.d.ts +1 -1
  25. package/dist/generated/contacts/index.d.ts +1 -1
  26. package/dist/generated/contacts/index.js +1 -1
  27. package/dist/generated/contacts/sdk.gen.d.ts +5 -1
  28. package/dist/generated/contacts/types.gen.d.ts +56 -0
  29. package/dist/generated/email/types.gen.d.ts +8 -2
  30. package/dist/generated/notification/index.d.ts +1 -1
  31. package/dist/generated/notification/index.js +1 -1
  32. package/dist/generated/notification/sdk.gen.d.ts +2 -1
  33. package/dist/generated/notification/types.gen.d.ts +174 -1
  34. package/dist/generated/scheduled-action/index.d.ts +1 -1
  35. package/dist/generated/scheduled-action/index.js +1 -1
  36. package/dist/generated/scheduled-action/sdk.gen.d.ts +107 -2
  37. package/dist/generated/scheduled-action/types.gen.d.ts +2451 -479
  38. package/dist/generated/search/index.d.ts +1 -1
  39. package/dist/generated/search/types.gen.d.ts +50 -11
  40. package/dist/generated/storage/index.d.ts +1 -1
  41. package/dist/generated/storage/index.js +1 -1
  42. package/dist/generated/storage/sdk.gen.d.ts +511 -18
  43. package/dist/generated/storage/types.gen.d.ts +18528 -11395
  44. package/dist/src/entities/account-managers/grant.d.ts +28 -5
  45. package/dist/src/entities/account-managers/namespace.d.ts +15 -3
  46. package/dist/src/entities/activity/entity.d.ts +7 -0
  47. package/dist/src/entities/activity/namespace.d.ts +58 -0
  48. package/dist/src/entities/activity/namespace.test.d.ts +1 -0
  49. package/dist/src/entities/agent-sessions/activity.d.ts +12 -3
  50. package/dist/src/entities/agent-sessions/agent-session.d.ts +209 -22
  51. package/dist/src/entities/agent-sessions/code-execution.d.ts +15 -3
  52. package/dist/src/entities/agent-sessions/conversation.d.ts +46 -9
  53. package/dist/src/entities/agent-sessions/namespace.d.ts +72 -16
  54. package/dist/src/entities/agent-sessions/origin.d.ts +1 -1
  55. package/dist/src/entities/agent-sessions/queued-action.d.ts +17 -3
  56. package/dist/src/entities/agent-sessions/review.d.ts +56 -5
  57. package/dist/src/entities/agent-sessions/tool-approval.d.ts +5 -1
  58. package/dist/src/entities/agents/agent.d.ts +98 -3
  59. package/dist/src/entities/agents/namespace.d.ts +52 -8
  60. package/dist/src/entities/ai/namespace.d.ts +10 -2
  61. package/dist/src/entities/api-keys/api-key.d.ts +6 -1
  62. package/dist/src/entities/api-keys/namespace.d.ts +18 -3
  63. package/dist/src/entities/bots/bot.d.ts +44 -9
  64. package/dist/src/entities/bots/namespace.d.ts +13 -1
  65. package/dist/src/entities/bots/token.d.ts +6 -1
  66. package/dist/src/entities/calendar/booking-link.d.ts +7 -1
  67. package/dist/src/entities/calendar/booking-namespace.d.ts +14 -1
  68. package/dist/src/entities/calendar/booking.d.ts +15 -0
  69. package/dist/src/entities/calendar/calendar.d.ts +10 -3
  70. package/dist/src/entities/calendar/event.d.ts +68 -9
  71. package/dist/src/entities/calendar/namespace.d.ts +91 -12
  72. package/dist/src/entities/calendar/replacement.d.ts +19 -3
  73. package/dist/src/entities/calls/call-record.d.ts +107 -17
  74. package/dist/src/entities/calls/connection.d.ts +7 -1
  75. package/dist/src/entities/calls/message.d.ts +27 -5
  76. package/dist/src/entities/calls/namespace.d.ts +15 -3
  77. package/dist/src/entities/canvases/canvas.d.ts +329 -0
  78. package/dist/src/entities/channels/access-request.d.ts +10 -2
  79. package/dist/src/entities/channels/activity.d.ts +20 -4
  80. package/dist/src/entities/channels/channel.d.ts +154 -27
  81. package/dist/src/entities/channels/labels.d.ts +41 -7
  82. package/dist/src/entities/channels/message.d.ts +105 -8
  83. package/dist/src/entities/channels/message.test.d.ts +1 -0
  84. package/dist/src/entities/channels/namespace.d.ts +37 -7
  85. package/dist/src/entities/channels/post.d.ts +13 -7
  86. package/dist/src/entities/channels/post.test.d.ts +1 -0
  87. package/dist/src/entities/channels/share.d.ts +9 -0
  88. package/dist/src/entities/channels/share.test.d.ts +1 -0
  89. package/dist/src/entities/channels/thread.d.ts +24 -4
  90. package/dist/src/entities/chats/chat.d.ts +57 -7
  91. package/dist/src/entities/chats/generation.d.ts +11 -2
  92. package/dist/src/entities/chats/namespace.d.ts +10 -2
  93. package/dist/src/entities/connected-apps/connected-app.d.ts +16 -2
  94. package/dist/src/entities/connected-apps/connector.d.ts +3 -0
  95. package/dist/src/entities/connected-apps/namespace.d.ts +18 -0
  96. package/dist/src/entities/crm/company.d.ts +64 -16
  97. package/dist/src/entities/crm/contact.d.ts +102 -14
  98. package/dist/src/entities/crm/namespace.d.ts +113 -22
  99. package/dist/src/entities/crm/pipeline-entry.d.ts +109 -0
  100. package/dist/src/entities/crm/pipeline.d.ts +292 -29
  101. package/dist/src/entities/crm/pipelines.d.ts +69 -4
  102. package/dist/src/entities/crm-email-privacy/email-privacy.d.ts +238 -0
  103. package/dist/src/entities/crm-email-privacy/email-rule-preview.d.ts +55 -0
  104. package/dist/src/entities/crm-email-privacy/email-rule-revision.d.ts +27 -0
  105. package/dist/src/entities/crm-email-privacy/email-rules.d.ts +32 -0
  106. package/dist/src/entities/databases/column.d.ts +54 -7
  107. package/dist/src/entities/databases/database.d.ts +160 -18
  108. package/dist/src/entities/databases/namespace.d.ts +40 -8
  109. package/dist/src/entities/databases/row.d.ts +2 -0
  110. package/dist/src/entities/databases/saved-query.d.ts +151 -0
  111. package/dist/src/entities/databases/table.d.ts +73 -10
  112. package/dist/src/entities/databases/view.d.ts +37 -5
  113. package/dist/src/entities/databases/webhook.d.ts +8 -1
  114. package/dist/src/entities/documents/ai-edit.d.ts +2 -0
  115. package/dist/src/entities/documents/anchor.d.ts +12 -2
  116. package/dist/src/entities/documents/comment.d.ts +29 -5
  117. package/dist/src/entities/documents/create.test.d.ts +1 -0
  118. package/dist/src/entities/documents/document.d.ts +284 -26
  119. package/dist/src/entities/documents/markdown.d.ts +25 -0
  120. package/dist/src/entities/documents/namespace.d.ts +146 -13
  121. package/dist/src/entities/documents/skills.test.d.ts +1 -0
  122. package/dist/src/entities/documents/system-skill.d.ts +21 -1
  123. package/dist/src/entities/documents/text-comment.d.ts +41 -0
  124. package/dist/src/entities/documents/text-comment.test.d.ts +1 -0
  125. package/dist/src/entities/documents/version.d.ts +5 -1
  126. package/dist/src/entities/email/attachment.d.ts +3 -0
  127. package/dist/src/entities/email/draft.d.ts +61 -9
  128. package/dist/src/entities/email/filter.d.ts +12 -2
  129. package/dist/src/entities/email/label.d.ts +7 -1
  130. package/dist/src/entities/email/link.d.ts +5 -1
  131. package/dist/src/entities/email/message.d.ts +72 -14
  132. package/dist/src/entities/email/namespace.d.ts +134 -24
  133. package/dist/src/entities/email/thread.d.ts +124 -18
  134. package/dist/src/entities/entity-mentions/mention.d.ts +6 -1
  135. package/dist/src/entities/entity-mentions/namespace.d.ts +5 -1
  136. package/dist/src/entities/entity.d.ts +65 -6
  137. package/dist/src/entities/external-chat/chat.d.ts +80 -12
  138. package/dist/src/entities/external-chat/message.d.ts +1 -1
  139. package/dist/src/entities/external-chat/namespace.d.ts +5 -1
  140. package/dist/src/entities/external-chat/send.d.ts +10 -2
  141. package/dist/src/entities/favorites/namespace.d.ts +20 -3
  142. package/dist/src/entities/foreign/foreign-entity.d.ts +5 -1
  143. package/dist/src/entities/foreign/namespace.d.ts +5 -1
  144. package/dist/src/entities/forms/form.d.ts +91 -14
  145. package/dist/src/entities/forms/namespace.d.ts +10 -2
  146. package/dist/src/entities/forms/question.d.ts +35 -7
  147. package/dist/src/entities/forms/response.d.ts +25 -5
  148. package/dist/src/entities/forms/section.d.ts +15 -3
  149. package/dist/src/entities/github-pull-requests/namespace.d.ts +5 -1
  150. package/dist/src/entities/github-pull-requests/pull-request.d.ts +15 -3
  151. package/dist/src/entities/harnesses/harness.d.ts +51 -3
  152. package/dist/src/entities/harnesses/namespace.d.ts +54 -8
  153. package/dist/src/entities/harnesses/pairing.d.ts +13 -2
  154. package/dist/src/entities/images/image.d.ts +16 -5
  155. package/dist/src/entities/images/namespace.d.ts +8 -1
  156. package/dist/src/entities/imports/entry.d.ts +65 -0
  157. package/dist/src/entities/imports/namespace.d.ts +103 -0
  158. package/dist/src/entities/imports/namespace.test.d.ts +1 -0
  159. package/dist/src/entities/initiatives/initiative.d.ts +128 -4
  160. package/dist/src/entities/initiatives/initiative.test.d.ts +1 -0
  161. package/dist/src/entities/initiatives/namespace.d.ts +71 -7
  162. package/dist/src/entities/me/namespace.d.ts +28 -3
  163. package/dist/src/entities/meetings/meeting.d.ts +46 -8
  164. package/dist/src/entities/meetings/namespace.d.ts +20 -4
  165. package/dist/src/entities/memory/namespace.d.ts +49 -0
  166. package/dist/src/entities/memory/namespace.test.d.ts +1 -0
  167. package/dist/src/entities/messages/discussion.d.ts +84 -0
  168. package/dist/src/entities/messages/thread.d.ts +19 -5
  169. package/dist/src/entities/notifications/namespace.d.ts +41 -7
  170. package/dist/src/entities/notifications/notification.d.ts +31 -6
  171. package/dist/src/entities/passwords/item.d.ts +118 -0
  172. package/dist/src/entities/passwords/namespace.d.ts +45 -0
  173. package/dist/src/entities/pins/namespace.d.ts +23 -4
  174. package/dist/src/entities/projects/namespace.d.ts +29 -0
  175. package/dist/src/entities/projects/project.d.ts +58 -7
  176. package/dist/src/entities/properties/namespace.d.ts +67 -11
  177. package/dist/src/entities/properties/namespace.test.d.ts +1 -0
  178. package/dist/src/entities/properties/property-definition.d.ts +30 -5
  179. package/dist/src/entities/properties/property-option.d.ts +14 -2
  180. package/dist/src/entities/referrals/namespace.d.ts +8 -1
  181. package/dist/src/entities/routines/namespace.d.ts +198 -14
  182. package/dist/src/entities/routines/routine.d.ts +174 -27
  183. package/dist/src/entities/routines/suggestion.d.ts +38 -0
  184. package/dist/src/entities/saved-views/namespace.d.ts +58 -0
  185. package/dist/src/entities/saved-views/saved-view.d.ts +78 -0
  186. package/dist/src/entities/search/exclusions.d.ts +6 -0
  187. package/dist/src/entities/search/namespace.d.ts +9 -3
  188. package/dist/src/entities/search/options.d.ts +3 -2
  189. package/dist/src/entities/sharing/access.d.ts +50 -9
  190. package/dist/src/entities/spreadsheets/spreadsheet.d.ts +201 -0
  191. package/dist/src/entities/suggestions/namespace.d.ts +118 -0
  192. package/dist/src/entities/suggestions/suggestion.d.ts +172 -0
  193. package/dist/src/entities/suggestions/suggestion.test.d.ts +1 -0
  194. package/dist/src/entities/tasks/namespace.d.ts +18 -5
  195. package/dist/src/entities/tasks/task.d.ts +21 -3
  196. package/dist/src/entities/teams/invite.d.ts +3 -0
  197. package/dist/src/entities/teams/namespace.d.ts +10 -2
  198. package/dist/src/entities/teams/team.d.ts +22 -2
  199. package/dist/src/entities/ui/app-link.d.ts +24 -0
  200. package/dist/src/entities/ui/namespace.d.ts +75 -0
  201. package/dist/src/entities/unfurls/namespace.d.ts +12 -2
  202. package/dist/src/entities/users/namespace.d.ts +26 -4
  203. package/dist/src/entities/users/profile-picture.d.ts +29 -0
  204. package/dist/src/entities/users/profile-picture.test.d.ts +1 -0
  205. package/dist/src/entities/users/user.d.ts +52 -1
  206. package/dist/src/entities/web/namespace.d.ts +6 -0
  207. package/dist/src/entities/webhooks/namespace.d.ts +5 -0
  208. package/dist/src/entities/webhooks/webhook.d.ts +47 -7
  209. package/dist/src/entities/whatsapp/account.d.ts +5 -1
  210. package/dist/src/entities/whatsapp/chat.d.ts +9 -1
  211. package/dist/src/entities/whatsapp/namespace.d.ts +7 -1
  212. package/dist/src/entities/workspace/namespace.d.ts +12 -4
  213. package/dist/src/entities/workspace/query.d.ts +5 -1
  214. package/dist/src/entities/workspace/query.test.d.ts +1 -0
  215. package/dist/src/events/hydrate/document.d.ts +5 -0
  216. package/dist/src/events/hydrate/user.d.ts +14 -0
  217. package/dist/src/events/receiver.d.ts +2 -0
  218. package/dist/src/events/types.d.ts +2 -1
  219. package/dist/src/macro.d.ts +59 -6
  220. package/dist/src/macro.js +18710 -10355
  221. package/dist/src/utils/activity.d.ts +2 -0
  222. package/dist/src/utils/index.d.ts +1 -1
  223. package/dist/src/utils/lazy.d.ts +20 -1
  224. package/dist/src/utils/options.d.ts +7 -0
  225. package/dist/src/utils/pagination.d.ts +16 -0
  226. package/dist/src/utils/verbs.d.ts +3 -0
  227. package/package.json +1 -1
  228. package/dist/src/entities/crm/comment.d.ts +0 -64
@@ -1,8 +1,16 @@
1
1
  import type { Harness as HarnessRecord } from '../../../generated/storage/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
+ import { Agent } from '../agents/agent';
3
4
  import { MacroEntity } from '../entity';
4
- /** A registered host for coding agents. */
5
+ import { type AccessRequest, EntityAccess } from '../sharing/access';
6
+ import { User } from '../users/user';
7
+ /** A registered host for agents: a teammate's computer running macrod. */
5
8
  export declare class Harness extends MacroEntity<HarnessRecord> {
9
+ /**
10
+ * Access requests for this host. Asking for access works from any credential;
11
+ * deciding who gets it takes the owner's own session, in the app.
12
+ */
13
+ readonly access: EntityAccess;
6
14
  /** Construct a lazy host handle. */
7
15
  static byId(client: MacroClient, id: string): Harness;
8
16
  /** Seed from a listed host. */
@@ -19,10 +27,50 @@ export declare class Harness extends MacroEntity<HarnessRecord> {
19
27
  /**
20
28
  * Allow or forbid agents here to bypass permission prompts. Live sessions
21
29
  * pick the change up at their next turn.
30
+ *
31
+ * @write
32
+ * @idempotent
22
33
  */
23
34
  setPermissionBypass(allowed: boolean): Promise<void>;
24
- /** Rename the host. */
35
+ /**
36
+ * Rename the host.
37
+ *
38
+ * @write
39
+ * @idempotent
40
+ */
25
41
  rename(name: string): Promise<void>;
26
- /** Remove the host. */
42
+ /** The person whose computer this is. */
43
+ readonly owner: () => Promise<User>;
44
+ /**
45
+ * The caller's role: `owner`, `user` (can run agents), `read` (can see what is
46
+ * on it, cannot run agents), or `none` (can only see it exists).
47
+ */
48
+ readonly callerAccess: () => Promise<NonNullable<import("../../../generated/storage").HarnessAccess | undefined> | undefined>;
49
+ /**
50
+ * Ask the host's owner for access in the caller's name, and show them which
51
+ * agent asked.
52
+ *
53
+ * Agents: call this only when the user asked for it or agreed after being
54
+ * offered it, typically after `callerAccess()` was `none` or `read`, or a prompt to an
55
+ * agent on this host was refused; never request access on your own. It never
56
+ * grants access: agents cannot approve requests or share a host, even one
57
+ * their own user owns. Tell the user it is pending with `owner()`, and check
58
+ * `callerAccess()` later.
59
+ *
60
+ * @write
61
+ */
62
+ requestAccess(role?: 'read' | 'user'): Promise<AccessRequest>;
63
+ /**
64
+ * Agents living on the host, for callers with at least `read`.
65
+ *
66
+ * @readonly
67
+ */
68
+ residents(): Promise<Agent[]>;
69
+ /**
70
+ * Remove the host.
71
+ *
72
+ * @destructive
73
+ * @idempotent
74
+ */
27
75
  delete(): Promise<void>;
28
76
  }
@@ -7,26 +7,72 @@ 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;
14
14
  constructor(client: MacroClient);
15
15
  /** Construct a lazy host handle. */
16
16
  byId(id: string): Harness;
17
- /** All hosts visible to the caller. */
17
+ /**
18
+ * The hosts the caller may run agents on.
19
+ *
20
+ * @readonly
21
+ */
18
22
  list(): Promise<Harness[]>;
19
- /** The currently authenticated host. */
23
+ /**
24
+ * Every host of the caller's teammates, including ones the caller cannot use
25
+ * yet. `Harness.callerAccess()` says which, and `Harness.requestAccess()` asks.
26
+ *
27
+ * @readonly
28
+ */
29
+ directory(): Promise<Harness[]>;
30
+ /**
31
+ * The currently authenticated host.
32
+ *
33
+ * @readonly
34
+ * @mcp-exclude Requires host credentials
35
+ * MCP calls authenticate as a user.
36
+ */
20
37
  me(): Promise<Harness>;
21
- /** Revoke the currently authenticated host. */
38
+ /**
39
+ * Revoke the currently authenticated host.
40
+ *
41
+ * @destructive
42
+ * @idempotent
43
+ * @mcp-exclude Requires host credentials
44
+ * MCP calls authenticate as a user.
45
+ */
22
46
  deleteSelf(): Promise<void>;
23
- /** Agent handles for the currently authenticated host. */
47
+ /**
48
+ * Agent handles for the currently authenticated host.
49
+ *
50
+ * @readonly
51
+ * @mcp-exclude Requires host credentials
52
+ * MCP calls authenticate as a user.
53
+ */
24
54
  agents(): Promise<Agent[]>;
25
- /** Session handles for the currently authenticated host. */
55
+ /**
56
+ * Session handles for the currently authenticated host.
57
+ *
58
+ * @readonly
59
+ * @mcp-exclude Requires host credentials
60
+ * MCP calls authenticate as a user.
61
+ */
26
62
  sessions(): Promise<AgentSession[]>;
27
- /** Construct a lazy pairing from its displayed code. */
63
+ /**
64
+ * Construct a lazy pairing from its displayed code.
65
+ *
66
+ * @readonly
67
+ */
28
68
  pairing(code: string): HarnessPairing;
29
- /** Start pairing a device; persist the secret separately from the handles. */
69
+ /**
70
+ * Start pairing a device; persist the secret separately from the handles.
71
+ *
72
+ * @write
73
+ * @mcp-exclude Device-side pairing step
74
+ * returns a device secret meant for the host process.
75
+ */
30
76
  createPairing(options: CreatePairingRequest): Promise<{
31
77
  pairing: HarnessPairing;
32
78
  device: DevicePairing;
@@ -12,7 +12,12 @@ export declare class HarnessPairing extends MacroEntity<PairingDetails> {
12
12
  readonly name: () => Promise<string>;
13
13
  /** Expiration time. */
14
14
  readonly expiresAt: () => Promise<string>;
15
- /** Approve this pairing. */
15
+ /**
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.
18
+ *
19
+ * @write
20
+ */
16
21
  approve(options?: {
17
22
  name?: string;
18
23
  team?: Team;
@@ -27,7 +32,13 @@ export declare class DevicePairing {
27
32
  private constructor();
28
33
  /** Construct the device side handle. */
29
34
  static byId(client: MacroClient, id: string): DevicePairing;
30
- /** Attempt to claim an approved pairing. Pending claims return undefined. */
35
+ /**
36
+ * Attempt to claim an approved pairing. Pending claims return undefined.
37
+ *
38
+ * @write
39
+ * @mcp-exclude Device-side pairing step
40
+ * returns a host token meant for the host process.
41
+ */
31
42
  claim(deviceSecret: string): Promise<{
32
43
  harness: Harness;
33
44
  token: string;
@@ -1,9 +1,11 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
2
  /**
3
- * An image in static file storage: an upload, or one made with
4
- * `macro.images.generate()`. Attach it to a channel message with
5
- * `channel.send(text, { images: [image] })`, or pass it back to `generate` as
6
- * a reference.
3
+ * An image in static file storage: an upload, a render from
4
+ * `canvas.render()`, or one made with `macro.images.generate()`. Attach it to
5
+ * a channel message with `channel.send(text, { images: [image] })`, show it in
6
+ * a reply or Markdown with {@link StaticImage.toMarkdown}, or pass it back to
7
+ * `generate` as a reference. It is not a document: never mention its `id` as
8
+ * one.
7
9
  */
8
10
  export declare class StaticImage {
9
11
  /** Static file id. */
@@ -32,12 +34,20 @@ export declare class StaticImage {
32
34
  width: number;
33
35
  height: number;
34
36
  }): StaticImage;
35
- /** Serialize the image reference without its client. */
37
+ /**
38
+ * The `<m-image>` tag that shows this image in an agent reply, a channel
39
+ * message or a Markdown document. Put it on a line of its own.
40
+ *
41
+ * @readonly
42
+ */
43
+ toMarkdown(alt?: string): string;
44
+ /** Serialize the image reference, and the markup that shows it, without its client. */
36
45
  toJSON(): {
37
46
  id: string;
38
47
  url: string;
39
48
  width: number | undefined;
40
49
  height: number | undefined;
50
+ markdown: string;
41
51
  };
42
52
  }
43
53
  /** An image made by `macro.images.generate()`, stored as a static file. */
@@ -73,5 +83,6 @@ export declare class GeneratedImage extends StaticImage {
73
83
  url: string;
74
84
  width: number | undefined;
75
85
  height: number | undefined;
86
+ markdown: string;
76
87
  };
77
88
  }
@@ -1,7 +1,7 @@
1
1
  import type { GenerateImageAspectRatio } from '../../../generated/cognition/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import { Document } from '../documents/document';
4
- import { GeneratedImage, type StaticImage } from './image';
4
+ import { GeneratedImage, StaticImage } from './image';
5
5
  export type { GenerateImageAspectRatio };
6
6
  /** What image to generate. */
7
7
  export interface GenerateImageOptions {
@@ -31,6 +31,11 @@ export interface GenerateImageOptions {
31
31
  export declare class ImagesNamespace {
32
32
  private readonly client;
33
33
  constructor(client: MacroClient);
34
+ /**
35
+ * A handle to an image already in static file storage, such as a profile
36
+ * picture uploaded earlier whose id you saved.
37
+ */
38
+ byId(id: string): StaticImage;
34
39
  /**
35
40
  * Generate or edit an image with Google's Nano Banana model and store it as
36
41
  * a static file. Takes several seconds. Post it with
@@ -43,6 +48,8 @@ export declare class ImagesNamespace {
43
48
  * aspectRatio: 'widescreen',
44
49
  * });
45
50
  * await channel.send('Fresh off the press', { images: [image] });
51
+ *
52
+ * @write
46
53
  */
47
54
  generate(options: GenerateImageOptions): Promise<GeneratedImage>;
48
55
  }
@@ -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';
@@ -1,6 +1,9 @@
1
- import type { CreateInitiativeRequest, InitiativeDetail } from '../../../generated/storage/types.gen';
1
+ import type { CreateInitiativeRequest, EntityAppearance, InitiativeDetail } from '../../../generated/storage/types.gen';
2
+ import type { RichMessage } from '../../mentions';
2
3
  import type { MacroClient } from '../../utils/client';
3
4
  import { MacroEntity } from '../entity';
5
+ import { DiscussionComment, type DiscussionThread } from '../messages/discussion';
6
+ import { MessageThread, type TimelineOptions } from '../messages/thread';
4
7
  import { EntityAccess } from '../sharing/access';
5
8
  import { type SharePermissionOptions } from '../sharing/permissions';
6
9
  import { Task } from '../tasks/task';
@@ -18,11 +21,32 @@ export interface InitiativeOptions {
18
21
  /** Whether the current team can access it. */
19
22
  shareWithTeam?: boolean;
20
23
  }
24
+ /** One change in an initiative's history. */
25
+ export interface InitiativeActivityEntry {
26
+ /** Stable record id, for deduplicating entries across reads. */
27
+ id: string;
28
+ /** Who mechanically acted: a user, or an agent acting for one. */
29
+ actor: User;
30
+ /** The user the change is attributed to, the same as `actor` unless an agent acted for them. */
31
+ subject: User;
32
+ /** Activity tag, e.g. `created`, `edited`, `property_changed`, `task_added`, `task_removed`. */
33
+ action: string;
34
+ /** The action's details; absent for actions this deployment does not know. */
35
+ payload: unknown;
36
+ /** When it happened, RFC 3339. */
37
+ occurredAt: string;
38
+ }
21
39
  /** A group of tasks and members working toward an outcome. */
22
40
  export declare class Initiative extends MacroEntity<InitiativeDetail> {
41
+ /** How entity-addressed APIs identify this entity's type. */
42
+ readonly entityType = "initiative";
23
43
  /** Access requests and direct user grants. */
24
44
  readonly access: EntityAccess;
25
- /** The initiative's URL in the Macro web app; hand it to users as the link. */
45
+ /**
46
+ * The initiative's URL in the Macro web app; hand it to users as the link.
47
+ *
48
+ * @readonly
49
+ */
26
50
  webUrl(): string;
27
51
  /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
28
52
  toJSON(): {
@@ -37,6 +61,15 @@ export declare class Initiative extends MacroEntity<InitiativeDetail> {
37
61
  protected fetch(): Promise<InitiativeDetail>;
38
62
  /** Display name. */
39
63
  readonly name: () => Promise<string>;
64
+ /** Shared icon and color overrides. */
65
+ readonly appearance: () => Promise<EntityAppearance | undefined>;
66
+ /**
67
+ * Replace shared appearance. Pass {} to reset both overrides.
68
+ *
69
+ * @write
70
+ * @idempotent
71
+ */
72
+ setAppearance(appearance: EntityAppearance): Promise<EntityAppearance>;
40
73
  /** Owner. */
41
74
  readonly owner: () => Promise<User>;
42
75
  /** Assigned members. */
@@ -50,12 +83,103 @@ export declare class Initiative extends MacroEntity<InitiativeDetail> {
50
83
  readonly accessLevel: () => Promise<import("../../../generated/storage").AccessLevel>;
51
84
  /** Sharing configuration. */
52
85
  readonly sharePermissions: () => Promise<import("../../../generated/storage").SharePermissionV2>;
53
- /** Update the name, membership or sharing configuration. */
86
+ /**
87
+ * The description as Macro's lossless Markdown, with chips, tables and other
88
+ * rich content as `<m-*>` tags; empty while no one has opened or written it.
89
+ *
90
+ * @readonly
91
+ */
92
+ description(): Promise<string>;
93
+ /** The initiative this discussion hangs off. */
94
+ private get commentParent();
95
+ /**
96
+ * The discussion's comment threads, each with its comments, newest thread first.
97
+ *
98
+ * @readonly
99
+ */
100
+ comments(): Promise<DiscussionThread[]>;
101
+ /**
102
+ * Start a new thread in the discussion; reply to a thread with
103
+ * {@link DiscussionComment.reply} on one of its comments.
104
+ *
105
+ * @param body - Plain text, or a rich body composed with {@link msg}.
106
+ *
107
+ * @write
108
+ */
109
+ comment(body: string | RichMessage): Promise<DiscussionComment>;
110
+ /**
111
+ * A handle to one of the discussion's comments by id.
112
+ *
113
+ * @readonly
114
+ */
115
+ commentById(id: string): DiscussionComment;
116
+ /**
117
+ * A discussion thread, to resolve or delete it.
118
+ *
119
+ * @readonly
120
+ */
121
+ messageThreadById(id: string): MessageThread;
122
+ /**
123
+ * A mixed page of discussion comments and activity.
124
+ *
125
+ * @readonly
126
+ */
127
+ timelinePage(selection?: TimelineOptions<DiscussionComment>): Promise<{
128
+ entries: ({
129
+ type: "activity";
130
+ activity: {
131
+ actor: User;
132
+ action: string;
133
+ actor_id: string;
134
+ id: string;
135
+ occurred_at: string;
136
+ payload?: unknown;
137
+ };
138
+ message?: undefined;
139
+ } | {
140
+ type: "message";
141
+ message: DiscussionComment;
142
+ activity?: undefined;
143
+ })[];
144
+ nextCursor: import("../../../generated/storage").MessageCursor | undefined;
145
+ previousCursor: import("../../../generated/storage").MessageCursor | undefined;
146
+ }>;
147
+ /**
148
+ * Update the name, membership or sharing configuration.
149
+ *
150
+ * @write
151
+ * @idempotent
152
+ */
54
153
  update(options: {
55
154
  name?: string;
56
155
  members?: User[];
57
156
  sharePermission?: SharePermissionOptions;
58
157
  }): Promise<void>;
59
- /** Delete this initiative. */
158
+ /**
159
+ * This initiative's history, newest first, auto-paginated (`maxItems` caps the total): creation, edits,
160
+ * property changes and tasks added or removed, optionally within
161
+ * `[after, before)`.
162
+ *
163
+ * Task entries appear only for tasks you can currently view.
164
+ *
165
+ * @example
166
+ * const since = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
167
+ * for await (const entry of initiative.activity({ after: since })) {
168
+ * console.log(entry.occurredAt, entry.action, await entry.actor.name());
169
+ * }
170
+ *
171
+ * @readonly
172
+ */
173
+ activity(window?: {
174
+ after?: Date | string;
175
+ before?: Date | string;
176
+ maxItems?: number;
177
+ }): AsyncGenerator<InitiativeActivityEntry>;
178
+ /**
179
+ * Delete this initiative.
180
+ *
181
+ * @destructive
182
+ * @idempotent
183
+ */
60
184
  delete(): Promise<void>;
61
185
  }
@@ -0,0 +1 @@
1
+ export {};