@postalsys/ee-client 1.8.0 → 1.8.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 (3) hide show
  1. package/README.md +12 -12
  2. package/index.js +145 -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,65 @@
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
+ color: inherit;
10
+ font-family: var(--ee-font, sans-serif);
11
+ font-size: 14px;
12
+ line-height: 1.6;
13
+ overflow-wrap: break-word;
14
+ }
15
+
16
+ *,
17
+ *::before,
18
+ *::after {
19
+ box-sizing: border-box;
20
+ }
21
+
22
+ img {
23
+ max-width: 100%;
24
+ height: auto;
25
+ }
26
+
27
+ /* Quoted thread history, folded away by EmailEngine - see _labelCollapsedThreads() */
28
+ .ee-collapsed-thread {
29
+ margin-top: 12px;
30
+ }
31
+
32
+ .ee-collapsed-thread-toggle {
33
+ display: inline-block;
34
+ padding: 4px 10px;
35
+ border: 1px solid var(--ee-toggle-border, #ddd);
36
+ border-radius: 4px;
37
+ background: var(--ee-toggle-bg, white);
38
+ color: var(--ee-toggle-color, inherit);
39
+ cursor: pointer;
40
+ /* The message brings its own fonts along; the control keeps the client's */
41
+ font-family: var(--ee-font, sans-serif);
42
+ font-size: 12px;
43
+ line-height: 1;
44
+ user-select: none;
45
+ list-style: none;
46
+ }
47
+
48
+ .ee-collapsed-thread-toggle:hover {
49
+ background: var(--ee-toggle-hover-bg, #f0f0f0);
50
+ border-color: var(--ee-toggle-hover-border, #ddd);
51
+ }
52
+
53
+ /* Same, for Safari before it supported list-style on a summary */
54
+ .ee-collapsed-thread-toggle::-webkit-details-marker {
55
+ display: none;
56
+ }
57
+
58
+ .ee-collapsed-thread[open] > .ee-collapsed-thread-toggle {
59
+ margin-bottom: 12px;
60
+ }
61
+ `;
62
+
1
63
  export class EmailEngineClient {
2
64
  constructor(options = {}) {
3
65
  this.apiUrl = options.apiUrl || 'http://127.0.0.1:3000';
@@ -148,13 +210,27 @@ export class EmailEngineClient {
148
210
  return await response.json();
149
211
  }
150
212
 
213
+ // Base path for this account's endpoints. The id is a path segment, so characters such as
214
+ // '#', '?', '/' or '%' in it must be encoded or they cut or redirect the request.
215
+ _accountPath() {
216
+ return `/v1/account/${encodeURIComponent(this.account)}`;
217
+ }
218
+
219
+ _messagePath(messageId, suffix = '') {
220
+ return `${this._accountPath()}/message/${encodeURIComponent(messageId)}${suffix}`;
221
+ }
222
+
223
+ _attachmentPath(attachmentId) {
224
+ return `${this._accountPath()}/attachment/${encodeURIComponent(attachmentId)}`;
225
+ }
226
+
151
227
  async loadFolders() {
152
228
  // Reset the pane to its loading state so a retry after a failure does not
153
229
  // keep showing the previous error while the new request is in flight.
154
230
  this._setPaneHtml('.ee-folder-tree', '<div class="ee-loading">Loading folders...</div>');
155
231
 
156
232
  try {
157
- const data = await this.apiRequest('GET', `/v1/account/${this.account}/mailboxes`);
233
+ const data = await this.apiRequest('GET', `${this._accountPath()}/mailboxes`);
158
234
  this.folders = data.mailboxes || [];
159
235
  this._folderTreeCache = null;
160
236
  if (this.container) {
@@ -177,7 +253,7 @@ export class EmailEngineClient {
177
253
  params.set('cursor', cursor);
178
254
  }
179
255
 
180
- const data = await this.apiRequest('GET', `/v1/account/${this.account}/messages?${params}`);
256
+ const data = await this.apiRequest('GET', `${this._accountPath()}/messages?${params}`);
181
257
  this.messages = data.messages || [];
182
258
  this.currentFolder = path;
183
259
  this.nextPageCursor = data.nextPageCursor || null;
@@ -214,7 +290,7 @@ export class EmailEngineClient {
214
290
  webSafeHtml: true,
215
291
  markAsSeen: true
216
292
  });
217
- const data = await this.apiRequest('GET', `/v1/account/${this.account}/message/${messageId}?${params}`);
293
+ const data = await this.apiRequest('GET', this._messagePath(messageId, `?${params}`));
218
294
  this.currentMessage = data;
219
295
 
220
296
  this.currentMessage.unseen = false;
@@ -254,7 +330,7 @@ export class EmailEngineClient {
254
330
  try {
255
331
  const flagUpdate = seen ? { flags: { add: ['\\Seen'] } } : { flags: { delete: ['\\Seen'] } };
256
332
 
257
- await this.apiRequest('PUT', `/v1/account/${this.account}/message/${messageId}`, flagUpdate);
333
+ await this.apiRequest('PUT', this._messagePath(messageId), flagUpdate);
258
334
 
259
335
  const msg = this.messages.find(m => m.id === messageId);
260
336
  if (msg) {
@@ -280,7 +356,7 @@ export class EmailEngineClient {
280
356
 
281
357
  async deleteMessage(messageId) {
282
358
  try {
283
- await this.apiRequest('DELETE', `/v1/account/${this.account}/message/${messageId}`);
359
+ await this.apiRequest('DELETE', this._messagePath(messageId));
284
360
 
285
361
  this.messages = this.messages.filter(m => m.id !== messageId);
286
362
  if (this.container) {
@@ -303,7 +379,7 @@ export class EmailEngineClient {
303
379
 
304
380
  async moveMessage(messageId, targetPath) {
305
381
  try {
306
- await this.apiRequest('PUT', `/v1/account/${this.account}/message/${messageId}/move`, {
382
+ await this.apiRequest('PUT', this._messagePath(messageId, '/move'), {
307
383
  path: targetPath
308
384
  });
309
385
 
@@ -336,7 +412,7 @@ export class EmailEngineClient {
336
412
  // of the instance; used as the From identity of saved drafts.
337
413
  async _getAccountInfo() {
338
414
  if (!this._accountInfo) {
339
- this._accountInfo = await this.apiRequest('GET', `/v1/account/${this.account}`);
415
+ this._accountInfo = await this.apiRequest('GET', this._accountPath());
340
416
  }
341
417
  return this._accountInfo;
342
418
  }
@@ -349,7 +425,7 @@ export class EmailEngineClient {
349
425
  text: text
350
426
  };
351
427
 
352
- const response = await this.apiRequest('POST', `/v1/account/${this.account}/submit`, messageData);
428
+ const response = await this.apiRequest('POST', `${this._accountPath()}/submit`, messageData);
353
429
  return response;
354
430
  } catch (error) {
355
431
  console.error('Failed to send message:', error);
@@ -390,7 +466,7 @@ export class EmailEngineClient {
390
466
  // Non-fatal: the draft is saved without a From header
391
467
  }
392
468
 
393
- const response = await this.apiRequest('POST', `/v1/account/${this.account}/message`, messageData);
469
+ const response = await this.apiRequest('POST', `${this._accountPath()}/message`, messageData);
394
470
  return response;
395
471
  } catch (error) {
396
472
  console.error('Failed to save draft:', error);
@@ -400,11 +476,7 @@ export class EmailEngineClient {
400
476
 
401
477
  async submitDraft(messageId, options = null) {
402
478
  try {
403
- const response = await this.apiRequest(
404
- 'POST',
405
- `/v1/account/${this.account}/message/${messageId}/submit`,
406
- options
407
- );
479
+ const response = await this.apiRequest('POST', this._messagePath(messageId, '/submit'), options);
408
480
  return response;
409
481
  } catch (error) {
410
482
  console.error('Failed to submit draft:', error);
@@ -618,7 +690,7 @@ export class EmailEngineClient {
618
690
 
619
691
  async downloadAttachment(attachmentId, suggestedFilename = null) {
620
692
  try {
621
- const response = await this._fetchBlob(`/v1/account/${this.account}/attachment/${attachmentId}`);
693
+ const response = await this._fetchBlob(this._attachmentPath(attachmentId));
622
694
 
623
695
  // Get filename from Content-Disposition header if available
624
696
  const contentDisposition = response.headers.get('content-disposition');
@@ -646,7 +718,7 @@ export class EmailEngineClient {
646
718
 
647
719
  async downloadOriginalMessage(messageId, subject = null) {
648
720
  try {
649
- const response = await this._fetchBlob(`/v1/account/${this.account}/message/${messageId}/source`);
721
+ const response = await this._fetchBlob(this._messagePath(messageId, '/source'));
650
722
 
651
723
  // Get the email data
652
724
  const blob = await response.blob();
@@ -669,17 +741,24 @@ export class EmailEngineClient {
669
741
  }
670
742
  }
671
743
 
672
- createStyles() {
673
- if (typeof document === 'undefined') {
674
- return;
675
- }
676
-
744
+ // A <style> element carrying styleNonce, for the widget stylesheet and the message body's
745
+ // shadow root alike: a stylesheet inside a shadow root is checked against style-src-elem too.
746
+ _createStyle(css) {
677
747
  const style = document.createElement('style');
678
748
  if (this.styleNonce) {
679
749
  // the IDL property, which is what the policy check reads on an element a script inserts
680
750
  style.nonce = this.styleNonce;
681
751
  }
682
- style.textContent = `
752
+ style.textContent = css;
753
+ return style;
754
+ }
755
+
756
+ createStyles() {
757
+ if (typeof document === 'undefined') {
758
+ return;
759
+ }
760
+
761
+ const style = this._createStyle(`
683
762
  .ee-client {
684
763
  --ee-font: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
685
764
  display: flex;
@@ -879,8 +958,7 @@ export class EmailEngineClient {
879
958
  box-shadow: 0 1px 3px rgba(0,0,0,0.1);
880
959
  }
881
960
 
882
- .ee-button,
883
- .ee-collapsed-thread-toggle {
961
+ .ee-button {
884
962
  padding: 4px 10px;
885
963
  border: 1px solid #ddd;
886
964
  background: white;
@@ -897,8 +975,7 @@ export class EmailEngineClient {
897
975
  height: 24px;
898
976
  }
899
977
 
900
- .ee-button:hover:not(:disabled),
901
- .ee-collapsed-thread-toggle:hover {
978
+ .ee-button:hover:not(:disabled) {
902
979
  background: #f0f0f0;
903
980
  }
904
981
 
@@ -932,38 +1009,6 @@ export class EmailEngineClient {
932
1009
  font-weight: 500;
933
1010
  }
934
1011
 
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
1012
  .ee-attachments {
968
1013
  margin-top: 16px;
969
1014
  padding-top: 16px;
@@ -1436,6 +1481,15 @@ export class EmailEngineClient {
1436
1481
  color: #e0e0e0;
1437
1482
  }
1438
1483
 
1484
+ /* Read inside the message body's shadow root, where .ee-dark-mode selectors cannot reach */
1485
+ .ee-dark-mode {
1486
+ --ee-toggle-bg: #333;
1487
+ --ee-toggle-border: #444;
1488
+ --ee-toggle-color: #e0e0e0;
1489
+ --ee-toggle-hover-bg: #444;
1490
+ --ee-toggle-hover-border: #555;
1491
+ }
1492
+
1439
1493
  .ee-dark-mode .ee-message-viewer {
1440
1494
  background: #1a1a1a;
1441
1495
  }
@@ -1445,15 +1499,13 @@ export class EmailEngineClient {
1445
1499
  border-color: #333;
1446
1500
  }
1447
1501
 
1448
- .ee-dark-mode .ee-button,
1449
- .ee-dark-mode .ee-collapsed-thread-toggle {
1502
+ .ee-dark-mode .ee-button {
1450
1503
  background: #333;
1451
1504
  border-color: #444;
1452
1505
  color: #e0e0e0;
1453
1506
  }
1454
1507
 
1455
- .ee-dark-mode .ee-button:hover,
1456
- .ee-dark-mode .ee-collapsed-thread-toggle:hover {
1508
+ .ee-dark-mode .ee-button:hover {
1457
1509
  background: #444;
1458
1510
  border-color: #555;
1459
1511
  }
@@ -1564,7 +1616,7 @@ export class EmailEngineClient {
1564
1616
  background: #66b2ff;
1565
1617
  color: #1a1a1a;
1566
1618
  }
1567
- `;
1619
+ `);
1568
1620
  document.head.appendChild(style);
1569
1621
  this._styleElement = style;
1570
1622
  }
@@ -1861,9 +1913,7 @@ export class EmailEngineClient {
1861
1913
  ${this.escapeHtml(msg.subject || '(no subject)')}
1862
1914
  </div>
1863
1915
  </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>
1916
+ <div class="ee-message-body"></div>
1867
1917
  ${
1868
1918
  msg.attachments && msg.attachments.length > 0
1869
1919
  ? `
@@ -1890,7 +1940,8 @@ export class EmailEngineClient {
1890
1940
  `;
1891
1941
  viewer.innerHTML = html;
1892
1942
 
1893
- this._labelCollapsedThreads(viewer);
1943
+ const bodyRoot = this._renderMessageBody(viewer.querySelector('.ee-message-body'), msg);
1944
+ this._labelCollapsedThreads(bodyRoot);
1894
1945
 
1895
1946
  const sendDraftButton = viewer.querySelector('[data-action="send-draft"]');
1896
1947
  if (sendDraftButton) {
@@ -1976,6 +2027,30 @@ export class EmailEngineClient {
1976
2027
  // Message content scrolling is now handled in loadMessage method
1977
2028
  }
1978
2029
 
2030
+ // The message body goes into a shadow root on its container. Sanitised message HTML still
2031
+ // carries class and id attributes, and in the host document those would pick up the host's
2032
+ // own stylesheet (a utility class like "fixed inset-0" could cover the whole page) or collide
2033
+ // with its ids. Inside the shadow root no host selector matches, while the message's inline
2034
+ // style attributes keep working. The host element is the same .ee-message-body as before, so
2035
+ // sizing and scrolling of the viewer are unchanged.
2036
+ _renderMessageBody(host, msg) {
2037
+ const root = host.attachShadow({ mode: 'open' });
2038
+ const style = this._createStyle(MESSAGE_BODY_STYLES);
2039
+
2040
+ const content = document.createElement('div');
2041
+ content.className = 'ee-message-body-content';
2042
+ if (msg.text && msg.text.html) {
2043
+ content.innerHTML = msg.text.html;
2044
+ } else if (msg.text && msg.text.plain) {
2045
+ const pre = document.createElement('pre');
2046
+ pre.textContent = msg.text.plain;
2047
+ content.appendChild(pre);
2048
+ }
2049
+
2050
+ root.replaceChildren(style, content);
2051
+ return root;
2052
+ }
2053
+
1979
2054
  // EmailEngine's web-safe HTML folds quoted thread history (reply history, forwarded content,
1980
2055
  // disclaimers) into a <details class="ee-collapsed-thread"> whose <summary> it leaves empty on
1981
2056
  // purpose, for the renderer to label. The fold is closed until the reader opens it.
@@ -1983,8 +2058,8 @@ export class EmailEngineClient {
1983
2058
  // A sender can put the same markup in their own HTML - it survives sanitization - so every
1984
2059
  // match is relabelled rather than trusted, and the control always reads as one of these two
1985
2060
  // 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 => {
2061
+ _labelCollapsedThreads(root) {
2062
+ root.querySelectorAll('details.ee-collapsed-thread > summary.ee-collapsed-thread-toggle').forEach(toggle => {
1988
2063
  const details = toggle.parentElement;
1989
2064
  const applyLabel = () => {
1990
2065
  toggle.textContent = details.open ? 'Hide quoted text' : 'Show quoted text';
@@ -2381,7 +2456,7 @@ export class EmailEngineClient {
2381
2456
  async _keepTokenAlive() {
2382
2457
  try {
2383
2458
  // Ping account endpoint to keep token alive
2384
- await this.apiRequest('GET', `/v1/account/${this.account}`);
2459
+ await this.apiRequest('GET', this._accountPath());
2385
2460
  console.debug('Keep-alive ping sent for sess_ token');
2386
2461
  } catch (error) {
2387
2462
  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.1",
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"