@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
@@ -0,0 +1,118 @@
1
+ import type { PasswordAgentAccessRequestState, PasswordAgentItemAccess, PasswordAgentSearchHit, PasswordAgentSecretPatch, PasswordAgentSecretSelector, PasswordItemKind, PasswordPermission } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import type { Team } from '../teams/team';
4
+ /**
5
+ * The one agent wake (a single agent query) a vault call is attributed to:
6
+ * a UUIDv7 the agent's runtime mints per wake. It is untrusted correlation for
7
+ * audit, never authorization, and is never kept across wakes.
8
+ */
9
+ export interface AgentWake {
10
+ /** The wake's UUIDv7. */
11
+ wake: string;
12
+ }
13
+ /** One field of a login or API credential an agent may copy. */
14
+ export type SecretSelector = PasswordAgentSecretSelector;
15
+ /** One disclosed field, for the agent's clipboard; never for model context. */
16
+ export interface DisclosedSecret {
17
+ /** The field's value. */
18
+ value: string;
19
+ /** The committed version it was read from. */
20
+ version: number;
21
+ /** The field that was disclosed. */
22
+ selector: SecretSelector;
23
+ }
24
+ /** A verification code with its conservative remaining lifetime. */
25
+ export interface VerificationCode {
26
+ /** The current code. */
27
+ code: string;
28
+ /** Conservative usable-until time on the server clock. */
29
+ expiresAt: string;
30
+ /** Code period in seconds. */
31
+ periodSeconds: number;
32
+ /**
33
+ * Milliseconds the server measured until `expiresAt`. Subtract the whole
34
+ * time since the request was sent, rounded up, before using the code.
35
+ */
36
+ validForMs: number;
37
+ }
38
+ /** An agent's access request on one item. */
39
+ export interface AgentAccessRequest {
40
+ /** Request lifecycle; `none` when the agent has never requested. */
41
+ status: PasswordAgentAccessRequestState['status'];
42
+ /** Requested permission, when a request exists. */
43
+ permission?: PasswordPermission;
44
+ /** Request revision; 0 when none exists. */
45
+ revision: number;
46
+ /** The agent's current access to the item. */
47
+ access: PasswordAgentItemAccess;
48
+ /** Last transition time, when a request exists. */
49
+ updatedAt?: string;
50
+ }
51
+ /** The wire headers of every agent vault call; mutations also carry the CSRF header. */
52
+ export declare function vaultHeaders(wake: AgentWake): {
53
+ 'X-Macro-Agent-Session-Id': string;
54
+ 'X-Macro-Passwords': string;
55
+ };
56
+ /**
57
+ * A team vault item as seen by the authenticated agent, for one wake. Search
58
+ * hits carry metadata only; values are disclosed one field at a time.
59
+ *
60
+ * @mcp-exclude Agent vault values must reach only the agent's secrets capability, never model context.
61
+ */
62
+ export declare class PasswordItem {
63
+ private readonly client;
64
+ /** The team that owns the item. */
65
+ readonly team: Team;
66
+ private readonly wake;
67
+ /** The item's id. */
68
+ readonly id: string;
69
+ private hit?;
70
+ private constructor();
71
+ /** A handle to an item from a search hit or write result. */
72
+ static fromHit(client: MacroClient, team: Team, wake: AgentWake, hit: PasswordAgentSearchHit): PasswordItem;
73
+ /** A handle to an item by id, without metadata until a write returns it. */
74
+ static byId(client: MacroClient, team: Team, wake: AgentWake, id: string): PasswordItem;
75
+ /** Display name, when this handle came from a search or write. */
76
+ get name(): string | undefined;
77
+ /** Stored kind, when known. */
78
+ get kind(): PasswordItemKind | undefined;
79
+ /** Website URL, when known. */
80
+ get url(): string | undefined;
81
+ /** Committed version, when known. */
82
+ get version(): number | undefined;
83
+ /** The agent's access when this handle was read; recomputed by every call. */
84
+ get access(): PasswordAgentItemAccess | undefined;
85
+ private path;
86
+ /** Disclose one field for copying. Values never belong in model context. */
87
+ disclose(selector: SecretSelector, opts?: {
88
+ /** Fail with `version_conflict` unless this is the committed version. */
89
+ expectedVersion?: number;
90
+ }): Promise<DisclosedSecret>;
91
+ /** The current verification code of a login or verification-code item. */
92
+ verificationCode(): Promise<VerificationCode>;
93
+ /**
94
+ * Replace supplied fields of a login or API item at `expectedVersion`.
95
+ * Notes and custom fields are kept exactly. A retry with the same
96
+ * `operationId` returns the accepted result.
97
+ */
98
+ update(opts: {
99
+ expectedVersion: number;
100
+ secret?: PasswordAgentSecretPatch;
101
+ name?: string;
102
+ /** `null` clears the URL. */
103
+ url?: string | null;
104
+ /** UUIDv7 stable across retries of this update; generated when omitted. */
105
+ operationId?: string;
106
+ }): Promise<PasswordItem>;
107
+ /** Enroll a base32 verification-code seed on a login item this agent created. */
108
+ setVerificationSeed(opts: {
109
+ seed: string;
110
+ expectedVersion: number;
111
+ /** UUIDv7 naming this enrollment, stable across retries; generated when omitted. */
112
+ operationId?: string;
113
+ }): Promise<void>;
114
+ /** Ask the item's managers for access; deduplicated while pending. */
115
+ requestAccess(permission: PasswordPermission): Promise<AgentAccessRequest>;
116
+ /** This agent's own request state for the item. */
117
+ accessRequest(): Promise<AgentAccessRequest>;
118
+ }
@@ -0,0 +1,45 @@
1
+ import type { PasswordAgentCreateSecret } from '../../../generated/storage/types.gen';
2
+ import { type IterationOptions } from '../../utils';
3
+ import type { MacroClient } from '../../utils/client';
4
+ import type { Team } from '../teams/team';
5
+ import { type AgentWake, PasswordItem } from './item';
6
+ /**
7
+ * Team vault access for the authenticated agent. Only the agent's own API key
8
+ * can use it; human vault routes are not part of the SDK.
9
+ *
10
+ * @mcp-exclude Agent vault values must reach only the agent's secrets capability, never model context.
11
+ */
12
+ export declare class PasswordNamespace {
13
+ private readonly client;
14
+ constructor(client: MacroClient);
15
+ /** The team's vault as this agent sees it during one wake. */
16
+ forAgent(team: Team, wake: AgentWake): AgentVault;
17
+ }
18
+ /**
19
+ * One team's vault for one agent wake. Every call recomputes the agent's
20
+ * current access.
21
+ *
22
+ * @mcp-exclude Agent vault values must reach only the agent's secrets capability, never model context.
23
+ */
24
+ export declare class AgentVault {
25
+ private readonly client;
26
+ /** The team that owns the vault. */
27
+ readonly team: Team;
28
+ private readonly wake;
29
+ constructor(client: MacroClient,
30
+ /** The team that owns the vault. */
31
+ team: Team, wake: AgentWake);
32
+ /** Items the agent may use or request, newest first, metadata only; `maxItems` caps the total. */
33
+ search(query?: string, opts?: IterationOptions): AsyncGenerator<PasswordItem>;
34
+ /**
35
+ * Create a login or API item owned by the team and usable by this agent at
36
+ * once. A retry with the same `operationId` returns the same item.
37
+ */
38
+ create(opts: {
39
+ name: string;
40
+ url?: string;
41
+ secret: PasswordAgentCreateSecret;
42
+ /** UUIDv7 stable across retries; generated when omitted. */
43
+ operationId?: string;
44
+ }): Promise<PasswordItem>;
45
+ }
@@ -10,14 +10,33 @@ export type { PinnedItem, ReorderPinRequest };
10
10
  export declare class PinsNamespace {
11
11
  private readonly client;
12
12
  constructor(client: MacroClient);
13
- /** The user's pinned items, with their pin indices. */
13
+ /**
14
+ * The user's pinned items, with their pin indices.
15
+ *
16
+ * @readonly
17
+ */
14
18
  list(): Promise<PinnedItem[]>;
15
- /** Pin an entity to a slot. `index` is the slot to put it in. */
19
+ /**
20
+ * Pin an entity to a slot. `index` is the slot to put it in.
21
+ *
22
+ * @write
23
+ * @idempotent
24
+ */
16
25
  add(entity: FavoritableEntity<unknown>, opts: {
17
26
  index: number;
18
27
  }): Promise<void>;
19
- /** Unpin an entity. */
28
+ /**
29
+ * Unpin an entity.
30
+ *
31
+ * @write
32
+ * @idempotent
33
+ */
20
34
  remove(entity: FavoritableEntity<unknown>): Promise<void>;
21
- /** Reorder pins: pass each pinned item with its type and new index. */
35
+ /**
36
+ * Reorder pins: pass each pinned item with its type and new index.
37
+ *
38
+ * @write
39
+ * @idempotent
40
+ */
22
41
  reorder(pins: ReorderPinRequest[]): Promise<void>;
23
42
  }
@@ -2,15 +2,44 @@ import type { MacroClient } from '../../utils/client';
2
2
  import type { SearchOpts } from '../search/options';
3
3
  import { Project } from './project';
4
4
  /**
5
+ * Projects are folders that hold documents, chats and other projects.
6
+ *
7
+ * An agent session cannot be placed in a project: sessions have no project,
8
+ * and `Project.items()` never lists them. To keep a session with a project's
9
+ * work, create a Markdown document in the project that links the session with
10
+ * an agent session chip; `"expanded": true` shows the card that follows its
11
+ * latest turn.
12
+ *
13
+ * @example Link an agent session from a project.
14
+ * ```js
15
+ * const chip = JSON.stringify({ id: session.id, label: '', expanded: true });
16
+ * const document = await macro.documents.create({
17
+ * name: 'Agent work',
18
+ * project,
19
+ * markdown: `<m-agent-session-mention>${chip}</m-agent-session-mention>`,
20
+ * });
21
+ * return { data: { url: document.webUrl() } };
22
+ * ```
23
+ *
5
24
  * @routing Use when organizing items into projects (folders); not initiatives, which group tasks.
6
25
  */
7
26
  export declare class ProjectNamespace {
8
27
  private readonly client;
9
28
  constructor(client: MacroClient);
10
29
  byId(id: string): Project;
30
+ /**
31
+ * Create a project, optionally nested inside a parent project.
32
+ *
33
+ * @write
34
+ */
11
35
  create(opts: {
12
36
  name: string;
13
37
  parent?: Project;
14
38
  }): Promise<Project>;
39
+ /**
40
+ * Search projects by name and content, most relevant first, auto-paginated; `maxItems` caps the total.
41
+ *
42
+ * @readonly
43
+ */
15
44
  search(query: string, opts?: SearchOpts): AsyncGenerator<Project>;
16
45
  }
@@ -1,23 +1,55 @@
1
1
  import type { GetProjectContentHandlerResponses, GetProjectHandlerResponses } from '../../../generated/storage/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
+ import type { Channel } from '../channels/channel';
3
4
  import { PropertiedEntity } from '../entity';
4
5
  import { EntityAccess } from '../sharing/access';
6
+ import { type SharePermissionOptions } from '../sharing/permissions';
5
7
  type ProjectDetail = GetProjectHandlerResponses[200]['data']['projectMetadata'];
6
8
  type ProjectItem = GetProjectContentHandlerResponses[200]['data'][number]['item'];
7
9
  /** A Macro project: a folder-like container for documents, chats, and subprojects. */
8
10
  export declare class Project extends PropertiedEntity<ProjectDetail> {
9
- /** Read this project's sharing configuration. */
11
+ /**
12
+ * Read this project's sharing configuration.
13
+ *
14
+ * @readonly
15
+ */
10
16
  sharePermissions(): Promise<import("../../../generated/storage").SharePermissionV2>;
11
- /** Read the caller's effective access level. */
17
+ /**
18
+ * Change who can open the project and its contents: the link share and its
19
+ * access level, the owner's team, and channel grants. Omitted fields are
20
+ * left as they are.
21
+ *
22
+ * @write
23
+ * @idempotent
24
+ */
25
+ updateSharePermissions(options: SharePermissionOptions): Promise<void>;
26
+ /**
27
+ * Read the caller's effective access level.
28
+ *
29
+ * @readonly
30
+ */
12
31
  accessLevel(): Promise<"view" | "comment" | "edit" | "owner">;
13
32
  /** Access requests and direct user grants. */
14
33
  readonly access: EntityAccess;
15
34
  /** Favorites identify projects as `project`. */
16
35
  readonly entityType = "project";
36
+ /**
37
+ * Share this project with a channel's current members, as posting it in the
38
+ * channel does. The caller must be in the channel and able to share the
39
+ * project; sharing again changes nothing.
40
+ *
41
+ * @write
42
+ * @idempotent
43
+ */
44
+ shareWithChannel(channel: Channel): Promise<void>;
17
45
  /** The properties service identifies projects as `PROJECT`. */
18
46
  protected readonly propertyEntityType = "PROJECT";
19
47
  protected fetch(): Promise<ProjectDetail>;
20
- /** The project's URL in the Macro web app; hand it to users as the link. */
48
+ /**
49
+ * The project's URL in the Macro web app; hand it to users as the link.
50
+ *
51
+ * @readonly
52
+ */
21
53
  webUrl(): string;
22
54
  /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
23
55
  toJSON(): {
@@ -38,20 +70,39 @@ export declare class Project extends PropertiedEntity<ProjectDetail> {
38
70
  readonly parent: () => Promise<Project | undefined>;
39
71
  /** When the project was created (RFC 3339 timestamp). */
40
72
  readonly createdAt: () => Promise<string | undefined>;
41
- /** The items (documents, chats, subprojects) directly inside this project. */
73
+ /**
74
+ * The items (documents, chats, subprojects) directly inside this project.
75
+ * Agent sessions are never project items; link one from a document in the
76
+ * project instead (see `ProjectNamespace`).
77
+ *
78
+ * @readonly
79
+ */
42
80
  items(): Promise<ProjectItem[]>;
43
- /** Rename the project. */
81
+ /**
82
+ * Rename the project.
83
+ *
84
+ * @write
85
+ * @idempotent
86
+ */
44
87
  rename(name: string): Promise<void>;
45
88
  /**
46
89
  * Delete the project and its contents. Soft by default (reversible with
47
90
  * {@link restore}); pass `permanent: true` to delete irreversibly.
91
+ *
92
+ * @destructive
93
+ * @idempotent
48
94
  */
49
95
  delete(opts?: {
50
96
  permanent?: boolean;
51
97
  }): Promise<void>;
52
- /** Restore a soft-deleted project. */
98
+ /**
99
+ * Restore a soft-deleted project.
100
+ *
101
+ * @write
102
+ * @idempotent
103
+ */
53
104
  restore(): Promise<void>;
54
- /** Search projects by name and content, most relevant first, auto-paginated. */
105
+ /** Search projects by name and content, most relevant first, auto-paginated; `maxItems` caps the total. */
55
106
  static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<Project, any, any>;
56
107
  }
57
108
  export {};
@@ -1,49 +1,105 @@
1
- import type { BulkEntityOptionUpdateResult, BulkEntityPropertiesRequest, CreatePropertyScope, EntityPropertiesResponse, PropertyDataType, PropertyDefinition as PropertyDefinitionRecord, PropertyTargetEntityType as PropertyEntityType, PropertyScope, TagSetResponse } from '../../../generated/properties/types.gen';
1
+ import type { BulkEntityOptionUpdateResult, BulkEntityPropertiesRequest, CreatePropertyScope, EntityPropertiesResponse, PropertyDataType, PropertyDefinition as PropertyDefinitionRecord, PropertyTargetEntityType as PropertyEntityType, PropertyScope, TagScope, TagSetResponse } from '../../../generated/properties/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import type { PropertiedEntity, PropertyOptionDelta } from '../entity';
4
4
  import { PropertyDefinition } from './property-definition';
5
5
  import { PropertyOption } from './property-option';
6
- export type { BulkEntityPropertiesRequest, CreatePropertyScope, EntityPropertiesResponse, PropertyDataType, PropertyDefinitionRecord, PropertyEntityType, PropertyScope, TagSetResponse, };
6
+ export type { BulkEntityPropertiesRequest, CreatePropertyScope, EntityPropertiesResponse, PropertyDataType, PropertyDefinitionRecord, PropertyEntityType, PropertyScope, TagScope, TagSetResponse, };
7
7
  export { PropertyDefinition, PropertyOption };
8
8
  /**
9
9
  * Property definitions and tag sets. Entity-level reads and writes live on
10
10
  * the entity handles ({@link PropertiedEntity.properties}, `setProperty`,
11
11
  * `deleteProperty`).
12
12
  *
13
- * @routing Use when the request is about an item's custom properties themselves, such as defining a property or bulk-setting its options; not creating or updating a task, deal, event or row, whose own methods set their fields.
13
+ * @routing Use when the request is about an item's custom properties or tags themselves, such as defining a property, creating or editing a tag, or bulk-setting options; not creating or updating a task, deal, event or row, whose own methods set their fields.
14
14
  */
15
15
  export declare class PropertiesNamespace {
16
16
  private readonly client;
17
17
  constructor(client: MacroClient);
18
- /** List property definitions visible to the user, pre-hydrated with their records. */
18
+ /**
19
+ * List property definitions visible to the user, pre-hydrated with their records.
20
+ *
21
+ * @readonly
22
+ */
19
23
  list(opts?: {
20
24
  scope?: PropertyScope;
21
25
  forEntityType?: PropertyEntityType;
22
26
  }): Promise<PropertyDefinition[]>;
23
- /** Create a new custom property definition. */
27
+ /**
28
+ * Create a new custom property definition.
29
+ *
30
+ * @write
31
+ */
24
32
  create(opts: {
25
33
  displayName: string;
26
34
  scope: CreatePropertyScope;
27
35
  dataType: PropertyDataType;
28
36
  }): Promise<PropertyDefinition>;
29
- /** A handle to an existing property definition by id. */
37
+ /**
38
+ * A handle to an existing property definition by id.
39
+ *
40
+ * @readonly
41
+ */
30
42
  definition(id: string): PropertyDefinition;
31
- /** Get properties for multiple entities in a single request. */
43
+ /**
44
+ * Get properties for multiple entities in a single request.
45
+ *
46
+ * @readonly
47
+ */
32
48
  bulkEntityProperties(request: BulkEntityPropertiesRequest): Promise<Record<string, EntityPropertiesResponse>>;
33
- /** Apply one multi-select option delta to several entity handles. */
49
+ /**
50
+ * Apply one multi-select option delta to several entity handles.
51
+ *
52
+ * @write
53
+ * @idempotent
54
+ * @mcp-exclude Takes a handle built from a listing record, which an MCP call can't reference.
55
+ */
34
56
  updateEntityPropertyOptions(entities: PropertiedEntity<unknown>[], change: PropertyOptionDelta): Promise<BulkEntityOptionUpdateResult[]>;
35
- /** Add a select option to a multi-select property value on an entity. */
57
+ /**
58
+ * Add a select option to a multi-select property value on an entity.
59
+ *
60
+ * @write
61
+ * @idempotent
62
+ * @mcp-exclude Takes a handle built from a listing record, which an MCP call can't reference.
63
+ */
36
64
  addEntityPropertyOption(opts: {
37
65
  entity: PropertiedEntity<unknown>;
38
66
  property: PropertyDefinition;
39
67
  option: PropertyOption;
40
68
  }): Promise<void>;
41
- /** Remove a select option from a multi-select property value on an entity. */
69
+ /**
70
+ * Remove a select option from a multi-select property value on an entity.
71
+ *
72
+ * @write
73
+ * @idempotent
74
+ * @mcp-exclude Takes a handle built from a listing record, which an MCP call can't reference.
75
+ */
42
76
  removeEntityPropertyOption(opts: {
43
77
  entity: PropertiedEntity<unknown>;
44
78
  property: PropertyDefinition;
45
79
  option: PropertyOption;
46
80
  }): Promise<void>;
47
- /** The user's tag sets: their personal set, plus their team's when on a team. */
81
+ /**
82
+ * The user's tag sets: their personal set, plus their team's when on a team.
83
+ * A set without a `definition` has no tags yet; {@link createTag} creates it.
84
+ * Edit or delete a tag through `definition(set.definition.id).options()`.
85
+ *
86
+ * @readonly
87
+ */
48
88
  tags(): Promise<TagSetResponse[]>;
89
+ /**
90
+ * Create a tag, provisioning the tag set on its first tag. Tags match by
91
+ * label, so check {@link tags} first and never duplicate one in the same set.
92
+ * Apply it with `item.updatePropertyOptions([{ property, add: [tag] }])`,
93
+ * where `property` is `definition(tag.definitionId)`.
94
+ *
95
+ * @write
96
+ */
97
+ createTag(opts: {
98
+ /** The label, e.g. "Urgent". */
99
+ label: string;
100
+ /** A hex color such as `#46A758`. */
101
+ color?: string;
102
+ /** `user` (the default) for the user's own tags, `team` for their team's shared tags. */
103
+ scope?: TagScope;
104
+ }): Promise<PropertyOption>;
49
105
  }
@@ -0,0 +1 @@
1
+ export {};
@@ -32,14 +32,39 @@ export declare class PropertyDefinition {
32
32
  get isMultiSelect(): Promise<boolean>;
33
33
  get createdAt(): Promise<string>;
34
34
  get updatedAt(): Promise<string>;
35
- /** Delete this property definition. */
35
+ /**
36
+ * Delete this property definition.
37
+ *
38
+ * @destructive
39
+ * @idempotent
40
+ */
36
41
  delete(): Promise<void>;
37
- /** The selectable options for this definition (select-type properties). */
42
+ /**
43
+ * The selectable options for this definition (select-type properties).
44
+ *
45
+ * @readonly
46
+ */
38
47
  options(): Promise<PropertyOption[]>;
39
- /** Add an option to this select-type property. */
48
+ /**
49
+ * Add an option to this select-type property.
50
+ *
51
+ * @write
52
+ */
40
53
  addOption(option: AddPropertyOptionRequest): Promise<PropertyOption>;
41
- /** Update an option (label, color, display order). */
54
+ /**
55
+ * Update an option (label, color, display order).
56
+ *
57
+ * @write
58
+ * @idempotent
59
+ * @mcp-exclude Takes a handle built from a listing record, which an MCP call can't reference.
60
+ */
42
61
  updateOption(option: PropertyOption, updates: UpdatePropertyOptionRequest): Promise<PropertyOption>;
43
- /** Delete an option from this property. */
62
+ /**
63
+ * Delete an option from this property.
64
+ *
65
+ * @destructive
66
+ * @idempotent
67
+ * @mcp-exclude Takes a handle built from a listing record, which an MCP call can't reference.
68
+ */
44
69
  deleteOption(option: PropertyOption): Promise<void>;
45
70
  }
@@ -5,6 +5,8 @@ export type { UpdatePropertyOptionRequest };
5
5
  * A selectable option on a select-type property definition. There is no
6
6
  * single-option GET, so instances are only built from a seed record — via
7
7
  * {@link PropertyDefinition.options} or {@link PropertyDefinition.addOption}.
8
+ *
9
+ * @mcp-exclude Built from a listing record; no id-only reference an MCP call can pass.
8
10
  */
9
11
  export declare class PropertyOption {
10
12
  private readonly client;
@@ -25,8 +27,18 @@ export declare class PropertyOption {
25
27
  get createdAt(): string;
26
28
  /** When the option was last updated. */
27
29
  get updatedAt(): string;
28
- /** Update this option's label, color, or display order. */
30
+ /**
31
+ * Update this option's label, color, or display order.
32
+ *
33
+ * @write
34
+ * @idempotent
35
+ */
29
36
  update(updates: UpdatePropertyOptionRequest): Promise<this>;
30
- /** Delete this option from its property definition. */
37
+ /**
38
+ * Delete this option from its property definition.
39
+ *
40
+ * @destructive
41
+ * @idempotent
42
+ */
31
43
  delete(): Promise<void>;
32
44
  }
@@ -15,7 +15,11 @@ export interface ReferralLink {
15
15
  export declare class ReferralNamespace {
16
16
  private readonly client;
17
17
  constructor(client: MacroClient);
18
- /** The caller's referral link, to share wherever the user wants. */
18
+ /**
19
+ * The caller's referral link, to share wherever the user wants.
20
+ *
21
+ * @readonly
22
+ */
19
23
  link(): Promise<ReferralLink>;
20
24
  /**
21
25
  * Email an invite to join Macro, with the caller's referral link; only send
@@ -28,6 +32,9 @@ export declare class ReferralNamespace {
28
32
  * instead, use `Team.invite`.
29
33
  *
30
34
  * @param email - The address to invite.
35
+ *
36
+ * @send
37
+ * @openworld
31
38
  */
32
39
  invite(email: string): Promise<void>;
33
40
  }