@macro-inc/sdk 0.2.2 → 0.4.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 (175) hide show
  1. package/README.md +177 -3
  2. package/dist/{chunk-OGE7WXJE.js → chunk-AZJUIUIV.js} +177 -23
  3. package/dist/{chunk-PRUFPW3B.js → chunk-G43PLP2U.js} +144 -0
  4. package/dist/{chunk-7LVVPVNT.js → chunk-K4G5VO4P.js} +76 -1
  5. package/dist/{chunk-PAAFJYGO.js → chunk-PPR7IWZ7.js} +77 -51
  6. package/dist/{chunk-QVBNNMQS.js → chunk-PTX2RV2N.js} +169 -20
  7. package/dist/{chunk-SUINKDXF.js → chunk-PZPTJI6F.js} +42 -0
  8. package/dist/{chunk-7YJ6Y7HJ.js → chunk-XFA7NCJ5.js} +207 -0
  9. package/dist/{chunk-ZQXOHNDB.js → chunk-ZLBDES7U.js} +789 -12
  10. package/dist/generated/agent-fold/index.d.ts +4332 -0
  11. package/dist/generated/agent-fold/index.js +0 -0
  12. package/dist/generated/agent-harness/index.d.ts +1 -1
  13. package/dist/generated/agent-harness/index.js +1 -1
  14. package/dist/generated/agent-harness/sdk.gen.d.ts +83 -9
  15. package/dist/generated/agent-harness/types.gen.d.ts +1504 -160
  16. package/dist/generated/agent-reviews/index.d.ts +893 -0
  17. package/dist/generated/agent-reviews/index.js +0 -0
  18. package/dist/generated/auth/index.d.ts +1 -1
  19. package/dist/generated/auth/index.js +1 -1
  20. package/dist/generated/auth/sdk.gen.d.ts +108 -2
  21. package/dist/generated/auth/types.gen.d.ts +799 -6
  22. package/dist/generated/calendar/index.d.ts +1 -1
  23. package/dist/generated/calendar/index.js +1 -1
  24. package/dist/generated/calendar/sdk.gen.d.ts +63 -1
  25. package/dist/generated/calendar/types.gen.d.ts +1234 -5
  26. package/dist/generated/cognition/index.d.ts +1 -1
  27. package/dist/generated/cognition/index.js +1 -1
  28. package/dist/generated/cognition/sdk.gen.d.ts +85 -20
  29. package/dist/generated/cognition/types.gen.d.ts +1040 -121
  30. package/dist/generated/connection/index.d.ts +1 -1
  31. package/dist/generated/connection/index.js +15 -0
  32. package/dist/generated/connection/sdk.gen.d.ts +6 -1
  33. package/dist/generated/connection/types.gen.d.ts +18 -1
  34. package/dist/generated/email/index.d.ts +1 -1
  35. package/dist/generated/email/index.js +1 -1
  36. package/dist/generated/email/sdk.gen.d.ts +44 -2
  37. package/dist/generated/email/types.gen.d.ts +475 -10
  38. package/dist/generated/notification/index.d.ts +1 -1
  39. package/dist/generated/notification/index.js +1 -1
  40. package/dist/generated/notification/sdk.gen.d.ts +29 -21
  41. package/dist/generated/notification/types.gen.d.ts +267 -73
  42. package/dist/generated/properties/index.d.ts +1 -1
  43. package/dist/generated/properties/types.gen.d.ts +21 -1
  44. package/dist/generated/scheduled-action/index.d.ts +1 -1
  45. package/dist/generated/scheduled-action/index.js +1 -1
  46. package/dist/generated/scheduled-action/sdk.gen.d.ts +8 -1
  47. package/dist/generated/scheduled-action/types.gen.d.ts +669 -19
  48. package/dist/generated/search/index.d.ts +1 -1
  49. package/dist/generated/search/types.gen.d.ts +87 -7
  50. package/dist/generated/static-files/types.gen.d.ts +6 -0
  51. package/dist/generated/storage/index.d.ts +1 -1
  52. package/dist/generated/storage/index.js +1 -1
  53. package/dist/generated/storage/sdk.gen.d.ts +376 -13
  54. package/dist/generated/storage/types.gen.d.ts +12038 -5562
  55. package/dist/src/entities/account-managers/grant.d.ts +39 -0
  56. package/dist/src/entities/account-managers/namespace.d.ts +17 -0
  57. package/dist/src/entities/agent-sessions/activity.d.ts +39 -0
  58. package/dist/src/entities/agent-sessions/agent-session.d.ts +148 -6
  59. package/dist/src/entities/agent-sessions/code-execution.d.ts +5 -0
  60. package/dist/src/entities/agent-sessions/namespace.d.ts +54 -4
  61. package/dist/src/entities/agent-sessions/origin.d.ts +94 -0
  62. package/dist/src/entities/agent-sessions/review.d.ts +18 -62
  63. package/dist/src/entities/agent-sessions/view.d.ts +11 -0
  64. package/dist/src/entities/agents/namespace.d.ts +11 -2
  65. package/dist/src/entities/ai/namespace.d.ts +5 -1
  66. package/dist/src/entities/api-keys/namespace.d.ts +5 -1
  67. package/dist/src/entities/bots/bot.d.ts +108 -0
  68. package/dist/src/entities/bots/namespace.d.ts +17 -4
  69. package/dist/src/entities/bots/token.d.ts +34 -0
  70. package/dist/src/entities/calendar/booking-link.d.ts +49 -0
  71. package/dist/src/entities/calendar/booking-namespace.d.ts +130 -0
  72. package/dist/src/entities/calendar/booking-namespace.test.d.ts +1 -0
  73. package/dist/src/entities/calendar/booking.d.ts +77 -0
  74. package/dist/src/entities/calendar/calendar.d.ts +11 -4
  75. package/dist/src/entities/calendar/create-confirmed.test.d.ts +1 -0
  76. package/dist/src/entities/calendar/event.d.ts +104 -3
  77. package/dist/src/entities/calendar/namespace.d.ts +151 -7
  78. package/dist/src/entities/calendar/namespace.test.d.ts +1 -0
  79. package/dist/src/entities/calls/call-record.d.ts +34 -4
  80. package/dist/src/entities/calls/connection.d.ts +53 -0
  81. package/dist/src/entities/calls/errors.d.ts +15 -0
  82. package/dist/src/entities/calls/namespace.d.ts +21 -1
  83. package/dist/src/entities/calls/participant.d.ts +22 -0
  84. package/dist/src/entities/channels/access-request.d.ts +34 -0
  85. package/dist/src/entities/channels/channel.d.ts +47 -1
  86. package/dist/src/entities/channels/namespace.d.ts +21 -5
  87. package/dist/src/entities/channels/namespace.test.d.ts +1 -0
  88. package/dist/src/entities/channels/post.d.ts +14 -3
  89. package/dist/src/entities/channels/thread.d.ts +10 -1
  90. package/dist/src/entities/chats/chat.d.ts +7 -1
  91. package/dist/src/entities/chats/namespace.d.ts +14 -1
  92. package/dist/src/entities/connected-apps/connected-app.d.ts +107 -0
  93. package/dist/src/entities/connected-apps/connector.d.ts +56 -0
  94. package/dist/src/entities/connected-apps/namespace.d.ts +74 -0
  95. package/dist/src/entities/crm/company.d.ts +7 -3
  96. package/dist/src/entities/crm/contact.d.ts +4 -4
  97. package/dist/src/entities/crm/namespace.d.ts +34 -1
  98. package/dist/src/entities/crm/pipeline.d.ts +43 -2
  99. package/dist/src/entities/databases/database.d.ts +17 -0
  100. package/dist/src/entities/databases/namespace.d.ts +56 -0
  101. package/dist/src/entities/documents/ai-edit.d.ts +52 -0
  102. package/dist/src/entities/documents/document.d.ts +244 -5
  103. package/dist/src/entities/documents/namespace.d.ts +89 -4
  104. package/dist/src/entities/documents/office-files.d.ts +47 -0
  105. package/dist/src/entities/email/draft.d.ts +36 -7
  106. package/dist/src/entities/email/message.d.ts +99 -3
  107. package/dist/src/entities/email/namespace.d.ts +47 -4
  108. package/dist/src/entities/email/namespace.test.d.ts +1 -0
  109. package/dist/src/entities/email/thread.d.ts +55 -3
  110. package/dist/src/entities/entity-mentions/namespace.d.ts +5 -1
  111. package/dist/src/entities/external-chat/chat.d.ts +105 -0
  112. package/dist/src/entities/external-chat/message.d.ts +54 -0
  113. package/dist/src/entities/external-chat/namespace.d.ts +18 -0
  114. package/dist/src/entities/external-chat/participant.d.ts +28 -0
  115. package/dist/src/entities/external-chat/send.d.ts +32 -0
  116. package/dist/src/entities/external-chat/upload.d.ts +25 -0
  117. package/dist/src/entities/favorites/namespace.d.ts +5 -1
  118. package/dist/src/entities/foreign/namespace.d.ts +3 -0
  119. package/dist/src/entities/forms/form.d.ts +17 -2
  120. package/dist/src/entities/forms/namespace.d.ts +5 -1
  121. package/dist/src/entities/github-pull-requests/namespace.d.ts +5 -1
  122. package/dist/src/entities/harnesses/harness.d.ts +9 -0
  123. package/dist/src/entities/harnesses/namespace.d.ts +5 -1
  124. package/dist/src/entities/images/image.d.ts +77 -0
  125. package/dist/src/entities/images/namespace.d.ts +48 -0
  126. package/dist/src/entities/images/namespace.test.d.ts +1 -0
  127. package/dist/src/entities/initiatives/initiative.d.ts +12 -1
  128. package/dist/src/entities/initiatives/namespace.d.ts +15 -2
  129. package/dist/src/entities/me/namespace.d.ts +43 -0
  130. package/dist/src/entities/meetings/meeting.d.ts +5 -0
  131. package/dist/src/entities/meetings/namespace.d.ts +5 -1
  132. package/dist/src/entities/messages/thread.d.ts +1 -1
  133. package/dist/src/entities/notifications/namespace.d.ts +3 -0
  134. package/dist/src/entities/pins/namespace.d.ts +5 -1
  135. package/dist/src/entities/projects/namespace.d.ts +4 -1
  136. package/dist/src/entities/projects/project.d.ts +9 -1
  137. package/dist/src/entities/properties/namespace.d.ts +2 -0
  138. package/dist/src/entities/referrals/namespace.d.ts +33 -0
  139. package/dist/src/entities/routines/namespace.d.ts +42 -2
  140. package/dist/src/entities/routines/routine.d.ts +84 -5
  141. package/dist/src/entities/search/namespace.d.ts +65 -0
  142. package/dist/src/entities/{search.d.ts → search/options.d.ts} +8 -2
  143. package/dist/src/entities/search/types.d.ts +90 -0
  144. package/dist/src/entities/sharing/access.d.ts +14 -0
  145. package/dist/src/entities/tasks/namespace.d.ts +42 -3
  146. package/dist/src/entities/tasks/task.d.ts +47 -6
  147. package/dist/src/entities/teams/invite.d.ts +30 -0
  148. package/dist/src/entities/teams/namespace.d.ts +3 -0
  149. package/dist/src/entities/teams/team.d.ts +37 -0
  150. package/dist/src/entities/unfurls/namespace.d.ts +5 -1
  151. package/dist/src/entities/users/namespace.d.ts +9 -0
  152. package/dist/src/entities/users/user.d.ts +8 -0
  153. package/dist/src/entities/web/namespace.d.ts +61 -0
  154. package/dist/src/entities/web/namespace.test.d.ts +1 -0
  155. package/dist/src/entities/webhooks/namespace.d.ts +2 -0
  156. package/dist/src/entities/whatsapp/account.d.ts +20 -0
  157. package/dist/src/entities/whatsapp/chat.d.ts +54 -0
  158. package/dist/src/entities/whatsapp/namespace.d.ts +23 -0
  159. package/dist/src/entities/workspace/items.d.ts +7 -0
  160. package/dist/src/entities/workspace/namespace.d.ts +14 -9
  161. package/dist/src/entities/workspace/query.d.ts +23 -0
  162. package/dist/src/entities/workspace/types.d.ts +6 -3
  163. package/dist/src/events/hydrate/agentSession.d.ts +1 -1
  164. package/dist/src/events/hydrate/call.d.ts +101 -0
  165. package/dist/src/events/hydrate/channel.d.ts +8 -1
  166. package/dist/src/events/hydrate/document.d.ts +1 -1
  167. package/dist/src/events/hydrate/message.d.ts +1 -1
  168. package/dist/src/events/types.d.ts +2 -1
  169. package/dist/src/macro.d.ts +73 -4
  170. package/dist/src/macro.js +8235 -3701
  171. package/dist/src/mentions.d.ts +6 -1
  172. package/dist/src/utils/activity.d.ts +23 -2
  173. package/dist/src/utils/index.d.ts +1 -1
  174. package/dist/src/utils/unwrap.d.ts +27 -2
  175. package/package.json +2 -2
@@ -57,7 +57,7 @@ export declare class MessageThread extends MacroEntity<ThreadState> {
57
57
  readonly parent: MessageParent;
58
58
  /** Serialize identity with its owning resource. */
59
59
  toJSON(): {
60
- parentType: "channel" | "document" | "crm_company" | "crm_contact" | "call";
60
+ parentType: "call" | "channel" | "document" | "crm_company" | "crm_contact";
61
61
  parentId: string;
62
62
  id: string;
63
63
  detail?: ThreadState | undefined;
@@ -4,6 +4,9 @@ import { Notification } from './notification';
4
4
  /** A notification event type name, e.g. `channel_mention`. */
5
5
  export type NotificationType = NotifEvent['tag'];
6
6
  type NotificationTypePreferences = GetNotificationTypePreferencesResponses[200];
7
+ /**
8
+ * @routing Use when reading the user's notifications or marking them seen, such as catching up on what they missed; not sending messages.
9
+ */
7
10
  export declare class NotificationNamespace {
8
11
  private readonly client;
9
12
  constructor(client: MacroClient);
@@ -2,7 +2,11 @@ import type { PinnedItem, ReorderPinRequest } from '../../../generated/storage/t
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import type { FavoritableEntity } from '../entity';
4
4
  export type { PinnedItem, ReorderPinRequest };
5
- /** The user's pins: items pinned to fixed slots in the home view. */
5
+ /**
6
+ * The user's pins: items pinned to fixed slots in the home view.
7
+ *
8
+ * @routing Use when pinning or unpinning items; not favorites (`macro.favorites`).
9
+ */
6
10
  export declare class PinsNamespace {
7
11
  private readonly client;
8
12
  constructor(client: MacroClient);
@@ -1,6 +1,9 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
- import type { SearchOpts } from '../search';
2
+ import type { SearchOpts } from '../search/options';
3
3
  import { Project } from './project';
4
+ /**
5
+ * @routing Use when organizing items into projects (folders); not initiatives, which group tasks.
6
+ */
4
7
  export declare class ProjectNamespace {
5
8
  private readonly client;
6
9
  constructor(client: MacroClient);
@@ -17,6 +17,14 @@ export declare class Project extends PropertiedEntity<ProjectDetail> {
17
17
  /** The properties service identifies projects as `PROJECT`. */
18
18
  protected readonly propertyEntityType = "PROJECT";
19
19
  protected fetch(): Promise<ProjectDetail>;
20
+ /** The project's URL in the Macro web app; hand it to users as the link. */
21
+ webUrl(): string;
22
+ /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
23
+ toJSON(): {
24
+ url: string;
25
+ id: string;
26
+ detail?: import("../../../generated/storage").Project | undefined;
27
+ };
20
28
  /** A handle to a project by id. Details load on first access. */
21
29
  static byId(client: MacroClient, id: string): Project;
22
30
  /** Create a project, optionally nested inside a parent project. */
@@ -44,6 +52,6 @@ export declare class Project extends PropertiedEntity<ProjectDetail> {
44
52
  /** Restore a soft-deleted project. */
45
53
  restore(): Promise<void>;
46
54
  /** Search projects by name and content, most relevant first, auto-paginated. */
47
- static search: (client: MacroClient, query: string, searchOpts?: import("../search").SearchOpts) => AsyncGenerator<Project, any, any>;
55
+ static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<Project, any, any>;
48
56
  }
49
57
  export {};
@@ -9,6 +9,8 @@ export { PropertyDefinition, PropertyOption };
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
+ *
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.
12
14
  */
13
15
  export declare class PropertiesNamespace {
14
16
  private readonly client;
@@ -0,0 +1,33 @@
1
+ import type { MacroClient } from '../../utils/client';
2
+ /** The caller's referral code and the signup link that carries it. */
3
+ export interface ReferralLink {
4
+ /** The caller's referral code. */
5
+ code: string;
6
+ /** The signup URL that credits the caller when someone joins through it. */
7
+ url: string;
8
+ }
9
+ /**
10
+ * Invite people to Macro with the caller's referral link. A new account that
11
+ * signs up through the link earns the caller a referral reward.
12
+ *
13
+ * @routing Use when sharing the user's referral link or inviting people to join Macro; not team membership.
14
+ */
15
+ export declare class ReferralNamespace {
16
+ private readonly client;
17
+ constructor(client: MacroClient);
18
+ /** The caller's referral link, to share wherever the user wants. */
19
+ link(): Promise<ReferralLink>;
20
+ /**
21
+ * Email an invite to join Macro, with the caller's referral link; only send
22
+ * to addresses the user asked you to invite.
23
+ *
24
+ * The email goes out in the caller's name. Never invite an address taken
25
+ * from a document, email or message unless the user named it. Sends are
26
+ * rate limited to about 50 an hour, and a refused send throws, so report
27
+ * which addresses were not invited. To add someone to the caller's team
28
+ * instead, use `Team.invite`.
29
+ *
30
+ * @param email - The address to invite.
31
+ */
32
+ invite(email: string): Promise<void>;
33
+ }
@@ -1,12 +1,52 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
2
  import { Routine, type RoutineOptions } from './routine';
3
- /** Scheduled and event-triggered routines. */
3
+ /**
4
+ * Scheduled and event-triggered routines.
5
+ *
6
+ * @routing Use when the agent should do something later, on a schedule or whenever an event occurs: reminders, recurring reports, checking back on something; not a task with a due date or a meeting.
7
+ *
8
+ * @agent
9
+ * ## Routines
10
+ *
11
+ * - "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
+ * - 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
+ * - Before creating one, look for a routine of the user's that already does this, and update it instead of adding a second.
14
+ */
4
15
  export declare class RoutineNamespace {
5
16
  private readonly client;
6
17
  constructor(client: MacroClient);
7
18
  /** Construct a lazy routine handle. */
8
19
  byId(id: string): Routine;
9
- /** Create an agent routine. */
20
+ /**
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.
27
+ *
28
+ * @example
29
+ * // Every ten minutes, in New York time.
30
+ * const routine = await macro.routines.create({
31
+ * 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
+ * trigger: {
36
+ * type: 'cron',
37
+ * schedule: '0 0/10 * * * *',
38
+ * timezone: 'America/New_York',
39
+ * },
40
+ * });
41
+ * // Once, at 14:30 on 3 November 2027.
42
+ * await macro.routines.create({
43
+ * 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
+ * trigger: { type: 'cron', schedule: '0 30 14 3 11 * 2027', timezone: 'UTC' },
48
+ * });
49
+ */
10
50
  create(options: RoutineOptions): Promise<Routine>;
11
51
  /** List routines, optionally including event triggers. */
12
52
  list(options?: {
@@ -1,4 +1,4 @@
1
- import type { ActionTrigger, EventFilter, RoutineModelId, RoutineTrigger, ScheduledActionResponse } from '../../../generated/scheduled-action/types.gen';
1
+ import type { ActionTrigger, EventFilter, RoutineModelId, RoutineTemplate as RoutineTemplateRecord, RoutineTrigger, RunVisibility, ScheduledActionResponse, TemplateVariable } from '../../../generated/scheduled-action/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import { AgentSession } from '../agent-sessions/agent-session';
4
4
  import type { Agent } from '../agents/agent';
@@ -13,9 +13,16 @@ export type RoutineEventFilter = Omit<EventFilter, 'ids' | 'condition'> & {
13
13
  /** Optional yes/no condition on the triggering content. */
14
14
  condition?: string;
15
15
  };
16
- /** One schedule or set of event selectors. */
16
+ /**
17
+ * One schedule, one exact time, or one set of event selectors. A `once`
18
+ * trigger runs a single time at `at` (RFC 3339), within about a second; a time
19
+ * already past runs as soon as the routine is saved. Use it to check back on
20
+ * something later instead of waiting inside a program.
21
+ */
17
22
  export type SingleRoutineTrigger = Extract<RoutineTrigger, {
18
23
  type: 'cron';
24
+ }> | Extract<RoutineTrigger, {
25
+ type: 'once';
19
26
  }> | {
20
27
  type: 'events';
21
28
  filters: RoutineEventFilter[];
@@ -29,21 +36,44 @@ export type RoutineTriggerOptions = SingleRoutineTrigger | {
29
36
  export interface RoutineOptions {
30
37
  /** Display name. */
31
38
  name: string;
32
- /** Schedules or Macro events that start the routine. */
39
+ /**
40
+ * Schedules or Macro events that start the routine. A cron `schedule` has 6
41
+ * or 7 fields: `sec min hour day-of-month month day-of-week [year]`.
42
+ */
33
43
  trigger: RoutineTriggerOptions;
34
44
  /** Instructions delivered to the agent. */
35
45
  prompt: string;
36
46
  /** Original user instructions. */
37
47
  userPrompt: string;
38
- /** Model override. */
48
+ /**
49
+ * Model to run the task, e.g. `anthropic/claude-sonnet-5-5`, or the model
50
+ * override for `agent`. Set `model`, `agent`, or both.
51
+ */
39
52
  model?: RoutineModelId;
40
- /** Agent to run the task. */
53
+ /**
54
+ * Agent to run the task: a built-in agent, or one the caller owns or can
55
+ * use, including one on a self-hosted runtime. Access is checked on save and
56
+ * again on every run. Set `model`, `agent`, or both.
57
+ */
41
58
  agent?: Agent;
42
59
  /** Whether triggers can start executions. Defaults to true on creation. */
43
60
  enabled?: boolean;
61
+ /**
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.
64
+ */
65
+ runVisibility?: RunVisibility;
44
66
  }
45
67
  /** A scheduled or event-triggered agent task. */
46
68
  export declare class Routine extends MacroEntity<ScheduledActionResponse> {
69
+ /** The routine's URL in the Macro web app; hand it to users as the link. */
70
+ webUrl(): string;
71
+ /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
72
+ toJSON(): {
73
+ url: string;
74
+ id: string;
75
+ detail?: ScheduledActionResponse | undefined;
76
+ };
47
77
  /** Construct a lazy routine handle. */
48
78
  static byId(client: MacroClient, id: string): Routine;
49
79
  /** Seed a handle from a server record. */
@@ -55,12 +85,36 @@ export declare class Routine extends MacroEntity<ScheduledActionResponse> {
55
85
  readonly trigger: () => Promise<ActionTrigger>;
56
86
  /** Whether the routine is enabled. */
57
87
  readonly enabled: () => Promise<boolean>;
88
+ /** Whether the routine's runs appear in Home and the Agents list. */
89
+ readonly runVisibility: () => Promise<RunVisibility>;
58
90
  /** Next scheduled execution. */
59
91
  readonly nextRunAt: () => Promise<string | undefined>;
60
92
  /** Configuration revision. */
61
93
  readonly revision: () => Promise<number>;
62
94
  /** Routine owner. */
63
95
  readonly owner: () => Promise<User>;
96
+ /** The shared routine whose template this routine was activated from. */
97
+ readonly sourceTemplate: () => Promise<Routine | undefined>;
98
+ /** This routine's shared template, or `undefined` when it isn't shared. */
99
+ template(): Promise<RoutineTemplate | undefined>;
100
+ /**
101
+ * Share this routine as a template, or update its shared snapshot. People
102
+ * get the template, never the routine, its runs or its results.
103
+ */
104
+ shareAsTemplate(options: {
105
+ /** What the routine does for someone. */
106
+ description: string;
107
+ /** How each user-specific reference fills in when someone activates it. */
108
+ variables: TemplateVariable[];
109
+ }): Promise<RoutineTemplate>;
110
+ /**
111
+ * Create the caller's own routine from this routine's shared template, with
112
+ * its references already filled in for them.
113
+ */
114
+ activateTemplate(options: RoutineOptions): Promise<Routine>;
115
+ private toTemplate;
116
+ /** Stop sharing this routine. Routines already activated keep running. */
117
+ stopSharingTemplate(): Promise<void>;
64
118
  /** Replace the routine's task and trigger configuration. */
65
119
  update(options: RoutineOptions): Promise<void>;
66
120
  /** Enable or disable triggering. */
@@ -72,6 +126,29 @@ export declare class Routine extends MacroEntity<ScheduledActionResponse> {
72
126
  /** Delete the routine. */
73
127
  delete(): Promise<void>;
74
128
  }
129
+ /** A routine shared as a template, which people activate as their own routine. */
130
+ export declare class RoutineTemplate {
131
+ /** The shared routine. */
132
+ readonly routine: Routine;
133
+ /** Who shared it. */
134
+ readonly author: User;
135
+ /** Template snapshot. */
136
+ readonly record: RoutineTemplateRecord;
137
+ constructor(
138
+ /** The shared routine. */
139
+ routine: Routine,
140
+ /** Who shared it. */
141
+ author: User,
142
+ /** Template snapshot. */
143
+ record: RoutineTemplateRecord);
144
+ /**
145
+ * Create the caller's own routine from this template, with its references
146
+ * already filled in for them.
147
+ */
148
+ activate(options: RoutineOptions): Promise<Routine>;
149
+ /** Serialize without the authenticated client. */
150
+ toJSON(): RoutineTemplateRecord;
151
+ }
75
152
  /** A completed routine execution, as recorded by the service. */
76
153
  export declare class RoutineExecution {
77
154
  /** Parent routine. */
@@ -105,9 +182,11 @@ export declare function routineBody(options: RoutineOptions): {
105
182
  kind: "Agent";
106
183
  name: string;
107
184
  enabled: boolean | undefined;
185
+ run_visibility: RunVisibility | undefined;
108
186
  trigger: ActionTrigger;
109
187
  task: {
110
188
  agent?: null | import("../../../generated/scheduled-action").AgentTaskAgent;
189
+ mcp_servers?: Array<import("../../../generated/scheduled-action").AgentMcpServer>;
111
190
  model?: null | RoutineModelId;
112
191
  prompt: string;
113
192
  user_prompt: string;
@@ -0,0 +1,65 @@
1
+ import type { MacroClient } from '../../utils/client';
2
+ import type { SearchOptions, SearchPage, SearchPageOptions, SearchResult } from './types';
3
+ /**
4
+ * Search the user's Macro content across every kind of item in one call:
5
+ * documents and tasks, email, channels and their messages, projects, call
6
+ * transcripts, calendar events, agent session transcripts, AI chats, and CRM
7
+ * companies when asked for. Results come most relevant first, as typed entity
8
+ * handles, with the same filters as the per-type searches and more: exact
9
+ * matching, tags, one inbox and agent session transcripts.
10
+ *
11
+ * @routing Use when finding or looking up the user's own Macro content by keyword, across types or in one; not browsing recent items (`macro.workspace`), the web, or one item already in context.
12
+ *
13
+ * @agent
14
+ * Search is keyword search, not semantic: pass 1-3 words that would literally appear in the item, not the user's description. Whitespace-separated terms are ANDed; for documents and email each word is a prefix and terms may match different passages, while for other kinds the query is one adjacent phrase prefix, so long phrases match nothing. Quote a multi-word phrase; use matchType 'exact' for a whole word, identifier or email address. Search a person and a topic separately. To find someone's email, search their quoted address, not their name.
15
+ *
16
+ * Use macro.search.all(query) when the request does not name one kind of item, and keep any scope the user gives (types, inbox, tags) on follow-ups and retries. Per-type searches remain for one kind: macro.documents.search returns document handles, macro.email.search email threads, macro.tasks.search tasks. SearchOpts and SearchOptions select searchOn: 'name', 'content', or 'name_content'. These iterators auto-paginate; bound the work explicitly and record when you stop before exhaustion.
17
+ *
18
+ * For activity rather than keywords ("what happened today", "catch me up", my recent or favorite items, tasks updated this week), browse with macro.workspace.page or macro.workspace.list, filtered by type, time, tags or inbox; for a sample of several kinds, fetch one small page per type concurrently. Read an AI chat's messages with macro.chats.byId(id).history(), or chat.history() on a search or workspace result.
19
+ *
20
+ * ```javascript
21
+ * export async function main({macro}) {
22
+ * const queries = ['launch decision', 'release readiness'];
23
+ * const outcomes = await Promise.allSettled(queries.map(async query => {
24
+ * const evidence = [];
25
+ * let stoppedEarly = false;
26
+ * for await (const result of macro.search.all(query, {searchOn:'content'})) {
27
+ * if (evidence.length === 5) { stoppedEarly = true; break; }
28
+ * evidence.push({type:result.type, id:result.entity.id, name:result.hit.name,
29
+ * text: result.type === 'document' ? (await result.entity.content()).slice(0,3000) : undefined});
30
+ * }
31
+ * return {query,evidence,stoppedEarly};
32
+ * }));
33
+ * return {data: outcomes.map((item,index) => item.status === 'fulfilled'
34
+ * ? item.value : {query:queries[index],error:String(item.reason)}), reviews:[]};
35
+ * }
36
+ * ```
37
+ * Preserve useful evidence from each query. A short sample cannot establish corpus-wide completeness or absence. Use precise terms, metadata and relevant reads before expanding breadth. Do not swallow rejected branches. Normal for/while/for-await with break and sequential dependent calls are supported.
38
+ *
39
+ * Skills are documents. When a request names a skill that is not attached, find it by name with macro.documents.search(name, {searchOn:'name'}), read its instructions with content() before doing the task, and follow them for that request only. Built-in system skills (macro.documents.systemSkills()) have no document; read them with the ReadSkill tool.
40
+ *
41
+ * @example Find a contract across email and documents, in one inbox
42
+ * ```js
43
+ * const page = await macro.search.page('"master services agreement"', {
44
+ * types: ['email', 'document'], inbox: 'me@example.com', matchType: 'exact',
45
+ * });
46
+ * return {data: page.results.map(r => ({type: r.type, id: r.entity.id, tags: r.tags})),
47
+ * hasMore: page.hasMore};
48
+ * ```
49
+ */
50
+ export declare class SearchNamespace {
51
+ private readonly client;
52
+ constructor(client: MacroClient);
53
+ /**
54
+ * One bounded page of matches across every kind of item, most relevant
55
+ * first; resume with `nextCursor` and the same options.
56
+ */
57
+ page(query: string, options?: SearchPageOptions): Promise<SearchPage>;
58
+ /**
59
+ * Every match across every kind of item, most relevant first, auto-paginated.
60
+ * Break a `for await` loop to stop; no further page is fetched.
61
+ */
62
+ all(query: string, options?: SearchOptions): AsyncGenerator<SearchResult>;
63
+ private request;
64
+ private fetch;
65
+ }
@@ -1,5 +1,11 @@
1
- import type { EntityFilters, UnifiedSearchResponseItem } from '../../generated/search/types.gen';
2
- import type { MacroClient } from '../utils/client';
1
+ /**
2
+ * Per-type search: the options every entity's own `search()` takes, and the
3
+ * helper that builds one. Cross-type search is `macro.search`.
4
+ *
5
+ * @packageDocumentation
6
+ */
7
+ import type { EntityFilters, UnifiedSearchResponseItem } from '../../../generated/search/types.gen';
8
+ import type { MacroClient } from '../../utils/client';
3
9
  type Hit = UnifiedSearchResponseItem;
4
10
  export type SearchOn = 'name' | 'content' | 'name_content';
5
11
  export interface SearchOpts {
@@ -0,0 +1,90 @@
1
+ import type { CalendarEventSearchScope, UnifiedSearchResponseItem } from '../../../generated/search/types.gen';
2
+ import type { AgentSession } from '../agent-sessions/agent-session';
3
+ import type { CalendarEvent } from '../calendar/event';
4
+ import type { CallRecord } from '../calls/call-record';
5
+ import type { Channel } from '../channels/channel';
6
+ import type { Message } from '../channels/message';
7
+ import type { Chat } from '../chats/chat';
8
+ import type { Company } from '../crm/company';
9
+ import type { Document } from '../documents/document';
10
+ import type { EmailThread } from '../email/thread';
11
+ import type { Project } from '../projects/project';
12
+ import type { TagFilter } from '../workspace/query';
13
+ import type { WorkspaceTag } from '../workspace/types';
14
+ import type { SearchOn } from './options';
15
+ /**
16
+ * The kinds of item one search can reach. `document` includes tasks;
17
+ * `channel` covers channel names and the messages posted in them; `company`
18
+ * is CRM, searched only when named.
19
+ */
20
+ export type SearchType = 'document' | 'email' | 'channel' | 'project' | 'call' | 'calendar_event' | 'agent_session' | 'chat' | 'company';
21
+ /** Options shared by {@link SearchNamespace.page} and {@link SearchNamespace.all}. */
22
+ export type SearchOptions = {
23
+ /**
24
+ * Which kinds of item to search. Omit to search every kind but `company`;
25
+ * set it only when the user scopes the request, and keep that scope on
26
+ * follow-ups and retries.
27
+ */
28
+ types?: SearchType[];
29
+ /** Match names, content or both (the default). Projects and calendar events have only names. */
30
+ searchOn?: SearchOn;
31
+ /**
32
+ * `partial` (the default) matches each word as a prefix, so `scri` matches
33
+ * `script`; `exact` matches whole tokens or a quoted phrase, for an exact
34
+ * word, identifier or email address.
35
+ */
36
+ matchType?: 'partial' | 'exact';
37
+ /**
38
+ * Only items carrying these tags, by case-insensitive label; set `scope`
39
+ * only when the user tells personal and team tags apart. An unknown label
40
+ * fails with the available tags. Only documents, email, projects, calls and
41
+ * calendar events carry tags.
42
+ */
43
+ tags?: TagFilter[];
44
+ /** `any` (the default) or `all` of `tags`; `all` rejects a label both scopes share. */
45
+ tagsMatch?: 'any' | 'all';
46
+ /** Restrict email results to one connected inbox, by its address. Omit for every accessible inbox. */
47
+ inbox?: string;
48
+ /**
49
+ * Search only these agent sessions' transcripts, and nothing else; `types`
50
+ * is then ignored. Pass your own session to find the exact words of
51
+ * something said earlier in it.
52
+ */
53
+ agentSessions?: AgentSession[];
54
+ /**
55
+ * `own` (the default): events on the caller's own and delegated calendars.
56
+ * `shared_with_you`: only events shared to a channel they are in that are
57
+ * on none of their calendars.
58
+ */
59
+ calendarScope?: CalendarEventSearchScope;
60
+ /** Results per request, default 50. Iteration may fetch many pages. */
61
+ pageSize?: number;
62
+ };
63
+ /** Resume a page with its opaque cursor and the same options. */
64
+ export type SearchPageOptions = SearchOptions & {
65
+ cursor?: string;
66
+ };
67
+ type Hit = UnifiedSearchResponseItem;
68
+ type Entry<Kind extends Hit['type'], Type extends string, Entity> = {
69
+ type: Type;
70
+ /** A handle to the matching item, for reads and mutations; nothing is fetched yet. */
71
+ entity: Entity;
72
+ /** The search hit: name, highlights, matching passages and metadata, readable without another request. */
73
+ hit: Extract<Hit, {
74
+ type: Kind;
75
+ }>;
76
+ /** The caller-visible tags on the item. */
77
+ tags: WorkspaceTag[];
78
+ };
79
+ /** One match, discriminated by `type`. */
80
+ export type SearchResult = Entry<'document', 'document', Document> | Entry<'email', 'email', EmailThread> | Entry<'channel', 'channel', Channel> | (Entry<'channelMessage', 'channel_message', Message> & {
81
+ /** The channel the message was posted in. */
82
+ channel: Channel;
83
+ }) | Entry<'project', 'project', Project> | Entry<'call', 'call', CallRecord> | Entry<'calendarEvent', 'calendar_event', CalendarEvent> | Entry<'agentSession', 'agent_session', AgentSession> | Entry<'chat', 'chat', Chat> | Entry<'company', 'company', Company>;
84
+ /** A bounded page. A cursor means more results exist, not an exact total count. */
85
+ export type SearchPage = {
86
+ results: SearchResult[];
87
+ nextCursor?: string | null;
88
+ hasMore: boolean;
89
+ };
90
+ export {};
@@ -22,6 +22,20 @@ export declare class EntityAccess {
22
22
  mine: AccessRequest | undefined;
23
23
  requests: AccessRequest[];
24
24
  }>;
25
+ /**
26
+ * Ask the item's reviewers for more access in the caller's name, as the Share
27
+ * menu's Request access does, superseding the caller's latest request.
28
+ *
29
+ * Agents: call this only when the user asked for it or agreed after being
30
+ * offered it, typically after a write failed with `MacroForbiddenError`
31
+ * because the user can only view the item; never request access on your
32
+ * own. It never grants access: the request stays pending until a reviewer
33
+ * decides. Tell the user it is pending and who reviews it (`state().owner`),
34
+ * do not claim the failed write succeeded, check `state()` later (`mine`
35
+ * holds this request's `status()`), and retry the write only once
36
+ * `state().accessLevel` allows it.
37
+ */
38
+ request(requestedLevel: Exclude<AccessLevel, 'owner'>): Promise<AccessRequest>;
25
39
  /** Request access, optionally naming the revision of an earlier request. */
26
40
  submit(requestedLevel: AccessLevel, revision?: number): Promise<AccessRequest>;
27
41
  /** Cancel the caller's own request at its observed revision. */
@@ -1,21 +1,60 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
+ import type { Initiative } from '../initiatives/initiative';
2
3
  import type { Project } from '../projects/project';
3
- import type { SearchOpts } from '../search';
4
+ import type { SearchOpts } from '../search/options';
4
5
  import type { Team } from '../teams/team';
5
- import { Task } from './task';
6
+ import type { User } from '../users/user';
7
+ import { type SimilarTask, Task, type TaskSummary } from './task';
8
+ /**
9
+ * Tasks: one `create` call sets initiative, assignees and due date; one
10
+ * `summaries` call reads many names (`name()` loads each whole document).
11
+ * Creating a task needs only what the request states; don't research what it
12
+ * describes unless asked.
13
+ *
14
+ * @routing Use when creating, assigning or updating tasks, or reporting on tasks such as open or overdue ones; not reminders, which are routines.
15
+ *
16
+ * @agent
17
+ * Never edit, merge or delete the tasks `findSimilar` matches unless the user asks.
18
+ */
6
19
  export declare class TaskNamespace {
7
20
  private readonly client;
8
21
  constructor(client: MacroClient);
9
22
  /** A handle to a task by document id. Details load on first access. */
10
23
  byId(id: string): Task;
11
- /** Create a task. */
24
+ /**
25
+ * Create a task, with its initiative, assignees and due date in the same
26
+ * request. The task starts Not started.
27
+ */
12
28
  create(opts: {
13
29
  name: string;
14
30
  markdown?: string;
31
+ /** Folder the task document is filed in; unrelated to `initiative`. */
15
32
  project?: Project;
33
+ /** The initiative (shown as the task's Project in the app) it belongs to. */
34
+ initiative?: Initiative;
35
+ /** Assignees; defaults to the creator. Pass `[]` to leave it unassigned. */
36
+ assignees?: User[];
37
+ dueDate?: Date;
38
+ /** Scopes the team task number; may be omitted when the creator belongs to exactly one team. */
16
39
  team?: Team;
40
+ /** Defaults to true. */
17
41
  shareWithTeam?: boolean;
18
42
  }): Promise<Task>;
43
+ /**
44
+ * Names and state of many tasks in one request, in the order given. Tasks
45
+ * that no longer exist are left out.
46
+ */
47
+ summaries(tasks: Task[]): Promise<TaskSummary[]>;
48
+ /**
49
+ * Existing tasks of yours or your team's that look like the same work as a
50
+ * task with this title and body, most similar first. Call it in the same
51
+ * program as `create`: create only when nothing is a likely duplicate, and
52
+ * otherwise return the matches and ask the user instead of creating.
53
+ */
54
+ findSimilar(opts: {
55
+ title: string;
56
+ body?: string;
57
+ }): Promise<SimilarTask[]>;
19
58
  /**
20
59
  * The tasks the GitHub pull request at `url` references, oldest link first.
21
60
  */