@postalsys/ee-client 1.8.0 → 1.8.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 (3) hide show
  1. package/README.md +12 -12
  2. package/index.js +150 -70
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -115,18 +115,18 @@ 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>` element the widget appends. Pass the page's Content-Security-Policy nonce when `style-src-elem` allows no inline stylesheet without one. |
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
130
 
131
131
  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
132
 
package/index.js CHANGED
@@ -1,3 +1,70 @@
1
+ // Stylesheet inside the message body's shadow root (see _renderMessageBody). Host rules do not
2
+ // reach in, so this carries everything the body needs: a reset on the host, the image cap, and
3
+ // the folded-thread control. Custom properties still inherit through the boundary, which is how
4
+ // the font and the dark mode colours arrive from .ee-client / .ee-dark-mode.
5
+ const MESSAGE_BODY_STYLES = `
6
+ :host {
7
+ all: initial;
8
+ display: block;
9
+ /* Nothing the message does paints outside this box, whatever its outermost wrapper says.
10
+ EmailEngine clips the message inside a wrapper of its own; this is the viewer's copy of
11
+ that rule, for a body rendered by a version whose wrapper the sender could still style.
12
+ clip, not hidden: the host must not become a scroll container of its own. */
13
+ overflow: clip;
14
+ color: inherit;
15
+ font-family: var(--ee-font, sans-serif);
16
+ font-size: 14px;
17
+ line-height: 1.6;
18
+ overflow-wrap: break-word;
19
+ }
20
+
21
+ *,
22
+ *::before,
23
+ *::after {
24
+ box-sizing: border-box;
25
+ }
26
+
27
+ img {
28
+ max-width: 100%;
29
+ height: auto;
30
+ }
31
+
32
+ /* Quoted thread history, folded away by EmailEngine - see _labelCollapsedThreads() */
33
+ .ee-collapsed-thread {
34
+ margin-top: 12px;
35
+ }
36
+
37
+ .ee-collapsed-thread-toggle {
38
+ display: inline-block;
39
+ padding: 4px 10px;
40
+ border: 1px solid var(--ee-toggle-border, #ddd);
41
+ border-radius: 4px;
42
+ background: var(--ee-toggle-bg, white);
43
+ color: var(--ee-toggle-color, inherit);
44
+ cursor: pointer;
45
+ /* The message brings its own fonts along; the control keeps the client's */
46
+ font-family: var(--ee-font, sans-serif);
47
+ font-size: 12px;
48
+ line-height: 1;
49
+ user-select: none;
50
+ list-style: none;
51
+ }
52
+
53
+ .ee-collapsed-thread-toggle:hover {
54
+ background: var(--ee-toggle-hover-bg, #f0f0f0);
55
+ border-color: var(--ee-toggle-hover-border, #ddd);
56
+ }
57
+
58
+ /* Same, for Safari before it supported list-style on a summary */
59
+ .ee-collapsed-thread-toggle::-webkit-details-marker {
60
+ display: none;
61
+ }
62
+
63
+ .ee-collapsed-thread[open] > .ee-collapsed-thread-toggle {
64
+ margin-bottom: 12px;
65
+ }
66
+ `;
67
+
1
68
  export class EmailEngineClient {
2
69
  constructor(options = {}) {
3
70
  this.apiUrl = options.apiUrl || 'http://127.0.0.1:3000';
@@ -148,13 +215,27 @@ export class EmailEngineClient {
148
215
  return await response.json();
149
216
  }
150
217
 
218
+ // Base path for this account's endpoints. The id is a path segment, so characters such as
219
+ // '#', '?', '/' or '%' in it must be encoded or they cut or redirect the request.
220
+ _accountPath() {
221
+ return `/v1/account/${encodeURIComponent(this.account)}`;
222
+ }
223
+
224
+ _messagePath(messageId, suffix = '') {
225
+ return `${this._accountPath()}/message/${encodeURIComponent(messageId)}${suffix}`;
226
+ }
227
+
228
+ _attachmentPath(attachmentId) {
229
+ return `${this._accountPath()}/attachment/${encodeURIComponent(attachmentId)}`;
230
+ }
231
+
151
232
  async loadFolders() {
152
233
  // Reset the pane to its loading state so a retry after a failure does not
153
234
  // keep showing the previous error while the new request is in flight.
154
235
  this._setPaneHtml('.ee-folder-tree', '<div class="ee-loading">Loading folders...</div>');
155
236
 
156
237
  try {
157
- const data = await this.apiRequest('GET', `/v1/account/${this.account}/mailboxes`);
238
+ const data = await this.apiRequest('GET', `${this._accountPath()}/mailboxes`);
158
239
  this.folders = data.mailboxes || [];
159
240
  this._folderTreeCache = null;
160
241
  if (this.container) {
@@ -177,7 +258,7 @@ export class EmailEngineClient {
177
258
  params.set('cursor', cursor);
178
259
  }
179
260
 
180
- const data = await this.apiRequest('GET', `/v1/account/${this.account}/messages?${params}`);
261
+ const data = await this.apiRequest('GET', `${this._accountPath()}/messages?${params}`);
181
262
  this.messages = data.messages || [];
182
263
  this.currentFolder = path;
183
264
  this.nextPageCursor = data.nextPageCursor || null;
@@ -214,7 +295,7 @@ export class EmailEngineClient {
214
295
  webSafeHtml: true,
215
296
  markAsSeen: true
216
297
  });
217
- const data = await this.apiRequest('GET', `/v1/account/${this.account}/message/${messageId}?${params}`);
298
+ const data = await this.apiRequest('GET', this._messagePath(messageId, `?${params}`));
218
299
  this.currentMessage = data;
219
300
 
220
301
  this.currentMessage.unseen = false;
@@ -254,7 +335,7 @@ export class EmailEngineClient {
254
335
  try {
255
336
  const flagUpdate = seen ? { flags: { add: ['\\Seen'] } } : { flags: { delete: ['\\Seen'] } };
256
337
 
257
- await this.apiRequest('PUT', `/v1/account/${this.account}/message/${messageId}`, flagUpdate);
338
+ await this.apiRequest('PUT', this._messagePath(messageId), flagUpdate);
258
339
 
259
340
  const msg = this.messages.find(m => m.id === messageId);
260
341
  if (msg) {
@@ -280,7 +361,7 @@ export class EmailEngineClient {
280
361
 
281
362
  async deleteMessage(messageId) {
282
363
  try {
283
- await this.apiRequest('DELETE', `/v1/account/${this.account}/message/${messageId}`);
364
+ await this.apiRequest('DELETE', this._messagePath(messageId));
284
365
 
285
366
  this.messages = this.messages.filter(m => m.id !== messageId);
286
367
  if (this.container) {
@@ -303,7 +384,7 @@ export class EmailEngineClient {
303
384
 
304
385
  async moveMessage(messageId, targetPath) {
305
386
  try {
306
- await this.apiRequest('PUT', `/v1/account/${this.account}/message/${messageId}/move`, {
387
+ await this.apiRequest('PUT', this._messagePath(messageId, '/move'), {
307
388
  path: targetPath
308
389
  });
309
390
 
@@ -336,7 +417,7 @@ export class EmailEngineClient {
336
417
  // of the instance; used as the From identity of saved drafts.
337
418
  async _getAccountInfo() {
338
419
  if (!this._accountInfo) {
339
- this._accountInfo = await this.apiRequest('GET', `/v1/account/${this.account}`);
420
+ this._accountInfo = await this.apiRequest('GET', this._accountPath());
340
421
  }
341
422
  return this._accountInfo;
342
423
  }
@@ -349,7 +430,7 @@ export class EmailEngineClient {
349
430
  text: text
350
431
  };
351
432
 
352
- const response = await this.apiRequest('POST', `/v1/account/${this.account}/submit`, messageData);
433
+ const response = await this.apiRequest('POST', `${this._accountPath()}/submit`, messageData);
353
434
  return response;
354
435
  } catch (error) {
355
436
  console.error('Failed to send message:', error);
@@ -390,7 +471,7 @@ export class EmailEngineClient {
390
471
  // Non-fatal: the draft is saved without a From header
391
472
  }
392
473
 
393
- const response = await this.apiRequest('POST', `/v1/account/${this.account}/message`, messageData);
474
+ const response = await this.apiRequest('POST', `${this._accountPath()}/message`, messageData);
394
475
  return response;
395
476
  } catch (error) {
396
477
  console.error('Failed to save draft:', error);
@@ -400,11 +481,7 @@ export class EmailEngineClient {
400
481
 
401
482
  async submitDraft(messageId, options = null) {
402
483
  try {
403
- const response = await this.apiRequest(
404
- 'POST',
405
- `/v1/account/${this.account}/message/${messageId}/submit`,
406
- options
407
- );
484
+ const response = await this.apiRequest('POST', this._messagePath(messageId, '/submit'), options);
408
485
  return response;
409
486
  } catch (error) {
410
487
  console.error('Failed to submit draft:', error);
@@ -618,7 +695,7 @@ export class EmailEngineClient {
618
695
 
619
696
  async downloadAttachment(attachmentId, suggestedFilename = null) {
620
697
  try {
621
- const response = await this._fetchBlob(`/v1/account/${this.account}/attachment/${attachmentId}`);
698
+ const response = await this._fetchBlob(this._attachmentPath(attachmentId));
622
699
 
623
700
  // Get filename from Content-Disposition header if available
624
701
  const contentDisposition = response.headers.get('content-disposition');
@@ -646,7 +723,7 @@ export class EmailEngineClient {
646
723
 
647
724
  async downloadOriginalMessage(messageId, subject = null) {
648
725
  try {
649
- const response = await this._fetchBlob(`/v1/account/${this.account}/message/${messageId}/source`);
726
+ const response = await this._fetchBlob(this._messagePath(messageId, '/source'));
650
727
 
651
728
  // Get the email data
652
729
  const blob = await response.blob();
@@ -669,17 +746,24 @@ export class EmailEngineClient {
669
746
  }
670
747
  }
671
748
 
672
- createStyles() {
673
- if (typeof document === 'undefined') {
674
- return;
675
- }
676
-
749
+ // A <style> element carrying styleNonce, for the widget stylesheet and the message body's
750
+ // shadow root alike: a stylesheet inside a shadow root is checked against style-src-elem too.
751
+ _createStyle(css) {
677
752
  const style = document.createElement('style');
678
753
  if (this.styleNonce) {
679
754
  // the IDL property, which is what the policy check reads on an element a script inserts
680
755
  style.nonce = this.styleNonce;
681
756
  }
682
- style.textContent = `
757
+ style.textContent = css;
758
+ return style;
759
+ }
760
+
761
+ createStyles() {
762
+ if (typeof document === 'undefined') {
763
+ return;
764
+ }
765
+
766
+ const style = this._createStyle(`
683
767
  .ee-client {
684
768
  --ee-font: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
685
769
  display: flex;
@@ -879,8 +963,7 @@ export class EmailEngineClient {
879
963
  box-shadow: 0 1px 3px rgba(0,0,0,0.1);
880
964
  }
881
965
 
882
- .ee-button,
883
- .ee-collapsed-thread-toggle {
966
+ .ee-button {
884
967
  padding: 4px 10px;
885
968
  border: 1px solid #ddd;
886
969
  background: white;
@@ -897,8 +980,7 @@ export class EmailEngineClient {
897
980
  height: 24px;
898
981
  }
899
982
 
900
- .ee-button:hover:not(:disabled),
901
- .ee-collapsed-thread-toggle:hover {
983
+ .ee-button:hover:not(:disabled) {
902
984
  background: #f0f0f0;
903
985
  }
904
986
 
@@ -932,38 +1014,6 @@ export class EmailEngineClient {
932
1014
  font-weight: 500;
933
1015
  }
934
1016
 
935
- .ee-message-body {
936
- line-height: 1.6;
937
- }
938
-
939
- .ee-message-body img {
940
- max-width: 100%;
941
- height: auto;
942
- }
943
-
944
- /* Quoted thread history, folded away by EmailEngine - see _labelCollapsedThreads() */
945
- .ee-collapsed-thread {
946
- margin-top: 12px;
947
- }
948
-
949
- .ee-collapsed-thread-toggle {
950
- display: inline-block;
951
- height: auto;
952
- /* The message brings its own fonts along; the control keeps the client's */
953
- font-family: var(--ee-font);
954
- user-select: none;
955
- list-style: none;
956
- }
957
-
958
- /* Same, for Safari before it supported list-style on a summary */
959
- .ee-collapsed-thread-toggle::-webkit-details-marker {
960
- display: none;
961
- }
962
-
963
- .ee-collapsed-thread[open] > .ee-collapsed-thread-toggle {
964
- margin-bottom: 12px;
965
- }
966
-
967
1017
  .ee-attachments {
968
1018
  margin-top: 16px;
969
1019
  padding-top: 16px;
@@ -1436,6 +1486,15 @@ export class EmailEngineClient {
1436
1486
  color: #e0e0e0;
1437
1487
  }
1438
1488
 
1489
+ /* Read inside the message body's shadow root, where .ee-dark-mode selectors cannot reach */
1490
+ .ee-dark-mode {
1491
+ --ee-toggle-bg: #333;
1492
+ --ee-toggle-border: #444;
1493
+ --ee-toggle-color: #e0e0e0;
1494
+ --ee-toggle-hover-bg: #444;
1495
+ --ee-toggle-hover-border: #555;
1496
+ }
1497
+
1439
1498
  .ee-dark-mode .ee-message-viewer {
1440
1499
  background: #1a1a1a;
1441
1500
  }
@@ -1445,15 +1504,13 @@ export class EmailEngineClient {
1445
1504
  border-color: #333;
1446
1505
  }
1447
1506
 
1448
- .ee-dark-mode .ee-button,
1449
- .ee-dark-mode .ee-collapsed-thread-toggle {
1507
+ .ee-dark-mode .ee-button {
1450
1508
  background: #333;
1451
1509
  border-color: #444;
1452
1510
  color: #e0e0e0;
1453
1511
  }
1454
1512
 
1455
- .ee-dark-mode .ee-button:hover,
1456
- .ee-dark-mode .ee-collapsed-thread-toggle:hover {
1513
+ .ee-dark-mode .ee-button:hover {
1457
1514
  background: #444;
1458
1515
  border-color: #555;
1459
1516
  }
@@ -1564,7 +1621,7 @@ export class EmailEngineClient {
1564
1621
  background: #66b2ff;
1565
1622
  color: #1a1a1a;
1566
1623
  }
1567
- `;
1624
+ `);
1568
1625
  document.head.appendChild(style);
1569
1626
  this._styleElement = style;
1570
1627
  }
@@ -1861,9 +1918,7 @@ export class EmailEngineClient {
1861
1918
  ${this.escapeHtml(msg.subject || '(no subject)')}
1862
1919
  </div>
1863
1920
  </div>
1864
- <div class="ee-message-body">
1865
- ${msg.text && msg.text.html ? msg.text.html : msg.text && msg.text.plain ? `<pre>${this.escapeHtml(msg.text.plain)}</pre>` : ''}
1866
- </div>
1921
+ <div class="ee-message-body"></div>
1867
1922
  ${
1868
1923
  msg.attachments && msg.attachments.length > 0
1869
1924
  ? `
@@ -1890,7 +1945,8 @@ export class EmailEngineClient {
1890
1945
  `;
1891
1946
  viewer.innerHTML = html;
1892
1947
 
1893
- this._labelCollapsedThreads(viewer);
1948
+ const bodyRoot = this._renderMessageBody(viewer.querySelector('.ee-message-body'), msg);
1949
+ this._labelCollapsedThreads(bodyRoot);
1894
1950
 
1895
1951
  const sendDraftButton = viewer.querySelector('[data-action="send-draft"]');
1896
1952
  if (sendDraftButton) {
@@ -1976,6 +2032,30 @@ export class EmailEngineClient {
1976
2032
  // Message content scrolling is now handled in loadMessage method
1977
2033
  }
1978
2034
 
2035
+ // The message body goes into a shadow root on its container. Sanitised message HTML still
2036
+ // carries class and id attributes, and in the host document those would pick up the host's
2037
+ // own stylesheet (a utility class like "fixed inset-0" could cover the whole page) or collide
2038
+ // with its ids. Inside the shadow root no host selector matches, while the message's inline
2039
+ // style attributes keep working. The host element is the same .ee-message-body as before, so
2040
+ // sizing and scrolling of the viewer are unchanged.
2041
+ _renderMessageBody(host, msg) {
2042
+ const root = host.attachShadow({ mode: 'open' });
2043
+ const style = this._createStyle(MESSAGE_BODY_STYLES);
2044
+
2045
+ const content = document.createElement('div');
2046
+ content.className = 'ee-message-body-content';
2047
+ if (msg.text && msg.text.html) {
2048
+ content.innerHTML = msg.text.html;
2049
+ } else if (msg.text && msg.text.plain) {
2050
+ const pre = document.createElement('pre');
2051
+ pre.textContent = msg.text.plain;
2052
+ content.appendChild(pre);
2053
+ }
2054
+
2055
+ root.replaceChildren(style, content);
2056
+ return root;
2057
+ }
2058
+
1979
2059
  // EmailEngine's web-safe HTML folds quoted thread history (reply history, forwarded content,
1980
2060
  // disclaimers) into a <details class="ee-collapsed-thread"> whose <summary> it leaves empty on
1981
2061
  // purpose, for the renderer to label. The fold is closed until the reader opens it.
@@ -1983,8 +2063,8 @@ export class EmailEngineClient {
1983
2063
  // A sender can put the same markup in their own HTML - it survives sanitization - so every
1984
2064
  // match is relabelled rather than trusted, and the control always reads as one of these two
1985
2065
  // labels instead of whatever text came with the message.
1986
- _labelCollapsedThreads(viewer) {
1987
- viewer.querySelectorAll('details.ee-collapsed-thread > summary.ee-collapsed-thread-toggle').forEach(toggle => {
2066
+ _labelCollapsedThreads(root) {
2067
+ root.querySelectorAll('details.ee-collapsed-thread > summary.ee-collapsed-thread-toggle').forEach(toggle => {
1988
2068
  const details = toggle.parentElement;
1989
2069
  const applyLabel = () => {
1990
2070
  toggle.textContent = details.open ? 'Hide quoted text' : 'Show quoted text';
@@ -2381,7 +2461,7 @@ export class EmailEngineClient {
2381
2461
  async _keepTokenAlive() {
2382
2462
  try {
2383
2463
  // Ping account endpoint to keep token alive
2384
- await this.apiRequest('GET', `/v1/account/${this.account}`);
2464
+ await this.apiRequest('GET', this._accountPath());
2385
2465
  console.debug('Keep-alive ping sent for sess_ token');
2386
2466
  } catch (error) {
2387
2467
  console.warn('Keep-alive ping failed:', error.message);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@postalsys/ee-client",
3
- "version": "1.8.0",
3
+ "version": "1.8.2",
4
4
  "description": "EmailEngine client library for browser and Node.js applications",
5
5
  "main": "index.js",
6
6
  "module": "index.js",
@@ -43,7 +43,7 @@
43
43
  },
44
44
  "devDependencies": {
45
45
  "eslint": "^8.57.1",
46
- "prettier": "^3.9.6"
46
+ "prettier": "^3.9.9"
47
47
  },
48
48
  "peerDependencies": {
49
49
  "node-fetch": "^3.0.0"