@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,5 +1,6 @@
1
1
  import type { ExternalChatDetail, UpdateSharePermissionRequestV2 } from '../../../generated/storage/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
+ import type { Channel } from '../channels/channel';
3
4
  import { FavoritableEntity } from '../entity';
4
5
  import { User } from '../users/user';
5
6
  import { type WhatsAppCommunity } from '../whatsapp/chat';
@@ -30,6 +31,15 @@ export type ExternalChatContent = {
30
31
  export declare class ExternalChat extends FavoritableEntity<ExternalChatDetail> {
31
32
  /** Canonical sharing and favorites kind. */
32
33
  readonly entityType: "external_chat";
34
+ /**
35
+ * Share this chat with a channel's current members, as posting it in the
36
+ * channel does. The caller must be in the channel and able to share the
37
+ * chat; sharing again changes nothing.
38
+ *
39
+ * @write
40
+ * @idempotent
41
+ */
42
+ shareWithChannel(channel: Channel): Promise<void>;
33
43
  /** Reference an added chat; access is checked on each request. */
34
44
  static byId(client: MacroClient, id: string): ExternalChat;
35
45
  protected fetch(): Promise<ExternalChatDetail>;
@@ -59,35 +69,89 @@ export declare class ExternalChat extends FavoritableEntity<ExternalChatDetail>
59
69
  readonly disappearingSeconds: () => Promise<number | undefined>;
60
70
  /** Actual owner, independent of provider membership. */
61
71
  readonly owner: () => Promise<User>;
62
- /** The community a group belongs to, if any: the community's own provider chat, its name, and whether this is its announcement group. */
72
+ /**
73
+ * The community a group belongs to, if any: the community's own provider chat, its name, and whether this is its announcement group.
74
+ *
75
+ * @readonly
76
+ */
63
77
  community(): Promise<WhatsAppCommunity | undefined>;
64
- /** Iterate newest-first timeline pages lazily. */
78
+ /**
79
+ * Iterate newest-first timeline pages lazily; `maxItems` caps the total.
80
+ *
81
+ * @readonly
82
+ */
65
83
  messages(options?: {
66
84
  limit?: number;
85
+ maxItems?: number;
67
86
  }): AsyncGenerator<ExternalChatMessage>;
68
- /** Advance the caller's own read cursor. */
87
+ /**
88
+ * Advance the caller's own read cursor.
89
+ *
90
+ * @write
91
+ * @idempotent
92
+ */
69
93
  markRead(message: ExternalChatMessage): Promise<void>;
70
- /** Read standard link/team sharing settings. */
94
+ /**
95
+ * Read standard link/team sharing settings.
96
+ *
97
+ * @readonly
98
+ */
71
99
  permissions(): Promise<import("../../../generated/storage").SharePermissionV2>;
72
- /** Actual owner updates standard link/team sharing settings. */
100
+ /**
101
+ * Actual owner updates standard link/team sharing settings.
102
+ *
103
+ * @write
104
+ * @idempotent
105
+ */
73
106
  updatePermissions(update: UpdateSharePermissionRequestV2): Promise<void>;
74
- /** Owner stops syncing the chat; history and established sharing stay. */
107
+ /**
108
+ * Owner stops syncing the chat; history and established sharing stay.
109
+ *
110
+ * @destructive
111
+ * @idempotent
112
+ */
75
113
  remove(): Promise<void>;
76
- /** Stage a supported attachment for a deliberate send. */
114
+ /**
115
+ * Stage a supported attachment for a deliberate send.
116
+ *
117
+ * @write
118
+ * @mcp-exclude Takes file bytes; MCP calls carry JSON only.
119
+ */
77
120
  upload(file: Blob | File): Promise<ExternalChatUpload>;
78
- /** Personal sessions and owner API credentials can send. Bots never send.
121
+ /** Send to the chat; an agent's program must quote the user's reply approving this send in `userConfirmation`, or it is refused (403).
122
+ *
123
+ * Write the message out, ask, and send only after the user says yes; the
124
+ * request that asked for the message is not the approval. Personal sessions
125
+ * and owner API credentials can send. Bots never send.
79
126
  * Preserve the idempotency key; uncertain outcomes are never automatically resent.
80
127
  * The server enforces one request per second per user.
128
+ *
129
+ * @destructive
130
+ * @openworld
81
131
  */
82
132
  send(content: ExternalChatContent, options: {
83
133
  idempotencyKey: string;
84
134
  replyTo?: ExternalChatMessage;
135
+ /** The user's own reply approving this send, quoted verbatim. Required from an agent's program. */
136
+ userConfirmation?: string;
85
137
  }): Promise<ExternalChatSend>;
86
- /** Read only the caller's pending, uncertain or failed sends. */
138
+ /**
139
+ * Read only the caller's pending, uncertain or failed sends.
140
+ *
141
+ * @readonly
142
+ */
87
143
  sends(): Promise<ExternalChatSend[]>;
88
- /** Read delivery for selected caller-owned intents or messages. */
144
+ /**
145
+ * Read delivery for selected caller-owned intents or messages.
146
+ *
147
+ * @readonly
148
+ */
89
149
  delivery(sends: Array<ExternalChatSend | ExternalChatMessage>): Promise<ExternalChatSend[]>;
90
- /** Read attachment states for selected messages. */
150
+ /**
151
+ * Read attachment states for selected messages.
152
+ *
153
+ * @readonly
154
+ */
91
155
  messageAttachments(messages: ExternalChatMessage[]): Promise<{
92
156
  message: ExternalChatMessage;
93
157
  attachments: {
@@ -99,7 +163,11 @@ export declare class ExternalChat extends FavoritableEntity<ExternalChatDetail>
99
163
  url: string | undefined;
100
164
  }[];
101
165
  }[]>;
102
- /** Reload detail, permissions and caller capabilities. */
166
+ /**
167
+ * Reload detail, permissions and caller capabilities.
168
+ *
169
+ * @readonly
170
+ */
103
171
  refresh(): Promise<this>;
104
172
  private assertChat;
105
173
  }
@@ -22,7 +22,7 @@ export declare class ExternalChatMessage extends MacroEntity<ExternalChatMessage
22
22
  readonly editedAt: () => Promise<string | undefined>;
23
23
  /** Deleted for everyone. */
24
24
  readonly deleted: () => Promise<boolean>;
25
- /** Grouped emoji counts and caller's own reaction. */
25
+ /** Reactions by emoji: who reacted, and whether the caller did. */
26
26
  readonly reactions: () => Promise<import("../../../generated/storage").ExternalChatReaction[]>;
27
27
  /** Caller-owned send's delivery state, when present. */
28
28
  readonly deliveryState: () => Promise<NonNullable<import("../../../generated/storage").ExternalChatDeliveryState | null | undefined> | undefined>;
@@ -11,7 +11,11 @@ export declare class ExternalChatsNamespace {
11
11
  private readonly client;
12
12
  /** Bind external chat operations to this authenticated client. */
13
13
  constructor(client: MacroClient);
14
- /** Added chats the caller can view, including without a provider account of their own. */
14
+ /**
15
+ * Added chats the caller can view, including without a provider account of their own.
16
+ *
17
+ * @readonly
18
+ */
15
19
  list(): Promise<ExternalChat[]>;
16
20
  /** Reference an added chat without fetching it. */
17
21
  byId(id: string): ExternalChat;
@@ -21,12 +21,20 @@ export declare class ExternalChatSend extends MacroEntity<ExternalChatSendProgre
21
21
  readonly createdAt: () => Promise<string>;
22
22
  /** Chat message once the provider accepted the send. */
23
23
  readonly message: () => Promise<ExternalChatMessage | undefined>;
24
- /** Inspect the original intent for reconciliation; never resubmit an unknown outcome automatically. */
24
+ /**
25
+ * Inspect the original intent for reconciliation; never resubmit an unknown outcome automatically.
26
+ *
27
+ * @readonly
28
+ */
25
29
  request(): Promise<{
26
30
  idempotencyKey: string;
27
31
  message: ExternalChatContent;
28
32
  replyTo?: ExternalChatMessage;
29
33
  }>;
30
- /** Fetch current delivery state without retrying or submitting the message. */
34
+ /**
35
+ * Fetch current delivery state without retrying or submitting the message.
36
+ *
37
+ * @readonly
38
+ */
31
39
  refresh(): Promise<this>;
32
40
  }
@@ -22,14 +22,31 @@ export type FavoritesFilter = {
22
22
  export declare class FavoritesNamespace {
23
23
  private readonly client;
24
24
  constructor(client: MacroClient);
25
- /** The user's favorites, in manual order. */
25
+ /**
26
+ * The user's favorites, in manual order.
27
+ *
28
+ * @readonly
29
+ */
26
30
  list(filter?: FavoritesFilter): Promise<Favorite[]>;
27
31
  /**
28
32
  * Favorite an entity. Returns the favorite record.
33
+ *
34
+ * @write
35
+ * @idempotent
29
36
  */
30
37
  add(entity: FavoritableEntity<unknown>): Promise<Favorite>;
31
- /** Remove an entity from the user's favorites. */
38
+ /**
39
+ * Remove an entity from the user's favorites.
40
+ *
41
+ * @write
42
+ * @idempotent
43
+ */
32
44
  remove(entity: FavoritableEntity<unknown>): Promise<void>;
33
- /** Reorder the favorites: pass every favorited entity in the desired order. */
45
+ /**
46
+ * Reorder the favorites: pass every favorited entity in the desired order.
47
+ *
48
+ * @write
49
+ * @idempotent
50
+ */
34
51
  reorder(favorites: FavoriteEntityRef[]): Promise<void>;
35
52
  }
@@ -26,7 +26,11 @@ export declare class ForeignEntity extends FavoritableEntity<ForeignEntityDetail
26
26
  readonly createdAt: () => Promise<string>;
27
27
  /** When the record was last updated (ISO timestamp). */
28
28
  readonly updatedAt: () => Promise<string>;
29
- /** Arbitrary source-specific metadata stored with the mapping. */
29
+ /**
30
+ * Arbitrary source-specific metadata stored with the mapping.
31
+ *
32
+ * @readonly
33
+ */
30
34
  metadata(): Promise<unknown>;
31
35
  }
32
36
  export {};
@@ -27,7 +27,7 @@ export interface GithubPullRequestFacets {
27
27
  labels: GithubLabelFacet[];
28
28
  }
29
29
  /**
30
- * @routing Use when resolving a linked external entity, such as an imported item; not Macro's own items.
30
+ * @routing Use when looking up, favoriting or muting an item linked into Macro from another system, such as a GitHub pull request, by its id in that system; not items created in Macro.
31
31
  */
32
32
  export declare class ForeignEntityNamespace {
33
33
  private readonly client;
@@ -38,6 +38,8 @@ export declare class ForeignEntityNamespace {
38
38
  *
39
39
  * `foreignEntityId` may contain slashes — sources store them inside the
40
40
  * identifier, for example `owner/repo/pull/12`.
41
+ *
42
+ * @readonly
41
43
  */
42
44
  bySource(source: string, foreignEntityId: string): Promise<ForeignEntity>;
43
45
  /**
@@ -45,6 +47,8 @@ export declare class ForeignEntityNamespace {
45
47
  * requests visible to the authenticated user and their team, each with how
46
48
  * many pull requests it covers. A pull request visible to both the user and
47
49
  * the team counts once.
50
+ *
51
+ * @readonly
48
52
  */
49
53
  githubPullRequestFacets(): Promise<GithubPullRequestFacets>;
50
54
  }
@@ -1,5 +1,6 @@
1
- import type { BookingTarget, CellValue, EntityKind, FilterGroup, FilterTest, FormDetail, FormPublicationProblem, ResponseStatus, SharePermissionV2, UnlockedBooking, UpdateForm, UpdateSharePermissionRequestV2, Widget } from '../../../generated/storage/types.gen';
1
+ import type { BookingTarget, CellValue, EntityAppearance, EntityKind, FilterGroup, FilterTest, FormDetail, FormPublicationProblem, ResponseStatus, SharePermissionV2, UnlockedBooking, UpdateForm, UpdateSharePermissionRequestV2, Widget } from '../../../generated/storage/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
+ import type { Channel } from '../channels/channel';
3
4
  import type { DatabaseColumn } from '../databases/column';
4
5
  import { Database } from '../databases/database';
5
6
  import { DatabaseRow } from '../databases/row';
@@ -178,10 +179,23 @@ export declare class Form extends MacroEntity<FormDetail> {
178
179
  }): Promise<Form>;
179
180
  /** Forms shared with the caller, or live forms over a specified database. */
180
181
  static list(client: MacroClient, database?: Database): Promise<Form[]>;
181
- /** The form's presentation and column facts; this never contains response rows. */
182
+ /**
183
+ * The form's presentation and column facts; this never contains response rows.
184
+ *
185
+ * @readonly
186
+ */
182
187
  schema(): Promise<FormDetail>;
183
188
  /** The form's display name. */
184
189
  readonly name: () => Promise<string>;
190
+ /** Shared icon and color overrides. */
191
+ readonly appearance: () => Promise<EntityAppearance | null | undefined>;
192
+ /**
193
+ * Replace shared appearance. Pass {} to reset both overrides.
194
+ *
195
+ * @write
196
+ * @idempotent
197
+ */
198
+ setAppearance(appearance: EntityAppearance): Promise<EntityAppearance>;
185
199
  /** Introductory text shown to respondents. */
186
200
  readonly description: () => Promise<string>;
187
201
  /** The owning user. */
@@ -198,11 +212,33 @@ export declare class Form extends MacroEntity<FormDetail> {
198
212
  readonly closesAt: () => Promise<string | undefined>;
199
213
  /** The caller's access level. */
200
214
  readonly access: () => Promise<import("../../../generated/storage").FormAccess>;
201
- /** Sections in display order. */
215
+ /**
216
+ * Share this form with a channel's current members, as posting it in the
217
+ * channel does. The caller must be in the channel and able to share the
218
+ * form; sharing again changes nothing.
219
+ *
220
+ * @write
221
+ * @idempotent
222
+ */
223
+ shareWithChannel(channel: Channel): Promise<void>;
224
+ /**
225
+ * Sections in display order.
226
+ *
227
+ * @readonly
228
+ */
202
229
  sections(): Promise<FormSection[]>;
203
- /** All questions in display order, skipping gates. */
230
+ /**
231
+ * All questions in display order, skipping gates.
232
+ *
233
+ * @readonly
234
+ */
204
235
  questions(): Promise<FormQuestion[]>;
205
- /** Update presentation or owner-controlled settings; null explicitly clears the closing time. */
236
+ /**
237
+ * Update presentation or owner-controlled settings; null explicitly clears the closing time.
238
+ *
239
+ * @write
240
+ * @idempotent
241
+ */
206
242
  update(updates: UpdateForm): Promise<this>;
207
243
  private assertOwns;
208
244
  /**
@@ -210,26 +246,63 @@ export declare class Form extends MacroEntity<FormDetail> {
210
246
  * omitted handles mint sections or questions. Column facts use the database API.
211
247
  * A publicationError means the draft was saved but respondents still see the last
212
248
  * valid version. Repair the reported problem or reload to retry publication.
249
+ *
250
+ * @destructive
251
+ * @idempotent
213
252
  */
214
253
  replaceLayout(sections: FormSectionPlacement[]): Promise<FormLayoutResult>;
215
254
  private wireAnswers;
216
255
  private unlockedBooking;
217
256
  private outcome;
218
- /** Submit answers. Signed-in respondents get at most one response; use editResponse afterwards. */
257
+ /**
258
+ * Submit answers. Signed-in respondents get at most one response; use editResponse afterwards.
259
+ *
260
+ * @write
261
+ */
219
262
  submit(answers: FormAnswer[]): Promise<FormSubmissionOutcome>;
220
- /** Replace the caller's answers while the form is open; gates are evaluated again. */
263
+ /**
264
+ * Replace the caller's answers while the form is open; gates are evaluated again.
265
+ *
266
+ * @destructive
267
+ * @idempotent
268
+ */
221
269
  editResponse(answers: FormAnswer[]): Promise<FormSubmissionOutcome>;
222
- /** Read the caller's receipt and answers without reading anyone else's responses. */
270
+ /**
271
+ * Read the caller's receipt and answers without reading anyone else's responses.
272
+ *
273
+ * @readonly
274
+ */
223
275
  myResponse(): Promise<MyFormResponse>;
224
- /** Ledger counts and total table rows; requires edit access. */
276
+ /**
277
+ * Ledger counts and total table rows; requires edit access.
278
+ *
279
+ * @readonly
280
+ */
225
281
  responseSummary(): Promise<FormResponseSummary>;
226
- /** Choice and checkbox counts, available to viewers when tally visibility is enabled. */
282
+ /**
283
+ * Choice and checkbox counts, available to viewers when tally visibility is enabled.
284
+ *
285
+ * @readonly
286
+ */
227
287
  tally(): Promise<FormQuestionTally[]>;
228
- /** Read the form's sharing grants. Requires ownership. */
288
+ /**
289
+ * Read the form's sharing grants. Requires ownership.
290
+ *
291
+ * @readonly
292
+ */
229
293
  sharePermissions(): Promise<SharePermissionV2>;
230
- /** Update grants. Public responding is controlled by audience, not link sharing. */
294
+ /**
295
+ * Update grants. Public responding is controlled by audience, not link sharing.
296
+ *
297
+ * @write
298
+ * @idempotent
299
+ */
231
300
  updateSharePermissions(request: UpdateSharePermissionRequestV2): Promise<SharePermissionV2>;
232
- /** Open the form's builder in Macro. */
301
+ /**
302
+ * Open the form's builder in Macro.
303
+ *
304
+ * @readonly
305
+ */
233
306
  webUrl(): string;
234
307
  /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
235
308
  toJSON(): {
@@ -237,6 +310,10 @@ export declare class Form extends MacroEntity<FormDetail> {
237
310
  id: string;
238
311
  detail?: FormDetail | undefined;
239
312
  };
240
- /** The respondent page, which public forms also expose without signing in. */
313
+ /**
314
+ * The respondent page, which public forms also expose without signing in.
315
+ *
316
+ * @readonly
317
+ */
241
318
  respondUrl(): string;
242
319
  }
@@ -12,11 +12,19 @@ export declare class FormNamespace {
12
12
  constructor(client: MacroClient);
13
13
  /** A form handle. Details load on first access. */
14
14
  byId(id: string): Form;
15
- /** Create a form over an existing table, or create its own Responses database. */
15
+ /**
16
+ * Create a form over an existing table, or create its own Responses database.
17
+ *
18
+ * @write
19
+ */
16
20
  create(options: {
17
21
  name: string;
18
22
  table?: DatabaseTable;
19
23
  }): Promise<Form>;
20
- /** List forms shared with the caller, or forms over a database the caller can read. */
24
+ /**
25
+ * List forms shared with the caller, or forms over a database the caller can read.
26
+ *
27
+ * @readonly
28
+ */
21
29
  list(database?: Database): Promise<Form[]>;
22
30
  }
@@ -10,13 +10,29 @@ export declare class FormQuestion {
10
10
  private constructor();
11
11
  /** A question handle within a form. */
12
12
  static byId(form: Form, id: string): FormQuestion;
13
- /** The question's current presentation and column facts. */
13
+ /**
14
+ * The question's current presentation and column facts.
15
+ *
16
+ * @readonly
17
+ */
14
18
  detail(): Promise<FormQuestionDetail>;
15
- /** The question's current title (its column's name). */
19
+ /**
20
+ * The question's current title (its column's name).
21
+ *
22
+ * @readonly
23
+ */
16
24
  title(): Promise<string>;
17
- /** The column behind the question. Reading the column itself needs database access. */
25
+ /**
26
+ * The column behind the question. Reading the column itself needs database access.
27
+ *
28
+ * @readonly
29
+ */
18
30
  column(): Promise<DatabaseColumn>;
19
- /** Current choices, in display order. */
31
+ /**
32
+ * Current choices, in display order.
33
+ *
34
+ * @readonly
35
+ */
20
36
  options(): Promise<FormOption[]>;
21
37
  }
22
38
  /** A choice of one form question, resolved through that question's current options. */
@@ -28,10 +44,22 @@ export declare class FormOption {
28
44
  private constructor();
29
45
  /** A handle to a known choice of a question. */
30
46
  static byId(question: FormQuestion, id: string): FormOption;
31
- /** The choice's label and color. */
47
+ /**
48
+ * The choice's label and color.
49
+ *
50
+ * @readonly
51
+ */
32
52
  detail(): Promise<QuestionOption>;
33
- /** The choice's label. */
53
+ /**
54
+ * The choice's label.
55
+ *
56
+ * @readonly
57
+ */
34
58
  label(): Promise<string>;
35
- /** The choice's color, when one is set. */
59
+ /**
60
+ * The choice's color, when one is set.
61
+ *
62
+ * @readonly
63
+ */
36
64
  color(): Promise<string | undefined>;
37
65
  }
@@ -18,15 +18,35 @@ export declare class FormResponse {
18
18
  private load;
19
19
  /** A response handle, optionally seeded with an already returned receipt. */
20
20
  static byId(form: Form, id: string, snapshot?: ResponseSnapshot): FormResponse;
21
- /** Whether this receipt was submitted or stopped by a gate. */
21
+ /**
22
+ * Whether this receipt was submitted or stopped by a gate.
23
+ *
24
+ * @readonly
25
+ */
22
26
  status(): Promise<ResponseStatus>;
23
- /** The receipt's row, if any. Reading that row requires database access. */
27
+ /**
28
+ * The receipt's row, if any. Reading that row requires database access.
29
+ *
30
+ * @readonly
31
+ */
24
32
  row(): Promise<DatabaseRow | undefined>;
25
- /** Answers as submitted or last read. Refresh to include later changes to the row. */
33
+ /**
34
+ * Answers as submitted or last read. Refresh to include later changes to the row.
35
+ *
36
+ * @readonly
37
+ */
26
38
  answers(): Promise<FormAnswer[]>;
27
- /** The booking step unlocked by this saved response, if any. */
39
+ /**
40
+ * The booking step unlocked by this saved response, if any.
41
+ *
42
+ * @readonly
43
+ */
28
44
  booking(): Promise<FormBookingStep | undefined>;
29
- /** Reload the caller's current receipt; requires a signed-in respondent. */
45
+ /**
46
+ * Reload the caller's current receipt; requires a signed-in respondent.
47
+ *
48
+ * @readonly
49
+ */
30
50
  refresh(): Promise<this>;
31
51
  }
32
52
  export {};
@@ -10,10 +10,22 @@ export declare class FormSection {
10
10
  private constructor();
11
11
  /** A section handle within a form. */
12
12
  static byId(form: Form, id: string): FormSection;
13
- /** The section's current presentation. */
13
+ /**
14
+ * The section's current presentation.
15
+ *
16
+ * @readonly
17
+ */
14
18
  detail(): Promise<FormSectionDetail>;
15
- /** The section heading. */
19
+ /**
20
+ * The section heading.
21
+ *
22
+ * @readonly
23
+ */
16
24
  title(): Promise<string>;
17
- /** Questions in display order; gates contain no questions. */
25
+ /**
26
+ * Questions in display order; gates contain no questions.
27
+ *
28
+ * @readonly
29
+ */
18
30
  questions(): Promise<FormQuestion[]>;
19
31
  }
@@ -11,6 +11,10 @@ export declare class GithubPullRequestNamespace {
11
11
  constructor(client: MacroClient);
12
12
  /** Construct from a Macro foreign entity's identity. */
13
13
  byId(id: string): GithubPullRequest;
14
- /** Resolve a foreign entity as a pull request. */
14
+ /**
15
+ * Resolve a foreign entity as a pull request.
16
+ *
17
+ * @readonly
18
+ */
15
19
  forEntity(entity: ForeignEntity): GithubPullRequest;
16
20
  }
@@ -12,13 +12,21 @@ export declare class GithubPullRequest extends MacroEntity<StoredGithubPullReque
12
12
  readonly url: () => Promise<string>;
13
13
  /** Current state. */
14
14
  readonly status: () => Promise<NonNullable<"open" | "closed" | "merged" | null | undefined> | undefined>;
15
- /** Captured change metadata, when available. */
15
+ /**
16
+ * Captured change metadata, when available.
17
+ *
18
+ * @readonly
19
+ */
16
20
  changes(): Promise<{
17
21
  changeset?: PullRequestChangeset;
18
22
  error?: string;
19
23
  }>;
20
24
  }
21
- /** One captured diff belonging to a pull request. */
25
+ /**
26
+ * One captured diff belonging to a pull request.
27
+ *
28
+ * @mcp-exclude Built from a listing record; no id-only reference an MCP call can pass.
29
+ */
22
30
  export declare class PullRequestChangeset {
23
31
  private readonly client;
24
32
  /** Parent pull request. */
@@ -32,7 +40,11 @@ export declare class PullRequestChangeset {
32
40
  record: ChangesetDto);
33
41
  /** Captured identity. */
34
42
  get id(): string;
35
- /** Read the captured unified patch. */
43
+ /**
44
+ * Read the captured unified patch.
45
+ *
46
+ * @readonly
47
+ */
36
48
  patch(): Promise<string>;
37
49
  /** Serialize captured metadata and parent identity. */
38
50
  toJSON(): {