@macro-inc/sdk 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (193) hide show
  1. package/CALLS.md +82 -0
  2. package/README.md +176 -7
  3. package/dist/chunk-2IVGAIGQ.js +80 -0
  4. package/dist/{chunk-PTX2RV2N.js → chunk-3SW6QVDV.js} +33 -0
  5. package/dist/{chunk-XFA7NCJ5.js → chunk-GT5EUYOR.js} +13 -15
  6. package/dist/{chunk-ZLBDES7U.js → chunk-HIW6KU2I.js} +490 -4
  7. package/dist/{chunk-AZJUIUIV.js → chunk-J2VK3NOR.js} +56 -0
  8. package/dist/{chunk-PZPTJI6F.js → chunk-UVJLWLSJ.js} +41 -2
  9. package/dist/generated/agent-fold/index.d.ts +8 -6
  10. package/dist/generated/agent-harness/index.d.ts +1 -1
  11. package/dist/generated/agent-harness/index.js +1 -1
  12. package/dist/generated/agent-harness/sdk.gen.d.ts +17 -1
  13. package/dist/generated/agent-harness/types.gen.d.ts +188 -3
  14. package/dist/generated/auth/index.js +1 -1
  15. package/dist/generated/auth/sdk.gen.d.ts +13 -15
  16. package/dist/generated/auth/types.gen.d.ts +36 -17
  17. package/dist/generated/cognition/index.d.ts +1 -1
  18. package/dist/generated/cognition/index.js +1 -1
  19. package/dist/generated/cognition/sdk.gen.d.ts +38 -1
  20. package/dist/generated/cognition/types.gen.d.ts +473 -4
  21. package/dist/generated/connection/types.gen.d.ts +1 -1
  22. package/dist/generated/notification/index.d.ts +1 -1
  23. package/dist/generated/notification/types.gen.d.ts +36 -1
  24. package/dist/generated/scheduled-action/index.d.ts +1 -1
  25. package/dist/generated/scheduled-action/index.js +1 -1
  26. package/dist/generated/scheduled-action/sdk.gen.d.ts +17 -2
  27. package/dist/generated/scheduled-action/types.gen.d.ts +642 -104
  28. package/dist/generated/storage/index.d.ts +1 -1
  29. package/dist/generated/storage/index.js +1 -1
  30. package/dist/generated/storage/sdk.gen.d.ts +204 -5
  31. package/dist/generated/storage/types.gen.d.ts +3969 -374
  32. package/dist/src/calls/browser.d.ts +14 -0
  33. package/dist/src/calls/browser.js +102 -0
  34. package/dist/src/calls/common.d.ts +18 -0
  35. package/dist/src/calls/node.d.ts +24 -0
  36. package/dist/src/calls/node.js +145 -0
  37. package/dist/src/calls/telemetry.d.ts +5 -0
  38. package/dist/src/entities/account-managers/grant.d.ts +28 -5
  39. package/dist/src/entities/account-managers/namespace.d.ts +15 -3
  40. package/dist/src/entities/activity/entity.d.ts +7 -0
  41. package/dist/src/entities/activity/namespace.d.ts +58 -0
  42. package/dist/src/entities/activity/namespace.test.d.ts +1 -0
  43. package/dist/src/entities/agent-sessions/activity.d.ts +10 -2
  44. package/dist/src/entities/agent-sessions/agent-session.d.ts +193 -18
  45. package/dist/src/entities/agent-sessions/code-execution.d.ts +15 -3
  46. package/dist/src/entities/agent-sessions/conversation.d.ts +46 -9
  47. package/dist/src/entities/agent-sessions/namespace.d.ts +71 -16
  48. package/dist/src/entities/agent-sessions/origin.d.ts +1 -1
  49. package/dist/src/entities/agent-sessions/queued-action.d.ts +17 -3
  50. package/dist/src/entities/agent-sessions/review.d.ts +55 -4
  51. package/dist/src/entities/agent-sessions/tool-approval.d.ts +5 -1
  52. package/dist/src/entities/agents/agent.d.ts +98 -3
  53. package/dist/src/entities/agents/namespace.d.ts +52 -8
  54. package/dist/src/entities/ai/namespace.d.ts +9 -1
  55. package/dist/src/entities/api-keys/api-key.d.ts +6 -1
  56. package/dist/src/entities/api-keys/namespace.d.ts +15 -3
  57. package/dist/src/entities/bots/bot.d.ts +38 -6
  58. package/dist/src/entities/bots/namespace.d.ts +13 -1
  59. package/dist/src/entities/bots/token.d.ts +6 -1
  60. package/dist/src/entities/calendar/booking-link.d.ts +7 -1
  61. package/dist/src/entities/calendar/booking-namespace.d.ts +13 -0
  62. package/dist/src/entities/calendar/booking.d.ts +15 -0
  63. package/dist/src/entities/calendar/calendar.d.ts +7 -1
  64. package/dist/src/entities/calendar/event.d.ts +59 -9
  65. package/dist/src/entities/calendar/namespace.d.ts +88 -10
  66. package/dist/src/entities/calendar/replacement.d.ts +19 -3
  67. package/dist/src/entities/calls/call-record.d.ts +90 -14
  68. package/dist/src/entities/calls/connection.d.ts +7 -1
  69. package/dist/src/entities/calls/message.d.ts +27 -5
  70. package/dist/src/entities/calls/namespace.d.ts +15 -3
  71. package/dist/src/entities/canvases/canvas.d.ts +324 -0
  72. package/dist/src/entities/channels/access-request.d.ts +10 -2
  73. package/dist/src/entities/channels/activity.d.ts +20 -4
  74. package/dist/src/entities/channels/channel.d.ts +130 -23
  75. package/dist/src/entities/channels/labels.d.ts +41 -7
  76. package/dist/src/entities/channels/message.d.ts +41 -7
  77. package/dist/src/entities/channels/namespace.d.ts +28 -3
  78. package/dist/src/entities/channels/post.test.d.ts +1 -0
  79. package/dist/src/entities/channels/thread.d.ts +19 -3
  80. package/dist/src/entities/chats/chat.d.ts +56 -6
  81. package/dist/src/entities/chats/generation.d.ts +11 -2
  82. package/dist/src/entities/chats/namespace.d.ts +10 -2
  83. package/dist/src/entities/connected-apps/connected-app.d.ts +14 -1
  84. package/dist/src/entities/connected-apps/connector.d.ts +3 -0
  85. package/dist/src/entities/connected-apps/namespace.d.ts +16 -0
  86. package/dist/src/entities/crm/company.d.ts +63 -15
  87. package/dist/src/entities/crm/contact.d.ts +60 -13
  88. package/dist/src/entities/crm/namespace.d.ts +85 -11
  89. package/dist/src/entities/crm/pipeline-entry.d.ts +102 -0
  90. package/dist/src/entities/crm/pipeline.d.ts +271 -27
  91. package/dist/src/entities/crm/pipelines.d.ts +39 -2
  92. package/dist/src/entities/databases/column.d.ts +54 -7
  93. package/dist/src/entities/databases/database.d.ts +126 -12
  94. package/dist/src/entities/databases/namespace.d.ts +16 -4
  95. package/dist/src/entities/databases/row.d.ts +2 -0
  96. package/dist/src/entities/databases/saved-query.d.ts +145 -0
  97. package/dist/src/entities/databases/table.d.ts +64 -10
  98. package/dist/src/entities/databases/view.d.ts +27 -5
  99. package/dist/src/entities/databases/webhook.d.ts +8 -1
  100. package/dist/src/entities/documents/ai-edit.d.ts +2 -0
  101. package/dist/src/entities/documents/anchor.d.ts +12 -2
  102. package/dist/src/entities/documents/comment.d.ts +29 -5
  103. package/dist/src/entities/documents/document.d.ts +243 -20
  104. package/dist/src/entities/documents/markdown.d.ts +25 -0
  105. package/dist/src/entities/documents/namespace.d.ts +132 -13
  106. package/dist/src/entities/documents/skills.test.d.ts +1 -0
  107. package/dist/src/entities/documents/system-skill.d.ts +21 -1
  108. package/dist/src/entities/documents/text-comment.d.ts +41 -0
  109. package/dist/src/entities/documents/text-comment.test.d.ts +1 -0
  110. package/dist/src/entities/documents/version.d.ts +5 -1
  111. package/dist/src/entities/email/attachment.d.ts +3 -0
  112. package/dist/src/entities/email/draft.d.ts +61 -9
  113. package/dist/src/entities/email/filter.d.ts +12 -2
  114. package/dist/src/entities/email/label.d.ts +7 -1
  115. package/dist/src/entities/email/link.d.ts +5 -1
  116. package/dist/src/entities/email/message.d.ts +55 -8
  117. package/dist/src/entities/email/namespace.d.ts +127 -21
  118. package/dist/src/entities/email/thread.d.ts +99 -16
  119. package/dist/src/entities/entity-mentions/mention.d.ts +6 -1
  120. package/dist/src/entities/entity-mentions/namespace.d.ts +5 -1
  121. package/dist/src/entities/entity.d.ts +56 -6
  122. package/dist/src/entities/external-chat/chat.d.ts +62 -11
  123. package/dist/src/entities/external-chat/message.d.ts +1 -1
  124. package/dist/src/entities/external-chat/namespace.d.ts +5 -1
  125. package/dist/src/entities/external-chat/send.d.ts +10 -2
  126. package/dist/src/entities/favorites/namespace.d.ts +20 -3
  127. package/dist/src/entities/foreign/foreign-entity.d.ts +5 -1
  128. package/dist/src/entities/foreign/namespace.d.ts +4 -0
  129. package/dist/src/entities/forms/form.d.ts +71 -13
  130. package/dist/src/entities/forms/namespace.d.ts +10 -2
  131. package/dist/src/entities/forms/question.d.ts +35 -7
  132. package/dist/src/entities/forms/response.d.ts +25 -5
  133. package/dist/src/entities/forms/section.d.ts +15 -3
  134. package/dist/src/entities/github-pull-requests/namespace.d.ts +5 -1
  135. package/dist/src/entities/github-pull-requests/pull-request.d.ts +15 -3
  136. package/dist/src/entities/harnesses/harness.d.ts +51 -3
  137. package/dist/src/entities/harnesses/namespace.d.ts +53 -7
  138. package/dist/src/entities/harnesses/pairing.d.ts +12 -2
  139. package/dist/src/entities/images/image.d.ts +16 -5
  140. package/dist/src/entities/images/namespace.d.ts +8 -1
  141. package/dist/src/entities/initiatives/initiative.d.ts +117 -3
  142. package/dist/src/entities/initiatives/initiative.test.d.ts +1 -0
  143. package/dist/src/entities/initiatives/namespace.d.ts +69 -7
  144. package/dist/src/entities/me/namespace.d.ts +27 -2
  145. package/dist/src/entities/meetings/meeting.d.ts +45 -8
  146. package/dist/src/entities/meetings/namespace.d.ts +20 -4
  147. package/dist/src/entities/memory/namespace.d.ts +49 -0
  148. package/dist/src/entities/memory/namespace.test.d.ts +1 -0
  149. package/dist/src/entities/messages/discussion.d.ts +84 -0
  150. package/dist/src/entities/messages/thread.d.ts +19 -5
  151. package/dist/src/entities/notifications/namespace.d.ts +40 -7
  152. package/dist/src/entities/notifications/notification.d.ts +29 -5
  153. package/dist/src/entities/pins/namespace.d.ts +23 -4
  154. package/dist/src/entities/projects/namespace.d.ts +29 -0
  155. package/dist/src/entities/projects/project.d.ts +47 -6
  156. package/dist/src/entities/properties/namespace.d.ts +67 -11
  157. package/dist/src/entities/properties/namespace.test.d.ts +1 -0
  158. package/dist/src/entities/properties/property-definition.d.ts +30 -5
  159. package/dist/src/entities/properties/property-option.d.ts +14 -2
  160. package/dist/src/entities/referrals/namespace.d.ts +8 -1
  161. package/dist/src/entities/routines/namespace.d.ts +128 -7
  162. package/dist/src/entities/routines/routine.d.ts +111 -25
  163. package/dist/src/entities/saved-views/namespace.d.ts +57 -0
  164. package/dist/src/entities/saved-views/saved-view.d.ts +78 -0
  165. package/dist/src/entities/search/namespace.d.ts +5 -1
  166. package/dist/src/entities/sharing/access.d.ts +50 -9
  167. package/dist/src/entities/spreadsheets/spreadsheet.d.ts +201 -0
  168. package/dist/src/entities/tasks/namespace.d.ts +13 -1
  169. package/dist/src/entities/tasks/task.d.ts +7 -1
  170. package/dist/src/entities/teams/invite.d.ts +3 -0
  171. package/dist/src/entities/teams/namespace.d.ts +10 -2
  172. package/dist/src/entities/teams/team.d.ts +7 -0
  173. package/dist/src/entities/unfurls/namespace.d.ts +12 -2
  174. package/dist/src/entities/users/namespace.d.ts +19 -1
  175. package/dist/src/entities/users/profile-picture.d.ts +29 -0
  176. package/dist/src/entities/users/profile-picture.test.d.ts +1 -0
  177. package/dist/src/entities/users/user.d.ts +52 -1
  178. package/dist/src/entities/web/namespace.d.ts +6 -0
  179. package/dist/src/entities/webhooks/namespace.d.ts +5 -0
  180. package/dist/src/entities/webhooks/webhook.d.ts +47 -7
  181. package/dist/src/entities/whatsapp/account.d.ts +5 -1
  182. package/dist/src/entities/whatsapp/chat.d.ts +9 -1
  183. package/dist/src/entities/whatsapp/namespace.d.ts +7 -1
  184. package/dist/src/entities/workspace/namespace.d.ts +7 -1
  185. package/dist/src/entities/workspace/query.d.ts +5 -1
  186. package/dist/src/events/hydrate/user.d.ts +14 -0
  187. package/dist/src/events/receiver.d.ts +2 -0
  188. package/dist/src/events/types.d.ts +2 -1
  189. package/dist/src/macro.d.ts +33 -5
  190. package/dist/src/macro.js +15635 -10132
  191. package/dist/src/utils/lazy.d.ts +7 -1
  192. package/package.json +32 -5
  193. package/dist/src/entities/crm/comment.d.ts +0 -64
@@ -17,9 +17,7 @@ export type ActionConfiguration = {
17
17
  * Omitted by clients that predate the setting; runs then start unlisted.
18
18
  */
19
19
  run_visibility?: RunVisibility;
20
- task: {
21
- [key: string]: unknown;
22
- };
20
+ task: RoutineTask;
23
21
  trigger: ActionTrigger;
24
22
  };
25
23
  /**
@@ -41,9 +39,7 @@ export type ActionConfigurationUpdate = {
41
39
  kind: ActionKind;
42
40
  name: string;
43
41
  run_visibility?: null | RunVisibility;
44
- task: {
45
- [key: string]: unknown;
46
- };
42
+ task: RoutineTask;
47
43
  trigger: ActionTrigger;
48
44
  };
49
45
  export type ActionExecutionRecord = {
@@ -96,6 +92,21 @@ export type AgentMcpServer = {
96
92
  */
97
93
  server_name: string;
98
94
  };
95
+ /**
96
+ * Hand the run to a model running as Macro, or to an agent.
97
+ */
98
+ export type AgentStep = {
99
+ agent?: null | AgentTaskAgent;
100
+ /**
101
+ * What the model or agent should do. It also sees the triggering event
102
+ * and what earlier steps in this run did.
103
+ */
104
+ instructions: string;
105
+ /**
106
+ * Required when no agent is selected; otherwise overrides the agent's default model.
107
+ */
108
+ model?: string | null;
109
+ };
99
110
  /**
100
111
  * The single agent task: how routines were stored before they had steps,
101
112
  * and still how a routine that is only an agent is saved.
@@ -140,6 +151,136 @@ export type AiAdmissionErrorBody = {
140
151
  */
141
152
  error: string;
142
153
  };
154
+ /**
155
+ * One of Macro's routines, ready to start a new routine from.
156
+ */
157
+ export type CatalogEntry = {
158
+ /**
159
+ * What it does, in a few words, for the line beside its trigger.
160
+ */
161
+ action: string;
162
+ /**
163
+ * It changes or sends what other people see.
164
+ */
165
+ affectsOthers: boolean;
166
+ code?: null | RoutineStep;
167
+ /**
168
+ * What it does, in a short line.
169
+ */
170
+ description: string;
171
+ /**
172
+ * The Ask AI step's instructions: its only step without code, and the
173
+ * step to use where code can't be saved.
174
+ */
175
+ instructions: string;
176
+ /**
177
+ * Names it, e.g. `inbox`.
178
+ */
179
+ key: string;
180
+ /**
181
+ * The code step's text knobs whose value names one of the owner's
182
+ * items (a tag, channel or label), by knob name.
183
+ */
184
+ namedKnobs: {
185
+ [key: string]: NamedItemKind;
186
+ };
187
+ /**
188
+ * What someone asks for, with when it runs.
189
+ */
190
+ request: string;
191
+ /**
192
+ * It may be switched on before its owner changes anything.
193
+ */
194
+ safeDefault: boolean;
195
+ /**
196
+ * Offered unpicked as a suggestion from Macro.
197
+ */
198
+ suggest: boolean;
199
+ /**
200
+ * Where it is offered, first the part of the app it belongs to most.
201
+ */
202
+ surfaces: Array<Surface>;
203
+ /**
204
+ * Offered among the templates when someone creates a routine.
205
+ */
206
+ template: boolean;
207
+ /**
208
+ * Its name once saved.
209
+ */
210
+ title: string;
211
+ /**
212
+ * When it runs; schedules are in the zone the catalog was asked for.
213
+ */
214
+ trigger: ActionTrigger;
215
+ };
216
+ /**
217
+ * A routine to check, as the create body takes it.
218
+ */
219
+ export type CheckRoutineRequest = {
220
+ /**
221
+ * What a routine draft's session created for the routine to use, such as
222
+ * the database it writes to; kept with its draft for the person to see.
223
+ */
224
+ created?: Array<CreatedItem>;
225
+ routine: ActionConfiguration;
226
+ };
227
+ /**
228
+ * A code step that doesn't type-check.
229
+ */
230
+ export type CheckedStepProblems = {
231
+ /**
232
+ * Its place among the routine's steps, from zero.
233
+ */
234
+ index: number;
235
+ /**
236
+ * What the type checker reports, first problems first.
237
+ */
238
+ problems: Array<string>;
239
+ /**
240
+ * Its title.
241
+ */
242
+ title: string;
243
+ };
244
+ /**
245
+ * Who a routine's code steps write as.
246
+ */
247
+ export type CodeIdentity = 'agent' | 'owner';
248
+ /**
249
+ * TypeScript written against Macro's SDK, usually by the AI that built the
250
+ * routine. It is type-checked before it is saved and runs with its owner's
251
+ * access.
252
+ */
253
+ export type CodeStep = {
254
+ id?: null | StepId;
255
+ /**
256
+ * Values its owner can change without new code, which the code reads
257
+ * as `knobs.<name>`.
258
+ */
259
+ knobs?: Array<RoutineKnob>;
260
+ /**
261
+ * What it does as one sentence for its owner, with `{name}` where a
262
+ * knob's value shows and `{?name}` where a question knob's question
263
+ * shows, e.g. "Label it {label} when {?aboutMoney}". Saving checks every
264
+ * slot names one of its knobs.
265
+ */
266
+ sentence?: string | null;
267
+ /**
268
+ * A module exporting `async function main({ macro, run, routine,
269
+ * trigger, steps }: StepContext)`: `run` is this run (its time, zone and
270
+ * the previous run), `trigger` what started it (a schedule, an event and
271
+ * its item, or a person), `steps` the typed outputs of the steps before
272
+ * it. What `main` returns, as JSON of at most 64 KB, is the step's output.
273
+ */
274
+ source: string;
275
+ /**
276
+ * One or two sentences on how, for the routine's owner.
277
+ */
278
+ summary?: string;
279
+ /**
280
+ * What the step does, in a few words, e.g. "Label invoices".
281
+ */
282
+ title: string;
283
+ };
143
284
  /**
144
285
  * One time a routine's code was brought to a new SDK.
145
286
  */
@@ -154,19 +295,12 @@ export type CodeUpgrade = {
154
295
  /**
155
296
  * The task before.
156
297
  */
157
- previousTask: {
158
- [key: string]: unknown;
159
- };
298
+ previousTask: RoutineTask;
160
299
  /**
161
300
  * Why the routine needs its owner.
162
301
  */
163
302
  reason?: string | null;
164
- /**
165
- * The saved rewrite, or the rewrite that failed its checks.
166
- */
167
- task?: {
168
- [key: string]: unknown;
169
- } | null;
303
+ task?: null | RoutineTask;
170
304
  /**
171
305
  * The SDK it was brought to.
172
306
  */
@@ -185,6 +319,21 @@ export type ConditionResult = {
185
319
  } | {
186
320
  status: 'unavailable';
187
321
  };
322
+ /**
323
+ * Something a routine draft's session created for the routine to use, such
324
+ * as the database it writes to: it exists whether or not the routine is
325
+ * saved.
326
+ */
327
+ export type CreatedItem = {
328
+ /**
329
+ * Its id.
330
+ */
331
+ entityId: string;
332
+ /**
333
+ * What kind of item.
334
+ */
335
+ entityType: 'user' | 'chat' | 'channel' | 'channel_message' | 'document' | 'project' | 'email_thread' | 'calendar_event' | 'team' | 'call' | 'foreign_entity' | 'static_file' | 'crm_company' | 'crm_contact' | 'crm_pipeline' | 'reminder' | 'harness' | 'skill' | 'agent_session' | 'scheduled_action' | 'initiative' | 'database' | 'database_row' | 'form' | 'external_chat';
336
+ };
188
337
  /**
189
338
  * What AI drafted, or why it couldn't.
190
339
  */
@@ -193,11 +342,13 @@ export type Draft = (DraftedRoutine & {
193
342
  }) | (DraftedStep & {
194
343
  outcome: 'step';
195
344
  }) | {
345
+ created?: Array<DraftCreated>;
196
346
  message: string;
197
347
  outcome: 'failed';
198
348
  };
199
349
  /**
200
- * What the drafter may write, and the person's workspace by name and id.
350
+ * What the drafter may write. It looks up the items the person's words
351
+ * name itself, with their access.
201
352
  */
202
353
  export type DraftContext = {
203
354
  /**
@@ -218,7 +369,25 @@ export type DraftContext = {
218
369
  * IANA time zone schedules are written in, e.g. `America/New_York`.
219
370
  */
220
371
  timezone: string;
221
- workspace?: Workspace;
372
+ };
373
+ /**
374
+ * Something a draft's session created. It exists whether or not the draft
375
+ * is saved.
376
+ */
377
+ export type DraftCreated = {
378
+ /**
379
+ * Its id.
380
+ */
381
+ entityId: string;
382
+ /**
383
+ * What kind of item.
384
+ */
385
+ entityType: 'user' | 'chat' | 'channel' | 'channel_message' | 'document' | 'project' | 'email_thread' | 'calendar_event' | 'team' | 'call' | 'foreign_entity' | 'static_file' | 'crm_company' | 'crm_contact' | 'crm_pipeline' | 'reminder' | 'harness' | 'skill' | 'agent_session' | 'scheduled_action' | 'initiative' | 'database' | 'database_row' | 'form' | 'external_chat';
386
+ /**
387
+ * Whether the drafted routine uses it. One it doesn't use was made for
388
+ * nothing, or is the routine's own work done early.
389
+ */
390
+ used: boolean;
222
391
  };
223
392
  /**
224
393
  * What to draft.
@@ -248,6 +417,11 @@ export type DraftRoutineRequest = {
248
417
  * A drafted routine.
249
418
  */
250
419
  export type DraftedRoutine = {
420
+ /**
421
+ * What AI created while drafting, such as the database the routine
422
+ * writes to. These exist whether or not the routine is saved.
423
+ */
424
+ created: Array<DraftCreated>;
251
425
  name: string;
252
426
  /**
253
427
  * Steps whose code still fails the type checker.
@@ -257,15 +431,18 @@ export type DraftedRoutine = {
257
431
  * What it does, in the shape a routine's task holds steps, each code
258
432
  * step named as saving names it.
259
433
  */
260
- steps: Array<{
261
- [key: string]: unknown;
262
- }>;
434
+ steps: Array<RoutineStep>;
263
435
  trigger?: null | ActionTrigger;
264
436
  };
265
437
  /**
266
438
  * A drafted step.
267
439
  */
268
440
  export type DraftedStep = {
441
+ /**
442
+ * What AI created while drafting the step. These exist whether or not
443
+ * the step is saved.
444
+ */
445
+ created: Array<DraftCreated>;
269
446
  /**
270
447
  * What the type checker still finds in its code.
271
448
  */
@@ -278,9 +455,7 @@ export type DraftedStep = {
278
455
  /**
279
456
  * The step, in the shape a routine's task holds it.
280
457
  */
281
- step: {
282
- [key: string]: unknown;
283
- };
458
+ step: RoutineStep;
284
459
  };
285
460
  /**
286
461
  * Empty response is required due to custom fetch forcing `response.json()`
@@ -354,6 +529,10 @@ export type ExecutionResult = {
354
529
  }>;
355
530
  version: number;
356
531
  };
532
+ /**
533
+ * Where a person's suggestions are in being generated.
534
+ */
535
+ export type GenerationStatus = 'none' | 'generating' | 'ready' | 'failed';
357
536
  /**
358
537
  * Which GitHub deliveries match.
359
538
  */
@@ -383,12 +562,15 @@ export type InProgressExecution = {
383
562
  resource?: null | ExecutionResource;
384
563
  };
385
564
  /**
386
- * An item and its name.
565
+ * How code reads a knob: a lowercase letter, then up to 31 letters or
566
+ * digits, e.g. `dueWithinDays`.
387
567
  */
388
- export type NamedItem = {
389
- id: string;
390
- name: string;
391
- };
568
+ export type KnobName = string;
569
+ /**
570
+ * What a text knob's value names: one of its owner's items, which a client
571
+ * matches by name or lets them pick.
572
+ */
573
+ export type NamedItemKind = 'tag' | 'channel' | 'label';
392
574
  /**
393
575
  * `path` walks objects by key; `*` steps into every element of an array and
394
576
  * a number into one. Give exactly one test. `notIn` also passes when the
@@ -436,10 +618,150 @@ export type PropertySelector = {
436
618
  */
437
619
  values?: Array<string>;
438
620
  };
621
+ /**
622
+ * What saving a routine would find wrong, without saving it: the answer to
623
+ * `POST /scheduled-actions/check`.
624
+ */
625
+ export type RoutineCheck = {
626
+ /**
627
+ * Whether saving it would succeed: no problems and no failing steps.
628
+ */
629
+ ok: boolean;
630
+ /**
631
+ * Why saving it would fail, other than its code, for its author.
632
+ */
633
+ problems: Array<string>;
634
+ /**
635
+ * The routine as saving would store it: code steps named and the SDK
636
+ * their code checks against stamped.
637
+ */
638
+ routine: ActionConfiguration;
639
+ /**
640
+ * Code steps that don't type-check against Macro's SDK.
641
+ */
642
+ steps: Array<CheckedStepProblems>;
643
+ };
644
+ /**
645
+ * A value a code step reads as `knobs.<name>`, which its owner can change
646
+ * without the step being rewritten: the label it adds, a priority, a
647
+ * number of days, a question it asks AI. Its type is part of the step's
648
+ * type-checked contract; its value is not, so changing it needs no check.
649
+ */
650
+ export type RoutineKnob = {
651
+ /**
652
+ * What it is, for the owner, e.g. "Label for money email".
653
+ */
654
+ label: string;
655
+ /**
656
+ * How the code reads it: `knobs.<name>`.
657
+ */
658
+ name: KnobName;
659
+ type: 'text';
660
+ /**
661
+ * Its value.
662
+ */
663
+ value: string;
664
+ } | {
665
+ /**
666
+ * What it is, for the owner.
667
+ */
668
+ label: string;
669
+ /**
670
+ * The largest value the owner may set.
671
+ */
672
+ max?: number | null;
673
+ /**
674
+ * The smallest value the owner may set.
675
+ */
676
+ min?: number | null;
677
+ /**
678
+ * How the code reads it: `knobs.<name>`.
679
+ */
680
+ name: KnobName;
681
+ type: 'number';
682
+ /**
683
+ * Its value.
684
+ */
685
+ value: number;
686
+ } | {
687
+ /**
688
+ * What it is, for the owner.
689
+ */
690
+ label: string;
691
+ /**
692
+ * How the code reads it: `knobs.<name>`.
693
+ */
694
+ name: KnobName;
695
+ type: 'boolean';
696
+ /**
697
+ * Its value.
698
+ */
699
+ value: boolean;
700
+ } | {
701
+ /**
702
+ * What it is, for the owner.
703
+ */
704
+ label: string;
705
+ /**
706
+ * How the code reads it: `knobs.<name>`.
707
+ */
708
+ name: KnobName;
709
+ /**
710
+ * Every option, in the order they are offered.
711
+ */
712
+ options: Array<string>;
713
+ type: 'choice';
714
+ /**
715
+ * The chosen option.
716
+ */
717
+ value: string;
718
+ } | {
719
+ /**
720
+ * The condition as a short clause that reads inside the step's
721
+ * sentence, e.g. "it's about money".
722
+ */
723
+ label: string;
724
+ /**
725
+ * How the code reads it: `knobs.<name>`.
726
+ */
727
+ name: KnobName;
728
+ type: 'question';
729
+ /**
730
+ * The question AI is asked, e.g. "Is this email about money:
731
+ * investors, fundraising or finance?".
732
+ */
733
+ value: string;
734
+ };
439
735
  /**
440
736
  * A nonblank model identifier. Runtime catalogs, not the scheduler, own availability.
441
737
  */
442
738
  export type RoutineModelId = string;
739
+ /**
740
+ * What a routine does each time it runs.
741
+ */
742
+ export type RoutineProgram = {
743
+ /**
744
+ * Code steps write as the owner, with no agent badge: their posts,
745
+ * comments and emails appear written by the owner. Set only when the
746
+ * owner explicitly asked for the routine to act or send as them; by
747
+ * default code steps' writes are attributed to Macro's agent acting for
748
+ * the owner. Agent ("Ask AI") steps keep their own agent attribution
749
+ * either way: an agent session speaking as a person is a different
750
+ * change. A single agent task has no code steps, so it never applies.
751
+ */
752
+ dangerously_operate_as_user?: boolean;
753
+ /**
754
+ * Apps the routine requires, handed to its agent on top of the agent's
755
+ * own. The owner must have each one connected to save the routine and
756
+ * for it to run.
757
+ */
758
+ mcp_servers?: Array<AgentMcpServer>;
759
+ sdk?: null | SdkFingerprint;
760
+ /**
761
+ * Steps run in order. A failed step stops the run.
762
+ */
763
+ steps: Array<RoutineStep>;
764
+ };
443
765
  /**
444
766
  * The routine a step is added to or changed in.
445
767
  */
@@ -447,9 +769,7 @@ export type RoutineSoFar = {
447
769
  /**
448
770
  * Its steps, in the shape a routine's task holds them.
449
771
  */
450
- steps: Array<{
451
- [key: string]: unknown;
452
- }>;
772
+ steps: Array<RoutineStep>;
453
773
  /**
454
774
  * Its trigger as it would be saved, for AI to read; absent while it has none.
455
775
  */
@@ -457,6 +777,66 @@ export type RoutineSoFar = {
457
777
  [key: string]: unknown;
458
778
  } | null;
459
779
  };
780
+ /**
781
+ * One step of a routine.
782
+ */
783
+ export type RoutineStep = (CodeStep & {
784
+ type: 'code';
785
+ }) | (AgentStep & {
786
+ type: 'agent';
787
+ });
788
+ /**
789
+ * A routine offered to one person: one AI suggested for them, or one of
790
+ * Macro's catalog routines filling a surface.
791
+ */
792
+ export type RoutineSuggestion = SuggestedPick & {
793
+ /**
794
+ * Who suggests it: AI, for this person, or Macro, as a template.
795
+ */
796
+ from: SuggestionFrom;
797
+ /**
798
+ * Saving a routine from it passes this as `suggestion_id`; dismissing
799
+ * it uses it too.
800
+ */
801
+ id: string;
802
+ /**
803
+ * AI's estimate, from 0 to 1, that the person keeps it on; absent on
804
+ * Macro's templates.
805
+ */
806
+ keepProbability?: number | null;
807
+ /**
808
+ * Onboarding shows it switched on: one of at most two catalog
809
+ * routines AI picked that are safe by default and likely kept. Never a
810
+ * drafted routine or a template.
811
+ */
812
+ onByDefault: boolean;
813
+ /**
814
+ * Why it fits this person, in a line; absent on Macro's templates.
815
+ */
816
+ reason?: string | null;
817
+ /**
818
+ * The sidebars it shows in, first the one it belongs to most.
819
+ * Dismissing it in one dismisses it everywhere.
820
+ */
821
+ surfaces: Array<Surface>;
822
+ };
823
+ /**
824
+ * A person's suggestions, and whether more are on the way.
825
+ */
826
+ export type RoutineSuggestions = {
827
+ status: GenerationStatus;
828
+ /**
829
+ * Per surface, AI's first, best first, then Macro's templates, so each
830
+ * surface has at least one and ideally three. A suggestion with
831
+ * several surfaces appears once.
832
+ */
833
+ suggestions: Array<RoutineSuggestion>;
834
+ };
835
+ /**
836
+ * A stored task's two forms, as the scheduler's API describes `task`:
837
+ * [`RoutineProgram::from_task`] reads them.
838
+ */
839
+ export type RoutineTask = RoutineProgram | AgentTask;
460
840
  /**
461
841
  * A shared routine's snapshot, readable by signed-in users with sharing enabled.
462
842
  */
@@ -476,9 +856,7 @@ export type RoutineTemplate = {
476
856
  */
477
857
  id: string;
478
858
  name: string;
479
- task: {
480
- [key: string]: unknown;
481
- };
859
+ task: RoutineTask;
482
860
  trigger: ActionTrigger;
483
861
  updated_at: string;
484
862
  variables: Array<TemplateVariable>;
@@ -510,6 +888,7 @@ export type RunInfo = {
510
888
  * When the run counts as happening: its trigger's time.
511
889
  */
512
890
  at: string;
891
+ code_acts_as?: null | CodeIdentity;
513
892
  /**
514
893
  * When the routine's previous finished run started.
515
894
  */
@@ -599,9 +978,12 @@ export type ScheduledAction = {
599
978
  * Whether the action's runs are listed in Home and the Agents list.
600
979
  */
601
980
  run_visibility: RunVisibility;
602
- task: {
603
- [key: string]: unknown;
604
- };
981
+ /**
982
+ * The routine suggestion it was saved from, if any: a plain pointer
983
+ * that stays after the suggestion is replaced.
984
+ */
985
+ suggestion_id?: string | null;
986
+ task: RoutineTask;
605
987
  /**
606
988
  * The shared template this routine was activated from, if any.
607
989
  */
@@ -651,6 +1033,11 @@ export type ScheduledActionUpdate = {
651
1033
  resource?: null | ExecutionResource;
652
1034
  type: 'stopped';
653
1035
  };
1036
+ /**
1037
+ * Identifies the SDK API code was type-checked against: its version and a
1038
+ * hash of its declarations, e.g. `0.2.2+18cc1c19c35c`.
1039
+ */
1040
+ export type SdkFingerprint = string;
654
1041
  export type SetScheduledActionEnabled = {
655
1042
  enabled: boolean;
656
1043
  };
@@ -662,25 +1049,10 @@ export type ShareRoutineTemplate = {
662
1049
  variables: Array<TemplateVariable>;
663
1050
  };
664
1051
  /**
665
- * A starter routine whose step is code: offered when a routine is created,
666
- * and shown to the drafter as a worked example.
1052
+ * Names a step's output: a lowercase letter, then up to 31 lowercase
1053
+ * letters, digits or underscores.
667
1054
  */
668
- export type StarterRoutine = {
669
- /**
670
- * Names it, e.g. `inbox`.
671
- */
672
- key: string;
673
- /**
674
- * What someone asks for, with when it runs.
675
- */
676
- request: string;
677
- /**
678
- * Its steps, in the shape a routine's task holds them.
679
- */
680
- steps: Array<{
681
- [key: string]: unknown;
682
- }>;
683
- };
1055
+ export type StepId = string;
684
1056
  /**
685
1057
  * Code written once, or Ask AI each run.
686
1058
  */
@@ -695,6 +1067,75 @@ export type StepProblem = {
695
1067
  index: number;
696
1068
  problems: Array<string>;
697
1069
  };
1070
+ /**
1071
+ * What became of a suggestion handed back.
1072
+ */
1073
+ export type SuggestOutcome = {
1074
+ check?: null | RoutineCheck;
1075
+ /**
1076
+ * The kept suggestion's id.
1077
+ */
1078
+ id?: string | null;
1079
+ /**
1080
+ * Whether it was kept.
1081
+ */
1082
+ ok: boolean;
1083
+ /**
1084
+ * Why it wasn't, to fix and suggest again.
1085
+ */
1086
+ problems: Array<string>;
1087
+ };
1088
+ /**
1089
+ * What a suggestion session hands back through `macro.routines.suggest`.
1090
+ */
1091
+ export type SuggestRequest = {
1092
+ keepProbability: number;
1093
+ key: string;
1094
+ kind: 'catalog';
1095
+ knobs?: {
1096
+ [key: string]: unknown;
1097
+ };
1098
+ reason: string;
1099
+ surfaces: Array<Surface>;
1100
+ } | {
1101
+ /**
1102
+ * What the session created for it, as `macro.routines.check` takes.
1103
+ */
1104
+ created?: Array<CreatedItem>;
1105
+ keepProbability: number;
1106
+ kind: 'routine';
1107
+ reason: string;
1108
+ routine: ActionConfiguration;
1109
+ surfaces: Array<Surface>;
1110
+ };
1111
+ /**
1112
+ * What is suggested: a catalog routine with its knobs, or a routine AI
1113
+ * drafted and checked.
1114
+ */
1115
+ export type SuggestedPick = {
1116
+ /**
1117
+ * The catalog routine, e.g. `inbox`.
1118
+ */
1119
+ key: string;
1120
+ kind: 'catalog';
1121
+ /**
1122
+ * Knob values by knob name; knobs left out keep the catalog's.
1123
+ */
1124
+ knobs: {
1125
+ [key: string]: unknown;
1126
+ };
1127
+ } | {
1128
+ kind: 'routine';
1129
+ routine: ActionConfiguration;
1130
+ };
1131
+ /**
1132
+ * Who suggests a routine.
1133
+ */
1134
+ export type SuggestionFrom = 'for_you' | 'macro';
1135
+ /**
1136
+ * The part of the app a routine is about, where it is offered.
1137
+ */
1138
+ export type Surface = 'email' | 'calendar' | 'tasks' | 'files' | 'crm' | 'chat' | 'calls' | 'reviews' | 'agents';
698
1139
  /**
699
1140
  * A user-specific part of a shared routine.
700
1141
  */
@@ -725,45 +1166,6 @@ export type UpgradeOutcome = 'running' | 'checked' | 'rewritten' | 'needs_update
725
1166
  * How a variable is filled when someone activates the template.
726
1167
  */
727
1168
  export type VariableFill = 'activator' | 'shared' | 'choice';
728
- /**
729
- * The items AI may name in a draft. They are data for the model; saving
730
- * checks every id the draft uses.
731
- */
732
- export type Workspace = {
733
- /**
734
- * Agents a step may hand the run to.
735
- */
736
- agents?: Array<WorkspaceAgent>;
737
- channels?: Array<NamedItem>;
738
- /**
739
- * Projects.
740
- */
741
- folders?: Array<NamedItem>;
742
- /**
743
- * Email label names.
744
- */
745
- labels?: Array<string>;
746
- people?: Array<NamedItem>;
747
- /**
748
- * Tag options, by the property definition they belong to.
749
- */
750
- tags?: Array<WorkspaceTag>;
751
- };
752
- /**
753
- * An agent and its bot id.
754
- */
755
- export type WorkspaceAgent = {
756
- botId: string;
757
- name: string;
758
- };
759
- /**
760
- * A tag: one option of a property.
761
- */
762
- export type WorkspaceTag = {
763
- definitionId: string;
764
- label: string;
765
- optionId: string;
766
- };
767
1169
  export type ScheduledActionHealthData = {
768
1170
  body?: never;
769
1171
  path?: never;
@@ -801,7 +1203,12 @@ export type ListScheduledActionsResponse = ListScheduledActionsResponses[keyof L
801
1203
  export type CreateScheduledActionData = {
802
1204
  body: ActionConfiguration;
803
1205
  path?: never;
804
- query?: never;
1206
+ query?: {
1207
+ /**
1208
+ * The routine suggestion it is saved from, recorded on the routine.
1209
+ */
1210
+ suggestion_id?: string;
1211
+ };
805
1212
  url: '/scheduled-actions';
806
1213
  };
807
1214
  export type CreateScheduledActionErrors = {
@@ -815,23 +1222,50 @@ export type CreateScheduledActionResponses = {
815
1222
  201: ScheduledActionResponse;
816
1223
  };
817
1224
  export type CreateScheduledActionResponse = CreateScheduledActionResponses[keyof CreateScheduledActionResponses];
818
- export type RoutineCodeStartersData = {
1225
+ export type RoutineCatalogData = {
819
1226
  body?: never;
820
1227
  path?: never;
821
- query?: never;
822
- url: '/scheduled-actions/code/starters';
1228
+ query: {
1229
+ /**
1230
+ * IANA time zone, e.g. `America/New_York`.
1231
+ */
1232
+ timezone: string;
1233
+ };
1234
+ url: '/scheduled-actions/catalog';
823
1235
  };
824
- export type RoutineCodeStartersErrors = {
1236
+ export type RoutineCatalogErrors = {
1237
+ /**
1238
+ * Not a time zone
1239
+ */
1240
+ 400: string;
825
1241
  401: string;
826
1242
  };
827
- export type RoutineCodeStartersError = RoutineCodeStartersErrors[keyof RoutineCodeStartersErrors];
828
- export type RoutineCodeStartersResponses = {
1243
+ export type RoutineCatalogError = RoutineCatalogErrors[keyof RoutineCatalogErrors];
1244
+ export type RoutineCatalogResponses = {
829
1245
  /**
830
- * Starter routines whose step is code; empty where code steps aren't available
1246
+ * Macro's routines, with schedules in the given zone; code steps only where code can be saved
831
1247
  */
832
- 200: Array<StarterRoutine>;
1248
+ 200: Array<CatalogEntry>;
833
1249
  };
834
- export type RoutineCodeStartersResponse = RoutineCodeStartersResponses[keyof RoutineCodeStartersResponses];
1250
+ export type RoutineCatalogResponse = RoutineCatalogResponses[keyof RoutineCatalogResponses];
1251
+ export type CheckScheduledActionData = {
1252
+ body: CheckRoutineRequest;
1253
+ path?: never;
1254
+ query?: never;
1255
+ url: '/scheduled-actions/check';
1256
+ };
1257
+ export type CheckScheduledActionErrors = {
1258
+ 400: string;
1259
+ 401: string;
1260
+ 403: string;
1261
+ 500: string;
1262
+ 503: string;
1263
+ };
1264
+ export type CheckScheduledActionError = CheckScheduledActionErrors[keyof CheckScheduledActionErrors];
1265
+ export type CheckScheduledActionResponses = {
1266
+ 200: RoutineCheck;
1267
+ };
1268
+ export type CheckScheduledActionResponse = CheckScheduledActionResponses[keyof CheckScheduledActionResponses];
835
1269
  export type DraftRoutineData = {
836
1270
  body: DraftRoutineRequest;
837
1271
  path?: never;
@@ -859,6 +1293,110 @@ export type DraftRoutineResponses = {
859
1293
  200: Draft;
860
1294
  };
861
1295
  export type DraftRoutineResponse = DraftRoutineResponses[keyof DraftRoutineResponses];
1296
+ export type ListRoutineSuggestionsData = {
1297
+ body?: never;
1298
+ path?: never;
1299
+ query?: {
1300
+ /**
1301
+ * Only this surface's; every surface's when absent.
1302
+ */
1303
+ surface?: Surface;
1304
+ };
1305
+ url: '/scheduled-actions/suggestions';
1306
+ };
1307
+ export type ListRoutineSuggestionsErrors = {
1308
+ 401: string;
1309
+ /**
1310
+ * Routine suggestions are off for the caller
1311
+ */
1312
+ 404: string;
1313
+ 500: string;
1314
+ };
1315
+ export type ListRoutineSuggestionsError = ListRoutineSuggestionsErrors[keyof ListRoutineSuggestionsErrors];
1316
+ export type ListRoutineSuggestionsResponses = {
1317
+ /**
1318
+ * Per surface, the routines AI suggested for the caller, then Macro's templates; reading never generates
1319
+ */
1320
+ 200: RoutineSuggestions;
1321
+ };
1322
+ export type ListRoutineSuggestionsResponse = ListRoutineSuggestionsResponses[keyof ListRoutineSuggestionsResponses];
1323
+ export type SuggestRoutineData = {
1324
+ body: SuggestRequest;
1325
+ path?: never;
1326
+ query?: never;
1327
+ url: '/scheduled-actions/suggestions';
1328
+ };
1329
+ export type SuggestRoutineErrors = {
1330
+ 400: string;
1331
+ 401: string;
1332
+ /**
1333
+ * Only a routine suggestion session may suggest
1334
+ */
1335
+ 403: string;
1336
+ 500: string;
1337
+ };
1338
+ export type SuggestRoutineError = SuggestRoutineErrors[keyof SuggestRoutineErrors];
1339
+ export type SuggestRoutineResponses = {
1340
+ /**
1341
+ * Whether the suggestion was kept, and what to fix when it wasn't
1342
+ */
1343
+ 200: SuggestOutcome;
1344
+ };
1345
+ export type SuggestRoutineResponse = SuggestRoutineResponses[keyof SuggestRoutineResponses];
1346
+ export type GenerateRoutineSuggestionsData = {
1347
+ body?: never;
1348
+ path?: never;
1349
+ query: {
1350
+ /**
1351
+ * IANA time zone, e.g. `America/New_York`.
1352
+ */
1353
+ timezone: string;
1354
+ };
1355
+ url: '/scheduled-actions/suggestions/generate';
1356
+ };
1357
+ export type GenerateRoutineSuggestionsErrors = {
1358
+ 401: string;
1359
+ /**
1360
+ * Routine suggestions are off for the caller
1361
+ */
1362
+ 404: string;
1363
+ 500: string;
1364
+ };
1365
+ export type GenerateRoutineSuggestionsError = GenerateRoutineSuggestionsErrors[keyof GenerateRoutineSuggestionsErrors];
1366
+ export type GenerateRoutineSuggestionsResponses = {
1367
+ /**
1368
+ * The caller's suggestions; the first call, once their inbox is connected, starts AI suggesting in the background, and later calls change nothing
1369
+ */
1370
+ 200: RoutineSuggestions;
1371
+ };
1372
+ export type GenerateRoutineSuggestionsResponse = GenerateRoutineSuggestionsResponses[keyof GenerateRoutineSuggestionsResponses];
1373
+ export type DismissRoutineSuggestionData = {
1374
+ body?: never;
1375
+ path: {
1376
+ /**
1377
+ * ID of the suggestion, AI's or a template's
1378
+ */
1379
+ id: string;
1380
+ };
1381
+ query?: never;
1382
+ url: '/scheduled-actions/suggestions/{id}/dismiss';
1383
+ };
1384
+ export type DismissRoutineSuggestionErrors = {
1385
+ 401: string;
1386
+ /**
1387
+ * No such suggestion for the caller, or suggestions are off
1388
+ */
1389
+ 404: string;
1390
+ 500: string;
1391
+ };
1392
+ export type DismissRoutineSuggestionError = DismissRoutineSuggestionErrors[keyof DismissRoutineSuggestionErrors];
1393
+ export type DismissRoutineSuggestionResponses = {
1394
+ /**
1395
+ * Never suggested again, on any surface
1396
+ */
1397
+ 204: void;
1398
+ };
1399
+ export type DismissRoutineSuggestionResponse = DismissRoutineSuggestionResponses[keyof DismissRoutineSuggestionResponses];
862
1400
  export type DeleteScheduledActionData = {
863
1401
  body?: never;
864
1402
  path: {