@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
@@ -0,0 +1,105 @@
1
+ import type { ExternalChatDetail, UpdateSharePermissionRequestV2 } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { FavoritableEntity } from '../entity';
4
+ import { User } from '../users/user';
5
+ import { type WhatsAppCommunity } from '../whatsapp/chat';
6
+ import { ExternalChatMessage } from './message';
7
+ import { ExternalChatParticipant } from './participant';
8
+ import { ExternalChatSend } from './send';
9
+ import { ExternalChatUpload } from './upload';
10
+ /** Deliberate content sent from the credential owner's own provider account. */
11
+ export type ExternalChatContent = {
12
+ type: 'text';
13
+ text: string;
14
+ /** Participants mentioned (from `participants()`); the text names each as `@<mentionToken>`. */
15
+ mentions?: ExternalChatParticipant[];
16
+ } | {
17
+ type: 'media';
18
+ upload: ExternalChatUpload;
19
+ caption?: string;
20
+ } | {
21
+ type: 'mutation';
22
+ message: ExternalChatMessage;
23
+ operation: 'reaction' | 'edit' | 'delete';
24
+ text?: string;
25
+ };
26
+ /**
27
+ * A chat from an external messaging provider (WhatsApp today), added to Macro
28
+ * by its owner and shareable like any other entity: a group or a direct chat.
29
+ */
30
+ export declare class ExternalChat extends FavoritableEntity<ExternalChatDetail> {
31
+ /** Canonical sharing and favorites kind. */
32
+ readonly entityType: "external_chat";
33
+ /** Reference an added chat; access is checked on each request. */
34
+ static byId(client: MacroClient, id: string): ExternalChat;
35
+ protected fetch(): Promise<ExternalChatDetail>;
36
+ /** The messaging provider the chat lives in, such as `whatsapp`. */
37
+ readonly provider: () => Promise<"whatsapp">;
38
+ /** Display name: the group's, or a direct chat's other person. */
39
+ readonly name: () => Promise<string>;
40
+ /** `group`, or `direct` for a one-to-one chat (only its owner sends). */
41
+ readonly kind: () => Promise<import("../../../generated/storage").ExternalChatKind>;
42
+ /** Whether the caller can send from their own connected account. */
43
+ readonly canSend: () => Promise<boolean>;
44
+ /** Reason sending is blocked. */
45
+ readonly sendReason: () => Promise<NonNullable<import("../../../generated/storage").ExternalChatReplyBlock | null | undefined> | undefined>;
46
+ /** Caller's own verified sending identity. */
47
+ readonly sendingIdentity: () => Promise<string | undefined>;
48
+ /** Per-user unread count. */
49
+ readonly unreadCount: () => Promise<number>;
50
+ /** Importing earlier messages from the owner's phone after adding, if any. */
51
+ readonly backfill: () => Promise<import("../../../generated/storage").ExternalChatBackfill | undefined>;
52
+ /** Supported sizes and mutation window. */
53
+ readonly limits: () => Promise<import("../../../generated/storage").ExternalChatCapabilities>;
54
+ /** Current remote members (name, participants, announce), when known. */
55
+ readonly members: () => Promise<import("../../../generated/storage").ExternalChatMembers | undefined>;
56
+ /** Everyone in the chat, from its members; empty when none are known. */
57
+ readonly participants: () => Promise<ExternalChatParticipant[]>;
58
+ /** The provider's disappearing-messages timer in seconds while on; Macro keeps the messages. */
59
+ readonly disappearingSeconds: () => Promise<number | undefined>;
60
+ /** Actual owner, independent of provider membership. */
61
+ readonly owner: () => Promise<User>;
62
+ /** The community a group belongs to, if any: the community's own provider chat, its name, and whether this is its announcement group. */
63
+ community(): Promise<WhatsAppCommunity | undefined>;
64
+ /** Iterate newest-first timeline pages lazily. */
65
+ messages(options?: {
66
+ limit?: number;
67
+ }): AsyncGenerator<ExternalChatMessage>;
68
+ /** Advance the caller's own read cursor. */
69
+ markRead(message: ExternalChatMessage): Promise<void>;
70
+ /** Read standard link/team sharing settings. */
71
+ permissions(): Promise<import("../../../generated/storage").SharePermissionV2>;
72
+ /** Actual owner updates standard link/team sharing settings. */
73
+ updatePermissions(update: UpdateSharePermissionRequestV2): Promise<void>;
74
+ /** Owner stops syncing the chat; history and established sharing stay. */
75
+ remove(): Promise<void>;
76
+ /** Stage a supported attachment for a deliberate send. */
77
+ upload(file: Blob | File): Promise<ExternalChatUpload>;
78
+ /** Personal sessions and owner API credentials can send. Bots never send.
79
+ * Preserve the idempotency key; uncertain outcomes are never automatically resent.
80
+ * The server enforces one request per second per user.
81
+ */
82
+ send(content: ExternalChatContent, options: {
83
+ idempotencyKey: string;
84
+ replyTo?: ExternalChatMessage;
85
+ }): Promise<ExternalChatSend>;
86
+ /** Read only the caller's pending, uncertain or failed sends. */
87
+ sends(): Promise<ExternalChatSend[]>;
88
+ /** Read delivery for selected caller-owned intents or messages. */
89
+ delivery(sends: Array<ExternalChatSend | ExternalChatMessage>): Promise<ExternalChatSend[]>;
90
+ /** Read attachment states for selected messages. */
91
+ messageAttachments(messages: ExternalChatMessage[]): Promise<{
92
+ message: ExternalChatMessage;
93
+ attachments: {
94
+ ordinal: number;
95
+ state: import("../../../generated/storage").ExternalChatAttachmentState;
96
+ fileName: string;
97
+ mime: string;
98
+ size: number;
99
+ url: string | undefined;
100
+ }[];
101
+ }[]>;
102
+ /** Reload detail, permissions and caller capabilities. */
103
+ refresh(): Promise<this>;
104
+ private assertChat;
105
+ }
@@ -0,0 +1,54 @@
1
+ import type { ExternalChatMessage as ExternalChatMessageRecord } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { MacroEntity } from '../entity';
4
+ import type { ExternalChat } from './chat';
5
+ /** Message in an added external chat. */
6
+ export declare class ExternalChatMessage extends MacroEntity<ExternalChatMessageRecord> {
7
+ /** The chat this message is in. */
8
+ readonly chat: ExternalChat;
9
+ private constructor();
10
+ /** Reference a message within its original chat. */
11
+ static byId(client: MacroClient, chat: ExternalChat, id: string): ExternalChatMessage;
12
+ /** Seed a message handle from a timeline response. */
13
+ static from(client: MacroClient, chat: ExternalChat, record: ExternalChatMessageRecord): ExternalChatMessage;
14
+ protected fetch(): Promise<ExternalChatMessageRecord>;
15
+ /** Plain message text. */
16
+ readonly body: () => Promise<string>;
17
+ /** Protocol-verified sender association and display name. */
18
+ readonly sender: () => Promise<import("../../../generated/storage").ExternalChatSender>;
19
+ /** Provider timestamp. */
20
+ readonly sentAt: () => Promise<string>;
21
+ /** Last edit time. */
22
+ readonly editedAt: () => Promise<string | undefined>;
23
+ /** Deleted for everyone. */
24
+ readonly deleted: () => Promise<boolean>;
25
+ /** Grouped emoji counts and caller's own reaction. */
26
+ readonly reactions: () => Promise<import("../../../generated/storage").ExternalChatReaction[]>;
27
+ /** Caller-owned send's delivery state, when present. */
28
+ readonly deliveryState: () => Promise<NonNullable<import("../../../generated/storage").ExternalChatDeliveryState | null | undefined> | undefined>;
29
+ /** `message`, or `system` for something that happened in the chat (see `rich`). */
30
+ readonly kind: () => Promise<import("../../../generated/storage").ExternalChatMessageKind>;
31
+ /** Forwarded from another chat. */
32
+ readonly forwarded: () => Promise<boolean>;
33
+ /** Sent as view-once in the provider; Macro keeps and shows it like any media. */
34
+ readonly viewOnce: () => Promise<boolean>;
35
+ /** People the body @-mentions: `@<token>` in the body is this person. */
36
+ readonly mentions: () => Promise<import("../../../generated/storage").ExternalChatMention[]>;
37
+ /** Poll (with tallies), location, contact cards, event or system line. */
38
+ readonly rich: () => Promise<NonNullable<import("../../../generated/storage").ExternalChatRichContent | null | undefined> | undefined>;
39
+ /** Quoted message in this chat. */
40
+ readonly replyTo: () => Promise<ExternalChatMessage | undefined>;
41
+ /** Attachment states, with the stored file's URL once ready. */
42
+ readonly attachments: () => Promise<{
43
+ ordinal: number;
44
+ state: import("../../../generated/storage").ExternalChatAttachmentState;
45
+ fileName: string;
46
+ mime: string;
47
+ size: number;
48
+ width: number | undefined;
49
+ height: number | undefined;
50
+ durationSeconds: number | undefined;
51
+ presentation: import("../../../generated/storage").ExternalChatMediaPresentation | undefined;
52
+ url: string | undefined;
53
+ }[]>;
54
+ }
@@ -0,0 +1,18 @@
1
+ import type { MacroClient } from '../../utils/client';
2
+ import { ExternalChat } from './chat';
3
+ /**
4
+ * Chats from external messaging providers (WhatsApp today) that someone added
5
+ * to Macro: read, share and send in them. Find and add a provider's chats
6
+ * through its own namespace, such as `macro.whatsapp.chats()`.
7
+ *
8
+ * @routing Use when reading, sharing or sending in an external chat, such as a WhatsApp chat, already added to Macro; not Macro channels, or finding chats to add (`macro.whatsapp`).
9
+ */
10
+ export declare class ExternalChatsNamespace {
11
+ private readonly client;
12
+ /** Bind external chat operations to this authenticated client. */
13
+ constructor(client: MacroClient);
14
+ /** Added chats the caller can view, including without a provider account of their own. */
15
+ list(): Promise<ExternalChat[]>;
16
+ /** Reference an added chat without fetching it. */
17
+ byId(id: string): ExternalChat;
18
+ }
@@ -0,0 +1,28 @@
1
+ import type { ExternalChatParticipant as ExternalChatParticipantRecord } from '../../../generated/storage/types.gen';
2
+ import type { ExternalChat } from './chat';
3
+ /** Someone in an added external chat, from its members; mention them in a text reply. */
4
+ export declare class ExternalChatParticipant {
5
+ /** The chat whose members list them. */
6
+ readonly chat: ExternalChat;
7
+ /** Their provider id (a WhatsApp JID): correlation data, not a Macro user. */
8
+ readonly id: string;
9
+ private readonly record?;
10
+ private constructor();
11
+ /** Reference a participant of a chat by provider id. */
12
+ static byId(chat: ExternalChat, id: string): ExternalChatParticipant;
13
+ /** Seed a participant from the chat's members. */
14
+ static from(chat: ExternalChat, record: ExternalChatParticipantRecord): ExternalChatParticipant;
15
+ /** Their provider display name, untrusted, when known. */
16
+ get displayName(): string | undefined;
17
+ /** The digits a text reply writes as `@<digits>` to mention them. */
18
+ get mentionToken(): string;
19
+ /** Whether they administer the group, when read from its members. */
20
+ get admin(): boolean | undefined;
21
+ /** Serialize the participant reference without credentials. */
22
+ toJSON(): {
23
+ id: string;
24
+ chat: string;
25
+ displayName: string | undefined;
26
+ admin: boolean | undefined;
27
+ };
28
+ }
@@ -0,0 +1,32 @@
1
+ import type { ExternalChatSendProgress } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { MacroEntity } from '../entity';
4
+ import type { ExternalChat, ExternalChatContent } from './chat';
5
+ import { ExternalChatMessage } from './message';
6
+ /** One deliberate send intent. Unknown outcomes must never be automatically resent. */
7
+ export declare class ExternalChatSend extends MacroEntity<ExternalChatSendProgress> {
8
+ /** The chat containing this send. */
9
+ readonly chat: ExternalChat;
10
+ private constructor();
11
+ /** Reference a send intent within its original chat. */
12
+ static byId(client: MacroClient, chat: ExternalChat, id: string): ExternalChatSend;
13
+ /** Seed a send handle from a server response. */
14
+ static from(client: MacroClient, chat: ExternalChat, record: ExternalChatSendProgress): ExternalChatSend;
15
+ protected fetch(): Promise<ExternalChatSendProgress>;
16
+ /** Last observed delivery state; refresh explicitly to poll again. */
17
+ readonly state: () => Promise<import("../../../generated/storage").ExternalChatDeliveryState>;
18
+ /** Sanitized failure code, when present. */
19
+ readonly errorCode: () => Promise<string | undefined>;
20
+ /** When the send intent was created. */
21
+ readonly createdAt: () => Promise<string>;
22
+ /** Chat message once the provider accepted the send. */
23
+ readonly message: () => Promise<ExternalChatMessage | undefined>;
24
+ /** Inspect the original intent for reconciliation; never resubmit an unknown outcome automatically. */
25
+ request(): Promise<{
26
+ idempotencyKey: string;
27
+ message: ExternalChatContent;
28
+ replyTo?: ExternalChatMessage;
29
+ }>;
30
+ /** Fetch current delivery state without retrying or submitting the message. */
31
+ refresh(): Promise<this>;
32
+ }
@@ -0,0 +1,25 @@
1
+ import type { ExternalChatUploadedAttachment } from '../../../generated/storage/types.gen';
2
+ import type { ExternalChat } from './chat';
3
+ /** A staged attachment scoped to one added chat; use it in a deliberate media send. */
4
+ export declare class ExternalChatUpload {
5
+ /** Correlation identity of the staged upload. */
6
+ readonly id: string;
7
+ /** The chat this upload can be sent to. */
8
+ readonly chat: ExternalChat;
9
+ /** Display filename supplied by the server. */
10
+ readonly filename?: string | undefined;
11
+ /** Media category supplied by the server. */
12
+ readonly kind?: ExternalChatUploadedAttachment["kind"] | undefined;
13
+ private constructor();
14
+ /** Reference a previously staged upload in its original chat. */
15
+ static byId(chat: ExternalChat, id: string): ExternalChatUpload;
16
+ /** Seed a handle from the server's upload receipt. */
17
+ static from(chat: ExternalChat, record: ExternalChatUploadedAttachment): ExternalChatUpload;
18
+ /** Serialize the upload reference without credentials. */
19
+ toJSON(): {
20
+ id: string;
21
+ chat: string;
22
+ filename: string | undefined;
23
+ kind: import("../../../generated/storage").ExternalChatMediaKind | undefined;
24
+ };
25
+ }
@@ -14,7 +14,11 @@ export type FavoritesFilter = {
14
14
  entityTypes?: MacroEntityType[];
15
15
  entityIds?: string[];
16
16
  };
17
- /** The user's favorites: a manually ordered collection of entity references. */
17
+ /**
18
+ * The user's favorites: a manually ordered collection of entity references.
19
+ *
20
+ * @routing Use when adding or removing the user's favorites; not pins (`macro.pins`).
21
+ */
18
22
  export declare class FavoritesNamespace {
19
23
  private readonly client;
20
24
  constructor(client: MacroClient);
@@ -26,6 +26,9 @@ export interface GithubPullRequestFacets {
26
26
  /** Labels, most pull requests first. */
27
27
  labels: GithubLabelFacet[];
28
28
  }
29
+ /**
30
+ * @routing Use when resolving a linked external entity, such as an imported item; not Macro's own items.
31
+ */
29
32
  export declare class ForeignEntityNamespace {
30
33
  private readonly client;
31
34
  constructor(client: MacroClient);
@@ -118,8 +118,17 @@ export type FormSubmissionOutcome = {
118
118
  section: FormSection;
119
119
  message: string;
120
120
  };
121
- /** The caller's receipt and current answers, read without access to other responses. */
122
- export type MyFormResponse = {
121
+ /**
122
+ * The caller's receipt and current answers, read without access to other
123
+ * responses. On an anonymous form the caller only learns that they
124
+ * responded: nothing links them to their response.
125
+ */
126
+ export type MyFormResponse = SavedFormResponse | {
127
+ kind: 'anonymous';
128
+ };
129
+ /** The caller's saved response to a form that isn't anonymous. */
130
+ export type SavedFormResponse = {
131
+ kind: 'saved';
123
132
  booking?: FormBookingStep;
124
133
  response: FormResponse;
125
134
  status: ResponseStatus;
@@ -222,6 +231,12 @@ export declare class Form extends MacroEntity<FormDetail> {
222
231
  updateSharePermissions(request: UpdateSharePermissionRequestV2): Promise<SharePermissionV2>;
223
232
  /** Open the form's builder in Macro. */
224
233
  webUrl(): string;
234
+ /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
235
+ toJSON(): {
236
+ url: string;
237
+ id: string;
238
+ detail?: FormDetail | undefined;
239
+ };
225
240
  /** The respondent page, which public forms also expose without signing in. */
226
241
  respondUrl(): string;
227
242
  }
@@ -2,7 +2,11 @@ import type { MacroClient } from '../../utils/client';
2
2
  import type { Database } from '../databases/database';
3
3
  import type { DatabaseTable } from '../databases/table';
4
4
  import { Form } from './form';
5
- /** Forms collect answers into a database table without granting respondents table access. */
5
+ /**
6
+ * Forms collect answers into a database table without granting respondents table access.
7
+ *
8
+ * @routing Use when building a form, poll or survey, or reading its responses; not database tables.
9
+ */
6
10
  export declare class FormNamespace {
7
11
  private readonly client;
8
12
  constructor(client: MacroClient);
@@ -1,7 +1,11 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
2
  import type { ForeignEntity } from '../foreign/foreign-entity';
3
3
  import { GithubPullRequest } from './pull-request';
4
- /** GitHub pull request snapshots and captured diffs. */
4
+ /**
5
+ * GitHub pull request snapshots and captured diffs.
6
+ *
7
+ * @routing Use when reading a GitHub pull request's stored snapshot or diff; not changing code, which a coding agent does.
8
+ */
5
9
  export declare class GithubPullRequestNamespace {
6
10
  private readonly client;
7
11
  constructor(client: MacroClient);
@@ -14,6 +14,15 @@ export declare class Harness extends MacroEntity<HarnessRecord> {
14
14
  readonly connected: () => Promise<boolean>;
15
15
  /** Runtime kind. */
16
16
  readonly kind: () => Promise<string>;
17
+ /** Whether agents here may bypass permission prompts. */
18
+ readonly allowPermissionBypass: () => Promise<NonNullable<boolean | undefined> | undefined>;
19
+ /**
20
+ * Allow or forbid agents here to bypass permission prompts. Live sessions
21
+ * pick the change up at their next turn.
22
+ */
23
+ setPermissionBypass(allowed: boolean): Promise<void>;
24
+ /** Rename the host. */
25
+ rename(name: string): Promise<void>;
17
26
  /** Remove the host. */
18
27
  delete(): Promise<void>;
19
28
  }
@@ -4,7 +4,11 @@ import { AgentSession } from '../agent-sessions/agent-session';
4
4
  import { Agent } from '../agents/agent';
5
5
  import { Harness } from './harness';
6
6
  import { DevicePairing, HarnessPairing } from './pairing';
7
- /** Hosts and device pairing. Self operations require host credentials. */
7
+ /**
8
+ * Hosts and device pairing. Self operations require host credentials.
9
+ *
10
+ * @routing Use when listing, pairing or removing the machines (hosts) that run the user's agents; not changing an agent persona's setup (`macro.agents`).
11
+ */
8
12
  export declare class HarnessNamespace {
9
13
  private readonly client;
10
14
  constructor(client: MacroClient);
@@ -0,0 +1,77 @@
1
+ import type { MacroClient } from '../../utils/client';
2
+ /**
3
+ * An image in static file storage: an upload, or one made with
4
+ * `macro.images.generate()`. Attach it to a channel message with
5
+ * `channel.send(text, { images: [image] })`, or pass it back to `generate` as
6
+ * a reference.
7
+ */
8
+ export declare class StaticImage {
9
+ /** Static file id. */
10
+ readonly id: string;
11
+ /** Permanent URL of the image bytes. */
12
+ readonly url: string;
13
+ /** Intrinsic pixel width, when known; lets messages reserve space. */
14
+ readonly width?: number | undefined;
15
+ /** Intrinsic pixel height, when known. */
16
+ readonly height?: number | undefined;
17
+ protected constructor(
18
+ /** Static file id. */
19
+ id: string,
20
+ /** Permanent URL of the image bytes. */
21
+ url: string,
22
+ /** Intrinsic pixel width, when known; lets messages reserve space. */
23
+ width?: number | undefined,
24
+ /** Intrinsic pixel height, when known. */
25
+ height?: number | undefined);
26
+ /**
27
+ * A handle to an image already in static file storage. Pass `width` and
28
+ * `height` when you know them, so a message reserves the image's space
29
+ * before it loads.
30
+ */
31
+ static byId(client: MacroClient, id: string, size?: {
32
+ width: number;
33
+ height: number;
34
+ }): StaticImage;
35
+ /** Serialize the image reference without its client. */
36
+ toJSON(): {
37
+ id: string;
38
+ url: string;
39
+ width: number | undefined;
40
+ height: number | undefined;
41
+ };
42
+ }
43
+ /** An image made by `macro.images.generate()`, stored as a static file. */
44
+ export declare class GeneratedImage extends StaticImage {
45
+ /** Intrinsic pixel width. */
46
+ readonly width: number;
47
+ /** Intrinsic pixel height. */
48
+ readonly height: number;
49
+ /** IANA media type, e.g. `image/png`. */
50
+ readonly mimeType: string;
51
+ /** Size of the image in bytes. */
52
+ readonly sizeBytes: number;
53
+ /** Commentary the model returned alongside the image, if any. */
54
+ readonly note?: string | undefined;
55
+ /** @internal Built from the generation response. */
56
+ constructor(id: string, url: string,
57
+ /** Intrinsic pixel width. */
58
+ width: number,
59
+ /** Intrinsic pixel height. */
60
+ height: number,
61
+ /** IANA media type, e.g. `image/png`. */
62
+ mimeType: string,
63
+ /** Size of the image in bytes. */
64
+ sizeBytes: number,
65
+ /** Commentary the model returned alongside the image, if any. */
66
+ note?: string | undefined);
67
+ /** Serialize the generated image without its client. */
68
+ toJSON(): {
69
+ mimeType: string;
70
+ sizeBytes: number;
71
+ note: string | undefined;
72
+ id: string;
73
+ url: string;
74
+ width: number | undefined;
75
+ height: number | undefined;
76
+ };
77
+ }
@@ -0,0 +1,48 @@
1
+ import type { GenerateImageAspectRatio } from '../../../generated/cognition/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { Document } from '../documents/document';
4
+ import { GeneratedImage, type StaticImage } from './image';
5
+ export type { GenerateImageAspectRatio };
6
+ /** What image to generate. */
7
+ export interface GenerateImageOptions {
8
+ /**
9
+ * Description of the image: subject, style (photo, illustration, flat
10
+ * vector...), composition, colours, mood, and any text that must appear.
11
+ */
12
+ prompt: string;
13
+ /**
14
+ * Shape of the image: `square` (1:1, the default), `landscape` (4:3),
15
+ * `portrait` (3:4), `widescreen` (16:9, banners and slides) or `tall`
16
+ * (9:16, phone screens and stories).
17
+ */
18
+ aspectRatio?: GenerateImageAspectRatio;
19
+ /**
20
+ * Up to three images to edit or draw from, in the order the prompt refers
21
+ * to them ("image 1", "image 2"): image documents the caller can view, or
22
+ * static images such as an earlier generation or an attachment.
23
+ */
24
+ referenceImages?: (Document | StaticImage)[];
25
+ }
26
+ /**
27
+ * Image generation, charged to the acting user's AI allowance.
28
+ *
29
+ * @routing Use when generating an image; not structured output or classification (`macro.ai`).
30
+ */
31
+ export declare class ImagesNamespace {
32
+ private readonly client;
33
+ constructor(client: MacroClient);
34
+ /**
35
+ * Generate or edit an image with Google's Nano Banana model and store it as
36
+ * a static file. Takes several seconds. Post it with
37
+ * `channel.send(text, { images: [image] })`; the returned width and height
38
+ * let the message reserve space before the image loads.
39
+ *
40
+ * @example
41
+ * const image = await macro.images.generate({
42
+ * prompt: 'A watercolor lighthouse at dusk',
43
+ * aspectRatio: 'widescreen',
44
+ * });
45
+ * await channel.send('Fresh off the press', { images: [image] });
46
+ */
47
+ generate(options: GenerateImageOptions): Promise<GeneratedImage>;
48
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -22,6 +22,14 @@ export interface InitiativeOptions {
22
22
  export declare class Initiative extends MacroEntity<InitiativeDetail> {
23
23
  /** Access requests and direct user grants. */
24
24
  readonly access: EntityAccess;
25
+ /** The initiative's URL in the Macro web app; hand it to users as the link. */
26
+ webUrl(): string;
27
+ /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
28
+ toJSON(): {
29
+ url: string;
30
+ id: string;
31
+ detail?: InitiativeDetail | undefined;
32
+ };
25
33
  /** Construct a lazy initiative handle. */
26
34
  static byId(client: MacroClient, id: string): Initiative;
27
35
  /** Seed from an initiative detail response. */
@@ -33,7 +41,10 @@ export declare class Initiative extends MacroEntity<InitiativeDetail> {
33
41
  readonly owner: () => Promise<User>;
34
42
  /** Assigned members. */
35
43
  readonly members: () => Promise<User[]>;
36
- /** Tasks in this initiative. */
44
+ /**
45
+ * Tasks in this initiative. For their names, pass them to
46
+ * `macro.tasks.summaries` (one request) instead of calling `name()` on each.
47
+ */
37
48
  readonly tasks: () => Promise<Task[]>;
38
49
  /** Current user's access. */
39
50
  readonly accessLevel: () => Promise<import("../../../generated/storage").AccessLevel>;
@@ -1,13 +1,26 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
2
  import { Initiative, type InitiativeOptions } from './initiative';
3
- /** Initiatives in the caller's workspace. */
3
+ /** An initiative with the name and update time its listing already carries. */
4
+ export interface InitiativeSummary {
5
+ initiative: Initiative;
6
+ name: string;
7
+ updatedAt: string;
8
+ }
9
+ /**
10
+ * Initiatives in the caller's workspace; find one by name with one
11
+ * `summaries()` call, not `name()` on each listed handle (one request each).
12
+ *
13
+ * @routing Use when grouping tasks and members into initiatives or reading an initiative's tasks; not a single task.
14
+ */
4
15
  export declare class InitiativeNamespace {
5
16
  private readonly client;
6
17
  constructor(client: MacroClient);
7
18
  /** Construct a lazy initiative handle. */
8
19
  byId(id: string): Initiative;
9
- /** List accessible initiatives. */
20
+ /** List accessible initiatives as handles; use `summaries()` for their names. */
10
21
  list(): Promise<Initiative[]>;
22
+ /** Every accessible initiative with its name, in one request. */
23
+ summaries(): Promise<InitiativeSummary[]>;
11
24
  /** Create an initiative. */
12
25
  create(options: InitiativeOptions): Promise<Initiative>;
13
26
  }
@@ -0,0 +1,43 @@
1
+ import type { MacroClient } from '../../utils/client';
2
+ import { StaticImage } from '../images/image';
3
+ /** How to store an uploaded profile picture. */
4
+ export interface UploadProfilePictureOptions {
5
+ /** File name, such as `avatar.png`. */
6
+ fileName: string;
7
+ /** `image/png`, `image/jpeg`, `image/webp` or `image/gif`. */
8
+ contentType: string;
9
+ }
10
+ /** What to change on the authenticated user's profile. */
11
+ export interface UpdateMeOptions {
12
+ /** Display name. The first word becomes the first name. */
13
+ name?: string;
14
+ /** An image from {@link MeNamespace.uploadProfilePicture}. */
15
+ profilePicture?: StaticImage;
16
+ }
17
+ /**
18
+ * The authenticated user's own profile.
19
+ *
20
+ * @routing Use when changing the user's own name or profile picture; not looking up other people (`macro.users`).
21
+ */
22
+ export declare class MeNamespace {
23
+ private readonly client;
24
+ constructor(client: MacroClient);
25
+ /**
26
+ * Upload an image to use as your profile picture. This only stores it; pass
27
+ * the result to {@link MeNamespace.update} to start using it. Pictures can be
28
+ * at most 16 MB, and each user can start 20 uploads an hour.
29
+ */
30
+ uploadProfilePicture(data: Blob | Uint8Array<ArrayBuffer>, options: UploadProfilePictureOptions): Promise<StaticImage>;
31
+ /**
32
+ * Set your display name and profile picture. Agents should do this after
33
+ * signing in, so teammates can tell who they are working with.
34
+ *
35
+ * @example
36
+ * const image = await macro.me.uploadProfilePicture(bytes, {
37
+ * fileName: 'avatar.png',
38
+ * contentType: 'image/png',
39
+ * });
40
+ * await macro.me.update({ name: 'Research Agent', profilePicture: image });
41
+ */
42
+ update(options: UpdateMeOptions): Promise<void>;
43
+ }
@@ -1,11 +1,16 @@
1
1
  import type { Meeting as MeetingRecord, UpdateMeetingRequest } from '../../../generated/storage/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import { CallRecord } from '../calls/call-record';
4
+ import { CallConnection, type JoinOptions } from '../calls/connection';
4
5
  import { Channel } from '../channels/channel';
5
6
  import { MacroEntity } from '../entity';
6
7
  import type { User } from '../users/user';
7
8
  /** A meeting's schedule and invitation link. */
8
9
  export declare class Meeting extends MacroEntity<MeetingRecord> {
10
+ /** Join this meeting as the current account; always send a program join body. */
11
+ join(opts?: JoinOptions): Promise<CallConnection>;
12
+ /** Join the link as a named guest. */
13
+ joinAsGuest(name: string): Promise<CallConnection>;
9
14
  private lookupToken?;
10
15
  private constructor();
11
16
  /** Construct a lazy meeting handle. */
@@ -1,7 +1,11 @@
1
1
  import type { CreateMeetingRequest } from '../../../generated/storage/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import { Meeting } from './meeting';
4
- /** Meeting schedules and invitation lookup. */
4
+ /**
5
+ * Meeting schedules and invitation lookup.
6
+ *
7
+ * @routing Use when managing a recurring meeting series' schedule, invitations or sharing link; not finding a time, calendar events or booking links.
8
+ */
5
9
  export declare class MeetingNamespace {
6
10
  private readonly client;
7
11
  constructor(client: MacroClient);