@postalsys/ee-client 1.1.0 → 1.2.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 (4) hide show
  1. package/README.md +53 -30
  2. package/index.js +539 -5
  3. package/package.json +3 -10
  4. package/index.cjs +0 -1190
package/README.md CHANGED
@@ -52,18 +52,6 @@ const { messages } = await client.loadMessages('INBOX');
52
52
  const message = await client.loadMessage(messages[0].id);
53
53
  ```
54
54
 
55
- ### CommonJS
56
-
57
- ```javascript
58
- const { EmailEngineClient } = require('@postalsys/ee-client');
59
-
60
- const client = new EmailEngineClient({
61
- apiUrl: 'https://your-emailengine-server.com',
62
- account: 'your-account-id',
63
- accessToken: 'your-access-token'
64
- });
65
- ```
66
-
67
55
  ## API
68
56
 
69
57
  ### Constructor Options
@@ -72,7 +60,10 @@ const client = new EmailEngineClient({
72
60
  - `account` (string, required): Account identifier
73
61
  - `accessToken` (string, optional): Access token for authentication
74
62
  - `container` (HTMLElement, optional): DOM container for UI components (browser only)
75
- - `confirmMethod` (function, optional): Custom confirm dialog method. Can be sync or async. Defaults to browser's `confirm()`
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.
65
+
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.
76
67
 
77
68
  ### Methods
78
69
 
@@ -100,6 +91,18 @@ Delete a message.
100
91
 
101
92
  Move a message to another folder.
102
93
 
94
+ #### `sendMessage(to: string | object | array, subject: string, text: string): Promise<object>`
95
+
96
+ Send a new email message. The `to` parameter can be:
97
+
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
101
+
102
+ #### `destroy(): void`
103
+
104
+ Clean up the client instance, clearing any active timers (like the keep-alive timer for session tokens).
105
+
103
106
  ## Browser UI
104
107
 
105
108
  When used in a browser with a container element, the client automatically creates a full email interface with:
@@ -127,9 +130,9 @@ When used in a browser with a container element, the client automatically create
127
130
  </script>
128
131
  ```
129
132
 
130
- ### Custom Confirm Dialog
133
+ ### Custom Dialog Methods
131
134
 
132
- You can provide a custom confirm dialog method that will be used instead of the browser's default `confirm()`. This is useful for integrating with UI frameworks or custom dialog systems:
135
+ 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:
133
136
 
134
137
  ```javascript
135
138
  const client = new EmailEngineClient({
@@ -137,29 +140,49 @@ const client = new EmailEngineClient({
137
140
  account: 'your-account-id',
138
141
  accessToken: 'your-access-token',
139
142
  container: document.getElementById('email-client'),
140
- confirmMethod: async message => {
141
- // Example with a custom async dialog
143
+
144
+ // Custom alert method
145
+ alertMethod: async (message, title, cancelText, okText) => {
146
+ return await MyModal.alert({
147
+ title: title, // e.g., "Success", "Error", "Notice"
148
+ message: message,
149
+ okButton: okText // e.g., "OK"
150
+ // cancelText is null for alerts
151
+ });
152
+ },
153
+
154
+ // Custom confirm method
155
+ confirmMethod: async (message, title, cancelText, okText) => {
142
156
  return await MyModal.confirm({
143
- title: 'Confirm Action',
157
+ title: title, // e.g., "Delete Message", "Confirm"
144
158
  message: message,
145
- buttons: ['Cancel', 'OK']
159
+ cancelButton: cancelText, // e.g., "Cancel"
160
+ okButton: okText // e.g., "Delete", "OK"
146
161
  });
147
162
  }
148
163
  });
149
164
  ```
150
165
 
151
- The `confirmMethod` can be either synchronous or asynchronous:
166
+ #### Dialog Method Signatures
152
167
 
153
- ```javascript
154
- // Synchronous example
155
- confirmMethod: message => window.confirm(message);
156
-
157
- // Asynchronous example
158
- confirmMethod: async message => {
159
- const result = await customDialog.show(message);
160
- return result === 'ok';
161
- };
162
- ```
168
+ Both methods receive the same parameters:
169
+
170
+ - `message` (string): The message to display
171
+ - `title` (string): Dialog title (defaults: "Confirm" for confirm, "Notice" for alert)
172
+ - `cancelText` (string|null): Cancel button text ("Cancel" for confirm, `null` for alert)
173
+ - `okText` (string): OK/action button text (defaults: "OK")
174
+
175
+ #### Built-in Dialog Types
176
+
177
+ The library uses contextually appropriate titles and button texts:
178
+
179
+ - **Validation errors**: `alertMethod(message, "Validation Error", null, "OK")`
180
+ - **Success messages**: `alertMethod(message, "Success", null, "OK")`
181
+ - **Send errors**: `alertMethod(message, "Send Error", null, "OK")`
182
+ - **Download errors**: `alertMethod(message, "Download Error", null, "OK")`
183
+ - **Delete confirmation**: `confirmMethod(message, "Delete Message", "Cancel", "Delete")`
184
+
185
+ Both methods can be synchronous or asynchronous and should return a boolean for confirm dialogs.
163
186
 
164
187
  ## License
165
188