@macro-inc/sdk 0.0.1 → 0.2.2

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 (165) hide show
  1. package/README.md +628 -21
  2. package/dist/{chunk-5HAKQN23.js → chunk-7LVVPVNT.js} +70 -57
  3. package/dist/{chunk-JXIQT5TH.js → chunk-7YJ6Y7HJ.js} +234 -16
  4. package/dist/chunk-LMJW65ML.js +836 -0
  5. package/dist/{chunk-SGAHIERJ.js → chunk-OGE7WXJE.js} +16 -0
  6. package/dist/chunk-PRUFPW3B.js +943 -0
  7. package/dist/{chunk-CTKR64MY.js → chunk-QVBNNMQS.js} +242 -367
  8. package/dist/{chunk-QNUS5BC5.js → chunk-SUINKDXF.js} +30 -84
  9. package/dist/{chunk-77EI4LSQ.js → chunk-ZQXOHNDB.js} +1518 -386
  10. package/dist/generated/agent-harness/index.d.ts +1 -1
  11. package/dist/generated/agent-harness/index.js +1 -1
  12. package/dist/generated/agent-harness/sdk.gen.d.ts +174 -4
  13. package/dist/generated/agent-harness/types.gen.d.ts +2511 -189
  14. package/dist/generated/auth/index.d.ts +1 -1
  15. package/dist/generated/auth/index.js +1 -1
  16. package/dist/generated/auth/sdk.gen.d.ts +106 -8
  17. package/dist/generated/auth/types.gen.d.ts +1473 -116
  18. package/dist/generated/calendar/client/client.gen.d.ts +2 -0
  19. package/dist/generated/calendar/client/index.d.ts +10 -0
  20. package/dist/generated/calendar/client/types.gen.d.ts +120 -0
  21. package/dist/generated/calendar/client/utils.gen.d.ts +37 -0
  22. package/dist/generated/calendar/client.gen.d.ts +12 -0
  23. package/dist/generated/calendar/core/auth.gen.d.ts +25 -0
  24. package/dist/generated/calendar/core/bodySerializer.gen.d.ts +25 -0
  25. package/dist/generated/calendar/core/params.gen.d.ts +43 -0
  26. package/dist/generated/calendar/core/pathSerializer.gen.d.ts +33 -0
  27. package/dist/generated/calendar/core/queryKeySerializer.gen.d.ts +18 -0
  28. package/dist/generated/calendar/core/serverSentEvents.gen.d.ts +71 -0
  29. package/dist/generated/calendar/core/types.gen.d.ts +83 -0
  30. package/dist/generated/calendar/core/utils.gen.d.ts +19 -0
  31. package/dist/generated/calendar/index.d.ts +2 -0
  32. package/dist/generated/calendar/index.js +6 -0
  33. package/dist/generated/calendar/sdk.gen.d.ts +95 -0
  34. package/dist/generated/calendar/types.gen.d.ts +1091 -0
  35. package/dist/generated/cognition/index.d.ts +1 -1
  36. package/dist/generated/cognition/index.js +1 -1
  37. package/dist/generated/cognition/sdk.gen.d.ts +6 -1
  38. package/dist/generated/cognition/types.gen.d.ts +304 -36
  39. package/dist/generated/connection/types.gen.d.ts +1 -1
  40. package/dist/generated/email/index.d.ts +1 -1
  41. package/dist/generated/email/index.js +1 -1
  42. package/dist/generated/email/sdk.gen.d.ts +32 -27
  43. package/dist/generated/email/types.gen.d.ts +586 -409
  44. package/dist/generated/notification/index.d.ts +1 -1
  45. package/dist/generated/notification/types.gen.d.ts +384 -19
  46. package/dist/generated/properties/types.gen.d.ts +8 -5
  47. package/dist/generated/scheduled-action/index.d.ts +1 -1
  48. package/dist/generated/scheduled-action/index.js +3 -842
  49. package/dist/generated/scheduled-action/sdk.gen.d.ts +3 -1
  50. package/dist/generated/scheduled-action/types.gen.d.ts +277 -41
  51. package/dist/generated/search/index.d.ts +1 -1
  52. package/dist/generated/search/types.gen.d.ts +262 -43
  53. package/dist/generated/storage/index.d.ts +1 -1
  54. package/dist/generated/storage/index.js +1 -1
  55. package/dist/generated/storage/sdk.gen.d.ts +678 -107
  56. package/dist/generated/storage/types.gen.d.ts +14827 -5995
  57. package/dist/generated/unfurl/index.d.ts +1 -1
  58. package/dist/generated/unfurl/index.js +3 -832
  59. package/dist/generated/unfurl/types.gen.d.ts +20 -0
  60. package/dist/src/config.d.ts +33 -13
  61. package/dist/src/entities/agent-sessions/agent-session.d.ts +150 -6
  62. package/dist/src/entities/agent-sessions/code-execution.d.ts +43 -0
  63. package/dist/src/entities/agent-sessions/conversation.d.ts +54 -0
  64. package/dist/src/entities/agent-sessions/namespace.d.ts +23 -5
  65. package/dist/src/entities/agent-sessions/queued-action.d.ts +46 -0
  66. package/dist/src/entities/agent-sessions/review.d.ts +107 -0
  67. package/dist/src/entities/agent-sessions/tool-approval.d.ts +21 -0
  68. package/dist/src/entities/agents/agent.d.ts +47 -0
  69. package/dist/src/entities/agents/namespace.d.ts +13 -0
  70. package/dist/src/entities/ai/namespace.d.ts +24 -0
  71. package/dist/src/entities/api-keys/api-key.d.ts +17 -0
  72. package/dist/src/entities/api-keys/namespace.d.ts +18 -0
  73. package/dist/src/entities/calendar/calendar.d.ts +35 -0
  74. package/dist/src/entities/calendar/event.d.ts +123 -0
  75. package/dist/src/entities/calendar/event.test.d.ts +1 -0
  76. package/dist/src/entities/calendar/namespace.d.ts +111 -0
  77. package/dist/src/entities/calendar/replacement.d.ts +15 -0
  78. package/dist/src/entities/calls/call-record.d.ts +62 -6
  79. package/dist/src/entities/calls/message.d.ts +33 -0
  80. package/dist/src/entities/channels/activity.d.ts +24 -0
  81. package/dist/src/entities/channels/channel.d.ts +44 -3
  82. package/dist/src/entities/channels/labels.d.ts +39 -0
  83. package/dist/src/entities/channels/message.d.ts +9 -17
  84. package/dist/src/entities/channels/namespace.d.ts +6 -0
  85. package/dist/src/entities/channels/picture.d.ts +11 -0
  86. package/dist/src/entities/channels/post.d.ts +1 -1
  87. package/dist/src/entities/channels/thread.d.ts +5 -0
  88. package/dist/src/entities/chats/chat.d.ts +11 -1
  89. package/dist/src/entities/chats/generation.d.ts +46 -0
  90. package/dist/src/entities/crm/comment.d.ts +55 -34
  91. package/dist/src/entities/crm/company.d.ts +42 -10
  92. package/dist/src/entities/crm/contact.d.ts +42 -10
  93. package/dist/src/entities/crm/namespace.d.ts +18 -1
  94. package/dist/src/entities/crm/pipeline.d.ts +122 -0
  95. package/dist/src/entities/crm/pipelines.d.ts +14 -0
  96. package/dist/src/entities/databases/column.d.ts +75 -0
  97. package/dist/src/entities/databases/database.d.ts +272 -0
  98. package/dist/src/entities/databases/namespace.d.ts +21 -0
  99. package/dist/src/entities/databases/query.d.ts +86 -0
  100. package/dist/src/entities/databases/row.d.ts +27 -0
  101. package/dist/src/entities/databases/table.d.ts +61 -0
  102. package/dist/src/entities/databases/view.d.ts +40 -0
  103. package/dist/src/entities/databases/webhook.d.ts +32 -0
  104. package/dist/src/entities/documents/anchor.d.ts +29 -0
  105. package/dist/src/entities/documents/comment.d.ts +25 -22
  106. package/dist/src/entities/documents/document.d.ts +60 -12
  107. package/dist/src/entities/documents/namespace.d.ts +30 -0
  108. package/dist/src/entities/documents/version.d.ts +22 -0
  109. package/dist/src/entities/email/draft.d.ts +79 -0
  110. package/dist/src/entities/email/filter.d.ts +34 -0
  111. package/dist/src/entities/email/link.d.ts +6 -4
  112. package/dist/src/entities/email/message.d.ts +12 -1
  113. package/dist/src/entities/email/namespace.d.ts +34 -1
  114. package/dist/src/entities/email/thread.d.ts +23 -1
  115. package/dist/src/entities/entity-mentions/mention.d.ts +16 -0
  116. package/dist/src/entities/entity-mentions/namespace.d.ts +12 -0
  117. package/dist/src/entities/entity.d.ts +7 -0
  118. package/dist/src/entities/favorites/namespace.d.ts +14 -2
  119. package/dist/src/entities/foreign/foreign-entity.d.ts +2 -0
  120. package/dist/src/entities/foreign/namespace.d.ts +40 -0
  121. package/dist/src/entities/forms/form.d.ts +227 -0
  122. package/dist/src/entities/forms/namespace.d.ts +18 -0
  123. package/dist/src/entities/forms/question.d.ts +37 -0
  124. package/dist/src/entities/forms/response.d.ts +32 -0
  125. package/dist/src/entities/forms/section.d.ts +19 -0
  126. package/dist/src/entities/github-pull-requests/namespace.d.ts +12 -0
  127. package/dist/src/entities/github-pull-requests/pull-request.d.ts +52 -0
  128. package/dist/src/entities/harnesses/harness.d.ts +19 -0
  129. package/dist/src/entities/harnesses/namespace.d.ts +33 -0
  130. package/dist/src/entities/harnesses/pairing.d.ts +39 -0
  131. package/dist/src/entities/initiatives/initiative.d.ts +50 -0
  132. package/dist/src/entities/initiatives/namespace.d.ts +13 -0
  133. package/dist/src/entities/meetings/meeting.d.ts +38 -0
  134. package/dist/src/entities/meetings/namespace.d.ts +18 -0
  135. package/dist/src/entities/messages/thread.d.ts +101 -0
  136. package/dist/src/entities/notifications/notification.d.ts +6 -3
  137. package/dist/src/entities/notifications/notification.test.d.ts +1 -0
  138. package/dist/src/entities/projects/project.d.ts +7 -0
  139. package/dist/src/entities/reference.d.ts +82 -0
  140. package/dist/src/entities/routines/namespace.d.ts +15 -0
  141. package/dist/src/entities/routines/routine.d.ts +115 -0
  142. package/dist/src/entities/sharing/access.d.ts +65 -0
  143. package/dist/src/entities/sharing/permissions.d.ts +13 -0
  144. package/dist/src/entities/tasks/namespace.d.ts +4 -0
  145. package/dist/src/entities/tasks/task.d.ts +6 -0
  146. package/dist/src/entities/unfurls/namespace.d.ts +10 -0
  147. package/dist/src/entities/webhooks/webhook.d.ts +3 -1
  148. package/dist/src/entities/workspace/items.d.ts +7 -0
  149. package/dist/src/entities/workspace/namespace.d.ts +83 -0
  150. package/dist/src/entities/workspace/query.d.ts +12 -0
  151. package/dist/src/entities/workspace/types.d.ts +96 -0
  152. package/dist/src/events/hydrate/agentSession.d.ts +192 -0
  153. package/dist/src/events/hydrate/channel.d.ts +2 -39
  154. package/dist/src/events/hydrate/message.d.ts +70 -0
  155. package/dist/src/events/receiver.d.ts +57 -19
  156. package/dist/src/events/types.d.ts +3 -1
  157. package/dist/src/macro.d.ts +80 -3
  158. package/dist/src/macro.js +8832 -2784
  159. package/dist/src/utils/activity.d.ts +11 -0
  160. package/dist/src/utils/activity.test.d.ts +1 -0
  161. package/dist/src/utils/client.d.ts +10 -1
  162. package/dist/src/utils/concurrency.d.ts +5 -0
  163. package/dist/src/utils/index.d.ts +1 -0
  164. package/dist/src/utils/pagination.d.ts +9 -4
  165. package/package.json +11 -3
@@ -1,41 +1,44 @@
1
- import type { Comment as CommentRecord } from '../../../generated/storage/types.gen';
1
+ import type { Message as MessageRecord } from '../../../generated/storage/types.gen';
2
+ import { type RichMessage } from '../../mentions';
2
3
  import type { MacroClient } from '../../utils/client';
3
4
  import { MacroEntity } from '../entity';
4
5
  import { User } from '../users/user';
5
- import type { Document } from './document';
6
+ import { Document } from './document';
6
7
  /**
7
- * A comment on a document. Compound-keyed by `(documentId, commentId)`:
8
- * comment ids are numeric and only unique per document, so the numeric id is
9
- * kept as {@link commentId} and its string form backs the base class `id`.
8
+ * A comment on a document: a document-parent message, addressed by its
9
+ * document and message UUID. Its record and mutations are the ones channel
10
+ * messages use.
10
11
  */
11
- export declare class Comment extends MacroEntity<CommentRecord> {
12
+ export declare class Comment extends MacroEntity<MessageRecord> {
12
13
  /** The document this comment belongs to. */
13
14
  readonly documentId: string;
14
- /** The comment's numeric id, as the API uses it. */
15
- readonly commentId: number;
16
15
  private constructor();
17
- /**
18
- * There is no single-comment GET, so a fetch loads the document's comment
19
- * threads and finds this comment in them.
20
- */
21
- protected fetch(): Promise<CommentRecord>;
22
- /** Build a comment from a comment-thread record (pre-seeded, no fetch). */
23
- static from(client: MacroClient, document: Document, record: CommentRecord): Comment;
16
+ private get path();
17
+ protected fetch(): Promise<MessageRecord>;
18
+ /** A handle to a comment by id. Fields load on first access. */
19
+ static byId(client: MacroClient, documentId: string, id: string): Comment;
20
+ /** Build a comment from a message record (pre-seeded, no fetch). */
21
+ static from(client: MacroClient, documentId: string, record: MessageRecord): Comment;
24
22
  /** The comment's text. */
25
23
  readonly text: () => Promise<string>;
26
- /** The id of the thread this comment belongs to. */
27
- readonly threadId: () => Promise<number>;
28
24
  /** When the comment was created. */
29
- readonly createdAt: () => Promise<string | undefined>;
25
+ readonly createdAt: () => Promise<string>;
30
26
  /** When the comment was last updated. */
31
- readonly updatedAt: () => Promise<string | undefined>;
27
+ readonly updatedAt: () => Promise<string>;
28
+ /** The id of the thread this comment belongs to: its root, or itself for a root. */
29
+ threadId(): Promise<string>;
30
+ /** The document this comment is on. */
31
+ document(): Document;
32
32
  /** The user who wrote this comment. */
33
33
  author(): Promise<User>;
34
+ /** Reply in this comment's thread. */
35
+ reply(body: string | RichMessage): Promise<Comment>;
34
36
  /**
35
- * Replace the comment's text. The endpoint requires the thread id in the
36
- * body, which is resolved from the comment's own record.
37
+ * Replace the comment's text.
38
+ *
39
+ * @param body - Plain text, or a rich body composed with {@link msg}.
37
40
  */
38
- edit(text: string): Promise<this>;
41
+ edit(body: string | RichMessage): Promise<this>;
39
42
  /** Delete this comment. */
40
43
  delete(): Promise<void>;
41
44
  }
@@ -1,17 +1,21 @@
1
1
  import type { PropertyTargetEntityType as PropertyEntityType } from '../../../generated/properties/types.gen';
2
- import type { Thread as CommentThreadRecord, DocumentTeamShareResponse, GetDocumentResponses, GithubPullRequest } from '../../../generated/storage/types.gen';
3
- import { type Mentionable, type MentionPart } from '../../mentions';
2
+ import type { DocumentTeamShareResponse, GetDocumentResponses, GithubPullRequest, MessageCursor, PdfHighlightAnchorRequest, PreSaveDocumentRequest, SaveDocumentRequest, ThreadState } from '../../../generated/storage/types.gen';
3
+ import { type Mentionable, type MentionPart, type RichMessage } from '../../mentions';
4
4
  import type { MacroClient } from '../../utils/client';
5
5
  import { PropertiedEntity } from '../entity';
6
+ import { MessageThread, type TimelineOptions } from '../messages/thread';
6
7
  import { Project } from '../projects/project';
8
+ import { EntityAccess } from '../sharing/access';
7
9
  import { User } from '../users/user';
10
+ import { DocumentAnchor } from './anchor';
8
11
  import { Comment } from './comment';
12
+ import { DocumentVersion } from './version';
9
13
  type DocumentDetail = GetDocumentResponses[200]['data']['documentMetadata'];
10
- /** One of a document's comment threads: the thread record and its comments. */
14
+ /** One of a document's comment threads: its state and its comments. */
11
15
  export interface CommentThread {
12
- /** The thread record: id, resolved state, owner, timestamps. */
13
- thread: CommentThreadRecord;
14
- /** The thread's comments, in order. */
16
+ /** The thread state: root id, resolved flag, owner, anchor, timestamps. */
17
+ thread: ThreadState;
18
+ /** The root comment followed by its replies, in order. */
15
19
  comments: Comment[];
16
20
  }
17
21
  /**
@@ -19,6 +23,47 @@ export interface CommentThread {
19
23
  * inline link to the document.
20
24
  */
21
25
  export declare class Document extends PropertiedEntity<DocumentDetail> implements Mentionable {
26
+ /** PDF annotations in this document. */
27
+ anchors(): Promise<DocumentAnchor[]>;
28
+ /** Create a standalone PDF highlight. */
29
+ createHighlight(options: Omit<PdfHighlightAnchorRequest, 'uuid'>): Promise<DocumentAnchor>;
30
+ /** A handle to an immutable version. */
31
+ version(version: number): DocumentVersion;
32
+ /** Sharing configuration. */
33
+ sharePermissions(): Promise<import("../../../generated/storage").SharePermissionV2>;
34
+ /** Mint a scoped permissions token. */
35
+ permissionsToken(): Promise<string>;
36
+ /** Prepare multipart content saving and return the service's upload instructions. */
37
+ prepareSave(parts: PreSaveDocumentRequest['newBom']): Promise<import("../../../generated/storage").PreSaveDocumentResponseData>;
38
+ /** Commit uploaded content. Does not retry uncertain writes. */
39
+ save(options: SaveDocumentRequest): Promise<import("../../../generated/storage").SaveDocumentResponseData>;
40
+ /** Commit a simple document save. */
41
+ simpleSave(): Promise<import("../../../generated/storage").SaveDocumentResponseData>;
42
+ /** A shared message thread scoped to this resource. */
43
+ messageThreadById(id: string): MessageThread;
44
+ /** A mixed message and activity timeline page. */
45
+ timelinePage(selection?: TimelineOptions<Comment>): Promise<{
46
+ entries: ({
47
+ type: "activity";
48
+ activity: {
49
+ actor: User;
50
+ action: string;
51
+ actor_id: string;
52
+ id: string;
53
+ occurred_at: string;
54
+ payload?: unknown;
55
+ };
56
+ message?: undefined;
57
+ } | {
58
+ type: "message";
59
+ message: Comment;
60
+ activity?: undefined;
61
+ })[];
62
+ nextCursor: MessageCursor | undefined;
63
+ previousCursor: MessageCursor | undefined;
64
+ }>;
65
+ /** Access requests and direct user grants. */
66
+ readonly access: EntityAccess;
22
67
  protected fetch(): Promise<DocumentDetail>;
23
68
  /** A handle to a document by id. Details load on first access. */
24
69
  static byId(client: MacroClient, id: string): Document;
@@ -77,8 +122,8 @@ export declare class Document extends PropertiedEntity<DocumentDetail> implement
77
122
  /** When the document was deleted, if it has been. */
78
123
  readonly deletedAt: () => Promise<string | undefined>;
79
124
  /**
80
- * The document's raw content (markdown source for markdown documents),
81
- * downloaded via a presigned export URL.
125
+ * Current Markdown for native documents, extracted text for PDF/Word,
126
+ * or raw file content for other formats. Native reads include live edits.
82
127
  */
83
128
  content(): Promise<string>;
84
129
  /** Rename the document. */
@@ -102,14 +147,17 @@ export declare class Document extends PropertiedEntity<DocumentDetail> implement
102
147
  name: string;
103
148
  versionId?: number;
104
149
  }): Promise<Document>;
105
- /** The document's comment threads, each with its comments. */
150
+ /** The document's live comment threads, each with its comments, newest thread first. */
106
151
  comments(): Promise<CommentThread[]>;
107
152
  /**
108
153
  * Add a comment. Starts a new unanchored thread, or replies to an existing
109
- * one when `threadId` is given. Returns the created comment.
154
+ * one when `threadId` (the thread's root comment id) is given.
155
+ *
156
+ * @param body - Plain text, or a rich body composed with {@link msg}.
157
+ * @returns The created comment.
110
158
  */
111
- comment(text: string, opts?: {
112
- threadId?: number;
159
+ comment(body: string | RichMessage, opts?: {
160
+ threadId?: string;
113
161
  }): Promise<Comment>;
114
162
  /** The document's short id (used in compact links and branch names). */
115
163
  shortId(): Promise<string>;
@@ -1,10 +1,40 @@
1
1
  import type { MacroClient } from '../../utils/client';
2
+ import type { EmailAttachment } from '../email/attachment';
2
3
  import type { Project } from '../projects/project';
3
4
  import type { SearchOpts } from '../search';
5
+ import type { Team } from '../teams/team';
6
+ import { User } from '../users/user';
4
7
  import { Document } from './document';
5
8
  import { SystemSkill } from './system-skill';
6
9
  export declare class DocumentNamespace {
7
10
  private readonly client;
11
+ /** Resolve a team task reference such as ENG-42. */
12
+ byTeamSlug(slug: string): Promise<Document>;
13
+ /** Validate a permissions token, returning its document and optional user handles. */
14
+ validatePermissionsToken(token: string): Promise<{
15
+ document: Document;
16
+ user: User | undefined;
17
+ accessLevel: import("../../../generated/storage").AccessLevel;
18
+ expiresAt: number;
19
+ issuer: string;
20
+ }>;
21
+ /** Reserve a binary document and return upload instructions. Upload content before saving. */
22
+ createUpload(options: {
23
+ name: string;
24
+ sha: string;
25
+ fileType?: string;
26
+ mimeType?: string;
27
+ project?: Project;
28
+ team?: Team;
29
+ branchedFrom?: Document;
30
+ attachment?: EmailAttachment;
31
+ isTask?: boolean;
32
+ }): Promise<{
33
+ document: Document;
34
+ uploadUrl: string | undefined;
35
+ contentType: string;
36
+ content: import("../../../generated/storage").DocumentContent;
37
+ }>;
8
38
  constructor(client: MacroClient);
9
39
  /** A handle to a document by id. Details load on first access. */
10
40
  byId(id: string): Document;
@@ -0,0 +1,22 @@
1
+ import type { GetDocumentResponseData } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import type { Document } from './document';
4
+ /** An immutable document version, scoped to its document. */
5
+ export declare class DocumentVersion {
6
+ private readonly client;
7
+ /** Parent document. */
8
+ readonly document: Document;
9
+ /** Version number. */
10
+ readonly id: number;
11
+ private readonly detail;
12
+ private constructor();
13
+ /** Construct a version handle. */
14
+ static byId(client: MacroClient, document: Document, id: number): DocumentVersion;
15
+ /** Version metadata and the caller's access. */
16
+ read(): Promise<GetDocumentResponseData>;
17
+ /** Serialize only scoped identity. */
18
+ toJSON(): {
19
+ id: number;
20
+ documentId: string;
21
+ };
22
+ }
@@ -0,0 +1,79 @@
1
+ import type { ApiDraftInput } from '../../../generated/email/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import type { EmailAttachment } from './attachment';
4
+ import { EmailMessage } from './message';
5
+ import type { EmailThread } from './thread';
6
+ /** Draft content; relationships use message and thread handles. */
7
+ export type DraftOptions = Omit<ApiDraftInput, 'db_id' | 'provider_id' | 'provider_thread_id' | 'replying_to_id' | 'thread_db_id' | 'body_text' | 'body_html' | 'body_macro' | 'headers_json' | 'include_signature'> & {
8
+ /** Plain text body. */
9
+ bodyText?: string;
10
+ /** HTML body. */
11
+ bodyHtml?: string;
12
+ /** Macro body. */
13
+ bodyMacro?: string;
14
+ /** Extra headers. */
15
+ headers?: ApiDraftInput['headers_json'];
16
+ /** Include the inbox signature. */
17
+ includeSignature?: boolean;
18
+ /** Thread receiving this draft. */
19
+ thread?: EmailThread;
20
+ /** Message being replied to. */
21
+ replyingTo?: EmailMessage;
22
+ };
23
+ /** A draft email. Sending remains an explicit separate operation. */
24
+ export declare class EmailDraft extends EmailMessage {
25
+ private inboxHeaders;
26
+ /** Construct a lazy draft handle. */
27
+ static byId(client: MacroClient, id: string): EmailDraft;
28
+ /** Replace draft content without changing its identity or sending it. */
29
+ update(options: DraftOptions): Promise<void>;
30
+ /** Delete the draft. */
31
+ delete(): Promise<void>;
32
+ /** Schedule this draft for sending. */
33
+ schedule(sendTime: string, options?: {
34
+ includeSignature?: boolean;
35
+ }): Promise<void>;
36
+ /** Remove a scheduled send. */
37
+ unschedule(): Promise<void>;
38
+ /** Reserve an attachment upload. Upload to the returned URL, then call complete(). */
39
+ addAttachment(options: {
40
+ fileName: string;
41
+ sha: string;
42
+ size: number;
43
+ uploadId?: string;
44
+ }): Promise<{
45
+ attachment: DraftAttachment;
46
+ uploadUrl: string;
47
+ contentType: string;
48
+ }>;
49
+ /** Forward an existing attachment into this draft. */
50
+ forwardAttachment(attachment: EmailAttachment): Promise<DraftAttachment>;
51
+ /** Remove a draft attachment. */
52
+ removeAttachment(attachment: DraftAttachment): Promise<void>;
53
+ /** Complete verification of an uploaded attachment. */
54
+ verifyAttachment(attachment: DraftAttachment): Promise<void>;
55
+ }
56
+ /** An uploaded or forwarded attachment belonging to a draft. */
57
+ export declare class DraftAttachment {
58
+ /** Parent draft. */
59
+ readonly draft: EmailDraft;
60
+ /** Attachment identity. */
61
+ readonly id: string;
62
+ /** Whether this attachment was forwarded. */
63
+ readonly forwarded: boolean;
64
+ private constructor();
65
+ /** Construct a draft scoped attachment handle. */
66
+ static byId(_client: MacroClient, draft: EmailDraft, id: string, forwarded?: boolean): DraftAttachment;
67
+ /** Complete verification after uploading the file. */
68
+ complete(): Promise<void>;
69
+ /** Remove this attachment from its draft. */
70
+ remove(): Promise<void>;
71
+ /** Serialize identity without credentials. */
72
+ toJSON(): {
73
+ id: string;
74
+ draftId: string;
75
+ forwarded: boolean;
76
+ };
77
+ }
78
+ /** Translate draft content to the generated contract. */
79
+ export declare function draftBody(options: DraftOptions): ApiDraftInput;
@@ -0,0 +1,34 @@
1
+ import type { ApiEmailFilter } from '../../../generated/email/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { MacroEntity } from '../entity';
4
+ import type { Link } from './link';
5
+ /** Sender importance rule. */
6
+ export interface EmailFilterOptions {
7
+ /** Match an address. */
8
+ emailAddress?: string;
9
+ /** Match a domain. */
10
+ emailDomain?: string;
11
+ /** Whether matches are important. */
12
+ isImportant: boolean;
13
+ }
14
+ /** An importance filter matched by sender address or domain. */
15
+ export declare class EmailFilter extends MacroEntity<ApiEmailFilter> {
16
+ private readonly inbox?;
17
+ private constructor();
18
+ private get headers();
19
+ /** Construct a lazy filter handle. */
20
+ static byId(client: MacroClient, id: string, inbox?: Link): EmailFilter;
21
+ /** Seed from a server record. */
22
+ static from(client: MacroClient, record: ApiEmailFilter, inbox?: Link): EmailFilter;
23
+ protected fetch(): Promise<ApiEmailFilter>;
24
+ /** Matched address. */
25
+ readonly emailAddress: () => Promise<string | undefined>;
26
+ /** Matched domain. */
27
+ readonly emailDomain: () => Promise<string | undefined>;
28
+ /** Importance assigned by this filter. */
29
+ readonly isImportant: () => Promise<boolean>;
30
+ /** Change the importance for the same sender selector. */
31
+ setImportant(isImportant: boolean): Promise<void>;
32
+ /** Delete this filter. */
33
+ delete(): Promise<void>;
34
+ }
@@ -1,8 +1,8 @@
1
- import type { Link as LinkRecord } from '../../../generated/email/types.gen';
1
+ import type { Link as LinkRecord, MailboxSettingsOperation } from '../../../generated/email/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import { MacroEntity } from '../entity';
4
4
  /**
5
- * An email link: a connected inbox (e.g. a Gmail account) that threads and
5
+ * An email link: a connected inbox (e.g. Gmail or Outlook) that threads and
6
6
  * messages sync through. A free-to-construct handle, resolved from the
7
7
  * caller's connected links.
8
8
  */
@@ -14,8 +14,8 @@ export declare class Link extends MacroEntity<LinkRecord> {
14
14
  static list(client: MacroClient): Promise<Link[]>;
15
15
  /** The inbox's email address. */
16
16
  readonly emailAddress: () => Promise<string>;
17
- /** The email provider (e.g. `GMAIL`). */
18
- readonly provider: () => Promise<"GMAIL">;
17
+ /** The email provider (e.g. `GMAIL` or `OUTLOOK`). */
18
+ readonly provider: () => Promise<import("../../../generated/email").UserProvider>;
19
19
  /** Whether this is the user's primary inbox. */
20
20
  readonly isPrimary: () => Promise<boolean>;
21
21
  /** Whether syncing is currently active for this inbox. */
@@ -26,4 +26,6 @@ export declare class Link extends MacroEntity<LinkRecord> {
26
26
  readonly needsReauth: () => Promise<boolean>;
27
27
  /** The inbox's avatar URL, if any. */
28
28
  readonly photoUrl: () => Promise<string | undefined>;
29
+ /** Read category and sender-policy changes for this inbox. */
30
+ settingsOperations(): Promise<MailboxSettingsOperation[]>;
29
31
  }
@@ -1,4 +1,4 @@
1
- import type { ApiDraftContactInfo, GetMessageResponses } from '../../../generated/email/types.gen';
1
+ import type { ApiDraftContactInfo, GetMessageResponses, MessageOperationResponse, ResolveMessageOperationRequest, TransferDraftRequest, TransferDraftResponse } from '../../../generated/email/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import { MacroEntity } from '../entity';
4
4
  import type { Label } from './label';
@@ -49,6 +49,17 @@ export declare class EmailMessage extends MacroEntity<EmailMessageData> {
49
49
  readonly labels: () => Promise<import("../../../generated/email").LabelInfo[]>;
50
50
  /** The inbox (email link) this message belongs to. */
51
51
  readonly link: () => Promise<Link>;
52
+ /** Read the draft's durable send, upload, or conflict status without retrying it. */
53
+ operationStatus(): Promise<MessageOperationResponse>;
54
+ /** Resolve the displayed operation revision after the user chooses an action.
55
+ * Retrying an uncertain send requires explicit duplicate-risk acceptance. */
56
+ resolveOperation(request: ResolveMessageOperationRequest): Promise<void>;
57
+ /** Verify an uploaded draft attachment before it can be sent. */
58
+ completeDraftAttachment(attachmentId: string): Promise<void>;
59
+ /** Move a draft to another inbox using a caller-persisted operation UUID.
60
+ * Continue editing the returned message_id; the original identity is retired.
61
+ * On an interrupted response, use email.recoverDraftTransfer(operation_id). */
62
+ transferDraft(request: TransferDraftRequest): Promise<TransferDraftResponse>;
52
63
  /** Add a label to this message. */
53
64
  addLabel(label: Label): Promise<void>;
54
65
  /** Remove a label from this message. */
@@ -1,7 +1,11 @@
1
- import type { ApiSortMethod } from '../../../generated/email/types.gen';
1
+ import type { EmailConnectionProviders } from '../../../generated/auth/types.gen';
2
+ import type { ApiSortMethod, TransferRecoveryResponse } from '../../../generated/email/types.gen';
3
+ import type { ListEmailRemindersData } from '../../../generated/storage/types.gen';
2
4
  import type { MacroClient } from '../../utils/client';
3
5
  import type { SearchOpts } from '../search';
4
6
  import { EmailAttachment } from './attachment';
7
+ import { type DraftOptions, EmailDraft } from './draft';
8
+ import { EmailFilter, type EmailFilterOptions } from './filter';
5
9
  import { Label } from './label';
6
10
  import { Link } from './link';
7
11
  import { EmailMessage, type SendEmailOptions } from './message';
@@ -15,6 +19,30 @@ export interface InboxOptions {
15
19
  }
16
20
  export declare class EmailNamespace {
17
21
  private readonly client;
22
+ /** Create a draft without sending it; the inbox defaults to the caller's primary. */
23
+ createDraft(options: DraftOptions, inbox?: Link): Promise<EmailDraft>;
24
+ /** Construct a lazy draft handle. */
25
+ draftById(id: string): EmailDraft;
26
+ /** Scheduled drafts, fetched lazily in bounded pages. */
27
+ scheduled(options?: {
28
+ pageSize?: number;
29
+ inbox?: Link;
30
+ }): AsyncGenerator<EmailDraft>;
31
+ /** Importance filters. */
32
+ filters(inbox?: Link): Promise<EmailFilter[]>;
33
+ /** Create or replace a filter matching an address or domain. */
34
+ upsertFilter(options: EmailFilterOptions, inbox?: Link): Promise<EmailFilter>;
35
+ /** Address book contacts grouped by the service's interaction buckets. */
36
+ contacts(): Promise<{
37
+ [key: string]: import("../../../generated/email").ContactInfoWithInteraction[];
38
+ }>;
39
+ /** Follow-up reminders with thread handles, automatically paginated. */
40
+ reminders(options?: Omit<NonNullable<ListEmailRemindersData['query']>, 'inboxIds' | 'cursor'> & {
41
+ inboxes?: Link[];
42
+ }): AsyncGenerator<{
43
+ thread: EmailThread;
44
+ followup: import("../../../generated/storage").EmailFollowup;
45
+ }, any, any>;
18
46
  constructor(client: MacroClient);
19
47
  /** A handle to an email thread by id. */
20
48
  byId(id: string): EmailThread;
@@ -26,6 +54,11 @@ export declare class EmailNamespace {
26
54
  link(id: string): Link;
27
55
  /** The caller's connected inboxes (email links). */
28
56
  links(): Promise<Link[]>;
57
+ /** Providers the server currently permits this caller to connect. */
58
+ connectionProviders(): Promise<EmailConnectionProviders>;
59
+ /** Recover a draft move using its original operation UUID; never starts a new move.
60
+ * An empty committed result fences the old move so it cannot commit later. */
61
+ recoverDraftTransfer(operationId: string): Promise<TransferRecoveryResponse>;
29
62
  /** Send a new email message. */
30
63
  send(opts: SendEmailOptions): Promise<EmailMessage | undefined>;
31
64
  /** Search email threads by subject and content. */
@@ -1,7 +1,10 @@
1
- import type { ApiContactInfo, ApiDraftContactInfo, GetThreadResponses } from '../../../generated/email/types.gen';
1
+ import type { ApiContactInfo, ApiDraftContactInfo, GetThreadResponses, MailboxOperation, UpdateThreadStateRequest } from '../../../generated/email/types.gen';
2
+ import type { EmailFollowupCommand } from '../../../generated/storage/types.gen';
2
3
  import type { MacroClient } from '../../utils/client';
3
4
  import { PropertiedEntity } from '../entity';
4
5
  import { Project } from '../projects/project';
6
+ import { EntityAccess } from '../sharing/access';
7
+ import { type SharePermissionOptions } from '../sharing/permissions';
5
8
  import { EmailAttachment } from './attachment';
6
9
  import type { Label } from './label';
7
10
  import { Link } from './link';
@@ -27,6 +30,21 @@ export interface ReplyEmailOptions {
27
30
  * up to the first 100 messages) loads lazily on first field access.
28
31
  */
29
32
  export declare class EmailThread extends PropertiedEntity<ThreadDetail> {
33
+ /** Access requests and direct user grants. */
34
+ readonly access: EntityAccess;
35
+ /** Read follow-up state for this thread. */
36
+ followup(): Promise<import("../../../generated/storage").EmailFollowupResponse>;
37
+ /** Set or remove a follow-up using a persisted operation id and revision. */
38
+ setFollowup(command: EmailFollowupCommand): Promise<import("../../../generated/storage").EmailFollowup>;
39
+ /** Calendar invitations resolved from this thread's messages. */
40
+ calendarInvitations(): Promise<{
41
+ [key: string]: import("../../../generated/email").InvitationResolution;
42
+ }>;
43
+ /** Change project membership or share permissions for this thread. */
44
+ update(options: {
45
+ project?: Project | null;
46
+ sharePermission?: SharePermissionOptions;
47
+ }): Promise<void>;
30
48
  /** Favorites identify email threads as `email_thread`. */
31
49
  readonly entityType = "email_thread";
32
50
  /** The properties service identifies email threads as `THREAD`. */
@@ -74,6 +92,10 @@ export declare class EmailThread extends PropertiedEntity<ThreadDetail> {
74
92
  reply(opts: ReplyEmailOptions): Promise<EmailMessage | undefined>;
75
93
  /** Archive the thread (or unarchive with `false`). */
76
94
  archive(archived?: boolean): Promise<void>;
95
+ /** Update provider-neutral read, trash, spam, or star state. */
96
+ updateState(request: UpdateThreadStateRequest): Promise<void>;
97
+ /** Read pending or failed mailbox changes without initiating a retry. */
98
+ operations(): Promise<MailboxOperation[]>;
77
99
  /** Mark the thread as seen. */
78
100
  markSeen(): Promise<void>;
79
101
  /** Add a label to every message in the thread. */
@@ -0,0 +1,16 @@
1
+ import type { MacroClient } from '../../utils/client';
2
+ /** A stored mention connecting two resources. */
3
+ export declare class EntityMention {
4
+ private readonly client;
5
+ /** Mention identity. */
6
+ readonly id: string;
7
+ private constructor();
8
+ /** Construct a mention handle for removal. */
9
+ static byId(client: MacroClient, id: string): EntityMention;
10
+ /** Remove this mention. */
11
+ delete(): Promise<void>;
12
+ /** Serialize identity only. */
13
+ toJSON(): {
14
+ id: string;
15
+ };
16
+ }
@@ -0,0 +1,12 @@
1
+ import type { MacroClient } from '../../utils/client';
2
+ import type { EntityReference } from '../reference';
3
+ import { EntityMention } from './mention';
4
+ /** Stored entity mention relationships. */
5
+ export declare class EntityMentionNamespace {
6
+ private readonly client;
7
+ constructor(client: MacroClient);
8
+ /** Construct a stored mention handle. */
9
+ byId(id: string): EntityMention;
10
+ /** Create a mention from a source resource to a target resource. */
11
+ create(source: EntityReference, target: EntityReference): Promise<EntityMention>;
12
+ }
@@ -66,6 +66,13 @@ export declare abstract class MacroEntity<Detail> {
66
66
  export declare abstract class FavoritableEntity<Detail> extends MacroEntity<Detail> implements Favoritable {
67
67
  /** How the entity-addressed APIs (favorites) identify this entity's type. */
68
68
  abstract readonly entityType: MacroEntityType;
69
+ /** Read the caller's effective permission on this entity. */
70
+ permission(): Promise<{
71
+ permission: import("../../generated/storage").EntityPermission;
72
+ status: "access";
73
+ } | {
74
+ status: "no_access";
75
+ }>;
69
76
  /**
70
77
  * Add this entity to the user's favorites. Returns this handle for chaining.
71
78
  * Plain unwrap: favoriting alters the user's favorites collection, not this
@@ -1,13 +1,25 @@
1
1
  import type { Favorite, FavoriteEntityRef } from '../../../generated/storage/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
- import type { FavoritableEntity } from '../entity';
3
+ import type { FavoritableEntity, MacroEntityType } from '../entity';
4
4
  export type { Favorite, FavoriteEntityRef };
5
+ /**
6
+ * Which favorites to list.
7
+ *
8
+ * The two dimensions are independent. Within one, the values are alternatives;
9
+ * between them they are both required, so `entityTypes: ['document']` with
10
+ * `entityIds: [a, b]` matches only documents `a` and `b`. An omitted or empty
11
+ * list constrains nothing, which is why the default lists the whole collection.
12
+ */
13
+ export type FavoritesFilter = {
14
+ entityTypes?: MacroEntityType[];
15
+ entityIds?: string[];
16
+ };
5
17
  /** The user's favorites: a manually ordered collection of entity references. */
6
18
  export declare class FavoritesNamespace {
7
19
  private readonly client;
8
20
  constructor(client: MacroClient);
9
21
  /** The user's favorites, in manual order. */
10
- list(): Promise<Favorite[]>;
22
+ list(filter?: FavoritesFilter): Promise<Favorite[]>;
11
23
  /**
12
24
  * Favorite an entity. Returns the favorite record.
13
25
  */
@@ -12,6 +12,8 @@ export declare class ForeignEntity extends FavoritableEntity<ForeignEntityDetail
12
12
  protected fetch(): Promise<ForeignEntityDetail>;
13
13
  /** A handle to a foreign entity by its internal record id. Details load on first access. */
14
14
  static byId(client: MacroClient, id: string): ForeignEntity;
15
+ /** Build a foreign entity from an already-fetched record (pre-seeded, no fetch). */
16
+ static fromRecord(client: MacroClient, record: ForeignEntityDetail): ForeignEntity;
15
17
  /** The identifier assigned by the external system. */
16
18
  readonly foreignEntityId: () => Promise<string>;
17
19
  /** The source system that owns the external identifier (e.g. `github_pull_request`). */
@@ -1,7 +1,47 @@
1
+ import type { GithubRepositoryFacet, GithubLabelFacet as WireGithubLabelFacet, GithubUserFacet as WireGithubUserFacet } from '../../../generated/storage/types.gen';
1
2
  import type { MacroClient } from '../../utils/client';
2
3
  import { ForeignEntity } from './foreign-entity';
4
+ export type { GithubRepositoryFacet };
5
+ /** A GitHub user among the pull requests visible to the caller, as an author or an assignee. */
6
+ export type GithubUserFacet = Omit<WireGithubUserFacet, 'login'> & {
7
+ /** The user's most recently synced GitHub login, when known. */
8
+ login?: string;
9
+ };
10
+ /** A label among the GitHub pull requests visible to the caller. */
11
+ export type GithubLabelFacet = Omit<WireGithubLabelFacet, 'color'> & {
12
+ /** The label's most recently synced color, as six hex digits without `#`. */
13
+ color?: string;
14
+ };
15
+ /**
16
+ * Repositories, authors, assignees, and labels among the GitHub pull requests
17
+ * visible to the caller.
18
+ */
19
+ export interface GithubPullRequestFacets {
20
+ /** Repositories, most pull requests first. */
21
+ repositories: GithubRepositoryFacet[];
22
+ /** Authors, most pull requests first. */
23
+ authors: GithubUserFacet[];
24
+ /** Assignees, most pull requests first. */
25
+ assignees: GithubUserFacet[];
26
+ /** Labels, most pull requests first. */
27
+ labels: GithubLabelFacet[];
28
+ }
3
29
  export declare class ForeignEntityNamespace {
4
30
  private readonly client;
5
31
  constructor(client: MacroClient);
6
32
  byId(id: string): ForeignEntity;
33
+ /**
34
+ * Look a foreign entity up by the identifier its source system assigned.
35
+ *
36
+ * `foreignEntityId` may contain slashes — sources store them inside the
37
+ * identifier, for example `owner/repo/pull/12`.
38
+ */
39
+ bySource(source: string, foreignEntityId: string): Promise<ForeignEntity>;
40
+ /**
41
+ * Repositories, authors, assignees, and labels among the GitHub pull
42
+ * requests visible to the authenticated user and their team, each with how
43
+ * many pull requests it covers. A pull request visible to both the user and
44
+ * the team counts once.
45
+ */
46
+ githubPullRequestFacets(): Promise<GithubPullRequestFacets>;
7
47
  }