@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.
- package/README.md +23 -10
- package/index.d.ts +6 -0
- package/index.js +82 -16
- 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
|
|
119
|
-
|
|
|
120
|
-
| `account`
|
|
121
|
-
| `apiUrl`
|
|
122
|
-
| `accessToken`
|
|
123
|
-
| `container`
|
|
124
|
-
| `pageSize`
|
|
125
|
-
| `confirmMethod`
|
|
126
|
-
| `alertMethod`
|
|
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: -
|
|
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
|
-
|
|
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
|
-
|
|
1948
|
-
|
|
1949
|
-
|
|
1950
|
-
|
|
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.
|
|
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.
|
|
46
|
-
"prettier": "^3.
|
|
45
|
+
"eslint": "^8.57.1",
|
|
46
|
+
"prettier": "^3.9.5"
|
|
47
47
|
},
|
|
48
48
|
"peerDependencies": {
|
|
49
49
|
"node-fetch": "^3.0.0"
|