@postalsys/ee-client 1.9.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.
Files changed (4) hide show
  1. package/README.md +33 -7
  2. package/index.d.ts +79 -2
  3. package/index.js +1318 -333
  4. 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
- ### `sendMessage(to, subject, text): Promise<object>`
180
+ ### `openMessage(messageId: string): Promise<Message | null>`
178
181
 
179
- Send a plain-text email. `to` may be:
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
- ### `saveDraft(to?, subject?, text?): Promise<object>`
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` accepts the same values as `sendMessage()` and may be omitted for a draft without recipients. Resolves to EmailEngine's upload response (`{ id, path, uid, ... }`).
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, with a Save Draft option that stores the message in the Drafts folder instead of sending it
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
- sendMessage(to: SendRecipient | SendRecipient[], subject: string, text: string): Promise<any>;
144
- saveDraft(to?: SendRecipient | SendRecipient[] | null, subject?: string, text?: string): Promise<any>;
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>;