@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,13 @@
1
+ import type { RoutineCheck, RoutineSuggestionCard, SuggestOutcome, Surface } from '../../../generated/scheduled-action/types.gen';
1
2
  import type { MacroClient } from '../../utils/client';
3
+ import type { MacroEntityType } from '../entity';
2
4
  import { Routine, type RoutineOptions } from './routine';
5
+ import { RoutineSuggestion } from './suggestion';
6
+ /** Something created for a routine to use: any handle with an entity type, such as a `Database`. */
7
+ export interface CreatedEntity {
8
+ readonly id: string;
9
+ readonly entityType: MacroEntityType;
10
+ }
3
11
  /**
4
12
  * Scheduled and event-triggered routines.
5
13
  *
@@ -11,6 +19,31 @@ import { Routine, type RoutineOptions } from './routine';
11
19
  * - "Remind me", "every Monday", "tomorrow at 9" and "whenever something happens" ask for a routine: work that runs later, as the user, after this conversation ends. A meeting with other people is a calendar event, not a routine.
12
20
  * - A routine's run never sees this conversation. Write its instructions to stand alone: what to do, the items involved by id or link, absolute dates, and where to report the result.
13
21
  * - Before creating one, look for a routine of the user's that already does this, and update it instead of adding a second.
22
+ * - A routine created by a routine's run, from its code or its Ask AI step, is that routine's sub-routine: it is listed under it, pauses and is deleted with it, and `list()` leaves it out unless asked. A routine has at most 50 active sub-routines (one-time ones that have run don't count); creating another is refused. When a run may create the same routine again, pass a `key` so the second create updates the first instead of adding a duplicate.
23
+ *
24
+ * ### Writing one
25
+ *
26
+ * - Find each item the request names (a channel, person, folder, project, label, tag, agent, database or document) with SDK search, as the user would, paging and refining the search until you find the item itself. The item is the one whose name is exactly the name used, ignoring case and a leading # or @, not one whose name only contains it: "bug-reports" is the channel named bug-reports, never bug-reports-archive. When no item has that name, or several do, ask which one rather than guess.
27
+ * - In code, a trigger watches items through its event filter's `entities`, as references holding the handles the SDK returned, such as `{ type: 'channel', entity: channel }`: never an id, and never an `ids` key. A code step uses an item by its id, in a knob.
28
+ * - Create beforehand only what the routine needs to exist before it runs: when the request asks for something new that the routine then uses by id (a database it adds rows to, a folder it files into, a channel it posts in), create it with the name given and use its id. Create nothing else.
29
+ * - Never do the routine's own work while setting it up; it does its work each time it runs. "Every Monday make a task" makes no task today; "when an email arrives, reply" sends nothing; "post the weekly summary" posts nothing.
30
+ * - In a cron `schedule` (six fields: second minute hour day-of-month month day-of-week), name weekdays MON to SUN: weekday numbers start at 1 = Sunday, so Monday to Friday is `MON-FRI`, never `1-5`.
31
+ * - In code, check the whole routine with `macro.routines.check` before creating it, naming in `created` what you created for it, and fix what it reports until `ok` is true.
32
+ *
33
+ * Events an `events` trigger starts on (`EventName` lists every one):
34
+ *
35
+ * - `channel.created`: a channel you can access is created.
36
+ * - `channel.message_posted`: someone sends a message in a selected channel.
37
+ * - `channel.mentioned`: you are @ mentioned in a selected channel.
38
+ * - `document.created`: a document you can access is created. Tasks have their own trigger.
39
+ * - `document.deleted`: a selected document is deleted.
40
+ * - `task.created`: a task you can access is created.
41
+ * - `task.status_changed`: a task's status changes.
42
+ * - `task.priority_changed`: a task's priority changes.
43
+ * - `task.property_changed`: any property on a task changes, such as its assignees, due date, project or effort, including status and priority.
44
+ * - `email.message_received`: new mail arrives in your inbox. Excludes spam, trash, drafts and historical imports.
45
+ * - `call.started`: a call you start begins. The routine gets the call and who has joined so far.
46
+ * - `call.ended`: a call you joined ends. The routine gets the call's participants and transcript.
14
47
  */
15
48
  export declare class RoutineNamespace {
16
49
  private readonly client;
@@ -18,38 +51,189 @@ export declare class RoutineNamespace {
18
51
  /** Construct a lazy routine handle. */
19
52
  byId(id: string): Routine;
20
53
  /**
21
- * Create an agent routine. To check on something later, such as a spawned
22
- * session or a long job, create a routine instead of waiting in a program.
23
- * Set `model`, `agent`, or both. A cron `schedule` has 6 fields (second
24
- * minute hour day-of-month month day-of-week) or 7 with a year; a 7-field
25
- * schedule that names one date runs once. A rejected routine throws a
26
- * `MacroApiError` whose message says what the server refused.
54
+ * Create a routine from `steps`: code steps and at most one Ask AI
55
+ * (`agent`) step. The older single agent task (`prompt`, with `model`,
56
+ * `agent`, or both) still saves and runs as one Ask AI step; write new
57
+ * routines as steps. Set `dangerouslyOperateAsUser` only when the user
58
+ * explicitly asked for it to act, send or post as them. To check on
59
+ * something later, such as a spawned session or a long job, create a
60
+ * routine instead of waiting in a program. A cron `schedule` has 6 fields
61
+ * (second minute hour day-of-month month day-of-week) or 7 with a year; a
62
+ * 7-field schedule that names one date runs once. A code step's `source`
63
+ * exports `async function main({ macro, run, trigger, steps, knobs })` and
64
+ * is type-checked against this SDK when saved. A rejected routine throws a
65
+ * `MacroApiError` whose message says what the server refused, including
66
+ * type-check errors.
67
+ *
68
+ * Inside a routine's run, the new routine is that routine's sub-routine
69
+ * ({@link Routine.parent}). Pass `key` there to name it: creating with the
70
+ * same key again updates that sub-routine instead of adding another, so a
71
+ * run that repeats is safe. Without a key every create adds a routine, and
72
+ * the 51st active sub-routine is refused. Outside a routine's run a key is
73
+ * rejected.
27
74
  *
28
75
  * @example
29
76
  * // Every ten minutes, in New York time.
30
77
  * const routine = await macro.routines.create({
31
78
  * name: 'Check the import',
32
- * prompt: 'Read the import task and post its status in the channel.',
33
- * userPrompt: 'Check on the import every ten minutes.',
34
- * model: 'anthropic/claude-sonnet-5-5',
35
79
  * trigger: {
36
80
  * type: 'cron',
37
81
  * schedule: '0 0/10 * * * *',
38
82
  * timezone: 'America/New_York',
39
83
  * },
84
+ * steps: [
85
+ * {
86
+ * type: 'agent',
87
+ * instructions: 'Read the import task and post its status in the channel.',
88
+ * model: 'anthropic/claude-sonnet-5-5',
89
+ * },
90
+ * ],
40
91
  * });
41
92
  * // Once, at 14:30 on 3 November 2027.
42
93
  * await macro.routines.create({
43
94
  * name: 'Follow up on the review',
44
- * prompt: 'Read the review session and summarize its outcome.',
45
- * userPrompt: 'Follow up on the review on 3 November 2027.',
46
- * model: 'anthropic/claude-sonnet-5-5',
47
95
  * trigger: { type: 'cron', schedule: '0 30 14 3 11 * 2027', timezone: 'UTC' },
96
+ * steps: [
97
+ * {
98
+ * type: 'agent',
99
+ * instructions: 'Read the review session and summarize its outcome.',
100
+ * model: 'anthropic/claude-sonnet-5-5',
101
+ * },
102
+ * ],
103
+ * });
104
+ * // A code step that posts in a channel, disabled until turned on. The
105
+ * // user asked for the post to come from them.
106
+ * await macro.routines.create({
107
+ * name: 'Say hello',
108
+ * trigger: { type: 'once', at: '2027-11-03T14:30:00Z' },
109
+ * enabled: false,
110
+ * steps: [
111
+ * {
112
+ * type: 'code',
113
+ * title: 'Post hello',
114
+ * source: `export async function main({ macro }: StepContext) {
115
+ * await macro.channels.byId('<channel id>').send('Hello');
116
+ * }`,
117
+ * },
118
+ * ],
119
+ * dangerouslyOperateAsUser: true,
120
+ * });
121
+ * // In a routine's code step: one follow-up per task, however often it runs.
122
+ * await macro.routines.create(
123
+ * {
124
+ * name: `Check on ${taskName}`,
125
+ * trigger: { type: 'once', at: tomorrow },
126
+ * steps: [
127
+ * {
128
+ * type: 'agent',
129
+ * instructions: `Read task ${taskId} and post its status in the channel.`,
130
+ * model: 'anthropic/claude-sonnet-5-5',
131
+ * },
132
+ * ],
133
+ * },
134
+ * { key: `check-${taskId}` },
135
+ * );
136
+ *
137
+ * @write
138
+ */
139
+ create(options: RoutineOptions, extra?: {
140
+ /**
141
+ * Names the routine among its parent's sub-routines, up to 200
142
+ * characters. Only inside a routine's run.
143
+ */
144
+ key?: string;
145
+ }): Promise<Routine>;
146
+ /**
147
+ * Check a routine without saving it: the checks `create` makes, including
148
+ * type-checking its code steps, with nothing saved. Returns whether it
149
+ * would save (`ok`), what would stop it (`problems`), the code steps that
150
+ * don't type-check (`steps`, by place among the steps) and the routine as
151
+ * it would be stored. Check before creating, and fix what it reports.
152
+ * `created` names what you created for the routine to use, such as the
153
+ * database it writes to, so whoever reviews a drafted routine knows it
154
+ * exists.
155
+ *
156
+ * @example
157
+ * const check = await macro.routines.check({
158
+ * name: 'Say hello',
159
+ * trigger: { type: 'once', at: '2027-11-03T14:30:00Z' },
160
+ * steps: [{ type: 'code', title: 'Post hello', source }],
161
+ * });
162
+ * if (!check.ok) return { problems: check.problems, steps: check.steps };
163
+ *
164
+ * @readonly
165
+ */
166
+ check(options: RoutineOptions, extra?: {
167
+ created?: CreatedEntity[];
168
+ }): Promise<RoutineCheck>;
169
+ /**
170
+ * Suggest a routine to the user. Only a routines generation session may
171
+ * call this; any other session gets a 403. Suggest a catalog routine by
172
+ * `key` with `knobs`, or a `routine` the catalog lacks, written as `check`
173
+ * takes it and checked the same way. `surfaces` are the parts of the app
174
+ * whose sidebar shows it, best fit first; `reason` is one line, shown to
175
+ * the user, naming no one's email address; `keepProbability` is the
176
+ * chance, from 0 to 1, that the user keeps it on. A drafted `routine`
177
+ * also shows in the user's Suggestions feed, as its `card` says; a catalog
178
+ * routine takes no `card`. Returns whether it was kept (`ok`) and, when
179
+ * not, the `problems` to fix before suggesting it again.
180
+ *
181
+ * @example
182
+ * const outcome = await macro.routines.suggest({
183
+ * kind: 'catalog',
184
+ * key: 'inbox',
185
+ * knobs: {},
186
+ * reason: 'Most of your mail is supplier updates',
187
+ * surfaces: ['email'],
188
+ * keepProbability: 0.6,
48
189
  * });
190
+ * if (!outcome.ok) return outcome.problems;
191
+ *
192
+ * @write
193
+ */
194
+ suggest(suggestion: {
195
+ kind: 'catalog';
196
+ key: string;
197
+ knobs?: Record<string, unknown>;
198
+ reason: string;
199
+ surfaces: Surface[];
200
+ keepProbability: number;
201
+ } | {
202
+ kind: 'routine';
203
+ routine: RoutineOptions;
204
+ created?: CreatedEntity[];
205
+ reason: string;
206
+ surfaces: Surface[];
207
+ keepProbability: number;
208
+ /** How it shows in the user's Suggestions feed: a short title, an importance from 0 to 100, and fitting categories. */
209
+ card: RoutineSuggestionCard;
210
+ }): Promise<SuggestOutcome>;
211
+ /**
212
+ * Every routine suggestion AI made for the user, open or not, and how
213
+ * many more this session may hand back. Only a routines generation
214
+ * session may call this. Retire with `suggestion.retire(reason)` what no
215
+ * longer fits; suggestions are never rewritten.
216
+ *
217
+ * @mcp-exclude only a routines generation session may call it
218
+ */
219
+ review(): Promise<{
220
+ suggestions: RoutineSuggestion[];
221
+ keptLeft: number;
222
+ }>;
223
+ /**
224
+ * List the user's top-level routines, as their Routines list shows them:
225
+ * sub-routines, which other routines' runs created, are left out. Pass
226
+ * `parent` for one routine's sub-routines (its newest finished one-time
227
+ * ones included), or `includeChildren` to add active sub-routines; each
228
+ * sub-routine names its {@link Routine.parent} and
229
+ * {@link Routine.createdByRun}. `includeEvents` adds event-triggered
230
+ * routines.
231
+ *
232
+ * @readonly
49
233
  */
50
- create(options: RoutineOptions): Promise<Routine>;
51
- /** List routines, optionally including event triggers. */
52
234
  list(options?: {
53
235
  includeEvents?: boolean;
236
+ includeChildren?: boolean;
237
+ parent?: Routine;
54
238
  }): Promise<Routine[]>;
55
239
  }
@@ -1,4 +1,5 @@
1
- import type { ActionTrigger, EventFilter, RoutineModelId, RoutineTemplate as RoutineTemplateRecord, RoutineTrigger, RunVisibility, ScheduledActionResponse, TemplateVariable } from '../../../generated/scheduled-action/types.gen';
1
+ import type { ActionTrigger, CodeStep, EventFilter, RoutineModelId, RoutineTask, RoutineTemplate as RoutineTemplateRecord, RoutineTrigger, RunVisibility, ScheduledActionResponse, TemplateVariable } from '../../../generated/scheduled-action/types.gen';
2
+ import type { EntityAppearance } from '../../../generated/storage/types.gen';
2
3
  import type { MacroClient } from '../../utils/client';
3
4
  import { AgentSession } from '../agent-sessions/agent-session';
4
5
  import type { Agent } from '../agents/agent';
@@ -8,7 +9,11 @@ import type { EntityReference } from '../reference';
8
9
  import { User } from '../users/user';
9
10
  /** An event selector references resources by typed handles. */
10
11
  export type RoutineEventFilter = Omit<EventFilter, 'ids' | 'condition'> & {
11
- /** Resource selectors for these events. Omit to match all resources. */
12
+ /**
13
+ * The items these events are watched on, as references to handles the SDK
14
+ * returned, such as `{ type: 'channel', entity: channel }`; never ids.
15
+ * Omit to match all items.
16
+ */
12
17
  entities?: EntityReference[];
13
18
  /** Optional yes/no condition on the triggering content. */
14
19
  condition?: string;
@@ -32,8 +37,24 @@ export type RoutineTriggerOptions = SingleRoutineTrigger | {
32
37
  type: 'multiple';
33
38
  triggers: SingleRoutineTrigger[];
34
39
  };
35
- /** Configuration of an agent routine. */
36
- export interface RoutineOptions {
40
+ /**
41
+ * A routine step. A `code` step runs TypeScript against this SDK, as the
42
+ * routine's owner; an `agent` ("Ask AI") step hands the run to a model or
43
+ * agent with instructions. A routine has at most one agent step.
44
+ */
45
+ export type RoutineStepOptions = ({
46
+ type: 'code';
47
+ } & CodeStep) | {
48
+ type: 'agent';
49
+ /** What the model or agent should do; it also sees earlier steps' output. */
50
+ instructions: string;
51
+ /** Model to run the step, or the model override for `agent`. Set `model`, `agent`, or both. */
52
+ model?: RoutineModelId;
53
+ /** Agent to run the step. Set `model`, `agent`, or both. */
54
+ agent?: Agent;
55
+ };
56
+ /** What every routine has, whatever it runs. */
57
+ interface RoutineCommonOptions {
37
58
  /** Display name. */
38
59
  name: string;
39
60
  /**
@@ -41,6 +62,19 @@ export interface RoutineOptions {
41
62
  * or 7 fields: `sec min hour day-of-month month day-of-week [year]`.
42
63
  */
43
64
  trigger: RoutineTriggerOptions;
65
+ /** Whether triggers can start executions. Defaults to true on creation. */
66
+ enabled?: boolean;
67
+ /**
68
+ * Whether runs appear in Home and the Agents list. Defaults to `unlisted` on
69
+ * creation; an update that omits it keeps the stored value.
70
+ */
71
+ runVisibility?: RunVisibility;
72
+ }
73
+ /**
74
+ * A routine that hands each run to one model or agent: the older form, which
75
+ * runs as one Ask AI step. Write new routines as {@link StepsRoutineOptions}.
76
+ */
77
+ export interface AgentRoutineOptions extends RoutineCommonOptions {
44
78
  /** Instructions delivered to the agent. */
45
79
  prompt: string;
46
80
  /** Original user instructions. */
@@ -56,17 +90,35 @@ export interface RoutineOptions {
56
90
  * again on every run. Set `model`, `agent`, or both.
57
91
  */
58
92
  agent?: Agent;
59
- /** Whether triggers can start executions. Defaults to true on creation. */
60
- enabled?: boolean;
93
+ steps?: never;
94
+ dangerouslyOperateAsUser?: never;
95
+ }
96
+ /** A routine that runs code and Ask AI steps in order. */
97
+ export interface StepsRoutineOptions extends RoutineCommonOptions {
98
+ /** Run in order; a failed step stops the run. Saving type-checks the code. */
99
+ steps: readonly RoutineStepOptions[];
61
100
  /**
62
- * Whether runs appear in Home and the Agents list. Defaults to `unlisted` on
63
- * creation; an update that omits it keeps the stored value.
101
+ * Make code steps' messages, comments and emails appear written by the
102
+ * owner, with no agent badge. Set it only when the user explicitly asked
103
+ * for the routine to act, send or post as them; never infer it from what
104
+ * the routine does. Omitted, writes are attributed to Macro's agent acting
105
+ * for the owner, and an update that omits it turns it off.
64
106
  */
65
- runVisibility?: RunVisibility;
107
+ dangerouslyOperateAsUser?: boolean;
108
+ prompt?: never;
109
+ userPrompt?: never;
110
+ model?: never;
111
+ agent?: never;
66
112
  }
113
+ /** Configuration of a routine: code and Ask AI steps, or the older single agent task. */
114
+ export type RoutineOptions = AgentRoutineOptions | StepsRoutineOptions;
67
115
  /** A scheduled or event-triggered agent task. */
68
116
  export declare class Routine extends MacroEntity<ScheduledActionResponse> {
69
- /** The routine's URL in the Macro web app; hand it to users as the link. */
117
+ /**
118
+ * The routine's URL in the Macro web app; hand it to users as the link.
119
+ *
120
+ * @readonly
121
+ */
70
122
  webUrl(): string;
71
123
  /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
72
124
  toJSON(): {
@@ -81,6 +133,15 @@ export declare class Routine extends MacroEntity<ScheduledActionResponse> {
81
133
  protected fetch(): Promise<ScheduledActionResponse>;
82
134
  /** Routine name. */
83
135
  readonly name: () => Promise<string>;
136
+ /** Shared icon and color overrides. */
137
+ readonly appearance: () => Promise<import("../../../generated/scheduled-action").EntityAppearance | undefined>;
138
+ /**
139
+ * Replace shared appearance without rescheduling. Pass {} to reset both overrides.
140
+ *
141
+ * @write
142
+ * @idempotent
143
+ */
144
+ setAppearance(appearance: EntityAppearance): Promise<EntityAppearance>;
84
145
  /** Configured triggers. */
85
146
  readonly trigger: () => Promise<ActionTrigger>;
86
147
  /** Whether the routine is enabled. */
@@ -95,11 +156,45 @@ export declare class Routine extends MacroEntity<ScheduledActionResponse> {
95
156
  readonly owner: () => Promise<User>;
96
157
  /** The shared routine whose template this routine was activated from. */
97
158
  readonly sourceTemplate: () => Promise<Routine | undefined>;
98
- /** This routine's shared template, or `undefined` when it isn't shared. */
159
+ /**
160
+ * The routine this one follows, when one of that routine's runs created
161
+ * it: pausing the parent pauses it and deleting the parent deletes it.
162
+ * `undefined` for a top-level routine.
163
+ */
164
+ readonly parent: () => Promise<Routine | undefined>;
165
+ /**
166
+ * The run that created this sub-routine, by the id its history record
167
+ * has once that run ends. `undefined` for a top-level routine.
168
+ */
169
+ readonly createdByRun: () => Promise<RoutineRun | undefined>;
170
+ /** The key this sub-routine was created under, if its creator gave one. */
171
+ readonly key: () => Promise<string | undefined>;
172
+ /**
173
+ * This routine's sub-routines: the active ones and its newest finished
174
+ * one-time ones.
175
+ *
176
+ * @readonly
177
+ */
178
+ children(): Promise<Routine[]>;
179
+ /**
180
+ * Keep this sub-routine as the user's own routine: it moves to their main
181
+ * list and no longer pauses or is deleted with its parent.
182
+ *
183
+ * @write
184
+ */
185
+ keepAsOwn(): Promise<void>;
186
+ /**
187
+ * This routine's shared template, or `undefined` when it isn't shared.
188
+ *
189
+ * @readonly
190
+ */
99
191
  template(): Promise<RoutineTemplate | undefined>;
100
192
  /**
101
193
  * Share this routine as a template, or update its shared snapshot. People
102
194
  * get the template, never the routine, its runs or its results.
195
+ *
196
+ * @write
197
+ * @idempotent
103
198
  */
104
199
  shareAsTemplate(options: {
105
200
  /** What the routine does for someone. */
@@ -110,23 +205,73 @@ export declare class Routine extends MacroEntity<ScheduledActionResponse> {
110
205
  /**
111
206
  * Create the caller's own routine from this routine's shared template, with
112
207
  * its references already filled in for them.
208
+ *
209
+ * @write
113
210
  */
114
211
  activateTemplate(options: RoutineOptions): Promise<Routine>;
115
212
  private toTemplate;
116
- /** Stop sharing this routine. Routines already activated keep running. */
213
+ /**
214
+ * Stop sharing this routine. Routines already activated keep running.
215
+ *
216
+ * @destructive
217
+ * @idempotent
218
+ */
117
219
  stopSharingTemplate(): Promise<void>;
118
- /** Replace the routine's task and trigger configuration. */
220
+ /**
221
+ * Replace the routine's task and trigger configuration.
222
+ *
223
+ * @write
224
+ * @idempotent
225
+ */
119
226
  update(options: RoutineOptions): Promise<void>;
120
- /** Enable or disable triggering. */
227
+ /**
228
+ * Enable or disable triggering.
229
+ *
230
+ * @write
231
+ * @idempotent
232
+ */
121
233
  setEnabled(enabled: boolean): Promise<void>;
122
- /** Start an execution immediately and return its transcript handle if available. */
234
+ /**
235
+ * Start an execution immediately and return its transcript handle if available.
236
+ *
237
+ * @write
238
+ */
123
239
  execute(): Promise<Chat | AgentSession | undefined>;
124
- /** Completed executions, with their routine scoped identity. */
240
+ /**
241
+ * Completed executions, with their routine scoped identity.
242
+ *
243
+ * @readonly
244
+ */
125
245
  history(): Promise<RoutineExecution[]>;
126
- /** Delete the routine. */
246
+ /**
247
+ * Delete the routine.
248
+ *
249
+ * @destructive
250
+ * @idempotent
251
+ */
127
252
  delete(): Promise<void>;
128
253
  }
129
- /** A routine shared as a template, which people activate as their own routine. */
254
+ /**
255
+ * One run of a routine, by the id of its history record.
256
+ *
257
+ * @mcp-exclude Read from a sub-routine's record; no call takes one.
258
+ */
259
+ export declare class RoutineRun {
260
+ /** The run's id, which its {@link RoutineExecution} has once it ends. */
261
+ readonly id: string;
262
+ constructor(
263
+ /** The run's id, which its {@link RoutineExecution} has once it ends. */
264
+ id: string);
265
+ /** Serialize the run's identity. */
266
+ toJSON(): {
267
+ id: string;
268
+ };
269
+ }
270
+ /**
271
+ * A routine shared as a template, which people activate as their own routine.
272
+ *
273
+ * @mcp-exclude Built from a listing record; no id-only reference an MCP call can pass.
274
+ */
130
275
  export declare class RoutineTemplate {
131
276
  /** The shared routine. */
132
277
  readonly routine: Routine;
@@ -144,6 +289,8 @@ export declare class RoutineTemplate {
144
289
  /**
145
290
  * Create the caller's own routine from this template, with its references
146
291
  * already filled in for them.
292
+ *
293
+ * @write
147
294
  */
148
295
  activate(options: RoutineOptions): Promise<Routine>;
149
296
  /** Serialize without the authenticated client. */
@@ -154,12 +301,16 @@ export declare class RoutineExecution {
154
301
  /** Parent routine. */
155
302
  readonly routine: Routine;
156
303
  /** Execution snapshot. */
157
- readonly record: import('../../../generated/scheduled-action/types.gen').ActionExecutionRecord;
304
+ readonly record: import('../../../generated/scheduled-action/types.gen').ExecutionRecordResponse;
305
+ /** The sub-routines this run created that still follow the routine. */
306
+ readonly created: Routine[];
158
307
  constructor(
159
308
  /** Parent routine. */
160
309
  routine: Routine,
161
310
  /** Execution snapshot. */
162
- record: import('../../../generated/scheduled-action/types.gen').ActionExecutionRecord);
311
+ record: import('../../../generated/scheduled-action/types.gen').ExecutionRecordResponse,
312
+ /** The sub-routines this run created that still follow the routine. */
313
+ created?: Routine[]);
163
314
  /** Execution identity, when assigned. */
164
315
  get id(): string | undefined;
165
316
  /** Serialize without the authenticated client. */
@@ -174,6 +325,7 @@ export declare class RoutineExecution {
174
325
  [key: string]: unknown;
175
326
  };
176
327
  start_time: string;
328
+ created?: Array<import("../../../generated/scheduled-action").CreatedRoutine>;
177
329
  routine: string;
178
330
  };
179
331
  }
@@ -184,11 +336,6 @@ export declare function routineBody(options: RoutineOptions): {
184
336
  enabled: boolean | undefined;
185
337
  run_visibility: RunVisibility | undefined;
186
338
  trigger: ActionTrigger;
187
- task: {
188
- agent?: null | import("../../../generated/scheduled-action").AgentTaskAgent;
189
- mcp_servers?: Array<import("../../../generated/scheduled-action").AgentMcpServer>;
190
- model?: null | RoutineModelId;
191
- prompt: string;
192
- user_prompt: string;
193
- };
339
+ task: RoutineTask;
194
340
  };
341
+ export {};
@@ -0,0 +1,38 @@
1
+ import type { ReviewedState, ReviewedSuggestion, SuggestOutcome, Surface } from '../../../generated/scheduled-action/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ /**
4
+ * A routine suggestion AI made for the user, as a routines session reviews
5
+ * it. List-sourced only, from `macro.routines.review()`, so this wraps the
6
+ * record the caller already has.
7
+ */
8
+ export declare class RoutineSuggestion {
9
+ private readonly client;
10
+ private readonly record;
11
+ private constructor();
12
+ /** Wrap a reviewed suggestion already in hand. */
13
+ static from(client: MacroClient, record: ReviewedSuggestion): RoutineSuggestion;
14
+ /** The suggestion's id. */
15
+ get id(): string;
16
+ /** `open`; `dismissed` by the user (never suggest it again); `retired` by a session (it may come back); or `saved` as a routine. */
17
+ get state(): ReviewedState;
18
+ /** The reason the user reads. */
19
+ get reason(): string;
20
+ /** The sidebars it shows in. */
21
+ get surfaces(): Surface[];
22
+ /** The chance, from 0 to 1, the user keeps it on. */
23
+ get keepProbability(): number;
24
+ /** `catalog` with its `key` and `knobs`, or `routine` with the drafted `routine`. */
25
+ get pick(): ReviewedSuggestion;
26
+ /** When it was suggested, as RFC 3339. */
27
+ get createdAt(): string;
28
+ /** When it was dismissed or retired, as RFC 3339. */
29
+ get closedAt(): string | undefined;
30
+ /**
31
+ * Retire this open suggestion because it no longer fits the user's work,
32
+ * with a one-line `reason`. Only a routines generation session may. A
33
+ * retired catalog routine may be suggested again later.
34
+ *
35
+ * @mcp-exclude only a routines generation session may call it
36
+ */
37
+ retire(reason: string): Promise<SuggestOutcome>;
38
+ }
@@ -0,0 +1,58 @@
1
+ import type { MacroClient } from '../../utils/client';
2
+ import type { Team } from '../teams/team';
3
+ import { SavedView, type SavedViewConfig } from './saved-view';
4
+ /**
5
+ * Saved views: named filter definitions the app shows in a surface's sidebar,
6
+ * such as Email. Each user orders the views they can see for themselves.
7
+ *
8
+ * @routing Use when creating, editing, reordering or removing saved views, the named filters in the Email or Tasks sidebar; not favorites or pins.
9
+ */
10
+ export declare class SavedViewsNamespace {
11
+ private readonly client;
12
+ constructor(client: MacroClient);
13
+ /** A handle to a saved view by id. Details load on first access. */
14
+ byId(id: string): SavedView;
15
+ /**
16
+ * Create a saved view; `config.kind` names the app surface that shows it.
17
+ *
18
+ * An Email view (shown in Email's sidebar) has config
19
+ * `{ kind: 'email', version: 1, filters }`, with every one of these filters:
20
+ * `inboxIds` (inbox ids; empty for every inbox), `participants`
21
+ * (`{ type: 'address', email }` or `{ type: 'domain', domain }`, any of
22
+ * which matches), `participantFields` (which of `from`, `to`, `cc`, `bcc`
23
+ * they match in), `subject` (words, any of which matches), `starred`,
24
+ * `attachments` (`attachment-pdf`, `attachment-image`,
25
+ * `attachment-document`), `calendarInvite`, and `tags` (`[]`); and
26
+ * optionally `importance` (`signal` or `noise`), `read` (`unread` or
27
+ * `read`), `done` (`not-done` or `done`) and `receivedWithinDays` (1, 7,
28
+ * 30 or 90). Separate filters must all match.
29
+ *
30
+ * @write
31
+ */
32
+ create(opts: {
33
+ name: string;
34
+ config: SavedViewConfig;
35
+ /** Share with this team, which you must belong to; private when omitted. */
36
+ team?: Team;
37
+ }): Promise<SavedView>;
38
+ /**
39
+ * The saved views you can see, in your own order, auto-paginated (`maxItems` caps the total): placed
40
+ * views first, then by creation time. Each handle already holds its record.
41
+ *
42
+ * @readonly
43
+ */
44
+ list(opts?: {
45
+ /** Only views of this kind, such as `email`. */
46
+ kind?: string;
47
+ maxItems?: number;
48
+ }): AsyncGenerator<SavedView>;
49
+ /**
50
+ * Set your own order of one kind's views: `views` first, in the order
51
+ * given, and the rest after them by creation time. Returns the views in
52
+ * their new order; their definitions are unchanged.
53
+ *
54
+ * @write
55
+ * @idempotent
56
+ */
57
+ reorder(kind: string, views: SavedView[]): Promise<SavedView[]>;
58
+ }