@postalsys/ee-client 1.3.2 → 1.3.3

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 (2) hide show
  1. package/README.md +162 -113
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,20 @@
1
1
  # @postalsys/ee-client
2
2
 
3
- EmailEngine client library for browser and Node.js applications.
3
+ Client library for [EmailEngine](https://emailengine.app/) that works in both the browser and Node.js.
4
+
5
+ It wraps the EmailEngine REST API (`/v1/account/...`) so you can list folders, read and search messages, change flags, move and delete messages, download attachments, and send mail. When you also give it a DOM element, it renders a complete, self-contained webmail interface (folder tree, paginated message list, message viewer, compose modal, dark mode) into that element.
6
+
7
+ This is the same client that powers the built-in message browser in the EmailEngine admin UI.
8
+
9
+ ## About EmailEngine
10
+
11
+ [EmailEngine](https://emailengine.app/) is a headless email client application that exposes IMAP, SMTP, Gmail API, and Microsoft Graph API accounts through a single unified REST API and webhooks. This library talks to that REST API - you need a running EmailEngine instance to use it.
12
+
13
+ - Website: https://emailengine.app/
14
+ - API reference: https://api.emailengine.app/
15
+ - Documentation: https://docs.emailengine.app/
16
+
17
+ Note that EmailEngine (the server) is commercial software and requires a subscription; this client library is MIT-licensed.
4
18
 
5
19
  ## Installation
6
20
 
@@ -8,193 +22,228 @@ EmailEngine client library for browser and Node.js applications.
8
22
  npm install @postalsys/ee-client
9
23
  ```
10
24
 
11
- For Node.js environments, you may also need to install `node-fetch`:
25
+ This package is **ES modules only** (`"type": "module"`). Import it with `import`; `require()` will not work.
12
26
 
13
- ```bash
14
- npm install node-fetch
15
- ```
27
+ It has **no runtime dependencies** and uses the platform `fetch`:
16
28
 
17
- ## Usage
29
+ - In the browser and on Node.js 18+, the global `fetch` is used automatically.
30
+ - On older Node.js (14-17), install [`node-fetch`](https://www.npmjs.com/package/node-fetch) as a fallback:
18
31
 
19
- ### Browser
32
+ ```bash
33
+ npm install node-fetch
34
+ ```
20
35
 
21
- ```javascript
22
- import { EmailEngineClient } from '@postalsys/ee-client';
36
+ ## Quick start
23
37
 
24
- // Create client with UI container
25
- const client = new EmailEngineClient({
26
- apiUrl: 'https://your-emailengine-server.com',
27
- account: 'your-account-id',
28
- accessToken: 'your-access-token',
29
- container: document.getElementById('email-client')
30
- });
38
+ ### Browser (embedded webmail UI)
39
+
40
+ Pass a `container` element and the client renders a full webmail UI into it and loads the inbox automatically:
41
+
42
+ ```html
43
+ <div id="email-client" style="height: 600px;"></div>
44
+ <script type="module">
45
+ import { EmailEngineClient } from '@postalsys/ee-client';
46
+
47
+ const client = new EmailEngineClient({
48
+ apiUrl: 'https://your-emailengine-server.example.com',
49
+ account: 'your-account-id',
50
+ accessToken: 'your-access-token',
51
+ container: document.getElementById('email-client')
52
+ });
53
+ </script>
31
54
  ```
32
55
 
33
- ### Node.js
56
+ Because the browser talks to EmailEngine directly, use a short-lived, account-scoped token here (see [Authentication](#authentication)) - never a root or admin token.
57
+
58
+ ### Node.js (API client, no UI)
59
+
60
+ Omit `container` to use the client purely as an API wrapper:
34
61
 
35
62
  ```javascript
36
63
  import { EmailEngineClient } from '@postalsys/ee-client';
37
64
 
38
- // Create client for API-only usage
39
65
  const client = new EmailEngineClient({
40
- apiUrl: 'https://your-emailengine-server.com',
66
+ apiUrl: 'https://your-emailengine-server.example.com',
41
67
  account: 'your-account-id',
42
68
  accessToken: 'your-access-token'
43
69
  });
44
70
 
45
- // Load folders
71
+ // List folders
46
72
  const folders = await client.loadFolders();
47
73
 
48
74
  // Load messages from INBOX
49
- const { messages } = await client.loadMessages('INBOX');
75
+ const { messages, nextPageCursor } = await client.loadMessages('INBOX');
50
76
 
51
- // Load a specific message
77
+ // Load a single message (its HTML is returned pre-processed for safe display)
52
78
  const message = await client.loadMessage(messages[0].id);
79
+
80
+ // Send a plain-text message
81
+ await client.sendMessage('user@example.com', 'Hello', 'Sent from ee-client');
82
+
83
+ // Release the keep-alive timer when done (see destroy() below)
84
+ client.destroy();
85
+ ```
86
+
87
+ ## Authentication
88
+
89
+ Every request is sent to EmailEngine with an `Authorization: Bearer <accessToken>` header. Tokens are scoped to a single account, so create one token per account you expose. There are two kinds of tokens you can pass as `accessToken`:
90
+
91
+ ### Access tokens
92
+
93
+ Provision a long-lived, account-scoped access token with the `api` scope through the EmailEngine admin UI, or via the API:
94
+
95
+ ```bash
96
+ curl -XPOST "https://your-emailengine-server.example.com/v1/token" \
97
+ -H "Authorization: Bearer <root-token>" \
98
+ -H "Content-Type: application/json" \
99
+ -d '{
100
+ "account": "your-account-id",
101
+ "description": "Webmail client",
102
+ "scopes": ["api"]
103
+ }'
53
104
  ```
54
105
 
55
- ## API
106
+ The response contains a `token` string to use as `accessToken`. Keep root tokens on your server; only hand an account-scoped `api` token to the browser.
107
+
108
+ ### Session tokens (`sess_...`)
109
+
110
+ EmailEngine can also mint short-lived, session-bound tokens whose value starts with `sess_` (this is how its own built-in message browser is embedded). These expire quickly on inactivity. When the client detects a `sess_` token, it automatically pings `GET /v1/account/{account}` after about five minutes of inactivity to keep the token alive. Call [`destroy()`](#destroy-void) to stop that timer when you tear the client down.
111
+
112
+ ## Constructor options
113
+
114
+ ```javascript
115
+ new EmailEngineClient(options);
116
+ ```
56
117
 
57
- ### Constructor Options
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`. |
58
127
 
59
- - `apiUrl` (string, optional): EmailEngine API URL. Defaults to `http://127.0.0.1:3000`
60
- - `account` (string, required): Account identifier
61
- - `accessToken` (string, optional): Access token for authentication
62
- - `container` (HTMLElement, optional): DOM container for UI components (browser only)
63
- - `confirmMethod` (function, optional): Custom confirm dialog method. Receives `(message, title, cancelText, okText)` parameters. Can be sync or async. Defaults to browser's `confirm()` with standard parameters.
64
- - `alertMethod` (function, optional): Custom alert dialog method. Receives `(message, title, cancelText, okText)` parameters where `cancelText` is `null` for alerts. Can be sync or async. Defaults to browser's `alert()` with standard parameters.
128
+ 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.
65
129
 
66
- **Note**: For session tokens (starting with `sess_`), the client automatically implements a keep-alive mechanism that pings the `/v1/account/{account}` endpoint every 5 minutes of inactivity to prevent token expiration.
130
+ ### Factory helper
131
+
132
+ `createEmailEngineClient()` is a convenience wrapper that also accepts a container element or an element id, and validates that `account` is present:
133
+
134
+ ```javascript
135
+ import { createEmailEngineClient } from '@postalsys/ee-client';
136
+
137
+ // From an options object with a containerId
138
+ const client = createEmailEngineClient({
139
+ apiUrl: 'https://your-emailengine-server.example.com',
140
+ account: 'your-account-id',
141
+ accessToken: 'your-access-token',
142
+ containerId: 'email-client'
143
+ });
144
+ ```
67
145
 
68
- ### Methods
146
+ ## Methods
69
147
 
70
- #### `loadFolders(): Promise<Folder[]>`
148
+ ### `loadFolders(): Promise<Folder[]>`
71
149
 
72
- Load all folders/mailboxes for the account.
150
+ Load all folders/mailboxes for the account. Renders the folder tree when a container is set.
73
151
 
74
- #### `loadMessages(path: string, cursor?: string): Promise<MessageListResponse>`
152
+ ### `loadMessages(path: string, cursor?: string): Promise<MessageListResponse>`
75
153
 
76
- Load messages from a specific folder.
154
+ Load a page of messages from a folder. Pass `nextPageCursor` / `prevPageCursor` from a previous response to paginate. Resolves to `{ messages, nextPageCursor, prevPageCursor }`.
77
155
 
78
- #### `loadMessage(messageId: string): Promise<Message>`
156
+ ### `loadMessage(messageId: string): Promise<Message>`
79
157
 
80
- Load a specific message by ID.
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.
81
159
 
82
- #### `markAsRead(messageId: string, seen?: boolean): Promise<boolean>`
160
+ ### `markAsRead(messageId: string, seen?: boolean): Promise<boolean>`
83
161
 
84
- Mark a message as read or unread.
162
+ Add or remove the `\Seen` flag. Pass `false` to mark as unread.
85
163
 
86
- #### `deleteMessage(messageId: string): Promise<boolean>`
164
+ ### `deleteMessage(messageId: string): Promise<boolean>`
87
165
 
88
- Delete a message.
166
+ Delete a message (EmailEngine moves it to Trash, or removes it if already in Trash).
89
167
 
90
- #### `moveMessage(messageId: string, targetPath: string): Promise<boolean>`
168
+ ### `moveMessage(messageId: string, targetPath: string): Promise<boolean>`
91
169
 
92
170
  Move a message to another folder.
93
171
 
94
- #### `sendMessage(to: string | object | array, subject: string, text: string): Promise<object>`
172
+ ### `sendMessage(to, subject, text): Promise<object>`
95
173
 
96
- Send a new email message. The `to` parameter can be:
174
+ Send a plain-text email. `to` may be:
97
175
 
98
- - A string email address: `'user@example.com'`
99
- - An object with name and address: `{ name: 'John Doe', address: 'john@example.com' }`
100
- - An array of strings or objects for multiple recipients
176
+ - a string address: `'user@example.com'`
177
+ - an object: `{ name: 'John Doe', address: 'john@example.com' }`
178
+ - an array of strings and/or objects for multiple recipients
101
179
 
102
- #### `destroy(): void`
180
+ Resolves to EmailEngine's submit response.
103
181
 
104
- Clean up the client instance, clearing any active timers (like the keep-alive timer for session tokens).
182
+ ### `downloadAttachment(attachmentId: string, suggestedFilename?: string): Promise<void>`
105
183
 
106
- ## Browser UI
184
+ Browser only. Fetch an attachment and trigger a download, using the filename from the `Content-Disposition` header when available.
107
185
 
108
- When used in a browser with a container element, the client automatically creates a full email interface with:
186
+ ### `downloadOriginalMessage(messageId: string, subject?: string): Promise<void>`
109
187
 
110
- - Folder tree navigation
111
- - Message list with pagination
112
- - Message viewer with actions (mark as read/unread, delete, move)
113
- - Responsive design
114
- - Dark mode support with persistent preference
188
+ Browser only. Download the raw message source as an `.eml` file.
115
189
 
116
- ```html
117
- <div id="email-client" style="height: 600px;"></div>
118
- <script type="module">
119
- import { EmailEngineClient } from '@postalsys/ee-client';
190
+ ### `destroy(): void`
120
191
 
121
- new EmailEngineClient({
122
- apiUrl: 'https://your-emailengine-server.com',
123
- account: 'your-account-id',
124
- accessToken: 'your-access-token',
125
- container: document.getElementById('email-client'),
126
- // Optional: Custom confirm dialog
127
- confirmMethod: async message => {
128
- return await myCustomDialog.confirm(message);
129
- }
130
- });
131
- </script>
132
- ```
192
+ 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.
193
+
194
+ ## Browser UI
133
195
 
134
- ### Custom Dialog Methods
196
+ When a `container` is provided the client builds a full webmail interface:
135
197
 
136
- You can provide custom alert and confirm dialog methods that will be used instead of the browser's default dialogs. This is useful for integrating with UI frameworks or custom dialog systems:
198
+ - Folder tree with special-folder ordering (Inbox, Drafts, Sent, Trash, Junk, Archive) and nested folders
199
+ - Paginated message list with a selectable page size (persisted to `localStorage`)
200
+ - Message viewer with mark read/unread, delete, move-to-folder, download original, and attachment downloads
201
+ - Compose modal (floating button) for sending plain-text mail
202
+ - Dark mode toggle with the preference persisted to `localStorage`
203
+
204
+ ### Custom dialogs
205
+
206
+ 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:
137
207
 
138
208
  ```javascript
139
209
  const client = new EmailEngineClient({
140
- apiUrl: 'https://your-emailengine-server.com',
210
+ apiUrl: 'https://your-emailengine-server.example.com',
141
211
  account: 'your-account-id',
142
212
  accessToken: 'your-access-token',
143
213
  container: document.getElementById('email-client'),
144
214
 
145
- // Custom alert method
146
215
  alertMethod: async (message, title, cancelText, okText) => {
147
- return await MyModal.alert({
148
- title: title, // e.g., "Success", "Error", "Notice"
149
- message: message,
150
- okButton: okText // e.g., "OK"
151
- // cancelText is null for alerts
152
- });
216
+ return await MyModal.alert({ title, message, okButton: okText });
153
217
  },
154
218
 
155
- // Custom confirm method
156
219
  confirmMethod: async (message, title, cancelText, okText) => {
157
- return await MyModal.confirm({
158
- title: title, // e.g., "Delete Message", "Confirm"
159
- message: message,
160
- cancelButton: cancelText, // e.g., "Cancel"
161
- okButton: okText // e.g., "Delete", "OK"
162
- });
220
+ return await MyModal.confirm({ title, message, cancelButton: cancelText, okButton: okText });
163
221
  }
164
222
  });
165
223
  ```
166
224
 
167
- #### Dialog Method Signatures
168
-
169
- Both methods receive the same parameters:
170
-
171
- - `message` (string): The message to display
172
- - `title` (string): Dialog title (defaults: "Confirm" for confirm, "Notice" for alert)
173
- - `cancelText` (string|null): Cancel button text ("Cancel" for confirm, `null` for alert)
174
- - `okText` (string): OK/action button text (defaults: "OK")
225
+ Both methods receive the same arguments:
175
226
 
176
- #### Built-in Dialog Types
227
+ - `message` (string): text to display
228
+ - `title` (string): dialog title (defaults: `Confirm` / `Notice`)
229
+ - `cancelText` (string | null): cancel button text (`Cancel` for confirm, `null` for alert)
230
+ - `okText` (string): confirm/OK button text (default `OK`)
177
231
 
178
- The library uses contextually appropriate titles and button texts:
232
+ The client uses contextual titles such as `Delete Message`, `Validation Error`, `Success`, `Send Error`, and `Download Error`. `confirmMethod` should return a boolean (or a promise for one); `alertMethod` may be sync or async.
179
233
 
180
- - **Validation errors**: `alertMethod(message, "Validation Error", null, "OK")`
181
- - **Success messages**: `alertMethod(message, "Success", null, "OK")`
182
- - **Send errors**: `alertMethod(message, "Send Error", null, "OK")`
183
- - **Download errors**: `alertMethod(message, "Download Error", null, "OK")`
184
- - **Delete confirmation**: `confirmMethod(message, "Delete Message", "Cancel", "Delete")`
234
+ ## Security
185
235
 
186
- Both methods can be synchronous or asynchronous and should return a boolean for confirm dialogs.
236
+ This library renders attacker-controlled email content, so it is careful about HTML injection:
187
237
 
188
- ### Dark Mode
238
+ - All untrusted values (subjects, addresses, names, filenames, folder names) are HTML-escaped before being written to the DOM.
239
+ - The one intentional raw-HTML sink is the message body itself. The client fetches it with EmailEngine's `webSafeHtml` option so the HTML arrives already pre-processed for safe embedding.
189
240
 
190
- The email client includes built-in dark mode support with automatic persistence of user preference:
241
+ Do not disable escaping or add new raw-HTML sinks when extending the UI.
191
242
 
192
- - **Toggle Button**: A moon/sun icon in the top-right corner toggles between light and dark modes
193
- - **Persistent Preference**: Dark mode preference is saved to localStorage and restored on page reload
194
- - **Complete Theme**: All UI components are styled for optimal readability in both light and dark modes
243
+ ## TypeScript
195
244
 
196
- Dark mode is automatically initialized based on the saved preference when the client is created.
245
+ Type declarations ship with the package (`index.d.ts`), so `EmailEngineClient`, `createEmailEngineClient`, and the exported interfaces (`Folder`, `Message`, `MessageListResponse`, `EmailEngineClientOptions`, and others) are typed out of the box - no `@types` package needed.
197
246
 
198
247
  ## License
199
248
 
200
- MIT © Postal Systems OÜ
249
+ MIT (c) Postal Systems OÜ
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@postalsys/ee-client",
3
- "version": "1.3.2",
3
+ "version": "1.3.3",
4
4
  "description": "EmailEngine client library for browser and Node.js applications",
5
5
  "main": "index.js",
6
6
  "module": "index.js",