@macro-inc/sdk 0.4.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (185) hide show
  1. package/README.md +169 -7
  2. package/dist/{chunk-PTX2RV2N.js → chunk-3SW6QVDV.js} +33 -0
  3. package/dist/{chunk-XFA7NCJ5.js → chunk-GT5EUYOR.js} +13 -15
  4. package/dist/{chunk-ZLBDES7U.js → chunk-HIW6KU2I.js} +490 -4
  5. package/dist/{chunk-AZJUIUIV.js → chunk-J2VK3NOR.js} +56 -0
  6. package/dist/{chunk-PZPTJI6F.js → chunk-UVJLWLSJ.js} +41 -2
  7. package/dist/generated/agent-fold/index.d.ts +8 -6
  8. package/dist/generated/agent-harness/index.d.ts +1 -1
  9. package/dist/generated/agent-harness/index.js +1 -1
  10. package/dist/generated/agent-harness/sdk.gen.d.ts +17 -1
  11. package/dist/generated/agent-harness/types.gen.d.ts +188 -3
  12. package/dist/generated/auth/index.js +1 -1
  13. package/dist/generated/auth/sdk.gen.d.ts +13 -15
  14. package/dist/generated/auth/types.gen.d.ts +36 -17
  15. package/dist/generated/cognition/index.d.ts +1 -1
  16. package/dist/generated/cognition/index.js +1 -1
  17. package/dist/generated/cognition/sdk.gen.d.ts +38 -1
  18. package/dist/generated/cognition/types.gen.d.ts +473 -4
  19. package/dist/generated/connection/types.gen.d.ts +1 -1
  20. package/dist/generated/notification/index.d.ts +1 -1
  21. package/dist/generated/notification/types.gen.d.ts +36 -1
  22. package/dist/generated/scheduled-action/index.d.ts +1 -1
  23. package/dist/generated/scheduled-action/index.js +1 -1
  24. package/dist/generated/scheduled-action/sdk.gen.d.ts +17 -2
  25. package/dist/generated/scheduled-action/types.gen.d.ts +642 -104
  26. package/dist/generated/storage/index.d.ts +1 -1
  27. package/dist/generated/storage/index.js +1 -1
  28. package/dist/generated/storage/sdk.gen.d.ts +204 -5
  29. package/dist/generated/storage/types.gen.d.ts +3969 -374
  30. package/dist/src/entities/account-managers/grant.d.ts +28 -5
  31. package/dist/src/entities/account-managers/namespace.d.ts +15 -3
  32. package/dist/src/entities/activity/entity.d.ts +7 -0
  33. package/dist/src/entities/activity/namespace.d.ts +58 -0
  34. package/dist/src/entities/activity/namespace.test.d.ts +1 -0
  35. package/dist/src/entities/agent-sessions/activity.d.ts +10 -2
  36. package/dist/src/entities/agent-sessions/agent-session.d.ts +193 -18
  37. package/dist/src/entities/agent-sessions/code-execution.d.ts +15 -3
  38. package/dist/src/entities/agent-sessions/conversation.d.ts +46 -9
  39. package/dist/src/entities/agent-sessions/namespace.d.ts +71 -16
  40. package/dist/src/entities/agent-sessions/origin.d.ts +1 -1
  41. package/dist/src/entities/agent-sessions/queued-action.d.ts +17 -3
  42. package/dist/src/entities/agent-sessions/review.d.ts +55 -4
  43. package/dist/src/entities/agent-sessions/tool-approval.d.ts +5 -1
  44. package/dist/src/entities/agents/agent.d.ts +98 -3
  45. package/dist/src/entities/agents/namespace.d.ts +52 -8
  46. package/dist/src/entities/ai/namespace.d.ts +9 -1
  47. package/dist/src/entities/api-keys/api-key.d.ts +6 -1
  48. package/dist/src/entities/api-keys/namespace.d.ts +15 -3
  49. package/dist/src/entities/bots/bot.d.ts +38 -6
  50. package/dist/src/entities/bots/namespace.d.ts +13 -1
  51. package/dist/src/entities/bots/token.d.ts +6 -1
  52. package/dist/src/entities/calendar/booking-link.d.ts +7 -1
  53. package/dist/src/entities/calendar/booking-namespace.d.ts +13 -0
  54. package/dist/src/entities/calendar/booking.d.ts +15 -0
  55. package/dist/src/entities/calendar/calendar.d.ts +7 -1
  56. package/dist/src/entities/calendar/event.d.ts +59 -9
  57. package/dist/src/entities/calendar/namespace.d.ts +88 -10
  58. package/dist/src/entities/calendar/replacement.d.ts +19 -3
  59. package/dist/src/entities/calls/call-record.d.ts +90 -14
  60. package/dist/src/entities/calls/connection.d.ts +7 -1
  61. package/dist/src/entities/calls/message.d.ts +27 -5
  62. package/dist/src/entities/calls/namespace.d.ts +15 -3
  63. package/dist/src/entities/canvases/canvas.d.ts +324 -0
  64. package/dist/src/entities/channels/access-request.d.ts +10 -2
  65. package/dist/src/entities/channels/activity.d.ts +20 -4
  66. package/dist/src/entities/channels/channel.d.ts +130 -23
  67. package/dist/src/entities/channels/labels.d.ts +41 -7
  68. package/dist/src/entities/channels/message.d.ts +41 -7
  69. package/dist/src/entities/channels/namespace.d.ts +28 -3
  70. package/dist/src/entities/channels/post.test.d.ts +1 -0
  71. package/dist/src/entities/channels/thread.d.ts +19 -3
  72. package/dist/src/entities/chats/chat.d.ts +56 -6
  73. package/dist/src/entities/chats/generation.d.ts +11 -2
  74. package/dist/src/entities/chats/namespace.d.ts +10 -2
  75. package/dist/src/entities/connected-apps/connected-app.d.ts +14 -1
  76. package/dist/src/entities/connected-apps/connector.d.ts +3 -0
  77. package/dist/src/entities/connected-apps/namespace.d.ts +16 -0
  78. package/dist/src/entities/crm/company.d.ts +63 -15
  79. package/dist/src/entities/crm/contact.d.ts +60 -13
  80. package/dist/src/entities/crm/namespace.d.ts +85 -11
  81. package/dist/src/entities/crm/pipeline-entry.d.ts +102 -0
  82. package/dist/src/entities/crm/pipeline.d.ts +271 -27
  83. package/dist/src/entities/crm/pipelines.d.ts +39 -2
  84. package/dist/src/entities/databases/column.d.ts +54 -7
  85. package/dist/src/entities/databases/database.d.ts +126 -12
  86. package/dist/src/entities/databases/namespace.d.ts +16 -4
  87. package/dist/src/entities/databases/row.d.ts +2 -0
  88. package/dist/src/entities/databases/saved-query.d.ts +145 -0
  89. package/dist/src/entities/databases/table.d.ts +64 -10
  90. package/dist/src/entities/databases/view.d.ts +27 -5
  91. package/dist/src/entities/databases/webhook.d.ts +8 -1
  92. package/dist/src/entities/documents/ai-edit.d.ts +2 -0
  93. package/dist/src/entities/documents/anchor.d.ts +12 -2
  94. package/dist/src/entities/documents/comment.d.ts +29 -5
  95. package/dist/src/entities/documents/document.d.ts +243 -20
  96. package/dist/src/entities/documents/markdown.d.ts +25 -0
  97. package/dist/src/entities/documents/namespace.d.ts +132 -13
  98. package/dist/src/entities/documents/skills.test.d.ts +1 -0
  99. package/dist/src/entities/documents/system-skill.d.ts +21 -1
  100. package/dist/src/entities/documents/text-comment.d.ts +41 -0
  101. package/dist/src/entities/documents/text-comment.test.d.ts +1 -0
  102. package/dist/src/entities/documents/version.d.ts +5 -1
  103. package/dist/src/entities/email/attachment.d.ts +3 -0
  104. package/dist/src/entities/email/draft.d.ts +61 -9
  105. package/dist/src/entities/email/filter.d.ts +12 -2
  106. package/dist/src/entities/email/label.d.ts +7 -1
  107. package/dist/src/entities/email/link.d.ts +5 -1
  108. package/dist/src/entities/email/message.d.ts +55 -8
  109. package/dist/src/entities/email/namespace.d.ts +127 -21
  110. package/dist/src/entities/email/thread.d.ts +99 -16
  111. package/dist/src/entities/entity-mentions/mention.d.ts +6 -1
  112. package/dist/src/entities/entity-mentions/namespace.d.ts +5 -1
  113. package/dist/src/entities/entity.d.ts +56 -6
  114. package/dist/src/entities/external-chat/chat.d.ts +62 -11
  115. package/dist/src/entities/external-chat/message.d.ts +1 -1
  116. package/dist/src/entities/external-chat/namespace.d.ts +5 -1
  117. package/dist/src/entities/external-chat/send.d.ts +10 -2
  118. package/dist/src/entities/favorites/namespace.d.ts +20 -3
  119. package/dist/src/entities/foreign/foreign-entity.d.ts +5 -1
  120. package/dist/src/entities/foreign/namespace.d.ts +4 -0
  121. package/dist/src/entities/forms/form.d.ts +71 -13
  122. package/dist/src/entities/forms/namespace.d.ts +10 -2
  123. package/dist/src/entities/forms/question.d.ts +35 -7
  124. package/dist/src/entities/forms/response.d.ts +25 -5
  125. package/dist/src/entities/forms/section.d.ts +15 -3
  126. package/dist/src/entities/github-pull-requests/namespace.d.ts +5 -1
  127. package/dist/src/entities/github-pull-requests/pull-request.d.ts +15 -3
  128. package/dist/src/entities/harnesses/harness.d.ts +51 -3
  129. package/dist/src/entities/harnesses/namespace.d.ts +53 -7
  130. package/dist/src/entities/harnesses/pairing.d.ts +12 -2
  131. package/dist/src/entities/images/image.d.ts +16 -5
  132. package/dist/src/entities/images/namespace.d.ts +8 -1
  133. package/dist/src/entities/initiatives/initiative.d.ts +117 -3
  134. package/dist/src/entities/initiatives/initiative.test.d.ts +1 -0
  135. package/dist/src/entities/initiatives/namespace.d.ts +69 -7
  136. package/dist/src/entities/me/namespace.d.ts +27 -2
  137. package/dist/src/entities/meetings/meeting.d.ts +45 -8
  138. package/dist/src/entities/meetings/namespace.d.ts +20 -4
  139. package/dist/src/entities/memory/namespace.d.ts +49 -0
  140. package/dist/src/entities/memory/namespace.test.d.ts +1 -0
  141. package/dist/src/entities/messages/discussion.d.ts +84 -0
  142. package/dist/src/entities/messages/thread.d.ts +19 -5
  143. package/dist/src/entities/notifications/namespace.d.ts +40 -7
  144. package/dist/src/entities/notifications/notification.d.ts +29 -5
  145. package/dist/src/entities/pins/namespace.d.ts +23 -4
  146. package/dist/src/entities/projects/namespace.d.ts +29 -0
  147. package/dist/src/entities/projects/project.d.ts +47 -6
  148. package/dist/src/entities/properties/namespace.d.ts +67 -11
  149. package/dist/src/entities/properties/namespace.test.d.ts +1 -0
  150. package/dist/src/entities/properties/property-definition.d.ts +30 -5
  151. package/dist/src/entities/properties/property-option.d.ts +14 -2
  152. package/dist/src/entities/referrals/namespace.d.ts +8 -1
  153. package/dist/src/entities/routines/namespace.d.ts +128 -7
  154. package/dist/src/entities/routines/routine.d.ts +111 -25
  155. package/dist/src/entities/saved-views/namespace.d.ts +57 -0
  156. package/dist/src/entities/saved-views/saved-view.d.ts +78 -0
  157. package/dist/src/entities/search/namespace.d.ts +5 -1
  158. package/dist/src/entities/sharing/access.d.ts +50 -9
  159. package/dist/src/entities/spreadsheets/spreadsheet.d.ts +201 -0
  160. package/dist/src/entities/tasks/namespace.d.ts +13 -1
  161. package/dist/src/entities/tasks/task.d.ts +7 -1
  162. package/dist/src/entities/teams/invite.d.ts +3 -0
  163. package/dist/src/entities/teams/namespace.d.ts +10 -2
  164. package/dist/src/entities/teams/team.d.ts +7 -0
  165. package/dist/src/entities/unfurls/namespace.d.ts +12 -2
  166. package/dist/src/entities/users/namespace.d.ts +19 -1
  167. package/dist/src/entities/users/profile-picture.d.ts +29 -0
  168. package/dist/src/entities/users/profile-picture.test.d.ts +1 -0
  169. package/dist/src/entities/users/user.d.ts +52 -1
  170. package/dist/src/entities/web/namespace.d.ts +6 -0
  171. package/dist/src/entities/webhooks/namespace.d.ts +5 -0
  172. package/dist/src/entities/webhooks/webhook.d.ts +47 -7
  173. package/dist/src/entities/whatsapp/account.d.ts +5 -1
  174. package/dist/src/entities/whatsapp/chat.d.ts +9 -1
  175. package/dist/src/entities/whatsapp/namespace.d.ts +7 -1
  176. package/dist/src/entities/workspace/namespace.d.ts +7 -1
  177. package/dist/src/entities/workspace/query.d.ts +5 -1
  178. package/dist/src/events/hydrate/user.d.ts +14 -0
  179. package/dist/src/events/receiver.d.ts +2 -0
  180. package/dist/src/events/types.d.ts +2 -1
  181. package/dist/src/macro.d.ts +33 -5
  182. package/dist/src/macro.js +15635 -10132
  183. package/dist/src/utils/lazy.d.ts +7 -1
  184. package/package.json +1 -1
  185. package/dist/src/entities/crm/comment.d.ts +0 -64
@@ -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 {};
@@ -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
  }
@@ -178,7 +178,11 @@ export declare class Form extends MacroEntity<FormDetail> {
178
178
  }): Promise<Form>;
179
179
  /** Forms shared with the caller, or live forms over a specified database. */
180
180
  static list(client: MacroClient, database?: Database): Promise<Form[]>;
181
- /** The form's presentation and column facts; this never contains response rows. */
181
+ /**
182
+ * The form's presentation and column facts; this never contains response rows.
183
+ *
184
+ * @readonly
185
+ */
182
186
  schema(): Promise<FormDetail>;
183
187
  /** The form's display name. */
184
188
  readonly name: () => Promise<string>;
@@ -198,11 +202,24 @@ export declare class Form extends MacroEntity<FormDetail> {
198
202
  readonly closesAt: () => Promise<string | undefined>;
199
203
  /** The caller's access level. */
200
204
  readonly access: () => Promise<import("../../../generated/storage").FormAccess>;
201
- /** Sections in display order. */
205
+ /**
206
+ * Sections in display order.
207
+ *
208
+ * @readonly
209
+ */
202
210
  sections(): Promise<FormSection[]>;
203
- /** All questions in display order, skipping gates. */
211
+ /**
212
+ * All questions in display order, skipping gates.
213
+ *
214
+ * @readonly
215
+ */
204
216
  questions(): Promise<FormQuestion[]>;
205
- /** Update presentation or owner-controlled settings; null explicitly clears the closing time. */
217
+ /**
218
+ * Update presentation or owner-controlled settings; null explicitly clears the closing time.
219
+ *
220
+ * @write
221
+ * @idempotent
222
+ */
206
223
  update(updates: UpdateForm): Promise<this>;
207
224
  private assertOwns;
208
225
  /**
@@ -210,26 +227,63 @@ export declare class Form extends MacroEntity<FormDetail> {
210
227
  * omitted handles mint sections or questions. Column facts use the database API.
211
228
  * A publicationError means the draft was saved but respondents still see the last
212
229
  * valid version. Repair the reported problem or reload to retry publication.
230
+ *
231
+ * @destructive
232
+ * @idempotent
213
233
  */
214
234
  replaceLayout(sections: FormSectionPlacement[]): Promise<FormLayoutResult>;
215
235
  private wireAnswers;
216
236
  private unlockedBooking;
217
237
  private outcome;
218
- /** Submit answers. Signed-in respondents get at most one response; use editResponse afterwards. */
238
+ /**
239
+ * Submit answers. Signed-in respondents get at most one response; use editResponse afterwards.
240
+ *
241
+ * @write
242
+ */
219
243
  submit(answers: FormAnswer[]): Promise<FormSubmissionOutcome>;
220
- /** Replace the caller's answers while the form is open; gates are evaluated again. */
244
+ /**
245
+ * Replace the caller's answers while the form is open; gates are evaluated again.
246
+ *
247
+ * @destructive
248
+ * @idempotent
249
+ */
221
250
  editResponse(answers: FormAnswer[]): Promise<FormSubmissionOutcome>;
222
- /** Read the caller's receipt and answers without reading anyone else's responses. */
251
+ /**
252
+ * Read the caller's receipt and answers without reading anyone else's responses.
253
+ *
254
+ * @readonly
255
+ */
223
256
  myResponse(): Promise<MyFormResponse>;
224
- /** Ledger counts and total table rows; requires edit access. */
257
+ /**
258
+ * Ledger counts and total table rows; requires edit access.
259
+ *
260
+ * @readonly
261
+ */
225
262
  responseSummary(): Promise<FormResponseSummary>;
226
- /** Choice and checkbox counts, available to viewers when tally visibility is enabled. */
263
+ /**
264
+ * Choice and checkbox counts, available to viewers when tally visibility is enabled.
265
+ *
266
+ * @readonly
267
+ */
227
268
  tally(): Promise<FormQuestionTally[]>;
228
- /** Read the form's sharing grants. Requires ownership. */
269
+ /**
270
+ * Read the form's sharing grants. Requires ownership.
271
+ *
272
+ * @readonly
273
+ */
229
274
  sharePermissions(): Promise<SharePermissionV2>;
230
- /** Update grants. Public responding is controlled by audience, not link sharing. */
275
+ /**
276
+ * Update grants. Public responding is controlled by audience, not link sharing.
277
+ *
278
+ * @write
279
+ * @idempotent
280
+ */
231
281
  updateSharePermissions(request: UpdateSharePermissionRequestV2): Promise<SharePermissionV2>;
232
- /** Open the form's builder in Macro. */
282
+ /**
283
+ * Open the form's builder in Macro.
284
+ *
285
+ * @readonly
286
+ */
233
287
  webUrl(): string;
234
288
  /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
235
289
  toJSON(): {
@@ -237,6 +291,10 @@ export declare class Form extends MacroEntity<FormDetail> {
237
291
  id: string;
238
292
  detail?: FormDetail | undefined;
239
293
  };
240
- /** The respondent page, which public forms also expose without signing in. */
294
+ /**
295
+ * The respondent page, which public forms also expose without signing in.
296
+ *
297
+ * @readonly
298
+ */
241
299
  respondUrl(): string;
242
300
  }
@@ -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(): {
@@ -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
  }
@@ -14,19 +14,65 @@ export declare class HarnessNamespace {
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,11 @@ 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.
17
+ *
18
+ * @write
19
+ */
16
20
  approve(options?: {
17
21
  name?: string;
18
22
  team?: Team;
@@ -27,7 +31,13 @@ export declare class DevicePairing {
27
31
  private constructor();
28
32
  /** Construct the device side handle. */
29
33
  static byId(client: MacroClient, id: string): DevicePairing;
30
- /** Attempt to claim an approved pairing. Pending claims return undefined. */
34
+ /**
35
+ * Attempt to claim an approved pairing. Pending claims return undefined.
36
+ *
37
+ * @write
38
+ * @mcp-exclude Device-side pairing step
39
+ * returns a host token meant for the host process.
40
+ */
31
41
  claim(deviceSecret: string): Promise<{
32
42
  harness: Harness;
33
43
  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
  }