@postalsys/ee-client 1.4.0 → 1.6.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 +23 -10
  2. package/index.d.ts +6 -0
  3. package/index.js +82 -16
  4. package/package.json +3 -3
package/README.md CHANGED
@@ -115,15 +115,17 @@ 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`. |
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). |
127
129
 
128
130
  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.
129
131
 
@@ -155,7 +157,7 @@ Load a page of messages from a folder. Pass `nextPageCursor` / `prevPageCursor`
155
157
 
156
158
  ### `loadMessage(messageId: string): Promise<Message>`
157
159
 
158
- Load a single message. HTML is requested with `webSafeHtml=true`, so EmailEngine returns it pre-processed with inline images embedded for safe display, and the message is marked as seen.
160
+ Load a single message. HTML is requested with `webSafeHtml=true`, so EmailEngine returns it pre-processed with inline images embedded for safe display, and the message is marked as seen. Web-safe HTML also folds quoted thread history (reply history, forwarded content, disclaimers) into a `<details class="ee-collapsed-thread">` element - see [Quoted thread history](#quoted-thread-history).
159
161
 
160
162
  ### `markAsRead(messageId: string, seen?: boolean): Promise<boolean>`
161
163
 
@@ -187,6 +189,10 @@ Browser only. Fetch an attachment and trigger a download, using the filename fro
187
189
 
188
190
  Browser only. Download the raw message source as an `.eml` file.
189
191
 
192
+ ### `setDarkMode(enabled: boolean): void`
193
+
194
+ Set dark mode from the host application without touching the preference stored by the builtin toggle. Combine with `showDarkModeToggle: false` to keep the rendered UI in sync with the host page's own theme switch.
195
+
190
196
  ### `destroy(): void`
191
197
 
192
198
  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.
@@ -198,9 +204,16 @@ When a `container` is provided the client builds a full webmail interface:
198
204
  - Folder tree with special-folder ordering (Inbox, Drafts, Sent, Trash, Junk, Archive) and nested folders
199
205
  - Paginated message list with a selectable page size (persisted to `localStorage`)
200
206
  - Message viewer with mark read/unread, delete, move-to-folder, download original, and attachment downloads
207
+ - Quoted thread history collapsed behind a "Show quoted text" control
201
208
  - Compose modal (floating button) for sending plain-text mail
202
209
  - Dark mode toggle with the preference persisted to `localStorage`
203
210
 
211
+ ### Quoted thread history
212
+
213
+ EmailEngine's web-safe HTML wraps the quoted tail of a reply - reply history, forwarded content, disclaimers - in a single `<details class="ee-collapsed-thread">` element with an empty `<summary class="ee-collapsed-thread-toggle">`, leaving the label to the renderer. The message viewer labels that summary ("Show quoted text" / "Hide quoted text") and styles it as a button, so only what the sender actually wrote is visible until the reader asks for the rest. Messages with no quoted tail carry no such element and render unchanged.
214
+
215
+ Operators can turn the folding off server side with `EENGINE_DISABLE_THREAD_COLLAPSE=true`; older EmailEngine versions simply never emit the element.
216
+
204
217
  ### Custom dialogs
205
218
 
206
219
  Provide `confirmMethod` and `alertMethod` to route confirmations and alerts through your own modal system instead of the browser defaults - useful when integrating with a UI framework:
package/index.d.ts CHANGED
@@ -80,6 +80,10 @@ export interface EmailEngineClientOptions {
80
80
  pageSize?: number;
81
81
  confirmMethod?: DialogMethod;
82
82
  alertMethod?: DialogMethod;
83
+ /** Initial dark mode; overrides the preference stored by the builtin toggle */
84
+ darkMode?: boolean;
85
+ /** Render the builtin dark mode toggle button (default true); set false when the host drives the mode through setDarkMode() */
86
+ showDarkModeToggle?: boolean;
83
87
  }
84
88
 
85
89
  export declare class EmailEngineClient {
@@ -91,6 +95,7 @@ export declare class EmailEngineClient {
91
95
  alertMethod: DialogMethod;
92
96
  pageSize: number;
93
97
  darkMode: boolean;
98
+ showDarkModeToggle: boolean;
94
99
  currentFolder: string | null;
95
100
  currentMessage: Message | null;
96
101
  folders: Folder[];
@@ -120,6 +125,7 @@ export declare class EmailEngineClient {
120
125
  renderMessage(): void;
121
126
  createLayout(): void;
122
127
  init(): void;
128
+ setDarkMode(enabled: boolean): void;
123
129
  toggleDarkMode(): void;
124
130
  destroy(): void;
125
131
  }
package/index.js CHANGED
@@ -39,11 +39,18 @@ export class EmailEngineClient {
39
39
  this.keepAliveTimer = null;
40
40
  this.lastActivity = Date.now();
41
41
 
42
- // Dark mode state
42
+ // Dark mode state. An explicit darkMode option overrides the stored
43
+ // preference - for hosts that manage the theme themselves (usually
44
+ // together with showDarkModeToggle: false to hide the builtin button
45
+ // and drive the mode through setDarkMode()).
43
46
  this.darkMode = false;
44
47
  if (typeof window !== 'undefined' && window.localStorage) {
45
48
  this.darkMode = localStorage.getItem('ee-client-dark-mode') === 'true';
46
49
  }
50
+ if (typeof options.darkMode === 'boolean') {
51
+ this.darkMode = options.darkMode;
52
+ }
53
+ this.showDarkModeToggle = options.showDarkModeToggle !== false;
47
54
 
48
55
  // Get page size from localStorage or options or default
49
56
  const savedPageSize =
@@ -481,10 +488,11 @@ export class EmailEngineClient {
481
488
  const style = document.createElement('style');
482
489
  style.textContent = `
483
490
  .ee-client {
491
+ --ee-font: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
484
492
  display: flex;
485
493
  height: 100%;
486
494
  min-height: 400px;
487
- font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
495
+ font-family: var(--ee-font);
488
496
  font-size: 14px;
489
497
  line-height: 1.5;
490
498
  color: #333;
@@ -678,7 +686,8 @@ export class EmailEngineClient {
678
686
  box-shadow: 0 1px 3px rgba(0,0,0,0.1);
679
687
  }
680
688
 
681
- .ee-button {
689
+ .ee-button,
690
+ .ee-collapsed-thread-toggle {
682
691
  padding: 4px 10px;
683
692
  border: 1px solid #ddd;
684
693
  background: white;
@@ -695,7 +704,8 @@ export class EmailEngineClient {
695
704
  height: 24px;
696
705
  }
697
706
 
698
- .ee-button:hover:not(:disabled) {
707
+ .ee-button:hover:not(:disabled),
708
+ .ee-collapsed-thread-toggle:hover {
699
709
  background: #f0f0f0;
700
710
  }
701
711
 
@@ -737,7 +747,30 @@ export class EmailEngineClient {
737
747
  max-width: 100%;
738
748
  height: auto;
739
749
  }
740
-
750
+
751
+ /* Quoted thread history, folded away by EmailEngine - see _labelCollapsedThreads() */
752
+ .ee-collapsed-thread {
753
+ margin-top: 12px;
754
+ }
755
+
756
+ .ee-collapsed-thread-toggle {
757
+ display: inline-block;
758
+ height: auto;
759
+ /* The message brings its own fonts along; the control keeps the client's */
760
+ font-family: var(--ee-font);
761
+ user-select: none;
762
+ list-style: none;
763
+ }
764
+
765
+ /* Same, for Safari before it supported list-style on a summary */
766
+ .ee-collapsed-thread-toggle::-webkit-details-marker {
767
+ display: none;
768
+ }
769
+
770
+ .ee-collapsed-thread[open] > .ee-collapsed-thread-toggle {
771
+ margin-bottom: 12px;
772
+ }
773
+
741
774
  .ee-attachments {
742
775
  margin-top: 16px;
743
776
  padding-top: 16px;
@@ -1177,13 +1210,15 @@ export class EmailEngineClient {
1177
1210
  border-color: #333;
1178
1211
  }
1179
1212
 
1180
- .ee-dark-mode .ee-button {
1213
+ .ee-dark-mode .ee-button,
1214
+ .ee-dark-mode .ee-collapsed-thread-toggle {
1181
1215
  background: #333;
1182
1216
  border-color: #444;
1183
1217
  color: #e0e0e0;
1184
1218
  }
1185
1219
 
1186
- .ee-dark-mode .ee-button:hover {
1220
+ .ee-dark-mode .ee-button:hover,
1221
+ .ee-dark-mode .ee-collapsed-thread-toggle:hover {
1187
1222
  background: #444;
1188
1223
  border-color: #555;
1189
1224
  }
@@ -1603,6 +1638,8 @@ export class EmailEngineClient {
1603
1638
  `;
1604
1639
  viewer.innerHTML = html;
1605
1640
 
1641
+ this._labelCollapsedThreads(viewer);
1642
+
1606
1643
  viewer.querySelector('[data-action="toggle-read"]').addEventListener('click', () => {
1607
1644
  const currentlyUnseen = msg.unseen;
1608
1645
  this.markAsRead(msg.id, currentlyUnseen);
@@ -1643,6 +1680,25 @@ export class EmailEngineClient {
1643
1680
  // Message content scrolling is now handled in loadMessage method
1644
1681
  }
1645
1682
 
1683
+ // EmailEngine's web-safe HTML folds quoted thread history (reply history, forwarded content,
1684
+ // disclaimers) into a <details class="ee-collapsed-thread"> whose <summary> it leaves empty on
1685
+ // purpose, for the renderer to label. The fold is closed until the reader opens it.
1686
+ //
1687
+ // A sender can put the same markup in their own HTML - it survives sanitization - so every
1688
+ // match is relabelled rather than trusted, and the control always reads as one of these two
1689
+ // labels instead of whatever text came with the message.
1690
+ _labelCollapsedThreads(viewer) {
1691
+ viewer.querySelectorAll('details.ee-collapsed-thread > summary.ee-collapsed-thread-toggle').forEach(toggle => {
1692
+ const details = toggle.parentElement;
1693
+ const applyLabel = () => {
1694
+ toggle.textContent = details.open ? 'Hide quoted text' : 'Show quoted text';
1695
+ };
1696
+
1697
+ applyLabel();
1698
+ details.addEventListener('toggle', applyLabel);
1699
+ });
1700
+ }
1701
+
1646
1702
  createLayout() {
1647
1703
  if (typeof document === 'undefined' || !this.container) {
1648
1704
  return;
@@ -1650,9 +1706,13 @@ export class EmailEngineClient {
1650
1706
 
1651
1707
  this.container.innerHTML = `
1652
1708
  <div class="ee-client${this.darkMode ? ' ee-dark-mode' : ''}">
1653
- <button class="ee-dark-mode-toggle" title="Toggle dark mode">
1709
+ ${
1710
+ this.showDarkModeToggle
1711
+ ? `<button class="ee-dark-mode-toggle" title="Toggle dark mode">
1654
1712
  <span class="ee-dark-mode-icon">${this.darkMode ? '☀️' : '🌙'}</span>
1655
- </button>
1713
+ </button>`
1714
+ : ''
1715
+ }
1656
1716
  <div class="ee-sidebar">
1657
1717
  <div class="ee-pane-header">
1658
1718
  <span class="ee-pane-title">Folders</span>
@@ -1944,13 +2004,10 @@ export class EmailEngineClient {
1944
2004
  }
1945
2005
  }
1946
2006
 
1947
- toggleDarkMode() {
1948
- this.darkMode = !this.darkMode;
1949
-
1950
- // Save preference
1951
- if (typeof window !== 'undefined' && window.localStorage) {
1952
- localStorage.setItem('ee-client-dark-mode', this.darkMode.toString());
1953
- }
2007
+ // Set dark mode from the host application (does not touch the stored
2008
+ // preference - the builtin toggle owns that)
2009
+ setDarkMode(enabled) {
2010
+ this.darkMode = !!enabled;
1954
2011
 
1955
2012
  // DOM updates only apply to the rendered UI; skip without a container
1956
2013
  if (!this.container) {
@@ -1974,6 +2031,15 @@ export class EmailEngineClient {
1974
2031
  }
1975
2032
  }
1976
2033
 
2034
+ toggleDarkMode() {
2035
+ this.setDarkMode(!this.darkMode);
2036
+
2037
+ // Save preference
2038
+ if (typeof window !== 'undefined' && window.localStorage) {
2039
+ localStorage.setItem('ee-client-dark-mode', this.darkMode.toString());
2040
+ }
2041
+ }
2042
+
1977
2043
  destroy() {
1978
2044
  // Mark destroyed first so any in-flight async completion skips
1979
2045
  // re-rendering into a torn-down or recreated container.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@postalsys/ee-client",
3
- "version": "1.4.0",
3
+ "version": "1.6.0",
4
4
  "description": "EmailEngine client library for browser and Node.js applications",
5
5
  "main": "index.js",
6
6
  "module": "index.js",
@@ -42,8 +42,8 @@
42
42
  "node": ">=14.0.0"
43
43
  },
44
44
  "devDependencies": {
45
- "eslint": "^8.57.0",
46
- "prettier": "^3.2.5"
45
+ "eslint": "^8.57.1",
46
+ "prettier": "^3.9.5"
47
47
  },
48
48
  "peerDependencies": {
49
49
  "node-fetch": "^3.0.0"