@postalsys/ee-client 1.11.2 → 2.0.1

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 (4) hide show
  1. package/README.md +67 -42
  2. package/index.d.ts +96 -17
  3. package/index.js +1709 -637
  4. package/package.json +8 -2
package/README.md CHANGED
@@ -77,8 +77,8 @@ const { messages, nextPageCursor } = await client.loadMessages('INBOX');
77
77
  // Load a single message (its HTML is returned pre-processed for safe display)
78
78
  const message = await client.loadMessage(messages[0].id);
79
79
 
80
- // Send a plain-text message
81
- await client.sendMessage('user@example.com', 'Hello', 'Sent from ee-client');
80
+ // Send a message
81
+ await client.sendMessage({ to: 'user@example.com', subject: 'Hello', text: 'Sent from ee-client' });
82
82
 
83
83
  // Release the keep-alive timer when done (see destroy() below)
84
84
  client.destroy();
@@ -115,21 +115,24 @@ EmailEngine can also mint short-lived, session-bound tokens whose value starts w
115
115
  new EmailEngineClient(options);
116
116
  ```
117
117
 
118
- | Option | Type | Default | Description |
119
- | -------------------- | ------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
120
- | `account` | `string` | (required) | EmailEngine account identifier. |
121
- | `apiUrl` | `string` | `http://127.0.0.1:3000` | Base URL of your EmailEngine instance. |
122
- | `accessToken` | `string` | - | Bearer token for API authentication. |
123
- | `container` | `HTMLElement` | - | DOM element to render the webmail UI into. Omit for API-only use. |
124
- | `pageSize` | `number` | `20` | Messages per page. A saved value in `localStorage` takes precedence. |
125
- | `confirmMethod` | `function` | browser `confirm()` | Custom confirm dialog, `(message, title, cancelText, okText)`. May be sync or async; returns a boolean. |
126
- | `alertMethod` | `function` | browser `alert()` | Custom alert dialog, `(message, title, cancelText, okText)` where `cancelText` is `null`. |
127
- | `darkMode` | `boolean` | stored preference | Initial dark mode. Overrides the preference stored by the builtin toggle. |
128
- | `showDarkModeToggle` | `boolean` | `true` | Render the builtin dark mode toggle. Set `false` when the host application drives the mode through `client.setDarkMode(enabled)` (for example in sync with its own theme switch). |
129
- | `styleNonce` | `string` | none | Nonce set on the `<style>` elements the widget creates (its own stylesheet and the one inside the message body's shadow root). Pass the page's Content-Security-Policy nonce when `style-src-elem` allows no inline stylesheet without one. |
130
- | `message` | `string` | none | EmailEngine message ID to open on startup instead of the inbox. The folder holding it is listed next to it (the inbox for Gmail API accounts, which report no folder). Use it to deep-link into one message. |
131
- | `onNavigate` | `function` | none | Called with `{ path, messageId }` whenever the open folder or message changes, so the host page can keep its address bar in step (`history.replaceState`). `messageId` is `null` when no message is open. |
132
- | `maxAttachmentSize` | `number` | `25 MB` | Total size limit, in bytes, of the files attached in the compose form. Files are sent base64 encoded in one JSON request, so keep it under EmailEngine's API body limit. |
118
+ | Option | Type | Default | Description |
119
+ | -------------------- | ------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
120
+ | `account` | `string` | (required) | EmailEngine account identifier. |
121
+ | `apiUrl` | `string` | `http://127.0.0.1:3000` | Base URL of your EmailEngine instance. |
122
+ | `accessToken` | `string` | - | Bearer token for API authentication. |
123
+ | `container` | `HTMLElement` | - | DOM element to render the webmail UI into. Omit for API-only use. |
124
+ | `pageSize` | `number` | `20` | Messages per page. A saved value in `localStorage` takes precedence. |
125
+ | `confirmMethod` | `function` | browser `confirm()` | Custom confirm dialog, `(message, title, cancelText, okText)`. May be sync or async; returns a boolean, or `null` when the dialog was dismissed (see below). |
126
+ | `alertMethod` | `function` | browser `alert()` | Custom alert dialog, `(message, title, cancelText, okText)` where `cancelText` is `null`. |
127
+ | `darkMode` | `boolean` | stored preference | Initial dark mode. Overrides the preference stored by the builtin toggle. |
128
+ | `showDarkModeToggle` | `boolean` | `true` | Render the builtin dark mode toggle. Set `false` when the host application drives the mode through `client.setDarkMode(enabled)` (for example in sync with its own theme switch). |
129
+ | `styleNonce` | `string` | none | Nonce set on the `<style>` elements the widget creates (its own stylesheet and the one inside the message body's shadow root). Pass the page's Content-Security-Policy nonce when `style-src-elem` allows no inline stylesheet without one. |
130
+ | `message` | `string` | none | EmailEngine message ID to open on startup instead of the inbox. The folder holding it is listed next to it (the inbox for Gmail API accounts, which report no folder). Use it to deep-link into one message. |
131
+ | `onNavigate` | `function` | none | Called with `{ path, messageId }` whenever the open folder or message changes, so the host page can keep its address bar in step (`history.replaceState`). `messageId` is `null` when no message is open. |
132
+ | `maxAttachmentSize` | `number` | `25 MB` | Total size limit, in bytes, of the files attached in the compose form. Files are sent base64 encoded in one JSON request, so keep it under EmailEngine's API body limit. |
133
+ | `onMessageSent` | `function` | none | Called with EmailEngine's response whenever a message, or a stored draft, is queued for delivery, from the UI or `sendMessage()` / `submitDraft()`. |
134
+ | `onDraftSaved` | `function` | none | Called with EmailEngine's upload response whenever a draft is stored (`saveDraft()`, `updateDraft()` and the compose form). |
135
+ | `onError` | `function` | none | Called with the error and `{ action, description }` whenever a request fails. `action` is `loadFolders`, `loadMessages`, `loadMessage`, `markAsRead`, `delete`, `move`, `send`, `saveDraft` or `download`. The UI still shows the failure itself. |
133
136
 
134
137
  UI rendering, the compose modal, and dark mode only activate when a `container` is supplied. In a non-browser environment the UI is skipped and the instance behaves as a plain API client.
135
138
 
@@ -151,9 +154,13 @@ const client = createEmailEngineClient({
151
154
 
152
155
  ## Methods
153
156
 
154
- ### `loadFolders(): Promise<Folder[]>`
157
+ ### `loadFolders({ counters }?): Promise<Folder[]>`
155
158
 
156
- Load all folders/mailboxes for the account. Renders the folder tree when a container is set.
159
+ Load all folders/mailboxes for the account. Renders the folder tree when a container is set. With `counters: true` each folder carries its message and unread counts in `status` (one IMAP STATUS command per folder); the UI asks for them by default, an API-only client only when told to.
160
+
161
+ ### `ready: Promise<boolean>`
162
+
163
+ Resolves once the first view (the folders and a listing, or the deep-linked `message`) has loaded: `true` when it did, `false` when its requests failed and the panes show why. A deep-linked message that cannot be opened does not count as a failure, since the inbox is listed instead. It never rejects, and resolves `true` at once for an API-only client.
157
164
 
158
165
  ### `loadMessages(path: string, cursor?: string): Promise<MessageListResponse>`
159
166
 
@@ -181,37 +188,40 @@ Move a message to another folder.
181
188
 
182
189
  Open a message by its ID and list the folder that holds it, the way the `message` option does on startup. A message that cannot be loaded shows its error in the viewer and the inbox is listed instead.
183
190
 
184
- ### `sendMessage(to, subject, text, options?): Promise<object>`
185
-
186
- Send a plain-text email. Submitting queues the message; EmailEngine delivers it afterwards. `to` may be:
191
+ ### `sendMessage(message): Promise<object>`
187
192
 
188
- - a string address: `'user@example.com'`
189
- - an object: `{ name: 'John Doe', address: 'john@example.com' }`
190
- - an array of strings and/or objects for multiple recipients
193
+ Send an email. Submitting queues the message; EmailEngine delivers it afterwards. `message` is an object:
191
194
 
192
- The optional `options` object takes:
193
-
194
- - `cc`, `bcc`: recipients, in the same forms as `to`
195
- - `attachments`: `[{ filename, contentType, content }]` with `content` base64 encoded
196
- - `reference`: EmailEngine's submit reference block, `{ message, action, inline, forwardAttachments }`. With it EmailEngine sets the threading headers, quotes the referenced message when `inline` is true, carries its attachments over on a forward with `forwardAttachments`, and flags the original `\Answered` / `$Forwarded` once the message is delivered (IMAP accounts)
195
+ - `to`, `cc`, `bcc`: recipients, each a string address (`'user@example.com'`), an object (`{ name: 'John Doe', address: 'john@example.com' }`) or an array of either
196
+ - `subject`
197
+ - `text`: the plain text part, and `html`: the HTML part (either or both)
198
+ - `attachments`: new files as `{ filename, contentType, content }` with `content` base64 encoded, or attachments of a stored message as `{ reference, filename, contentType }`, where `reference` is the EmailEngine attachment ID. The server fetches a referenced file itself, so forwarding a large file does not pass it through the browser
199
+ - `reference`: EmailEngine's submit reference block, `{ message, action, inline, forwardAttachments }`. With it EmailEngine sets the threading headers, quotes the referenced message when `inline` is true, carries all of its attachments over on a forward with `forwardAttachments`, and flags the original `\Answered` / `$Forwarded` once the message is delivered (IMAP accounts)
200
+ - `headers`: extra headers, for example the `In-Reply-To` and `References` of a reopened draft
197
201
 
198
202
  Resolves to EmailEngine's submit response.
199
203
 
200
- ### `reply(messageId?, { all }?)`, `forward(messageId?)`, `compose(prefill?)`
204
+ ### `reply(messageId?, { all }?)`, `forward(messageId?)`, `compose(prefill?)`, `editDraft(messageId?)`
205
+
206
+ Open the compose form (UI only). `reply()` and `forward()` act on the open message when no ID is given and fill in the recipients, the `Re:` / `Fwd:` subject and the reference; the original is shown under the editor and quoted by EmailEngine when the message is sent. `reply(id, { all: true })` resolves reply-all in the client: the original sender goes in To and the other recipients in Cc, without the account's own address, and the message goes out exactly as the form shows it. A forward lists the original's files as attachments, each of which can be removed. `compose()` opens a blank form and takes `{ to, cc, bcc, subject, text, html }` to prefill it. `editDraft()` opens a stored draft; saving replaces it and sending removes it from Drafts.
201
207
 
202
- Open the compose form (UI only). `reply()` and `forward()` act on the open message when no ID is given and fill in the recipients, the `Re:` / `Fwd:` subject and the reference; the original is shown under the text box and quoted by EmailEngine when the message is sent. `reply(id, { all: true })` resolves reply-all in the client: the original sender goes in To and the other recipients in Cc, without the account's own address, and the message goes out exactly as the form shows it. `compose()` opens a blank form and takes `{ to, cc, bcc, subject, text }` to prefill it.
208
+ When the form already holds unsaved changes, these first ask whether to save them as a draft. They resolve `false` if saving that draft failed and the form stayed as it was, `true` otherwise.
203
209
 
204
210
  ### `prepareResponse(msg, action, ownAddress?): object`
205
211
 
206
- The recipients, subject and reference of a `'reply'`, `'reply-all'` or `'forward'` of a message, as `reply()` and `forward()` prefill them: `{ to, cc, subject, reference }`. A reply goes to the message's Reply-To, otherwise its sender, or to its recipients when the account sent it. Useful for building a compose UI of your own.
212
+ The recipients, subject and reference of a `'reply'`, `'reply-all'` or `'forward'` of a message, as `reply()` and `forward()` prefill them: `{ to, cc, subject, reference }`, plus `attachments` for a forward (the original's files as `{ reference, filename, contentType, size }`). A reply goes to the message's Reply-To, otherwise its sender, or to its recipients when the account sent it. Useful for building a compose UI of your own.
207
213
 
208
214
  ### `parseAddressList(value)` / `formatAddressList(list)`
209
215
 
210
216
  Convert between a typed address field (`"Doe, John" <john@example.com>, jane@example.com`) and address entries.
211
217
 
212
- ### `saveDraft(to?, subject?, text?, options?): Promise<object>`
218
+ ### `saveDraft(message): Promise<object>`
219
+
220
+ Store a message as a draft instead of sending it (`POST /v1/account/{account}/message`). It takes the same message object as `sendMessage()`, and every field may be left out. The message is uploaded to the account's Drafts special-use folder with the `\Draft` flag set and the account's own name and address as the sender, so it can later be delivered with `submitDraft()`. A draft saved with a `reference` keeps the threading headers and the quote. Resolves to EmailEngine's upload response (`{ id, path, uid, ... }`).
213
221
 
214
- Store a plain-text message as a draft instead of sending it (`POST /v1/account/{account}/message`). The message is uploaded to the account's Drafts special-use folder with the `\Draft` flag set and the account's own name and address as the sender, so it can later be delivered with `submitDraft()`. `to` and `options` accept the same values as in `sendMessage()`, and `to` may be omitted for a draft without recipients. A draft saved with a `reference` keeps the threading headers and the quote. Resolves to EmailEngine's upload response (`{ id, path, uid, ... }`).
222
+ ### `updateDraft(messageId, message): Promise<object>`
223
+
224
+ Replace a stored draft with a new version. IMAP cannot change a stored message, so the new version is saved first and the old draft removed for good afterwards; attachments the new version references from the old draft are copied before it goes. If the old draft cannot be removed, the new one is kept and the failure only logged. Resolves to the upload response of the new version.
215
225
 
216
226
  ### `submitDraft(messageId: string, options?: SubmitDraftOptions): Promise<object>`
217
227
 
@@ -235,17 +245,29 @@ Set dark mode from the host application without touching the preference stored b
235
245
 
236
246
  Clean up the instance and clear the `sess_` token keep-alive interval. Always call this when you are finished with a client (for example when unmounting the UI) to avoid a leaked timer.
237
247
 
248
+ ## Upgrading from 1.x
249
+
250
+ 2.0 changes how messages are sent and how compose behaves:
251
+
252
+ - `sendMessage()` and `saveDraft()` take one message object. `sendMessage(to, subject, text, { cc })` becomes `sendMessage({ to, subject, text, cc })`; `saveDraft(to, subject, text, options)` becomes `saveDraft({ to, subject, text, ...options })`. The old form throws a `TypeError` instead of sending a message without its subject and text.
253
+ - `compose()` returns a promise, like `reply()` and `forward()`.
254
+ - A forward attaches the original's files one by one as references (`prepareResponse()` returns them in `attachments`, and its reference has `forwardAttachments: false`).
255
+ - The compose form is a docked panel without a backdrop (class `ee-compose`, formerly `ee-compose-modal`) and writes HTML through its editor; the message textarea is gone. Hosts that styled or scripted the old modal need updating.
256
+ - The folder list is loaded with `counters=true` to show unread counts.
257
+ - New: `updateDraft()` replaces a stored draft, and `editDraft()` opens one in the compose form; `ready` tells when the first view has loaded; `onMessageSent`, `onDraftSaved` and `onError` report outcomes to the host; `loadFolders({ counters })` asks for unread counts.
258
+
238
259
  ## Browser UI
239
260
 
240
261
  When a `container` is provided the client builds a full webmail interface:
241
262
 
242
- - Folder tree with special-folder ordering (Inbox, Drafts, Sent, Trash, Junk, Archive) and nested folders
243
- - Paginated message list with a selectable page size (persisted to `localStorage`)
263
+ - Folder tree with special-folder ordering (Inbox, Drafts, Sent, Trash, Junk, Archive), icons, unread counts and nested folders. The folder list is requested with `counters=true`, which costs one IMAP STATUS command per folder
264
+ - Paginated message list with its position ("1-20 of 45") and a selectable page size (persisted to `localStorage`) in a footer. Unread messages are marked with a dot and bold text; Drafts and Sent list the recipients instead of the sender
244
265
  - Message viewer with reply, reply all, forward, mark read/unread, delete, move-to-folder, download original, and attachment downloads
245
266
  - Replied and forwarded markers in the list and the viewer, from the `\Answered` and `$Forwarded` flags (IMAP accounts)
246
- - Draft messages show a "Send Draft" button that submits the stored draft for delivery after confirmation (requires EmailEngine v2.76.0 or later; editing the draft first is not supported)
267
+ - Draft messages open with an "Edit" button that continues the draft in the compose form, and a "Send draft" button that submits it as it is (requires EmailEngine v2.76.0 or later)
247
268
  - Quoted thread history collapsed behind a "Show quoted text" control
248
- - Compose form for sending plain-text mail: To, Cc and Bcc fields that take several addresses, file attachments, and a Save Draft option that stores the message in the Drafts folder instead of sending it. Replies and forwards show the original under the text box and can include the original attachments
269
+ - Compose form docked to the bottom right of the window (full screen on a phone), so the message being answered stays readable. It has a minimal rich text editor (bold, italic, lists, links), To, Cc and Bcc fields that take several addresses, file attachments, and Save draft. A reply's quote is folded behind a "..." control; a forward shows the forwarded message with its header and lists the original's files as attachments that can be removed one by one. Closing a form with unsaved changes asks whether to save them as a draft
270
+ - Folders, messages and attachments are buttons, reachable and usable from the keyboard
249
271
  - Dark mode toggle with the preference persisted to `localStorage`
250
272
  - Failed requests replace the affected pane's placeholder with an error panel and a Retry button
251
273
 
@@ -263,7 +285,9 @@ When opening a message the client scrolls the page only if its top is scrolled o
263
285
 
264
286
  ### Compose and notices
265
287
 
266
- On wide layouts the Compose button sits at the top of the folder pane; in the one-pane layout it is a floating button. Problems with a message (no recipient, an address that is not one, a send the server refused) are shown inside the compose form next to its buttons, and the form keeps what was typed. Outcomes that need no answer ("Message queued for delivery.", "Draft saved to the Drafts folder.", "Message moved to Trash.") appear as a short notice at the bottom of the client, which `notify(message)` can show from the host too. `alertMethod` is used for failures outside the form.
288
+ On wide layouts the Compose button sits at the top of the folder pane; in the one-pane layout it is a floating button. Problems with a message (no recipient, an address that is not one, a send the server refused) are shown inside the compose form next to its buttons, and the form keeps what was typed. Outcomes that need no answer ("Message queued for delivery.", "Draft saved.", "Message moved to Trash.") appear as a short notice at the bottom of the client, which `notify(message)` can show from the host too. `alertMethod` is used for failures outside the form.
289
+
290
+ The editor keeps paragraphs, bold, italic, underline, lists, quotes and `http`, `https` and `mailto` links. Pasted content and reopened drafts are filtered down to those; anything else keeps only its text. A reopened draft of a reply keeps its quote as editable text. A reply to or forward of a message that has no HTML part of its own is quoted into the HTML part by EmailEngine versions after 2.89.0; older versions quote it into the plain text part only.
267
291
 
268
292
  ### Dark mode and styled messages
269
293
 
@@ -307,14 +331,15 @@ Both methods receive the same arguments:
307
331
  - `cancelText` (string | null): cancel button text (`Cancel` for confirm, `null` for alert)
308
332
  - `okText` (string): confirm/OK button text (default `OK`)
309
333
 
310
- The client uses contextual titles such as `Delete Message`, `Validation Error`, `Success`, `Send Error`, and `Download Error`. `confirmMethod` should return a boolean (or a promise for one); `alertMethod` may be sync or async.
334
+ The client uses contextual titles such as `Delete Message`, `Validation Error`, `Success`, `Send Error`, and `Download Error`. `confirmMethod` should return a boolean (or a promise for one); `alertMethod` may be sync or async. When your dialog can be closed without either button (a close button, Escape, a click on the backdrop), have `confirmMethod` return `null` for that: the client then treats the question as unanswered. It matters for "Save the message you are writing as a draft?", whose cancel button discards the message, so a dismissed question keeps the message open instead. The browser's own `confirm()` has no such state, and a host that returns only booleans works as before.
311
335
 
312
336
  ## Security
313
337
 
314
338
  This library renders attacker-controlled email content, so it is careful about HTML injection:
315
339
 
316
340
  - All untrusted values (subjects, addresses, names, filenames, folder names) are HTML-escaped before being written to the DOM.
317
- - The one intentional raw-HTML sink is the message body itself. The client fetches it with EmailEngine's `webSafeHtml` option so the HTML arrives already pre-processed for safe embedding.
341
+ - The one intentional raw-HTML sink is the message body itself. The client fetches it with EmailEngine's `webSafeHtml` option so the HTML arrives already pre-processed for safe embedding, and renders it inside a shadow root so host styles and ids cannot reach it.
342
+ - HTML that enters the compose editor (pasted content, a reopened draft, `compose({ html })`) is parsed in an inert document and rebuilt from an allowlist of tags with no attributes except `http`, `https` and `mailto` link targets. The same filter runs on the HTML that is sent.
318
343
 
319
344
  Do not disable escaping or add new raw-HTML sinks when extending the UI.
320
345
 
package/index.d.ts CHANGED
@@ -11,10 +11,13 @@ export interface MessageFlags {
11
11
  export interface MessageText {
12
12
  html?: string;
13
13
  plain?: string;
14
+ /** Sizes of the parts as stored; a message without `html` here had no HTML part of its own */
15
+ encodedSize?: { plain?: number; html?: number };
14
16
  }
15
17
 
16
18
  export interface MessageStatus {
17
19
  messages: number;
20
+ unseen?: number;
18
21
  }
19
22
 
20
23
  export interface Folder {
@@ -36,6 +39,11 @@ export interface Attachment {
36
39
  filename?: string;
37
40
  contentType?: string;
38
41
  size?: number;
42
+ /** Size of the attachment as encoded in the message (base64), as EmailEngine reports it */
43
+ encodedSize?: number;
44
+ /** An image the HTML body shows in place; not listed as an attachment */
45
+ embedded?: boolean;
46
+ inline?: boolean;
39
47
  }
40
48
 
41
49
  /** One-time passcode of a message, from its OTP-Token header (EmailEngine 2.87+, experimental) */
@@ -73,9 +81,17 @@ export interface MessageListResponse {
73
81
  prevPageCursor?: string;
74
82
  }
75
83
 
84
+ /** Where the listed page sits in its folder, when the server reports it */
85
+ export interface ListPosition {
86
+ /** 0-based page number */
87
+ page: number;
88
+ /** Messages in the folder */
89
+ total: number;
90
+ }
91
+
76
92
  export type SendRecipient = string | EmailAddress;
77
93
 
78
- /** A file to attach, as the compose form reads it */
94
+ /** A file to attach: new content, base64 encoded */
79
95
  export interface ComposeAttachment {
80
96
  filename: string;
81
97
  contentType?: string;
@@ -83,22 +99,43 @@ export interface ComposeAttachment {
83
99
  content: string;
84
100
  }
85
101
 
102
+ /**
103
+ * An attachment of a stored message, attached by its EmailEngine attachment ID. The server
104
+ * fetches the content itself; filename and contentType are kept on the new message.
105
+ */
106
+ export interface ReferencedAttachment {
107
+ reference: string;
108
+ filename?: string;
109
+ contentType?: string;
110
+ /** Size in bytes, for display only; not sent */
111
+ size?: number;
112
+ }
113
+
86
114
  /** EmailEngine's submit reference block: what the message replies to or forwards */
87
115
  export interface MessageReference {
88
116
  message: string;
89
117
  action: 'reply' | 'reply-all' | 'forward';
90
118
  /** Quote the referenced message under the new text */
91
119
  inline?: boolean;
92
- /** Carry the referenced message's attachments over (forward only) */
120
+ /** Carry all of the referenced message's attachments over (forward only) */
93
121
  forwardAttachments?: boolean;
94
122
  }
95
123
 
96
- /** Optional fields for `sendMessage()` and `saveDraft()` */
97
- export interface ComposeOptions {
98
- cc?: SendRecipient | SendRecipient[];
99
- bcc?: SendRecipient | SendRecipient[];
100
- attachments?: ComposeAttachment[];
124
+ /** The message `sendMessage()`, `saveDraft()` and `updateDraft()` take */
125
+ export interface OutgoingMessage {
126
+ to?: SendRecipient | SendRecipient[] | null;
127
+ cc?: SendRecipient | SendRecipient[] | null;
128
+ bcc?: SendRecipient | SendRecipient[] | null;
129
+ subject?: string;
130
+ /** The plain text part */
131
+ text?: string;
132
+ /** The HTML part */
133
+ html?: string;
134
+ attachments?: Array<ComposeAttachment | ReferencedAttachment>;
135
+ /** What the message replies to or forwards; the server adds the threading headers and the quote */
101
136
  reference?: MessageReference | null;
137
+ /** Extra headers, e.g. the In-Reply-To and References of a reopened draft */
138
+ headers?: Record<string, string>;
102
139
  }
103
140
 
104
141
  /** Recipients, subject and reference of a reply, reply-all or forward, from `prepareResponse()` */
@@ -107,6 +144,8 @@ export interface PreparedResponse {
107
144
  cc: EmailAddress[];
108
145
  subject: string;
109
146
  reference: MessageReference;
147
+ /** A forward's files: the original's attachments as references, one per file */
148
+ attachments?: ReferencedAttachment[];
110
149
  }
111
150
 
112
151
  /** Prefill for `compose()`. Address fields take a typed string or address entries */
@@ -116,6 +155,8 @@ export interface ComposePrefill {
116
155
  bcc?: string | EmailAddress[];
117
156
  subject?: string;
118
157
  text?: string;
158
+ /** Rich text for the editor; filtered to paragraphs, emphasis, lists, quotes and http(s)/mailto links */
159
+ html?: string;
119
160
  }
120
161
 
121
162
  /** What `onNavigate` is told whenever the open folder or message changes */
@@ -147,7 +188,13 @@ export interface SubmitDraftOptions {
147
188
  * `(message, title, cancelText, okText)`; `cancelText` is `null` for alerts.
148
189
  * May be synchronous or asynchronous. Confirm handlers should resolve to a boolean.
149
190
  */
150
- export type DialogMethod = (message: string, title?: string, cancelText?: string | null, okText?: string) => boolean | void | Promise<boolean | void>;
191
+ /** A confirm resolves true for the OK button and false for the cancel button. A host dialog closed without either (its close button, Escape, the backdrop) may resolve null: the client then treats the question as unanswered, which keeps an unsaved message open. */
192
+ export type DialogMethod = (
193
+ message: string,
194
+ title?: string,
195
+ cancelText?: string | null,
196
+ okText?: string
197
+ ) => boolean | null | void | Promise<boolean | null | void>;
151
198
 
152
199
  export interface EmailEngineClientOptions {
153
200
  apiUrl?: string;
@@ -170,6 +217,19 @@ export interface EmailEngineClientOptions {
170
217
  onNavigate?: (state: NavigationState) => void;
171
218
  /** Total size limit for files attached in the compose form, in bytes (default 25 MB) */
172
219
  maxAttachmentSize?: number;
220
+ /** Called with EmailEngine's response whenever a message or a stored draft is queued for delivery */
221
+ onMessageSent?: (response: any) => void;
222
+ /** Called with EmailEngine's upload response whenever a draft is stored */
223
+ onDraftSaved?: (response: any) => void;
224
+ /** Called whenever a request fails, with what the client was doing */
225
+ onError?: (error: Error, context: ErrorContext) => void;
226
+ }
227
+
228
+ /** What `onError` is told about a failed request */
229
+ export interface ErrorContext {
230
+ action: 'loadFolders' | 'loadMessages' | 'loadMessage' | 'markAsRead' | 'delete' | 'move' | 'send' | 'saveDraft' | 'download';
231
+ /** The failure in words, e.g. "Failed to load the folders" */
232
+ description: string;
173
233
  }
174
234
 
175
235
  export declare class EmailEngineClient {
@@ -190,11 +250,20 @@ export declare class EmailEngineClient {
190
250
  messages: Message[];
191
251
  nextPageCursor: string | null;
192
252
  prevPageCursor: string | null;
253
+ listPosition: ListPosition | null;
254
+ /**
255
+ * Resolves once the first view (folders and a listing, or a deep-linked message) has loaded:
256
+ * true when it did, false when its requests failed and the panes show why (a deep-linked
257
+ * message that could not be opened does not count, the inbox is listed instead). Resolves true
258
+ * at once for an API-only client, and false outside a browser.
259
+ */
260
+ ready: Promise<boolean>;
193
261
 
194
262
  constructor(options?: EmailEngineClientOptions);
195
263
 
196
264
  apiRequest(method: string, endpoint: string, data?: any): Promise<any>;
197
- loadFolders(): Promise<Folder[]>;
265
+ /** Lists the folders; counters adds message and unread counts (default: true when the UI is rendered) */
266
+ loadFolders(options?: { counters?: boolean }): Promise<Folder[]>;
198
267
  /** Loads a page of a folder's message list; the open message stays open */
199
268
  loadMessages(path: string, cursor?: string | null): Promise<MessageListResponse>;
200
269
  /** Closes the open message and lists another folder */
@@ -206,20 +275,30 @@ export declare class EmailEngineClient {
206
275
  moveMessage(messageId: string, targetPath: string): Promise<boolean>;
207
276
  /** Opens a message by ID and lists the folder that holds it */
208
277
  openMessage(messageId: string): Promise<Message | null>;
209
- sendMessage(to: SendRecipient | SendRecipient[], subject: string, text: string, options?: ComposeOptions): Promise<any>;
210
- saveDraft(to?: SendRecipient | SendRecipient[] | null, subject?: string, text?: string, options?: ComposeOptions): Promise<any>;
278
+ /** Submits a message for delivery. Since 2.0 it takes one message object */
279
+ sendMessage(message: OutgoingMessage): Promise<any>;
280
+ /** Stores a message in the Drafts folder */
281
+ saveDraft(message: OutgoingMessage): Promise<any>;
282
+ /** Replaces a stored draft: saves the new version, then removes the old one for good */
283
+ updateDraft(messageId: string, message: OutgoingMessage): Promise<any>;
211
284
  /** Parses a typed address field ("Name <a@example.com>, b@example.com") into address entries */
212
285
  parseAddressList(value: string | null | undefined): EmailAddress[];
213
286
  /** Formats address entries for an address field; the reverse of parseAddressList() */
214
287
  formatAddressList(list: EmailAddress | EmailAddress[] | null | undefined): string;
215
288
  /** Recipients, subject and reference for answering msg; ownAddress is left out of the recipients */
216
289
  prepareResponse(msg: Message, action: 'reply' | 'reply-all' | 'forward', ownAddress?: string | null): PreparedResponse;
217
- /** Opens the compose form, optionally prefilled (needs the UI) */
218
- compose(prefill?: ComposePrefill): void;
219
- /** Opens the compose form as a reply to a message, the open one by default (needs the UI) */
220
- reply(messageId?: string | null, options?: { all?: boolean }): Promise<void>;
221
- /** Opens the compose form to forward a message, the open one by default (needs the UI) */
222
- forward(messageId?: string | null): Promise<void>;
290
+ /**
291
+ * Opens the compose form, optionally prefilled. Like reply(), forward() and editDraft() it
292
+ * needs the UI, and resolves false when an unsaved message stayed open instead (the user chose
293
+ * to save it as a draft and saving failed), true otherwise.
294
+ */
295
+ compose(prefill?: ComposePrefill): Promise<boolean>;
296
+ /** Opens the compose form as a reply to a message, the open one by default */
297
+ reply(messageId?: string | null, options?: { all?: boolean }): Promise<boolean>;
298
+ /** Opens the compose form to forward a message, the open one by default */
299
+ forward(messageId?: string | null): Promise<boolean>;
300
+ /** Opens a stored draft in the compose form, the open message by default */
301
+ editDraft(messageId?: string | null): Promise<boolean>;
223
302
  submitDraft(messageId: string, options?: SubmitDraftOptions | null): Promise<any>;
224
303
  downloadAttachment(attachmentId: string, suggestedFilename?: string): Promise<void>;
225
304
  downloadOriginalMessage(messageId: string, subject?: string): Promise<void>;