@postalsys/ee-client 1.7.0 → 1.8.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 +6 -0
  2. package/index.d.ts +2 -0
  3. package/index.js +256 -102
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -126,6 +126,7 @@ new EmailEngineClient(options);
126
126
  | `alertMethod` | `function` | browser `alert()` | Custom alert dialog, `(message, title, cancelText, okText)` where `cancelText` is `null`. |
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
+ | `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. |
129
130
 
130
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.
131
132
 
@@ -218,6 +219,11 @@ When a `container` is provided the client builds a full webmail interface:
218
219
  - Quoted thread history collapsed behind a "Show quoted text" control
219
220
  - 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
220
221
  - Dark mode toggle with the preference persisted to `localStorage`
222
+ - Failed requests replace the affected pane's placeholder with an error panel and a Retry button
223
+
224
+ ### Failed requests
225
+
226
+ When a request behind a pane fails, that pane shows why instead of sitting on its "Loading..." placeholder. The reason is the message EmailEngine returned - for example "Requested account is not yet initialized" for an account that has not connected yet, or "Requested mailbox folder was not found" - and a Retry button re-runs the request. If the server could not be reached at all, the panel says so and names the configured `apiUrl`. The underlying promise still rejects, so callers driving the client programmatically can handle the error themselves.
221
227
 
222
228
  ### Quoted thread history
223
229
 
package/index.d.ts CHANGED
@@ -105,6 +105,8 @@ export interface EmailEngineClientOptions {
105
105
  darkMode?: boolean;
106
106
  /** Render the builtin dark mode toggle button (default true); set false when the host drives the mode through setDarkMode() */
107
107
  showDarkModeToggle?: boolean;
108
+ /** CSP nonce set on the <style> element the widget appends, for a host page whose style-src-elem requires one */
109
+ styleNonce?: string;
108
110
  }
109
111
 
110
112
  export declare class EmailEngineClient {
package/index.js CHANGED
@@ -52,6 +52,10 @@ export class EmailEngineClient {
52
52
  }
53
53
  this.showDarkModeToggle = options.showDarkModeToggle !== false;
54
54
 
55
+ // The nonce a Content-Security-Policy page hands the widget so the <style> element
56
+ // createStyles() appends passes a style-src-elem directive without 'unsafe-inline'
57
+ this.styleNonce = typeof options.styleNonce === 'string' && options.styleNonce ? options.styleNonce : null;
58
+
55
59
  // Get page size from localStorage or options or default
56
60
  const savedPageSize =
57
61
  typeof window !== 'undefined' && window.localStorage ? localStorage.getItem('ee-client-page-size') : null;
@@ -66,23 +70,13 @@ export class EmailEngineClient {
66
70
  this._startKeepAliveTimer();
67
71
  }
68
72
 
69
- async apiRequest(method, endpoint, data = null) {
70
- // Update activity timestamp for keep-alive
73
+ // Resolves the platform fetch (native in browsers and modern Node, node-fetch as
74
+ // an optional fallback on older Node) and normalizes transport failures, so both
75
+ // HTTP entry points - apiRequest and _fetchBlob - fail in the same shape.
76
+ async _fetch(url, options) {
77
+ // Any request counts as activity for the keep-alive timer
71
78
  this._updateActivity();
72
79
 
73
- const url = `${this.apiUrl}${endpoint}`;
74
- const options = {
75
- method: method,
76
- headers: {
77
- 'Content-Type': 'application/json',
78
- ...this._authHeaders()
79
- }
80
- };
81
-
82
- if (data) {
83
- options.body = JSON.stringify(data);
84
- }
85
-
86
80
  let fetchFn = globalThis.fetch;
87
81
  if (!fetchFn) {
88
82
  // Native fetch is missing (older Node.js). Fall back to node-fetch.
@@ -102,26 +96,63 @@ export class EmailEngineClient {
102
96
  );
103
97
  }
104
98
 
105
- const response = await fetchFn(url, options);
106
- if (!response.ok) {
107
- let errorDetails;
108
- try {
109
- errorDetails = await response.json();
110
- } catch (parseError) {
111
- // If JSON parsing fails, fall back to status text
112
- errorDetails = { message: response.statusText };
99
+ try {
100
+ return await fetchFn(url, options);
101
+ } catch (err) {
102
+ // Mark transport level failures - an unreachable server, DNS/TLS
103
+ // problems, a blocked CORS preflight - so callers can tell them apart
104
+ // from an API error that carries a server message.
105
+ const error = new Error(`Could not reach the EmailEngine server at ${this.apiUrl}`);
106
+ error.isNetworkError = true;
107
+ error.cause = err;
108
+ throw error;
109
+ }
110
+ }
111
+
112
+ // Turns a non-ok response into an Error carrying the server's own explanation.
113
+ // EmailEngine answers with Boom payloads - { statusCode, error, message, code,
114
+ // fields } - which _errorMessage() knows how to read.
115
+ async _responseError(response) {
116
+ let details;
117
+ try {
118
+ details = await response.json();
119
+ } catch (parseError) {
120
+ // Not a JSON body - the status line is all there is to go on
121
+ details = { message: response.statusText };
122
+ }
123
+
124
+ const error = new Error(`API request failed: ${response.statusText}`);
125
+ error.statusCode = response.status;
126
+ error.details = details;
127
+ return error;
128
+ }
129
+
130
+ async apiRequest(method, endpoint, data = null) {
131
+ const options = {
132
+ method: method,
133
+ headers: {
134
+ 'Content-Type': 'application/json',
135
+ ...this._authHeaders()
113
136
  }
137
+ };
114
138
 
115
- const error = new Error(`API request failed: ${response.statusText}`);
116
- error.statusCode = response.status;
117
- error.details = errorDetails;
118
- throw error;
139
+ if (data) {
140
+ options.body = JSON.stringify(data);
141
+ }
142
+
143
+ const response = await this._fetch(`${this.apiUrl}${endpoint}`, options);
144
+ if (!response.ok) {
145
+ throw await this._responseError(response);
119
146
  }
120
147
 
121
148
  return await response.json();
122
149
  }
123
150
 
124
151
  async loadFolders() {
152
+ // Reset the pane to its loading state so a retry after a failure does not
153
+ // keep showing the previous error while the new request is in flight.
154
+ this._setPaneHtml('.ee-folder-tree', '<div class="ee-loading">Loading folders...</div>');
155
+
125
156
  try {
126
157
  const data = await this.apiRequest('GET', `/v1/account/${this.account}/mailboxes`);
127
158
  this.folders = data.mailboxes || [];
@@ -132,17 +163,13 @@ export class EmailEngineClient {
132
163
  return this.folders;
133
164
  } catch (error) {
134
165
  console.error('Failed to load folders:', error);
166
+ this._renderPaneError('.ee-folder-tree', 'Folders unavailable', error, () => this._loadInitialView());
135
167
  throw error;
136
168
  }
137
169
  }
138
170
 
139
171
  async loadMessages(path, cursor = null) {
140
- if (this.container) {
141
- const messageList = this.container.querySelector('.ee-message-list');
142
- if (messageList) {
143
- messageList.innerHTML = '<div class="ee-loading">Loading messages...</div>';
144
- }
145
- }
172
+ this._setPaneHtml('.ee-message-list', '<div class="ee-loading">Loading messages...</div>');
146
173
 
147
174
  try {
148
175
  const params = new URLSearchParams({ path: path, pageSize: this.pageSize });
@@ -172,23 +199,15 @@ export class EmailEngineClient {
172
199
  };
173
200
  } catch (error) {
174
201
  console.error('Failed to load messages:', error);
175
- if (this.container) {
176
- const messageList = this.container.querySelector('.ee-message-list');
177
- if (messageList) {
178
- messageList.innerHTML = '<div class="ee-error">Failed to load messages</div>';
179
- }
180
- }
202
+ this._renderPaneError('.ee-message-list', 'Messages unavailable', error, () =>
203
+ this._fireAndForget(this.loadMessages(path, cursor))
204
+ );
181
205
  throw error;
182
206
  }
183
207
  }
184
208
 
185
209
  async loadMessage(messageId) {
186
- if (this.container) {
187
- const viewer = this.container.querySelector('.ee-message-viewer');
188
- if (viewer) {
189
- viewer.innerHTML = '<div class="ee-loading">Loading message...</div>';
190
- }
191
- }
210
+ this._setPaneHtml('.ee-message-viewer', '<div class="ee-loading">Loading message...</div>');
192
211
 
193
212
  try {
194
213
  const params = new URLSearchParams({
@@ -224,12 +243,9 @@ export class EmailEngineClient {
224
243
  return this.currentMessage;
225
244
  } catch (error) {
226
245
  console.error('Failed to load message:', error);
227
- if (this.container) {
228
- const viewer = this.container.querySelector('.ee-message-viewer');
229
- if (viewer) {
230
- viewer.innerHTML = '<div class="ee-error">Failed to load message</div>';
231
- }
232
- }
246
+ this._renderPaneError('.ee-message-viewer', 'Message unavailable', error, () =>
247
+ this._fireAndForget(this.loadMessage(messageId))
248
+ );
233
249
  throw error;
234
250
  }
235
251
  }
@@ -337,8 +353,6 @@ export class EmailEngineClient {
337
353
  return response;
338
354
  } catch (error) {
339
355
  console.error('Failed to send message:', error);
340
- // Try to parse detailed error information
341
- this._parseApiError(error);
342
356
  throw error;
343
357
  }
344
358
  }
@@ -380,7 +394,6 @@ export class EmailEngineClient {
380
394
  return response;
381
395
  } catch (error) {
382
396
  console.error('Failed to save draft:', error);
383
- this._parseApiError(error);
384
397
  throw error;
385
398
  }
386
399
  }
@@ -395,7 +408,6 @@ export class EmailEngineClient {
395
408
  return response;
396
409
  } catch (error) {
397
410
  console.error('Failed to submit draft:', error);
398
- this._parseApiError(error);
399
411
  throw error;
400
412
  }
401
413
  }
@@ -414,23 +426,21 @@ export class EmailEngineClient {
414
426
  return !!(folder && folder.specialUse === '\\Drafts');
415
427
  }
416
428
 
417
- _parseApiError(error) {
418
- try {
419
- // If error has response text, try to parse it
420
- if (error.message && error.message.includes('API request failed:')) {
421
- // This is our custom error from apiRequest, the actual response might have more details
422
- error.isDetailedError = false;
423
- }
424
- } catch (parseError) {
425
- // If parsing fails, just use the original error
426
- console.error('Failed to parse error details:', parseError);
429
+ // Best-effort human readable reason for a failed request. EmailEngine returns
430
+ // Boom style payloads - { statusCode, error, message, code, fields } - so the
431
+ // `message` field usually carries the actual cause, e.g. "Requested account is
432
+ // not yet initialized" when the account has not connected yet.
433
+ _errorMessage(error, fallback = 'Unexpected error') {
434
+ if (!error) {
435
+ return fallback;
427
436
  }
428
- }
429
437
 
430
- _formatSendError(error) {
431
- // If we have detailed error information from the API
432
- if (error.details && error.details.fields && Array.isArray(error.details.fields)) {
433
- const fieldErrors = error.details.fields
438
+ const details = error.details;
439
+ const detailsMessage = details && typeof details.message === 'string' ? details.message : '';
440
+
441
+ // Validation failures list the offending fields
442
+ if (details && Array.isArray(details.fields)) {
443
+ const fieldErrors = details.fields
434
444
  // Keep only entries that carry a usable message string.
435
445
  .filter(field => field && typeof field.message === 'string')
436
446
  // Map technical field names to user-friendly ones. Each replace
@@ -443,18 +453,100 @@ export class EmailEngineClient {
443
453
  .replace(/"text"/g, 'message')
444
454
  );
445
455
 
446
- const mainMessage = error.details.message || 'Failed to send email';
456
+ const mainMessage = detailsMessage || fallback;
447
457
  if (fieldErrors.length > 0) {
448
458
  return `${mainMessage}:\n\n• ${fieldErrors.join('\n• ')}`;
449
459
  }
450
460
  return mainMessage;
451
461
  }
452
462
 
453
- // No field-level details - fall back to the API-provided message, then to a generic one
454
- if (error.details && typeof error.details.message === 'string' && error.details.message) {
455
- return error.details.message;
463
+ if (detailsMessage) {
464
+ return detailsMessage;
465
+ }
466
+
467
+ if (error.statusCode) {
468
+ return `The server responded with status ${error.statusCode}`;
469
+ }
470
+
471
+ return error.message || fallback;
472
+ }
473
+
474
+ _formatSendError(error) {
475
+ return this._errorMessage(error, 'Failed to send email. Please check your input and try again.');
476
+ }
477
+
478
+ // Writes markup into one of the client's panes when the UI exists and is still
479
+ // alive, and hands the pane back so callers can wire up what they rendered.
480
+ _setPaneHtml(selector, html) {
481
+ if (typeof document === 'undefined' || !this.container || this._destroyed) {
482
+ return null;
483
+ }
484
+
485
+ const pane = this.container.querySelector(selector);
486
+ if (pane) {
487
+ pane.innerHTML = html;
456
488
  }
457
- return 'Failed to send email. Please check your input and try again.';
489
+ return pane;
490
+ }
491
+
492
+ // Replaces a pane's contents with an error panel explaining why its data is
493
+ // missing, optionally with a Retry button. Without this a failed request
494
+ // leaves the pane stuck on its "Loading..." placeholder forever, with the
495
+ // only trace of the failure in the developer console.
496
+ _renderPaneError(selector, title, error, retry = null) {
497
+ const detail = this._errorMessage(error, '');
498
+ const pane = this._setPaneHtml(
499
+ selector,
500
+ `
501
+ <div class="ee-error">
502
+ <div class="ee-error-title">${this.escapeHtml(title)}</div>
503
+ ${detail ? `<div class="ee-error-detail">${this.escapeHtml(detail)}</div>` : ''}
504
+ ${retry ? '<button type="button" class="ee-button ee-error-retry">Retry</button>' : ''}
505
+ </div>
506
+ `
507
+ );
508
+
509
+ if (pane && retry) {
510
+ const retryButton = pane.querySelector('.ee-error-retry');
511
+ if (retryButton) {
512
+ retryButton.addEventListener('click', () => {
513
+ if (this._destroyed) {
514
+ return;
515
+ }
516
+ // Disable while the request is in flight so an impatient second
517
+ // click can not fan out a duplicate round trip. A failed retry
518
+ // re-renders the panel with a fresh button.
519
+ retryButton.disabled = true;
520
+ retry();
521
+ });
522
+ }
523
+ }
524
+ }
525
+
526
+ // Loads started from a DOM handler render their own error panel, so the user
527
+ // has already been told. Swallow the rejection rather than letting it surface
528
+ // as an unhandled rejection in hosts with a global error reporter.
529
+ _fireAndForget(promise) {
530
+ promise.catch(() => {});
531
+ }
532
+
533
+ // Message actions (flag, delete, move) have no pane of their own to report into:
534
+ // when one fails the message simply stays put, which is indistinguishable from
535
+ // nothing having happened. Say so instead.
536
+ _alertActionFailed(error, fallback) {
537
+ console.error(`${fallback}:`, error);
538
+ return this.alertMethod(this._errorMessage(error, fallback), 'Error', null, 'OK');
539
+ }
540
+
541
+ // The message list before any folder is opened. Shared with createLayout so the
542
+ // pane header markup lives in one place.
543
+ _messageListPlaceholder() {
544
+ return `
545
+ <div class="ee-pane-header">
546
+ <span class="ee-pane-title">Messages</span>
547
+ </div>
548
+ <div class="ee-empty-state">Select a folder</div>
549
+ `;
458
550
  }
459
551
 
460
552
  formatDate(dateStr) {
@@ -508,15 +600,17 @@ export class EmailEngineClient {
508
600
  }
509
601
 
510
602
  // Authenticated GET for binary payloads (attachments, message source).
511
- // apiRequest is not reused here - it always parses the body as JSON.
603
+ // apiRequest is not reused here - it always parses the body as JSON - but the
604
+ // same _fetch/_responseError pair is, so a failed download reports the same
605
+ // reason as any other request.
512
606
  async _fetchBlob(endpoint) {
513
- const response = await fetch(`${this.apiUrl}${endpoint}`, {
607
+ const response = await this._fetch(`${this.apiUrl}${endpoint}`, {
514
608
  headers: this._authHeaders(),
515
609
  credentials: 'include'
516
610
  });
517
611
 
518
612
  if (!response.ok) {
519
- throw new Error(`HTTP error! status: ${response.status}`);
613
+ throw await this._responseError(response);
520
614
  }
521
615
 
522
616
  return response;
@@ -541,7 +635,12 @@ export class EmailEngineClient {
541
635
  this._saveBlob(blob, filename);
542
636
  } catch (error) {
543
637
  console.error('Failed to download attachment:', error);
544
- this.alertMethod('Failed to download attachment. Please try again.', 'Download Error', null, 'OK');
638
+ this.alertMethod(
639
+ this._errorMessage(error, 'Failed to download attachment. Please try again.'),
640
+ 'Download Error',
641
+ null,
642
+ 'OK'
643
+ );
545
644
  }
546
645
  }
547
646
 
@@ -561,7 +660,12 @@ export class EmailEngineClient {
561
660
  this._saveBlob(blob, filename);
562
661
  } catch (error) {
563
662
  console.error('Failed to download original message:', error);
564
- this.alertMethod('Failed to download original message. Please try again.', 'Download Error', null, 'OK');
663
+ this.alertMethod(
664
+ this._errorMessage(error, 'Failed to download original message. Please try again.'),
665
+ 'Download Error',
666
+ null,
667
+ 'OK'
668
+ );
565
669
  }
566
670
  }
567
671
 
@@ -571,6 +675,10 @@ export class EmailEngineClient {
571
675
  }
572
676
 
573
677
  const style = document.createElement('style');
678
+ if (this.styleNonce) {
679
+ // the IDL property, which is what the policy check reads on an element a script inserts
680
+ style.nonce = this.styleNonce;
681
+ }
574
682
  style.textContent = `
575
683
  .ee-client {
576
684
  --ee-font: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
@@ -926,6 +1034,25 @@ export class EmailEngineClient {
926
1034
  border: 1px solid #fcc;
927
1035
  border-radius: 4px;
928
1036
  margin: 16px;
1037
+ /* Panes can be as narrow as the 200px sidebar and server
1038
+ messages are arbitrary text, so break anywhere rather than
1039
+ letting a long word push the layout wider. */
1040
+ overflow-wrap: anywhere;
1041
+ }
1042
+
1043
+ .ee-error-title {
1044
+ font-weight: 500;
1045
+ }
1046
+
1047
+ .ee-error-detail {
1048
+ margin-top: 6px;
1049
+ font-size: 12px;
1050
+ /* Field level API errors arrive as a newline separated list */
1051
+ white-space: pre-line;
1052
+ }
1053
+
1054
+ .ee-error-retry {
1055
+ margin-top: 10px;
929
1056
  }
930
1057
 
931
1058
  .ee-flag {
@@ -1362,11 +1489,16 @@ export class EmailEngineClient {
1362
1489
  }
1363
1490
 
1364
1491
  .ee-dark-mode .ee-loading,
1365
- .ee-dark-mode .ee-empty-state,
1366
- .ee-dark-mode .ee-error {
1492
+ .ee-dark-mode .ee-empty-state {
1367
1493
  color: #999;
1368
1494
  }
1369
1495
 
1496
+ .ee-dark-mode .ee-error {
1497
+ background: #3a2222;
1498
+ border-color: #5c3030;
1499
+ color: #f0a5a5;
1500
+ }
1501
+
1370
1502
  .ee-dark-mode .ee-pagination {
1371
1503
  background: #252525;
1372
1504
  border-color: #333;
@@ -1560,7 +1692,7 @@ export class EmailEngineClient {
1560
1692
  folderTree.querySelectorAll('.ee-folder-item').forEach(item => {
1561
1693
  item.addEventListener('click', () => {
1562
1694
  const path = item.getAttribute('data-path');
1563
- this.loadMessages(path);
1695
+ this._fireAndForget(this.loadMessages(path));
1564
1696
  });
1565
1697
  });
1566
1698
  }
@@ -1636,19 +1768,19 @@ export class EmailEngineClient {
1636
1768
  messageList.querySelectorAll('.ee-message-item').forEach(item => {
1637
1769
  item.addEventListener('click', () => {
1638
1770
  const messageId = item.getAttribute('data-id');
1639
- this.loadMessage(messageId);
1771
+ this._fireAndForget(this.loadMessage(messageId));
1640
1772
  });
1641
1773
  });
1642
1774
 
1643
1775
  messageList.querySelectorAll('[data-action="prev-page"]').forEach(btn => {
1644
1776
  btn.addEventListener('click', () => {
1645
- this.loadMessages(this.currentFolder, this.prevPageCursor);
1777
+ this._fireAndForget(this.loadMessages(this.currentFolder, this.prevPageCursor));
1646
1778
  });
1647
1779
  });
1648
1780
 
1649
1781
  messageList.querySelectorAll('[data-action="next-page"]').forEach(btn => {
1650
1782
  btn.addEventListener('click', () => {
1651
- this.loadMessages(this.currentFolder, this.nextPageCursor);
1783
+ this._fireAndForget(this.loadMessages(this.currentFolder, this.nextPageCursor));
1652
1784
  });
1653
1785
  });
1654
1786
 
@@ -1660,7 +1792,7 @@ export class EmailEngineClient {
1660
1792
  if (typeof window !== 'undefined' && window.localStorage) {
1661
1793
  localStorage.setItem('ee-client-page-size', this.pageSize.toString());
1662
1794
  }
1663
- this.loadMessages(this.currentFolder);
1795
+ this._fireAndForget(this.loadMessages(this.currentFolder));
1664
1796
  });
1665
1797
  }
1666
1798
  }
@@ -1797,7 +1929,9 @@ export class EmailEngineClient {
1797
1929
 
1798
1930
  viewer.querySelector('[data-action="toggle-read"]').addEventListener('click', () => {
1799
1931
  const currentlyUnseen = msg.unseen;
1800
- this.markAsRead(msg.id, currentlyUnseen);
1932
+ this.markAsRead(msg.id, currentlyUnseen).catch(error =>
1933
+ this._alertActionFailed(error, 'Failed to update the message flags')
1934
+ );
1801
1935
  });
1802
1936
 
1803
1937
  viewer.querySelector('[data-action="delete"]').addEventListener('click', async () => {
@@ -1808,7 +1942,9 @@ export class EmailEngineClient {
1808
1942
  'Delete'
1809
1943
  );
1810
1944
  if (result) {
1811
- this.deleteMessage(msg.id);
1945
+ this.deleteMessage(msg.id).catch(error =>
1946
+ this._alertActionFailed(error, 'Failed to delete the message')
1947
+ );
1812
1948
  }
1813
1949
  });
1814
1950
 
@@ -1819,7 +1955,12 @@ export class EmailEngineClient {
1819
1955
  viewer.querySelector('[data-action="move"]').addEventListener('change', e => {
1820
1956
  const targetPath = e.target.value;
1821
1957
  if (targetPath) {
1822
- this.moveMessage(msg.id, targetPath);
1958
+ this.moveMessage(msg.id, targetPath).catch(error => {
1959
+ // The message did not move, so the select must not keep showing
1960
+ // the target folder as though it had
1961
+ e.target.value = '';
1962
+ this._alertActionFailed(error, 'Failed to move the message');
1963
+ });
1823
1964
  }
1824
1965
  });
1825
1966
 
@@ -1872,16 +2013,9 @@ export class EmailEngineClient {
1872
2013
  <div class="ee-pane-header">
1873
2014
  <span class="ee-pane-title">Folders</span>
1874
2015
  </div>
1875
- <div class="ee-folder-tree">
1876
- <div class="ee-loading">Loading folders...</div>
1877
- </div>
1878
- </div>
1879
- <div class="ee-message-list">
1880
- <div class="ee-pane-header">
1881
- <span class="ee-pane-title">Messages</span>
1882
- </div>
1883
- <div class="ee-empty-state">Select a folder</div>
2016
+ <div class="ee-folder-tree"></div>
1884
2017
  </div>
2018
+ <div class="ee-message-list">${this._messageListPlaceholder()}</div>
1885
2019
  <div class="ee-message-viewer">
1886
2020
  <div class="ee-empty-state">Select a message to view</div>
1887
2021
  </div>
@@ -2182,18 +2316,38 @@ export class EmailEngineClient {
2182
2316
  toggleBtn.addEventListener('click', () => this.toggleDarkMode());
2183
2317
  }
2184
2318
 
2185
- this.loadFolders()
2319
+ this._loadInitialView();
2320
+ }
2321
+
2322
+ // Load the folder list and open the account's inbox. Used on startup and by
2323
+ // the Retry button that loadFolders renders when the request fails; both
2324
+ // failure paths already put an error panel in the UI, so the rejection is
2325
+ // logged and swallowed here rather than surfacing as an unhandled rejection.
2326
+ _loadInitialView() {
2327
+ // Drop whatever a previous attempt left here; loadFolders and loadMessages
2328
+ // paint their own loading states from this point on.
2329
+ this._setPaneHtml('.ee-message-list', this._messageListPlaceholder());
2330
+
2331
+ return this.loadFolders()
2332
+ .catch(error => {
2333
+ // loadFolders reports into the sidebar, but the message list is the
2334
+ // larger pane and would still read "Select a folder" - a folder the
2335
+ // sidebar can no longer offer. Say what happened there too.
2336
+ this._renderPaneError('.ee-message-list', 'Folders unavailable', error, () => this._loadInitialView());
2337
+ throw error;
2338
+ })
2186
2339
  .then(() => {
2187
2340
  const inbox =
2188
2341
  this.folders.find(f => f.specialUse && f.specialUse.includes('\\Inbox')) ||
2189
2342
  this.folders.find(f => f.name.toLowerCase() === 'inbox') ||
2190
2343
  this.folders[0];
2191
2344
  if (inbox) {
2192
- this.loadMessages(inbox.path);
2345
+ return this.loadMessages(inbox.path);
2193
2346
  }
2194
2347
  })
2195
2348
  .catch(error => {
2196
- console.error('Failed to auto-select inbox:', error);
2349
+ // Both loadFolders and loadMessages have already rendered a panel
2350
+ console.error('Failed to load the initial view:', error);
2197
2351
  });
2198
2352
  }
2199
2353
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@postalsys/ee-client",
3
- "version": "1.7.0",
3
+ "version": "1.8.0",
4
4
  "description": "EmailEngine client library for browser and Node.js applications",
5
5
  "main": "index.js",
6
6
  "module": "index.js",