@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
@@ -1,27 +1,68 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
2
  import { Document } from '../documents/document';
3
+ import type { Initiative } from '../initiatives/initiative';
3
4
  import type { Project } from '../projects/project';
4
5
  import type { Team } from '../teams/team';
6
+ import { User } from '../users/user';
7
+ /** A task's name and state from one batched read, without its content. */
8
+ export interface TaskSummary {
9
+ task: Task;
10
+ name: string;
11
+ owner: User;
12
+ updatedAt?: string;
13
+ completed: boolean;
14
+ }
15
+ /** An existing task that looks like the same work as a proposed one. */
16
+ export interface SimilarTask {
17
+ /** The existing task. */
18
+ task: Task;
19
+ /** The existing task's name. */
20
+ name: string;
21
+ /** Cosine similarity of the two tasks' embeddings, from 0 to 1. */
22
+ similarity: number;
23
+ }
5
24
  /**
6
- * A Macro task: a document with sub-type `task`. Inherits the full document
7
- * surface ({@link Document.rename}, move, delete, restore, content, events)
25
+ * A Macro task: a document with sub-type `task`, so every `Document` method
26
+ * works on it, including `content` and `edit` for its body. Inherits the full
27
+ * document surface ({@link Document.rename}, move, delete, restore, events)
8
28
  * and adds task-specific state.
9
29
  */
10
30
  export declare class Task extends Document {
11
31
  /** A handle to a task by document id. Details load on first access. */
12
32
  static byId(client: MacroClient, id: string): Task;
13
33
  /**
14
- * Create a task. `team` scopes the team task number and may be omitted
15
- * when the creator belongs to exactly one team; `shareWithTeam` defaults
16
- * to true.
34
+ * Create a task, with its initiative, assignees and due date in the same
35
+ * request. The task starts Not started.
17
36
  */
18
37
  static create(client: MacroClient, opts: {
19
38
  name: string;
20
39
  markdown?: string;
40
+ /** Folder the task document is filed in; unrelated to `initiative`. */
21
41
  project?: Project;
42
+ /** The initiative (shown as the task's Project in the app) it belongs to. */
43
+ initiative?: Initiative;
44
+ /** Assignees; defaults to the creator. Pass `[]` to leave it unassigned. */
45
+ assignees?: User[];
46
+ dueDate?: Date;
47
+ /** Scopes the team task number; may be omitted when the creator belongs to exactly one team. */
22
48
  team?: Team;
49
+ /** Defaults to true. */
23
50
  shareWithTeam?: boolean;
24
51
  }): Promise<Task>;
52
+ /**
53
+ * Names and state of many tasks in one request, in the order given. Tasks
54
+ * that no longer exist are left out.
55
+ */
56
+ static summaries(client: MacroClient, tasks: Task[]): Promise<TaskSummary[]>;
57
+ /**
58
+ * Existing tasks of the caller or their team that look like the same work
59
+ * as a task with this title and body, most similar first. Creates and
60
+ * changes nothing; check it before creating a task.
61
+ */
62
+ static findSimilar(client: MacroClient, opts: {
63
+ title: string;
64
+ body?: string;
65
+ }): Promise<SimilarTask[]>;
25
66
  /**
26
67
  * The tasks the GitHub pull request at `url` references (as `MACRO-<id>` in
27
68
  * its text, branch, or comments), oldest link first. Empty when the caller
@@ -36,5 +77,5 @@ export declare class Task extends Document {
36
77
  /** The task's URL in the Macro web app. */
37
78
  webUrl(): string;
38
79
  /** Search tasks by name and content, most relevant first, auto-paginated. */
39
- static search: (client: MacroClient, query: string, searchOpts?: import("../search").SearchOpts) => AsyncGenerator<Task, any, any>;
80
+ static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<Task, any, any>;
40
81
  }
@@ -0,0 +1,30 @@
1
+ import type { TeamInviteDetails } from '../../../generated/auth/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { MacroEntity } from '../entity';
4
+ import { User } from '../users/user';
5
+ /**
6
+ * A pending invite to the caller's current team. Reading and revoking invites
7
+ * requires a team admin or owner; `Team.invite` sends new ones.
8
+ */
9
+ export declare class TeamInvite extends MacroEntity<TeamInviteDetails> {
10
+ /** A handle to a pending team invite by id. Details load on first access. */
11
+ static byId(client: MacroClient, id: string): TeamInvite;
12
+ /** Build an invite from an already-fetched record (pre-seeded, no fetch). */
13
+ static from(client: MacroClient, record: TeamInviteDetails): TeamInvite;
14
+ protected fetch(): Promise<TeamInviteDetails>;
15
+ /** The invited email address. */
16
+ readonly email: () => Promise<string>;
17
+ /** The role the invitee gets when they join. */
18
+ readonly role: () => Promise<import("../../../generated/auth").TeamRole>;
19
+ /** The member who sent the invite. */
20
+ readonly invitedBy: () => Promise<User>;
21
+ /** When the invite was created, as an ISO 8601 timestamp. */
22
+ readonly createdAt: () => Promise<string>;
23
+ /** When the invite email was last sent, as an ISO 8601 timestamp. */
24
+ readonly lastSentAt: () => Promise<string>;
25
+ /**
26
+ * Revoke this invite so it can no longer be accepted; only a team admin or
27
+ * owner may revoke.
28
+ */
29
+ revoke(): Promise<void>;
30
+ }
@@ -1,5 +1,8 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
2
  import { Team } from './team';
3
+ /**
4
+ * @routing Use when managing teams and membership or inviting people to a team; not inviting people to Macro, which is referrals.
5
+ */
3
6
  export declare class TeamNamespace {
4
7
  private readonly client;
5
8
  constructor(client: MacroClient);
@@ -2,6 +2,7 @@ import type { Team as TeamRecord, TeamRole } from '../../../generated/auth/types
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import { MacroEntity } from '../entity';
4
4
  import { User } from '../users/user';
5
+ import { TeamInvite } from './invite';
5
6
  /** A member of a team: the user and their role. */
6
7
  export interface TeamMembership {
7
8
  /** The member. */
@@ -37,4 +38,40 @@ export declare class Team extends MacroEntity<TeamRecord> {
37
38
  * the caller's current team, so this rejects for any other team.
38
39
  */
39
40
  members(): Promise<TeamMembership[]>;
41
+ /**
42
+ * Invite people to this team by email; only invite addresses the user asked
43
+ * you to invite. Each new address is emailed an invite in the caller's name.
44
+ *
45
+ * Joining gives the invitee access to everything shared with the team, so
46
+ * never invite an address taken from a document, email or message unless
47
+ * the user named it. Addresses that are already members or already invited
48
+ * are skipped, and a repeated address, in any letter case, is sent once.
49
+ * Only the caller's current team takes invites (see `Team.current`): the
50
+ * request names this team, and the API refuses it with a 409, sending
51
+ * nothing, when that is no longer the caller's team. A team that limits
52
+ * inviting to admins rejects other members, and teams without an
53
+ * enterprise plan accept a limited number of invites per day.
54
+ *
55
+ * Pass `{ agent: true }` to invite the addresses as agents. An agent invite
56
+ * to an address with no account creates an agent account when that address
57
+ * signs in: it skips onboarding, gets an SDK token, and joins this team, using
58
+ * a paid seat when the team has a subscription. An existing account keeps its
59
+ * type and accepts like any other invite.
60
+ *
61
+ * @param emails - One address or a list of addresses to invite.
62
+ * @param options - `agent` invites the addresses as agents.
63
+ * @returns `true` when at least one new invite was sent, `false` when every
64
+ * address was already a member or already invited.
65
+ */
66
+ invite(emails: string | readonly string[], options?: {
67
+ agent?: boolean;
68
+ }): Promise<boolean>;
69
+ /**
70
+ * Pending invites to this team; only a team admin or owner may list them.
71
+ * Only the caller's current team lists invites (see `Team.current`); the
72
+ * API refuses any other team with a 409.
73
+ */
74
+ invites(): Promise<TeamInvite[]>;
75
+ /** The caller's current team record, rejecting when this is another team. */
76
+ private requireCurrent;
40
77
  }
@@ -1,5 +1,9 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
- /** URL metadata lookup. */
2
+ /**
3
+ * URL metadata lookup.
4
+ *
5
+ * @routing Use when reading a URL's preview metadata; not fetching or searching the web.
6
+ */
3
7
  export declare class UnfurlNamespace {
4
8
  private readonly client;
5
9
  constructor(client: MacroClient);
@@ -1,5 +1,8 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
2
  import { User } from './user';
3
+ /**
4
+ * @routing Use when looking up people or their profiles; not team membership, or changing the user's own profile (`macro.me`).
5
+ */
3
6
  export declare class UserNamespace {
4
7
  private readonly client;
5
8
  constructor(client: MacroClient);
@@ -7,4 +10,10 @@ export declare class UserNamespace {
7
10
  byId(id: string): User;
8
11
  /** The current authenticated user. */
9
12
  me(): Promise<User>;
13
+ /**
14
+ * Find people in your existing Macro contacts by name or email, as in the
15
+ * mention picker. This is not a global directory. Returns every matching
16
+ * contact so callers can disambiguate; it never chooses a person for you.
17
+ */
18
+ search(query: string): Promise<User[]>;
10
19
  }
@@ -16,6 +16,8 @@ export declare class User extends PropertiedEntity<UserName> implements Mentiona
16
16
  protected fetch(): Promise<UserName>;
17
17
  /** A handle to a user by id. */
18
18
  static byId(client: MacroClient, id: string): User;
19
+ /** A user handle seeded with an already loaded auth-service name. */
20
+ static fromName(client: MacroClient, name: UserName): User;
19
21
  /** A handle to the current authenticated user. */
20
22
  static me(client: MacroClient): Promise<User>;
21
23
  /**
@@ -25,6 +27,12 @@ export declare class User extends PropertiedEntity<UserName> implements Mentiona
25
27
  * @returns The full name, or `undefined` if the user has no name on record.
26
28
  */
27
29
  name(): Promise<string | undefined>;
30
+ /**
31
+ * Whether this user is an agent account rather than a person.
32
+ *
33
+ * @returns `true` for an agent account.
34
+ */
35
+ isAgent(): Promise<boolean>;
28
36
  /**
29
37
  * This user's email address. Macro user ids encode it as `macro|<email>`,
30
38
  * so this reads straight off the id — no auth-service endpoint returns
@@ -0,0 +1,61 @@
1
+ import type { WebFetchResponse, WebSearchResult, WebSearchTopic } from '../../../generated/cognition/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ export type { WebFetchResponse, WebSearchResult, WebSearchTopic };
4
+ /** Filters for {@link WebNamespace.search}. */
5
+ export interface WebSearchOptions {
6
+ /** Only return pages from these domains, e.g. `['docs.rs', 'github.com']`. */
7
+ domains?: string[];
8
+ /** Never return pages from these domains. */
9
+ excludeDomains?: string[];
10
+ /** Only return pages published on or after this date, as `YYYY-MM-DD`. */
11
+ since?: string;
12
+ /** `news` for recent articles with publication dates; `general` (the default) otherwise. */
13
+ topic?: WebSearchTopic;
14
+ /** How many results to return, 1 to 20. Defaults to 5. */
15
+ maxResults?: number;
16
+ /** Also return each page's text as Markdown, up to 8,000 characters per result. */
17
+ includeContent?: boolean;
18
+ }
19
+ /** Options for {@link WebNamespace.fetch}. */
20
+ export interface WebFetchOptions {
21
+ /** Most characters of page text to return, 1 to 100,000. Defaults to 20,000. */
22
+ maxChars?: number;
23
+ }
24
+ /**
25
+ * Search the public web and read web pages, charged to the acting user's AI
26
+ * allowance.
27
+ *
28
+ * @routing Use when finding or reading information on the public internet; not searching the user's Macro workspace (`macro.search`) or reading a URL's preview card (`macro.unfurls`).
29
+ *
30
+ * @agent Search returns snippets, which often answer the question on their
31
+ * own; fetch a result's URL only when you need the whole page. Cite the URL of
32
+ * every page you rely on. Pages behind a login, or rendered only by
33
+ * JavaScript, may fail to fetch with `fetch_failed`.
34
+ */
35
+ export declare class WebNamespace {
36
+ private readonly client;
37
+ constructor(client: MacroClient);
38
+ /**
39
+ * Search the public web; returns title, URL and a query-relevant snippet per
40
+ * page, best match first. Cite the URLs you use.
41
+ *
42
+ * @example
43
+ * const { results } = await macro.web.search('Tokio 1.48 release notes', {
44
+ * domains: ['tokio.rs'],
45
+ * maxResults: 3,
46
+ * });
47
+ * for (const result of results) console.log(result.title, result.url, result.snippet);
48
+ */
49
+ search(query: string, options?: WebSearchOptions): Promise<{
50
+ results: WebSearchResult[];
51
+ }>;
52
+ /**
53
+ * Read one public web page as Markdown, cut to `maxChars` (`truncated` says
54
+ * whether it was). Use it when a search snippet is not enough; cite the URL.
55
+ *
56
+ * @example
57
+ * const page = await macro.web.fetch('https://tokio.rs/blog/2025-10-tokio-1-48');
58
+ * console.log(page.content);
59
+ */
60
+ fetch(url: string, options?: WebFetchOptions): Promise<WebFetchResponse>;
61
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -3,6 +3,8 @@ import type { MacroClient } from '../../utils/client';
3
3
  import { Webhook } from './webhook';
4
4
  /**
5
5
  * Webhook registrations for receiving signed entity-event deliveries.
6
+ *
7
+ * @routing Use when managing API webhook subscriptions; not database webhooks.
6
8
  */
7
9
  export declare class WebhooksNamespace {
8
10
  private readonly client;
@@ -0,0 +1,20 @@
1
+ import type { WhatsAppAccount as WhatsAppAccountRecord } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { MacroEntity } from '../entity';
4
+ import { User } from '../users/user';
5
+ /** The current user's WhatsApp account, connected through the Macro app. */
6
+ export declare class WhatsAppAccount extends MacroEntity<WhatsAppAccountRecord> {
7
+ /** Reference an account; reads still enforce the authenticated owner's scope. */
8
+ static byId(client: MacroClient, id: string): WhatsAppAccount;
9
+ /** Seed an account handle from an API record. */
10
+ static from(client: MacroClient, record: WhatsAppAccountRecord): WhatsAppAccount;
11
+ protected fetch(): Promise<WhatsAppAccountRecord>;
12
+ /** Account connection state; call refresh before polling it again. */
13
+ readonly state: () => Promise<import("../../../generated/storage").WhatsAppAccountState>;
14
+ /** Verified remote identity, absent until pairing succeeds. */
15
+ readonly identity: () => Promise<string | undefined>;
16
+ /** The Macro user who owns this account. */
17
+ readonly owner: () => Promise<User>;
18
+ /** Discard cached connection state and load its current value. */
19
+ refresh(): Promise<this>;
20
+ }
@@ -0,0 +1,54 @@
1
+ import type { ExternalChatCommunity, WhatsAppChat as WhatsAppChatRecord } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { MacroEntity } from '../entity';
4
+ import { ExternalChat } from '../external-chat/chat';
5
+ /** The WhatsApp community a group belongs to. */
6
+ export type WhatsAppCommunity = {
7
+ /** The community itself, as a chat of the list (it can't be added). */
8
+ chat: WhatsAppChat;
9
+ /** The community's name. */
10
+ name: string;
11
+ /** This group is the community's announcement group. */
12
+ announcements: boolean;
13
+ };
14
+ /** A community reference as a handle on the community's own chat. */
15
+ export declare function communityOf(client: MacroClient, record: ExternalChatCommunity): WhatsAppCommunity;
16
+ /** One chat of the current user's WhatsApp chat list: a group or a direct chat. */
17
+ export declare class WhatsAppChat extends MacroEntity<WhatsAppChatRecord> {
18
+ /** Reference a chat by its WhatsApp JID. */
19
+ static byId(client: MacroClient, id: string): WhatsAppChat;
20
+ /** Seed a chat handle from the chat list. */
21
+ static from(client: MacroClient, record: WhatsAppChatRecord): WhatsAppChat;
22
+ protected fetch(): Promise<WhatsAppChatRecord>;
23
+ /** `group` or `direct`. */
24
+ readonly kind: () => Promise<import("../../../generated/storage").ExternalChatKind>;
25
+ /** Group subject (or member names), or the other person's name or number. */
26
+ readonly name: () => Promise<string>;
27
+ /** The other person's phone number (`+<digits>`) of a direct chat, when known. */
28
+ readonly phoneNumber: () => Promise<string | undefined>;
29
+ /** Newest activity WhatsApp reported; unknown for saved contacts never written to. */
30
+ readonly lastActivityAt: () => Promise<string | undefined>;
31
+ /** Archived in WhatsApp. */
32
+ readonly archived: () => Promise<boolean>;
33
+ /** Pinned in WhatsApp. */
34
+ readonly pinned: () => Promise<boolean>;
35
+ /** Whether adding it to Macro works now. */
36
+ readonly canAdd: () => Promise<boolean>;
37
+ /** Why it can't be added (`not_in_group`, `community`, `own_chat`, `not_in_chat_list`), when it is neither added, shared nor addable. */
38
+ readonly cannotAddReason: () => Promise<NonNullable<import("../../../generated/storage").WhatsAppCannotAdd | null | undefined> | undefined>;
39
+ /** The WhatsApp community a group belongs to, if any: the community's own chat, its name, and whether this is its announcement group. */
40
+ readonly community: () => Promise<WhatsAppCommunity | undefined>;
41
+ /** The current user's own external chat for this chat, once added. */
42
+ readonly added: () => Promise<ExternalChat | undefined>;
43
+ /** Someone else's external chat for this chat, shared with the current user. */
44
+ readonly shared: () => Promise<ExternalChat | undefined>;
45
+ /**
46
+ * Add the chat (a group or a direct chat) to Macro as the current user's
47
+ * own external chat; its earlier messages are imported from the phone.
48
+ * Adding it again returns the same chat. Only the owner sends in a direct
49
+ * chat.
50
+ */
51
+ add(): Promise<ExternalChat>;
52
+ /** Reload the chat's list entry. */
53
+ refresh(): Promise<this>;
54
+ }
@@ -0,0 +1,23 @@
1
+ import type { MacroClient } from '../../utils/client';
2
+ import { WhatsAppAccount } from './account';
3
+ import { WhatsAppChat } from './chat';
4
+ /**
5
+ * The current user's WhatsApp account, paired through the Macro app, and its
6
+ * chat list. Added chats are external chats: read and send in them through
7
+ * `macro.externalChats`.
8
+ *
9
+ * @routing Use when checking the user's paired WhatsApp account or listing its chats to add to Macro; not reading or sending in an added chat (`macro.externalChats`).
10
+ */
11
+ export declare class WhatsAppNamespace {
12
+ private readonly client;
13
+ /** Bind existing-account operations to this authenticated client. */
14
+ constructor(client: MacroClient);
15
+ /** Current owner's account, or undefined when no account has been connected. */
16
+ account(): Promise<WhatsAppAccount | undefined>;
17
+ /**
18
+ * The caller's WhatsApp chat list (groups and direct chats), newest
19
+ * activity first: each chat says whether it is added, shared with the caller
20
+ * or addable, and `chat.add()` adds it.
21
+ */
22
+ chats(): Promise<WhatsAppChat[]>;
23
+ }
@@ -3,5 +3,12 @@ import type { MacroClient } from '../../utils/client';
3
3
  import type { WorkspaceItem, WorkspaceTag } from './types';
4
4
  /** @internal */
5
5
  export declare function properties(item: SoupApiItem): SoupProperty[];
6
+ /**
7
+ * The caller-visible labels of an item's tag properties, deduplicated; option
8
+ * ids outside the caller's tag sets are left out.
9
+ *
10
+ * @internal
11
+ */
12
+ export declare function visibleTags(properties: readonly Pick<SoupProperty, 'definition' | 'value'>[], tagMap: Map<string, WorkspaceTag>): WorkspaceTag[];
6
13
  /** @internal */
7
14
  export declare function workspaceItem(client: MacroClient, item: SoupApiItem, tagMap: Map<string, WorkspaceTag>): WorkspaceItem;
@@ -1,10 +1,11 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
2
  import type { WorkspaceItem, WorkspaceListOptions, WorkspacePage, WorkspacePageOptions } from './types';
3
3
  /**
4
- * Browse recent workspace documents (including tasks), chats, projects, email,
5
- * channels, message threads, calls, calendar events and foreign entities.
6
- * Queries run with the caller's normal access permissions. Use search namespaces
7
- * to find specific names/content; use this namespace for activity and filtered lists.
4
+ * Browse recent workspace documents (including tasks), agent sessions, AI chats,
5
+ * projects, email, channels, message threads, calls, calendar events and
6
+ * foreign entities. Queries run with the caller's normal access permissions.
7
+ * Use `macro.search` to find specific names/content; use this namespace for
8
+ * activity and filtered lists.
8
9
  *
9
10
  * Each item has an existing `entity` handle plus a generated API `snapshot` for
10
11
  * reading metadata without another request. Calendar snapshots contain event time
@@ -64,17 +65,21 @@ import type { WorkspaceItem, WorkspaceListOptions, WorkspacePage, WorkspacePageO
64
65
  * `ft`, `id`, `pid`, and `ca`/`ua` timestamp bounds. `ef` supports `Sender`,
65
66
  * `Recipient`, `Read`, `ThreadId`, `ca`/`ua`/`va`; `chanf` supports `ChannelId`,
66
67
  * `Sender`, `IsParticipant`; `cthf` supports `ChannelId`/`ThreadId`; `callf`
67
- * supports `CallId`/`ChannelId`/`Speaker`/`Attended`. Filters remain server-validated.
68
- * CRM, agent sessions, initiatives and database rows have their own namespaces
69
- * and are not included in this browsing surface.
68
+ * supports `CallId`/`ChannelId`/`Speaker`/`Attended`; `asf` supports `id`, `o`
69
+ * (owner principal), `src` and `vis`. Filters remain server-validated.
70
+ * CRM, initiatives and database rows have their own namespaces and are not
71
+ * included in this browsing surface.
72
+ *
73
+ * @routing Use when browsing the user's recent or filtered workspace items, such as what changed today; not keyword search (`macro.search`).
70
74
  */
71
75
  export declare class WorkspaceNamespace {
72
76
  private readonly client;
73
77
  constructor(client: MacroClient);
74
- /** One bounded page. Resume using nextCursor and the same options. */
78
+ /** One bounded page of recent items, newest first by default; resume using nextCursor and the same options. */
75
79
  page(options?: WorkspacePageOptions): Promise<WorkspacePage>;
76
80
  /**
77
- * Lazy automatic pagination. `limit` is a page size, not a total result limit.
81
+ * Every matching item, newest first by default, auto-paginated. `limit` is a
82
+ * page size, not a total result limit.
78
83
  * Break a `for await` loop to stop; no speculative next page is fetched.
79
84
  * Tag/inbox resolution is reused within this iterator.
80
85
  */
@@ -1,6 +1,17 @@
1
+ import type { Link as EmailLink } from '../../../generated/email/types.gen';
1
2
  import type { PostSoupAstRequest } from '../../../generated/storage/types.gen';
2
3
  import type { MacroClient } from '../../utils/client';
3
4
  import type { WorkspaceListOptions, WorkspaceTag } from './types';
5
+ /** A tag label as a filter names it: any scope unless one is given. */
6
+ export type TagFilter = {
7
+ label: string;
8
+ scope?: 'personal' | 'team';
9
+ };
10
+ /** One of the caller's tag options. */
11
+ type ResolvedTag = WorkspaceTag & {
12
+ id: string;
13
+ definitionId: string;
14
+ };
4
15
  /** @internal */
5
16
  export declare class WorkspaceQuery {
6
17
  private readonly client;
@@ -8,5 +19,17 @@ export declare class WorkspaceQuery {
8
19
  constructor(client: MacroClient);
9
20
  private sets;
10
21
  tagMap(): Promise<Map<string, WorkspaceTag>>;
22
+ /**
23
+ * The connected inbox an address names, matched case-insensitively; none for
24
+ * a blank address. An unknown or ambiguous address fails with the choices.
25
+ */
26
+ inbox(address: string | undefined): Promise<EmailLink | undefined>;
27
+ /**
28
+ * The caller's tag options that the labels name, deduplicated. An unknown
29
+ * label fails with the available tags; with `all`, so does a label both
30
+ * scopes share, rather than guessing one.
31
+ */
32
+ tags(filters: TagFilter[] | undefined, match: 'any' | 'all' | undefined): Promise<ResolvedTag[]>;
11
33
  body(options: WorkspaceListOptions): Promise<PostSoupAstRequest>;
12
34
  }
35
+ export {};
@@ -1,4 +1,5 @@
1
1
  import type { ApiEntityFilterAst, SoupApiItem } from '../../../generated/storage/types.gen';
2
+ import type { AgentSession } from '../agent-sessions/agent-session';
2
3
  import type { CalendarEvent } from '../calendar/event';
3
4
  import type { CallRecord } from '../calls/call-record';
4
5
  import type { Channel } from '../channels/channel';
@@ -9,7 +10,7 @@ import type { EmailThread } from '../email/thread';
9
10
  import type { ForeignEntity } from '../foreign/foreign-entity';
10
11
  import type { Project } from '../projects/project';
11
12
  /** Workspace types supported by the browsing API. Tasks are documents. */
12
- export type WorkspaceType = 'calendar_event' | 'document' | 'ai_chat' | 'project' | 'email' | 'channel' | 'channel_thread' | 'call' | 'foreign_entity';
13
+ export type WorkspaceType = 'agent_session' | 'calendar_event' | 'document' | 'ai_chat' | 'project' | 'email' | 'channel' | 'channel_thread' | 'call' | 'foreign_entity';
13
14
  /** A tag label visible to the caller, optionally qualified by ownership scope. */
14
15
  export type WorkspaceTag = {
15
16
  label: string;
@@ -23,7 +24,7 @@ export type WorkspaceTag = {
23
24
  * Each entity filter applies only to that type; `propf` applies across types.
24
25
  * See {@link WorkspaceNamespace} for task and time-window examples.
25
26
  */
26
- export type WorkspaceFilters = Pick<ApiEntityFilterAst, 'df' | 'pf' | 'cf' | 'ef' | 'chanf' | 'cthf' | 'callf' | 'fef' | 'calf' | 'propf'>;
27
+ export type WorkspaceFilters = Pick<ApiEntityFilterAst, 'df' | 'pf' | 'cf' | 'ef' | 'chanf' | 'cthf' | 'callf' | 'fef' | 'calf' | 'asf' | 'propf'>;
27
28
  /** Options shared by bounded pages and automatic iteration. */
28
29
  export type WorkspaceListOptions = WorkspaceFilters & {
29
30
  /** Omitted or empty means all supported types; signal defaults to email when omitted. */
@@ -84,7 +85,9 @@ export type WorkspaceItem = (Entry<'document', 'document', Document> & {
84
85
  createdBy: string;
85
86
  }) | (Entry<'calendarEvent', 'calendar_event', CalendarEvent> & Pick<Extract<SoupApiItem, {
86
87
  tag: 'calendarEvent';
87
- }>['data'], 'title' | 'status' | 'location' | 'conferenceUrl' | 'conferenceProvider' | 'time'>) | (Entry<'foreignEntity', 'foreign_entity', ForeignEntity> & Pick<Extract<SoupApiItem, {
88
+ }>['data'], 'title' | 'status' | 'location' | 'conferenceUrl' | 'conferenceProvider' | 'time'>) | (Entry<'agentSession', 'agent_session', AgentSession> & Pick<Extract<SoupApiItem, {
89
+ tag: 'agentSession';
90
+ }>['data'], 'name' | 'archivedAt' | 'pullRequestUrl' | 'repoUrl'>) | (Entry<'foreignEntity', 'foreign_entity', ForeignEntity> & Pick<Extract<SoupApiItem, {
88
91
  tag: 'foreignEntity';
89
92
  }>['data'], 'foreignEntityId' | 'foreignEntitySource' | 'metadata'>);
90
93
  /** A bounded page. A cursor means more results exist, not an exact total count. */
@@ -189,4 +189,4 @@ export declare function hydrateAgentSessionEvent(client: MacroClient, event: Age
189
189
  owner: User;
190
190
  event_type: "agent_session.deleted";
191
191
  metadata: import("../../../generated/storage").SessionDeletedMetadata;
192
- };
192
+ } | undefined;
@@ -0,0 +1,101 @@
1
+ import { CallRecord } from '../../entities/calls/call-record';
2
+ import { Channel } from '../../entities/channels/channel';
3
+ import { Meeting } from '../../entities/meetings/meeting';
4
+ import { User } from '../../entities/users/user';
5
+ import type { MacroClient } from '../../utils/client';
6
+ import type { MacroEvent } from '../types';
7
+ export type CallEvent = Extract<MacroEvent, {
8
+ event_type: `call.${string}`;
9
+ }>;
10
+ /** Attach call, channel, meeting, and actor handles to call notifications. */
11
+ export declare function hydrateCallEvent(client: MacroClient, event: CallEvent): {
12
+ call: CallRecord;
13
+ channel: Channel | undefined;
14
+ meeting: Meeting | undefined;
15
+ creator: User | undefined;
16
+ user: User | undefined;
17
+ inviter: User | undefined;
18
+ event_type: "call.started";
19
+ metadata: import("../../../generated/storage").CallNotificationMetadata;
20
+ } | {
21
+ call: CallRecord;
22
+ channel: Channel | undefined;
23
+ meeting: Meeting | undefined;
24
+ creator: User | undefined;
25
+ user: User | undefined;
26
+ inviter: User | undefined;
27
+ event_type: "call.ended";
28
+ metadata: import("../../../generated/storage").CallNotificationMetadata;
29
+ } | {
30
+ call: CallRecord;
31
+ channel: Channel | undefined;
32
+ meeting: Meeting | undefined;
33
+ creator: User | undefined;
34
+ user: User | undefined;
35
+ inviter: User | undefined;
36
+ event_type: "call.participant_joined";
37
+ metadata: import("../../../generated/storage").CallNotificationMetadata;
38
+ } | {
39
+ call: CallRecord;
40
+ channel: Channel | undefined;
41
+ meeting: Meeting | undefined;
42
+ creator: User | undefined;
43
+ user: User | undefined;
44
+ inviter: User | undefined;
45
+ event_type: "call.participant_left";
46
+ metadata: import("../../../generated/storage").CallNotificationMetadata;
47
+ } | {
48
+ call: CallRecord;
49
+ channel: Channel | undefined;
50
+ meeting: Meeting | undefined;
51
+ creator: User | undefined;
52
+ user: User | undefined;
53
+ inviter: User | undefined;
54
+ event_type: "call.recording_ready";
55
+ metadata: import("../../../generated/storage").CallNotificationMetadata;
56
+ } | {
57
+ call: CallRecord;
58
+ channel: Channel | undefined;
59
+ meeting: Meeting | undefined;
60
+ creator: User | undefined;
61
+ user: User | undefined;
62
+ inviter: User | undefined;
63
+ event_type: "call.summarized";
64
+ metadata: import("../../../generated/storage").CallNotificationMetadata;
65
+ } | {
66
+ call: CallRecord;
67
+ channel: Channel | undefined;
68
+ meeting: Meeting | undefined;
69
+ creator: User | undefined;
70
+ user: User | undefined;
71
+ inviter: User | undefined;
72
+ event_type: "call.ringing";
73
+ metadata: import("../../../generated/storage").CallNotificationMetadata;
74
+ } | {
75
+ call: CallRecord;
76
+ channel: Channel | undefined;
77
+ meeting: Meeting | undefined;
78
+ creator: User | undefined;
79
+ user: User | undefined;
80
+ inviter: User | undefined;
81
+ event_type: "call.answered";
82
+ metadata: import("../../../generated/storage").CallNotificationMetadata;
83
+ } | {
84
+ call: CallRecord;
85
+ channel: Channel | undefined;
86
+ meeting: Meeting | undefined;
87
+ creator: User | undefined;
88
+ user: User | undefined;
89
+ inviter: User | undefined;
90
+ event_type: "call.declined";
91
+ metadata: import("../../../generated/storage").CallNotificationMetadata;
92
+ } | {
93
+ call: CallRecord;
94
+ channel: Channel | undefined;
95
+ meeting: Meeting | undefined;
96
+ creator: User | undefined;
97
+ user: User | undefined;
98
+ inviter: User | undefined;
99
+ event_type: "call.invited";
100
+ metadata: import("../../../generated/storage").CallNotificationMetadata;
101
+ } | undefined;