@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
@@ -39,15 +39,39 @@ export declare class Notification extends MacroEntity<NotificationDetail> {
39
39
  readonly sender: () => Promise<User | undefined>;
40
40
  /** The typed notification payload (tagged by event type). */
41
41
  readonly metadata: () => Promise<import("../../../generated/notification").NotifEvent>;
42
- /** Whether the notification is acknowledged (seen or done). */
42
+ /**
43
+ * Whether the notification is acknowledged (seen or done).
44
+ *
45
+ * @readonly
46
+ */
43
47
  seen(): Promise<boolean>;
44
- /** Mark the notification as seen. */
48
+ /**
49
+ * Mark the notification as seen.
50
+ *
51
+ * @write
52
+ * @idempotent
53
+ */
45
54
  markSeen(): Promise<void>;
46
- /** Mark the notification as done. */
55
+ /**
56
+ * Mark the notification as done.
57
+ *
58
+ * @write
59
+ * @idempotent
60
+ */
47
61
  markDone(): Promise<void>;
48
- /** Move the notification back to not-done. */
62
+ /**
63
+ * Move the notification back to not-done.
64
+ *
65
+ * @write
66
+ * @idempotent
67
+ */
49
68
  markUndone(): Promise<void>;
50
- /** Delete the notification. */
69
+ /**
70
+ * Delete the notification.
71
+ *
72
+ * @destructive
73
+ * @idempotent
74
+ */
51
75
  delete(): Promise<void>;
52
76
  }
53
77
  export {};
@@ -10,14 +10,33 @@ export type { PinnedItem, ReorderPinRequest };
10
10
  export declare class PinsNamespace {
11
11
  private readonly client;
12
12
  constructor(client: MacroClient);
13
- /** The user's pinned items, with their pin indices. */
13
+ /**
14
+ * The user's pinned items, with their pin indices.
15
+ *
16
+ * @readonly
17
+ */
14
18
  list(): Promise<PinnedItem[]>;
15
- /** Pin an entity to a slot. `index` is the slot to put it in. */
19
+ /**
20
+ * Pin an entity to a slot. `index` is the slot to put it in.
21
+ *
22
+ * @write
23
+ * @idempotent
24
+ */
16
25
  add(entity: FavoritableEntity<unknown>, opts: {
17
26
  index: number;
18
27
  }): Promise<void>;
19
- /** Unpin an entity. */
28
+ /**
29
+ * Unpin an entity.
30
+ *
31
+ * @write
32
+ * @idempotent
33
+ */
20
34
  remove(entity: FavoritableEntity<unknown>): Promise<void>;
21
- /** Reorder pins: pass each pinned item with its type and new index. */
35
+ /**
36
+ * Reorder pins: pass each pinned item with its type and new index.
37
+ *
38
+ * @write
39
+ * @idempotent
40
+ */
22
41
  reorder(pins: ReorderPinRequest[]): Promise<void>;
23
42
  }
@@ -2,15 +2,44 @@ import type { MacroClient } from '../../utils/client';
2
2
  import type { SearchOpts } from '../search/options';
3
3
  import { Project } from './project';
4
4
  /**
5
+ * Projects are folders that hold documents, chats and other projects.
6
+ *
7
+ * An agent session cannot be placed in a project: sessions have no project,
8
+ * and `Project.items()` never lists them. To keep a session with a project's
9
+ * work, create a Markdown document in the project that links the session with
10
+ * an agent session chip; `"expanded": true` shows the card that follows its
11
+ * latest turn.
12
+ *
13
+ * @example Link an agent session from a project.
14
+ * ```js
15
+ * const chip = JSON.stringify({ id: session.id, label: '', expanded: true });
16
+ * const document = await macro.documents.create({
17
+ * name: 'Agent work',
18
+ * project,
19
+ * markdown: `<m-agent-session-mention>${chip}</m-agent-session-mention>`,
20
+ * });
21
+ * return { data: { url: document.webUrl() } };
22
+ * ```
23
+ *
5
24
  * @routing Use when organizing items into projects (folders); not initiatives, which group tasks.
6
25
  */
7
26
  export declare class ProjectNamespace {
8
27
  private readonly client;
9
28
  constructor(client: MacroClient);
10
29
  byId(id: string): Project;
30
+ /**
31
+ * Create a project, optionally nested inside a parent project.
32
+ *
33
+ * @write
34
+ */
11
35
  create(opts: {
12
36
  name: string;
13
37
  parent?: Project;
14
38
  }): Promise<Project>;
39
+ /**
40
+ * Search projects by name and content, most relevant first, auto-paginated.
41
+ *
42
+ * @readonly
43
+ */
15
44
  search(query: string, opts?: SearchOpts): AsyncGenerator<Project>;
16
45
  }
@@ -2,13 +2,31 @@ import type { GetProjectContentHandlerResponses, GetProjectHandlerResponses } fr
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import { PropertiedEntity } from '../entity';
4
4
  import { EntityAccess } from '../sharing/access';
5
+ import { type SharePermissionOptions } from '../sharing/permissions';
5
6
  type ProjectDetail = GetProjectHandlerResponses[200]['data']['projectMetadata'];
6
7
  type ProjectItem = GetProjectContentHandlerResponses[200]['data'][number]['item'];
7
8
  /** A Macro project: a folder-like container for documents, chats, and subprojects. */
8
9
  export declare class Project extends PropertiedEntity<ProjectDetail> {
9
- /** Read this project's sharing configuration. */
10
+ /**
11
+ * Read this project's sharing configuration.
12
+ *
13
+ * @readonly
14
+ */
10
15
  sharePermissions(): Promise<import("../../../generated/storage").SharePermissionV2>;
11
- /** Read the caller's effective access level. */
16
+ /**
17
+ * Change who can open the project and its contents: the link share and its
18
+ * access level, the owner's team, and channel grants. Omitted fields are
19
+ * left as they are.
20
+ *
21
+ * @write
22
+ * @idempotent
23
+ */
24
+ updateSharePermissions(options: SharePermissionOptions): Promise<void>;
25
+ /**
26
+ * Read the caller's effective access level.
27
+ *
28
+ * @readonly
29
+ */
12
30
  accessLevel(): Promise<"view" | "comment" | "edit" | "owner">;
13
31
  /** Access requests and direct user grants. */
14
32
  readonly access: EntityAccess;
@@ -17,7 +35,11 @@ export declare class Project extends PropertiedEntity<ProjectDetail> {
17
35
  /** The properties service identifies projects as `PROJECT`. */
18
36
  protected readonly propertyEntityType = "PROJECT";
19
37
  protected fetch(): Promise<ProjectDetail>;
20
- /** The project's URL in the Macro web app; hand it to users as the link. */
38
+ /**
39
+ * The project's URL in the Macro web app; hand it to users as the link.
40
+ *
41
+ * @readonly
42
+ */
21
43
  webUrl(): string;
22
44
  /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
23
45
  toJSON(): {
@@ -38,18 +60,37 @@ export declare class Project extends PropertiedEntity<ProjectDetail> {
38
60
  readonly parent: () => Promise<Project | undefined>;
39
61
  /** When the project was created (RFC 3339 timestamp). */
40
62
  readonly createdAt: () => Promise<string | undefined>;
41
- /** The items (documents, chats, subprojects) directly inside this project. */
63
+ /**
64
+ * The items (documents, chats, subprojects) directly inside this project.
65
+ * Agent sessions are never project items; link one from a document in the
66
+ * project instead (see `ProjectNamespace`).
67
+ *
68
+ * @readonly
69
+ */
42
70
  items(): Promise<ProjectItem[]>;
43
- /** Rename the project. */
71
+ /**
72
+ * Rename the project.
73
+ *
74
+ * @write
75
+ * @idempotent
76
+ */
44
77
  rename(name: string): Promise<void>;
45
78
  /**
46
79
  * Delete the project and its contents. Soft by default (reversible with
47
80
  * {@link restore}); pass `permanent: true` to delete irreversibly.
81
+ *
82
+ * @destructive
83
+ * @idempotent
48
84
  */
49
85
  delete(opts?: {
50
86
  permanent?: boolean;
51
87
  }): Promise<void>;
52
- /** Restore a soft-deleted project. */
88
+ /**
89
+ * Restore a soft-deleted project.
90
+ *
91
+ * @write
92
+ * @idempotent
93
+ */
53
94
  restore(): Promise<void>;
54
95
  /** Search projects by name and content, most relevant first, auto-paginated. */
55
96
  static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<Project, any, any>;
@@ -1,49 +1,105 @@
1
- import type { BulkEntityOptionUpdateResult, BulkEntityPropertiesRequest, CreatePropertyScope, EntityPropertiesResponse, PropertyDataType, PropertyDefinition as PropertyDefinitionRecord, PropertyTargetEntityType as PropertyEntityType, PropertyScope, TagSetResponse } from '../../../generated/properties/types.gen';
1
+ import type { BulkEntityOptionUpdateResult, BulkEntityPropertiesRequest, CreatePropertyScope, EntityPropertiesResponse, PropertyDataType, PropertyDefinition as PropertyDefinitionRecord, PropertyTargetEntityType as PropertyEntityType, PropertyScope, TagScope, TagSetResponse } from '../../../generated/properties/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import type { PropertiedEntity, PropertyOptionDelta } from '../entity';
4
4
  import { PropertyDefinition } from './property-definition';
5
5
  import { PropertyOption } from './property-option';
6
- export type { BulkEntityPropertiesRequest, CreatePropertyScope, EntityPropertiesResponse, PropertyDataType, PropertyDefinitionRecord, PropertyEntityType, PropertyScope, TagSetResponse, };
6
+ export type { BulkEntityPropertiesRequest, CreatePropertyScope, EntityPropertiesResponse, PropertyDataType, PropertyDefinitionRecord, PropertyEntityType, PropertyScope, TagScope, TagSetResponse, };
7
7
  export { PropertyDefinition, PropertyOption };
8
8
  /**
9
9
  * Property definitions and tag sets. Entity-level reads and writes live on
10
10
  * the entity handles ({@link PropertiedEntity.properties}, `setProperty`,
11
11
  * `deleteProperty`).
12
12
  *
13
- * @routing Use when the request is about an item's custom properties themselves, such as defining a property or bulk-setting its options; not creating or updating a task, deal, event or row, whose own methods set their fields.
13
+ * @routing Use when the request is about an item's custom properties or tags themselves, such as defining a property, creating or editing a tag, or bulk-setting options; not creating or updating a task, deal, event or row, whose own methods set their fields.
14
14
  */
15
15
  export declare class PropertiesNamespace {
16
16
  private readonly client;
17
17
  constructor(client: MacroClient);
18
- /** List property definitions visible to the user, pre-hydrated with their records. */
18
+ /**
19
+ * List property definitions visible to the user, pre-hydrated with their records.
20
+ *
21
+ * @readonly
22
+ */
19
23
  list(opts?: {
20
24
  scope?: PropertyScope;
21
25
  forEntityType?: PropertyEntityType;
22
26
  }): Promise<PropertyDefinition[]>;
23
- /** Create a new custom property definition. */
27
+ /**
28
+ * Create a new custom property definition.
29
+ *
30
+ * @write
31
+ */
24
32
  create(opts: {
25
33
  displayName: string;
26
34
  scope: CreatePropertyScope;
27
35
  dataType: PropertyDataType;
28
36
  }): Promise<PropertyDefinition>;
29
- /** A handle to an existing property definition by id. */
37
+ /**
38
+ * A handle to an existing property definition by id.
39
+ *
40
+ * @readonly
41
+ */
30
42
  definition(id: string): PropertyDefinition;
31
- /** Get properties for multiple entities in a single request. */
43
+ /**
44
+ * Get properties for multiple entities in a single request.
45
+ *
46
+ * @readonly
47
+ */
32
48
  bulkEntityProperties(request: BulkEntityPropertiesRequest): Promise<Record<string, EntityPropertiesResponse>>;
33
- /** Apply one multi-select option delta to several entity handles. */
49
+ /**
50
+ * Apply one multi-select option delta to several entity handles.
51
+ *
52
+ * @write
53
+ * @idempotent
54
+ * @mcp-exclude Takes a handle built from a listing record, which an MCP call can't reference.
55
+ */
34
56
  updateEntityPropertyOptions(entities: PropertiedEntity<unknown>[], change: PropertyOptionDelta): Promise<BulkEntityOptionUpdateResult[]>;
35
- /** Add a select option to a multi-select property value on an entity. */
57
+ /**
58
+ * Add a select option to a multi-select property value on an entity.
59
+ *
60
+ * @write
61
+ * @idempotent
62
+ * @mcp-exclude Takes a handle built from a listing record, which an MCP call can't reference.
63
+ */
36
64
  addEntityPropertyOption(opts: {
37
65
  entity: PropertiedEntity<unknown>;
38
66
  property: PropertyDefinition;
39
67
  option: PropertyOption;
40
68
  }): Promise<void>;
41
- /** Remove a select option from a multi-select property value on an entity. */
69
+ /**
70
+ * Remove a select option from a multi-select property value on an entity.
71
+ *
72
+ * @write
73
+ * @idempotent
74
+ * @mcp-exclude Takes a handle built from a listing record, which an MCP call can't reference.
75
+ */
42
76
  removeEntityPropertyOption(opts: {
43
77
  entity: PropertiedEntity<unknown>;
44
78
  property: PropertyDefinition;
45
79
  option: PropertyOption;
46
80
  }): Promise<void>;
47
- /** The user's tag sets: their personal set, plus their team's when on a team. */
81
+ /**
82
+ * The user's tag sets: their personal set, plus their team's when on a team.
83
+ * A set without a `definition` has no tags yet; {@link createTag} creates it.
84
+ * Edit or delete a tag through `definition(set.definition.id).options()`.
85
+ *
86
+ * @readonly
87
+ */
48
88
  tags(): Promise<TagSetResponse[]>;
89
+ /**
90
+ * Create a tag, provisioning the tag set on its first tag. Tags match by
91
+ * label, so check {@link tags} first and never duplicate one in the same set.
92
+ * Apply it with `item.updatePropertyOptions([{ property, add: [tag] }])`,
93
+ * where `property` is `definition(tag.definitionId)`.
94
+ *
95
+ * @write
96
+ */
97
+ createTag(opts: {
98
+ /** The label, e.g. "Urgent". */
99
+ label: string;
100
+ /** A hex color such as `#46A758`. */
101
+ color?: string;
102
+ /** `user` (the default) for the user's own tags, `team` for their team's shared tags. */
103
+ scope?: TagScope;
104
+ }): Promise<PropertyOption>;
49
105
  }
@@ -0,0 +1 @@
1
+ export {};
@@ -32,14 +32,39 @@ export declare class PropertyDefinition {
32
32
  get isMultiSelect(): Promise<boolean>;
33
33
  get createdAt(): Promise<string>;
34
34
  get updatedAt(): Promise<string>;
35
- /** Delete this property definition. */
35
+ /**
36
+ * Delete this property definition.
37
+ *
38
+ * @destructive
39
+ * @idempotent
40
+ */
36
41
  delete(): Promise<void>;
37
- /** The selectable options for this definition (select-type properties). */
42
+ /**
43
+ * The selectable options for this definition (select-type properties).
44
+ *
45
+ * @readonly
46
+ */
38
47
  options(): Promise<PropertyOption[]>;
39
- /** Add an option to this select-type property. */
48
+ /**
49
+ * Add an option to this select-type property.
50
+ *
51
+ * @write
52
+ */
40
53
  addOption(option: AddPropertyOptionRequest): Promise<PropertyOption>;
41
- /** Update an option (label, color, display order). */
54
+ /**
55
+ * Update an option (label, color, display order).
56
+ *
57
+ * @write
58
+ * @idempotent
59
+ * @mcp-exclude Takes a handle built from a listing record, which an MCP call can't reference.
60
+ */
42
61
  updateOption(option: PropertyOption, updates: UpdatePropertyOptionRequest): Promise<PropertyOption>;
43
- /** Delete an option from this property. */
62
+ /**
63
+ * Delete an option from this property.
64
+ *
65
+ * @destructive
66
+ * @idempotent
67
+ * @mcp-exclude Takes a handle built from a listing record, which an MCP call can't reference.
68
+ */
44
69
  deleteOption(option: PropertyOption): Promise<void>;
45
70
  }
@@ -5,6 +5,8 @@ export type { UpdatePropertyOptionRequest };
5
5
  * A selectable option on a select-type property definition. There is no
6
6
  * single-option GET, so instances are only built from a seed record — via
7
7
  * {@link PropertyDefinition.options} or {@link PropertyDefinition.addOption}.
8
+ *
9
+ * @mcp-exclude Built from a listing record; no id-only reference an MCP call can pass.
8
10
  */
9
11
  export declare class PropertyOption {
10
12
  private readonly client;
@@ -25,8 +27,18 @@ export declare class PropertyOption {
25
27
  get createdAt(): string;
26
28
  /** When the option was last updated. */
27
29
  get updatedAt(): string;
28
- /** Update this option's label, color, or display order. */
30
+ /**
31
+ * Update this option's label, color, or display order.
32
+ *
33
+ * @write
34
+ * @idempotent
35
+ */
29
36
  update(updates: UpdatePropertyOptionRequest): Promise<this>;
30
- /** Delete this option from its property definition. */
37
+ /**
38
+ * Delete this option from its property definition.
39
+ *
40
+ * @destructive
41
+ * @idempotent
42
+ */
31
43
  delete(): Promise<void>;
32
44
  }
@@ -15,7 +15,11 @@ export interface ReferralLink {
15
15
  export declare class ReferralNamespace {
16
16
  private readonly client;
17
17
  constructor(client: MacroClient);
18
- /** The caller's referral link, to share wherever the user wants. */
18
+ /**
19
+ * The caller's referral link, to share wherever the user wants.
20
+ *
21
+ * @readonly
22
+ */
19
23
  link(): Promise<ReferralLink>;
20
24
  /**
21
25
  * Email an invite to join Macro, with the caller's referral link; only send
@@ -28,6 +32,9 @@ export declare class ReferralNamespace {
28
32
  * instead, use `Team.invite`.
29
33
  *
30
34
  * @param email - The address to invite.
35
+ *
36
+ * @destructive
37
+ * @openworld
31
38
  */
32
39
  invite(email: string): Promise<void>;
33
40
  }
@@ -1,5 +1,12 @@
1
+ import type { RoutineCheck, 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
+ /** Something created for a routine to use: any handle with an entity type, such as a `Database`. */
6
+ export interface CreatedEntity {
7
+ readonly id: string;
8
+ readonly entityType: MacroEntityType;
9
+ }
3
10
  /**
4
11
  * Scheduled and event-triggered routines.
5
12
  *
@@ -11,6 +18,30 @@ import { Routine, type RoutineOptions } from './routine';
11
18
  * - "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
19
  * - 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
20
  * - Before creating one, look for a routine of the user's that already does this, and update it instead of adding a second.
21
+ *
22
+ * ### Writing one
23
+ *
24
+ * - 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.
25
+ * - 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.
26
+ * - 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.
27
+ * - 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.
28
+ * - 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`.
29
+ * - 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.
30
+ *
31
+ * Events an `events` trigger starts on (`EventName` lists every one):
32
+ *
33
+ * - `channel.created`: a channel you can access is created.
34
+ * - `channel.message_posted`: someone sends a message in a selected channel.
35
+ * - `channel.mentioned`: you are @ mentioned in a selected channel.
36
+ * - `document.created`: a document you can access is created. Tasks have their own trigger.
37
+ * - `document.deleted`: a selected document is deleted.
38
+ * - `task.created`: a task you can access is created.
39
+ * - `task.status_changed`: a task's status changes.
40
+ * - `task.priority_changed`: a task's priority changes.
41
+ * - `task.property_changed`: any property on a task changes, such as its assignees, due date, project or effort, including status and priority.
42
+ * - `email.message_received`: new mail arrives in your inbox. Excludes spam, trash, drafts and historical imports.
43
+ * - `call.started`: a call you start begins. The routine gets the call and who has joined so far.
44
+ * - `call.ended`: a call you joined ends. The routine gets the call's participants and transcript.
14
45
  */
15
46
  export declare class RoutineNamespace {
16
47
  private readonly client;
@@ -18,12 +49,17 @@ export declare class RoutineNamespace {
18
49
  /** Construct a lazy routine handle. */
19
50
  byId(id: string): Routine;
20
51
  /**
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.
52
+ * Create a routine: one agent task (`prompt`, with `model`, `agent`, or
53
+ * both), or code and Ask AI `steps`. Set `dangerouslyOperateAsUser` only
54
+ * when the user explicitly asked for it to act, send or post as them. To
55
+ * check on something later, such as a spawned session or a long job, create
56
+ * a routine instead of waiting in a program. A cron `schedule` has 6 fields
57
+ * (second minute hour day-of-month month day-of-week) or 7 with a year; a
58
+ * 7-field schedule that names one date runs once. A code step's `source`
59
+ * exports `async function main({ macro, run, trigger, steps, knobs })` and
60
+ * is type-checked against this SDK when saved. A rejected routine throws a
61
+ * `MacroApiError` whose message says what the server refused, including
62
+ * type-check errors.
27
63
  *
28
64
  * @example
29
65
  * // Every ten minutes, in New York time.
@@ -46,9 +82,94 @@ export declare class RoutineNamespace {
46
82
  * model: 'anthropic/claude-sonnet-5-5',
47
83
  * trigger: { type: 'cron', schedule: '0 30 14 3 11 * 2027', timezone: 'UTC' },
48
84
  * });
85
+ * // A code step that posts in a channel, disabled until turned on. The
86
+ * // user asked for the post to come from them.
87
+ * await macro.routines.create({
88
+ * name: 'Say hello',
89
+ * trigger: { type: 'once', at: '2027-11-03T14:30:00Z' },
90
+ * enabled: false,
91
+ * steps: [
92
+ * {
93
+ * type: 'code',
94
+ * title: 'Post hello',
95
+ * source: `export async function main({ macro }: StepContext) {
96
+ * await macro.channels.byId('<channel id>').send('Hello');
97
+ * }`,
98
+ * },
99
+ * ],
100
+ * dangerouslyOperateAsUser: true,
101
+ * });
102
+ *
103
+ * @write
49
104
  */
50
105
  create(options: RoutineOptions): Promise<Routine>;
51
- /** List routines, optionally including event triggers. */
106
+ /**
107
+ * Check a routine without saving it: the checks `create` makes, including
108
+ * type-checking its code steps, with nothing saved. Returns whether it
109
+ * would save (`ok`), what would stop it (`problems`), the code steps that
110
+ * don't type-check (`steps`, by place among the steps) and the routine as
111
+ * it would be stored. Check before creating, and fix what it reports.
112
+ * `created` names what you created for the routine to use, such as the
113
+ * database it writes to, so whoever reviews a drafted routine knows it
114
+ * exists.
115
+ *
116
+ * @example
117
+ * const check = await macro.routines.check({
118
+ * name: 'Say hello',
119
+ * trigger: { type: 'once', at: '2027-11-03T14:30:00Z' },
120
+ * steps: [{ type: 'code', title: 'Post hello', source }],
121
+ * });
122
+ * if (!check.ok) return { problems: check.problems, steps: check.steps };
123
+ *
124
+ * @readonly
125
+ */
126
+ check(options: RoutineOptions, extra?: {
127
+ created?: CreatedEntity[];
128
+ }): Promise<RoutineCheck>;
129
+ /**
130
+ * Suggest a routine to the user. Only a routine suggestion session may
131
+ * call this; any other session gets a 403. Suggest a catalog routine by
132
+ * `key` with `knobs`, or a `routine` the catalog lacks, written as `check`
133
+ * takes it and checked the same way. `surfaces` are the parts of the app
134
+ * whose sidebar shows it, best fit first; `reason` is one line, shown to
135
+ * the user, naming no one's email address; `keepProbability` is the
136
+ * chance, from 0 to 1, that the user keeps it on. Returns whether it was
137
+ * kept (`ok`) and, when not, the `problems` to fix before suggesting it
138
+ * again.
139
+ *
140
+ * @example
141
+ * const outcome = await macro.routines.suggest({
142
+ * kind: 'catalog',
143
+ * key: 'inbox',
144
+ * knobs: {},
145
+ * reason: 'Most of your mail is supplier updates',
146
+ * surfaces: ['email'],
147
+ * keepProbability: 0.6,
148
+ * });
149
+ * if (!outcome.ok) return outcome.problems;
150
+ *
151
+ * @write
152
+ */
153
+ suggest(suggestion: {
154
+ kind: 'catalog';
155
+ key: string;
156
+ knobs?: Record<string, unknown>;
157
+ reason: string;
158
+ surfaces: Surface[];
159
+ keepProbability: number;
160
+ } | {
161
+ kind: 'routine';
162
+ routine: RoutineOptions;
163
+ created?: CreatedEntity[];
164
+ reason: string;
165
+ surfaces: Surface[];
166
+ keepProbability: number;
167
+ }): Promise<SuggestOutcome>;
168
+ /**
169
+ * List routines, optionally including event triggers.
170
+ *
171
+ * @readonly
172
+ */
52
173
  list(options?: {
53
174
  includeEvents?: boolean;
54
175
  }): Promise<Routine[]>;