@postalsys/ee-client 1.10.0 → 1.11.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.
- package/README.md +33 -7
- package/index.d.ts +79 -2
- package/index.js +870 -183
- package/package.json +8 -4
package/README.md
CHANGED
|
@@ -127,6 +127,9 @@ new EmailEngineClient(options);
|
|
|
127
127
|
| `darkMode` | `boolean` | stored preference | Initial dark mode. Overrides the preference stored by the builtin toggle. |
|
|
128
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
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. |
|
|
130
133
|
|
|
131
134
|
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.
|
|
132
135
|
|
|
@@ -154,7 +157,7 @@ Load all folders/mailboxes for the account. Renders the folder tree when a conta
|
|
|
154
157
|
|
|
155
158
|
### `loadMessages(path: string, cursor?: string): Promise<MessageListResponse>`
|
|
156
159
|
|
|
157
|
-
Load a page of messages from a folder. Pass `nextPageCursor` / `prevPageCursor` from a previous response to paginate. Resolves to `{ messages, nextPageCursor, prevPageCursor }`.
|
|
160
|
+
Load a page of messages from a folder. Pass `nextPageCursor` / `prevPageCursor` from a previous response to paginate. Resolves to `{ messages, nextPageCursor, prevPageCursor }`. The open message stays open; `openFolder(path)` closes it and lists another folder, which is what a click in the folder tree does.
|
|
158
161
|
|
|
159
162
|
### `loadMessage(messageId: string): Promise<Message>`
|
|
160
163
|
|
|
@@ -174,19 +177,41 @@ Delete a message (EmailEngine moves it to Trash, or removes it if already in Tra
|
|
|
174
177
|
|
|
175
178
|
Move a message to another folder.
|
|
176
179
|
|
|
177
|
-
### `
|
|
180
|
+
### `openMessage(messageId: string): Promise<Message | null>`
|
|
178
181
|
|
|
179
|
-
|
|
182
|
+
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
|
+
|
|
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:
|
|
180
187
|
|
|
181
188
|
- a string address: `'user@example.com'`
|
|
182
189
|
- an object: `{ name: 'John Doe', address: 'john@example.com' }`
|
|
183
190
|
- an array of strings and/or objects for multiple recipients
|
|
184
191
|
|
|
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)
|
|
197
|
+
|
|
185
198
|
Resolves to EmailEngine's submit response.
|
|
186
199
|
|
|
187
|
-
### `
|
|
200
|
+
### `reply(messageId?, { all }?)`, `forward(messageId?)`, `compose(prefill?)`
|
|
201
|
+
|
|
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.
|
|
203
|
+
|
|
204
|
+
### `prepareResponse(msg, action, ownAddress?): object`
|
|
205
|
+
|
|
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.
|
|
207
|
+
|
|
208
|
+
### `parseAddressList(value)` / `formatAddressList(list)`
|
|
209
|
+
|
|
210
|
+
Convert between a typed address field (`"Doe, John" <john@example.com>, jane@example.com`) and address entries.
|
|
211
|
+
|
|
212
|
+
### `saveDraft(to?, subject?, text?, options?): Promise<object>`
|
|
188
213
|
|
|
189
|
-
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`
|
|
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, ... }`).
|
|
190
215
|
|
|
191
216
|
### `submitDraft(messageId: string, options?: SubmitDraftOptions): Promise<object>`
|
|
192
217
|
|
|
@@ -216,10 +241,11 @@ When a `container` is provided the client builds a full webmail interface:
|
|
|
216
241
|
|
|
217
242
|
- Folder tree with special-folder ordering (Inbox, Drafts, Sent, Trash, Junk, Archive) and nested folders
|
|
218
243
|
- Paginated message list with a selectable page size (persisted to `localStorage`)
|
|
219
|
-
- Message viewer with mark read/unread, delete, move-to-folder, download original, and attachment downloads
|
|
244
|
+
- Message viewer with reply, reply all, forward, mark read/unread, delete, move-to-folder, download original, and attachment downloads
|
|
245
|
+
- Replied and forwarded markers in the list and the viewer, from the `\Answered` and `$Forwarded` flags (IMAP accounts)
|
|
220
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)
|
|
221
247
|
- Quoted thread history collapsed behind a "Show quoted text" control
|
|
222
|
-
- Compose modal (floating button) for sending plain-text mail,
|
|
248
|
+
- Compose modal (floating button) 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
|
|
223
249
|
- Dark mode toggle with the preference persisted to `localStorage`
|
|
224
250
|
- Failed requests replace the affected pane's placeholder with an error panel and a Retry button
|
|
225
251
|
|
package/index.d.ts
CHANGED
|
@@ -53,7 +53,10 @@ export interface Message {
|
|
|
53
53
|
from?: EmailAddress;
|
|
54
54
|
to?: EmailAddress[];
|
|
55
55
|
cc?: EmailAddress[];
|
|
56
|
+
replyTo?: EmailAddress[];
|
|
56
57
|
date: string;
|
|
58
|
+
/** IMAP-style flags, e.g. "\\Seen", "\\Answered", "$Forwarded" */
|
|
59
|
+
flags?: string[];
|
|
57
60
|
unseen: boolean;
|
|
58
61
|
draft?: boolean;
|
|
59
62
|
/** Special-use flag of the folder the message is stored in, e.g. "\\Drafts" */
|
|
@@ -72,6 +75,55 @@ export interface MessageListResponse {
|
|
|
72
75
|
|
|
73
76
|
export type SendRecipient = string | EmailAddress;
|
|
74
77
|
|
|
78
|
+
/** A file to attach, as the compose form reads it */
|
|
79
|
+
export interface ComposeAttachment {
|
|
80
|
+
filename: string;
|
|
81
|
+
contentType?: string;
|
|
82
|
+
/** Base64 encoded file content */
|
|
83
|
+
content: string;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** EmailEngine's submit reference block: what the message replies to or forwards */
|
|
87
|
+
export interface MessageReference {
|
|
88
|
+
message: string;
|
|
89
|
+
action: 'reply' | 'reply-all' | 'forward';
|
|
90
|
+
/** Quote the referenced message under the new text */
|
|
91
|
+
inline?: boolean;
|
|
92
|
+
/** Carry the referenced message's attachments over (forward only) */
|
|
93
|
+
forwardAttachments?: boolean;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/** Optional fields for `sendMessage()` and `saveDraft()` */
|
|
97
|
+
export interface ComposeOptions {
|
|
98
|
+
cc?: SendRecipient | SendRecipient[];
|
|
99
|
+
bcc?: SendRecipient | SendRecipient[];
|
|
100
|
+
attachments?: ComposeAttachment[];
|
|
101
|
+
reference?: MessageReference | null;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** Recipients, subject and reference of a reply, reply-all or forward, from `prepareResponse()` */
|
|
105
|
+
export interface PreparedResponse {
|
|
106
|
+
to: EmailAddress[];
|
|
107
|
+
cc: EmailAddress[];
|
|
108
|
+
subject: string;
|
|
109
|
+
reference: MessageReference;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/** Prefill for `compose()`. Address fields take a typed string or address entries */
|
|
113
|
+
export interface ComposePrefill {
|
|
114
|
+
to?: string | EmailAddress[];
|
|
115
|
+
cc?: string | EmailAddress[];
|
|
116
|
+
bcc?: string | EmailAddress[];
|
|
117
|
+
subject?: string;
|
|
118
|
+
text?: string;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/** What `onNavigate` is told whenever the open folder or message changes */
|
|
122
|
+
export interface NavigationState {
|
|
123
|
+
path: string | null;
|
|
124
|
+
messageId: string | null;
|
|
125
|
+
}
|
|
126
|
+
|
|
75
127
|
/**
|
|
76
128
|
* Optional payload for `submitDraft()`. Mirrors the SubmitDraft schema of the
|
|
77
129
|
* EmailEngine API; all fields are optional and most only apply to SMTP deliveries.
|
|
@@ -112,6 +164,12 @@ export interface EmailEngineClientOptions {
|
|
|
112
164
|
showDarkModeToggle?: boolean;
|
|
113
165
|
/** CSP nonce set on the <style> element the widget appends, for a host page whose style-src-elem requires one */
|
|
114
166
|
styleNonce?: string;
|
|
167
|
+
/** EmailEngine message ID to open on startup (with its folder) instead of the inbox */
|
|
168
|
+
message?: string;
|
|
169
|
+
/** Called whenever the open folder or message changes, e.g. to keep the address bar in step */
|
|
170
|
+
onNavigate?: (state: NavigationState) => void;
|
|
171
|
+
/** Total size limit for files attached in the compose form, in bytes (default 25 MB) */
|
|
172
|
+
maxAttachmentSize?: number;
|
|
115
173
|
}
|
|
116
174
|
|
|
117
175
|
export declare class EmailEngineClient {
|
|
@@ -126,6 +184,8 @@ export declare class EmailEngineClient {
|
|
|
126
184
|
showDarkModeToggle: boolean;
|
|
127
185
|
currentFolder: string | null;
|
|
128
186
|
currentMessage: Message | null;
|
|
187
|
+
onNavigate: ((state: NavigationState) => void) | null;
|
|
188
|
+
maxAttachmentSize: number;
|
|
129
189
|
folders: Folder[];
|
|
130
190
|
messages: Message[];
|
|
131
191
|
nextPageCursor: string | null;
|
|
@@ -135,13 +195,30 @@ export declare class EmailEngineClient {
|
|
|
135
195
|
|
|
136
196
|
apiRequest(method: string, endpoint: string, data?: any): Promise<any>;
|
|
137
197
|
loadFolders(): Promise<Folder[]>;
|
|
198
|
+
/** Loads a page of a folder's message list; the open message stays open */
|
|
138
199
|
loadMessages(path: string, cursor?: string | null): Promise<MessageListResponse>;
|
|
200
|
+
/** Closes the open message and lists another folder */
|
|
201
|
+
openFolder(path: string): Promise<MessageListResponse>;
|
|
139
202
|
loadMessage(messageId: string): Promise<Message>;
|
|
140
203
|
markAsRead(messageId: string, seen?: boolean): Promise<boolean>;
|
|
141
204
|
deleteMessage(messageId: string): Promise<boolean>;
|
|
142
205
|
moveMessage(messageId: string, targetPath: string): Promise<boolean>;
|
|
143
|
-
|
|
144
|
-
|
|
206
|
+
/** Opens a message by ID and lists the folder that holds it */
|
|
207
|
+
openMessage(messageId: string): Promise<Message | null>;
|
|
208
|
+
sendMessage(to: SendRecipient | SendRecipient[], subject: string, text: string, options?: ComposeOptions): Promise<any>;
|
|
209
|
+
saveDraft(to?: SendRecipient | SendRecipient[] | null, subject?: string, text?: string, options?: ComposeOptions): Promise<any>;
|
|
210
|
+
/** Parses a typed address field ("Name <a@example.com>, b@example.com") into address entries */
|
|
211
|
+
parseAddressList(value: string | null | undefined): EmailAddress[];
|
|
212
|
+
/** Formats address entries for an address field; the reverse of parseAddressList() */
|
|
213
|
+
formatAddressList(list: EmailAddress | EmailAddress[] | null | undefined): string;
|
|
214
|
+
/** Recipients, subject and reference for answering msg; ownAddress is left out of the recipients */
|
|
215
|
+
prepareResponse(msg: Message, action: 'reply' | 'reply-all' | 'forward', ownAddress?: string | null): PreparedResponse;
|
|
216
|
+
/** Opens the compose form, optionally prefilled (needs the UI) */
|
|
217
|
+
compose(prefill?: ComposePrefill): void;
|
|
218
|
+
/** Opens the compose form as a reply to a message, the open one by default (needs the UI) */
|
|
219
|
+
reply(messageId?: string | null, options?: { all?: boolean }): Promise<void>;
|
|
220
|
+
/** Opens the compose form to forward a message, the open one by default (needs the UI) */
|
|
221
|
+
forward(messageId?: string | null): Promise<void>;
|
|
145
222
|
submitDraft(messageId: string, options?: SubmitDraftOptions | null): Promise<any>;
|
|
146
223
|
downloadAttachment(attachmentId: string, suggestedFilename?: string): Promise<void>;
|
|
147
224
|
downloadOriginalMessage(messageId: string, subject?: string): Promise<void>;
|