engagelab-email-cli 1.1.0 → 1.2.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 (3) hide show
  1. package/README.md +227 -119
  2. package/dist/index.cjs +53 -40
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,211 +1,319 @@
1
- # EngageLab Email CLI
1
+ # EngageLab Email CLI
2
2
 
3
- Pure JavaScript ES Modules CLI for EngageLab Email Agent/Skill workflows.
3
+ EngageLab Email CLI helps agents and developers work with inbound and outbound email from the command line.
4
+
5
+ Use it to:
6
+
7
+ - List and inspect email threads
8
+ - Read inbound messages
9
+ - Poll for new inbound messages
10
+ - Reply to inbound messages
11
+ - Send new emails
4
12
 
5
13
  ## Install
6
14
 
7
- Install dependencies for local development:
15
+ ```bash
16
+ npm install -g engagelab-email-cli
17
+ ```
18
+
19
+ Check the installed version:
8
20
 
9
21
  ```bash
10
- pnpm install
22
+ engagelab-email-cli -V
11
23
  ```
12
24
 
13
- Install from npm after publishing:
25
+ When you run a command that connects to EngageLab Email, the CLI checks whether a newer CLI version is available. If an update is required, it stops and shows the update command:
14
26
 
15
27
  ```bash
16
- npm install -g engagelab-email-cli
28
+ npm install -g engagelab-email-cli@latest
29
+ ```
30
+
31
+ ## Configure
32
+
33
+ Save your service address and Secret Key locally:
34
+
35
+ ```bash
36
+ engagelab-email-cli config set --base-url http://localhost:8087 --secret-key sk_xxx
17
37
  ```
18
38
 
19
- ## Test
39
+ View the saved configuration:
20
40
 
21
41
  ```bash
22
- npm test
42
+ engagelab-email-cli config list
23
43
  ```
24
44
 
25
- The test command runs CLI smoke tests. The console prints each CLI command, the mocked HTTP request, the HTTP status code, and the CLI output summary.
45
+ `config list` masks the Secret Key.
46
+
47
+ You can also pass credentials for a single command:
48
+
49
+ ```bash
50
+ engagelab-email-cli --base-url http://localhost:8087 --secret-key sk_xxx emails receiving list
51
+ ```
52
+
53
+ Configuration priority:
54
+
55
+ 1. Command options: `--base-url`, `--secret-key`
56
+ 2. Environment variables: `ENGAGELAB_EMAIL_BASE_URL`, `ENGAGELAB_EMAIL_SECRET_KEY`
57
+ 3. Local config file
58
+
59
+ ## Quick Start
60
+
61
+ List recent inbound messages:
26
62
 
27
- ## Build And Publish
63
+ ```bash
64
+ engagelab-email-cli emails receiving list --page-size 20
65
+ ```
28
66
 
29
- Build the CLI package locally:
67
+ Read one inbound message:
30
68
 
31
69
  ```bash
32
- npm run build
70
+ engagelab-email-cli emails receiving get <message-uid>
33
71
  ```
34
72
 
35
- Check the package contents before publishing:
73
+ View the full thread around a message:
36
74
 
37
75
  ```bash
38
- npm run packcheck
76
+ engagelab-email-cli threads messages <thread-id> --include-content
39
77
  ```
40
78
 
41
- Publish manually to the public npm registry:
79
+ Reply to an inbound message:
42
80
 
43
81
  ```bash
44
- npm login
45
- npm run publish:npm
82
+ engagelab-email-cli emails receiving reply <message-uid> --text "Thanks, we received your message."
46
83
  ```
47
84
 
48
- GitHub Actions can also publish the package from `.github/workflows/publish-npm.yml`. The workflow runs tests before publishing.
85
+ Send a new email:
49
86
 
50
- Current package name and CLI command:
87
+ ```bash
88
+ engagelab-email-cli emails send \
89
+ --mailbox-id 1001 \
90
+ --to alice@example.com \
91
+ --subject "Hello" \
92
+ --text "Hello from EngageLab Email CLI."
93
+ ```
51
94
 
52
- ```text
53
- engagelab-email-cli
95
+ For scripts or agents, add `--json` to get machine-readable output:
96
+
97
+ ```bash
98
+ engagelab-email-cli emails receiving list --page-size 20 --json
54
99
  ```
55
100
 
56
- ## Configuration
101
+ ## Commands
102
+
103
+ ### `config set`
104
+
105
+ Save local configuration.
106
+
107
+ | Option | Description |
108
+ | --- | --- |
109
+ | `--base-url <url>` | Service address, such as `http://localhost:8087`. |
110
+ | `--secret-key <key>` | Secret Key. It must start with `sk_`. |
111
+
112
+ Example:
57
113
 
58
114
  ```bash
59
115
  engagelab-email-cli config set --base-url http://localhost:8087 --secret-key sk_xxx
60
- engagelab-email-cli config list
61
116
  ```
62
117
 
63
- Runtime config precedence:
118
+ ### `config list`
64
119
 
65
- 1. CLI options: `--base-url`, `--secret-key`
66
- 2. Environment variables: `ENGAGELAB_EMAIL_BASE_URL`, `ENGAGELAB_EMAIL_SECRET_KEY`
67
- 3. Local config file
120
+ Show saved configuration.
68
121
 
69
- `config list` masks the Secret Key and never prints the full value.
122
+ Example:
70
123
 
71
- ## Skill-Friendly Usage
124
+ ```bash
125
+ engagelab-email-cli config list
126
+ ```
72
127
 
73
- For Agent/Skill integrations, prefer JSON input files and JSON output:
128
+ ### `threads list`
129
+
130
+ List email threads.
131
+
132
+ | Option | Description |
133
+ | --- | --- |
134
+ | `--mailbox-id <id>` | Filter by mailbox ID. |
135
+ | `--subject <text>` | Search by subject. |
136
+ | `--participant <email>` | Search by participant email address. |
137
+ | `--start-time <timestamp>` | Filter by latest message start time in milliseconds. |
138
+ | `--end-time <timestamp>` | Filter by latest message end time in milliseconds. |
139
+ | `--page-no <number>` | Page number. |
140
+ | `--page-size <number>` | Number of results per page. |
141
+ | `--json` | Output raw JSON. |
142
+
143
+ Example:
74
144
 
75
145
  ```bash
76
- engagelab-email-cli emails receiving listen --limit 10 --interval 5 --json
77
- engagelab-email-cli threads messages <thread-id> --include-content --json
78
- engagelab-email-cli emails receiving reply <message-uid> --body-file reply.json --json
79
- engagelab-email-cli emails send --body-file send.json --json
146
+ engagelab-email-cli threads list --subject refund --page-no 1 --page-size 20
80
147
  ```
81
148
 
82
- `listen` is a long-running polling command. It prints each new message as it arrives and exits when you press `Ctrl+C`.
83
- With `--json`, `listen` outputs NDJSON: one JSON object per message line. JSON input files avoid shell quoting issues with long text, HTML, arrays, and newlines.
149
+ ### `threads get <thread-id>`
84
150
 
85
- ## Threads
151
+ Show one thread.
152
+
153
+ | Argument/Option | Description |
154
+ | --- | --- |
155
+ | `<thread-id>` | Thread ID. |
156
+ | `--json` | Output raw JSON. |
157
+
158
+ Example:
86
159
 
87
160
  ```bash
88
- engagelab-email-cli threads list \
89
- --mailbox-id 1001 \
90
- --subject refund \
91
- --participant alice@example.com \
92
- --page-no 1 \
93
- --page-size 20
161
+ engagelab-email-cli threads get b0d9d6a1-1d17-4df8-8245-c807d7e8cb50
162
+ ```
163
+
164
+ ### `threads messages <thread-id>`
94
165
 
95
- engagelab-email-cli threads get <thread-id> --json
166
+ List messages in a thread.
96
167
 
97
- engagelab-email-cli threads messages <thread-id> \
98
- --limit 50 \
99
- --include-content \
100
- --json
168
+ | Argument/Option | Description |
169
+ | --- | --- |
170
+ | `<thread-id>` | Thread ID. |
171
+ | `--limit <number>` | Maximum number of messages to return. |
172
+ | `--include-content` | Include message content and attachment information. |
173
+ | `--json` | Output raw JSON. |
174
+
175
+ Example:
176
+
177
+ ```bash
178
+ engagelab-email-cli threads messages b0d9d6a1-1d17-4df8-8245-c807d7e8cb50 --include-content --json
101
179
  ```
102
180
 
103
- ## Receiving
181
+ ### `emails receiving list`
182
+
183
+ List inbound messages.
184
+
185
+ | Option | Description |
186
+ | --- | --- |
187
+ | `--mailbox-id <id>` | Filter by mailbox ID. |
188
+ | `--keyword <text>` | Search by keyword. |
189
+ | `--page-no <number>` | Page number. |
190
+ | `--page-size <number>` | Number of results per page. |
191
+ | `--json` | Output raw JSON. |
192
+
193
+ Example:
104
194
 
105
195
  ```bash
106
- engagelab-email-cli emails receiving list \
107
- --mailbox-id 1001 \
108
- --keyword refund \
109
- --json
196
+ engagelab-email-cli emails receiving list --keyword refund --page-size 20
197
+ ```
110
198
 
111
- engagelab-email-cli emails receiving get <message-uid> --json
199
+ ### `emails receiving get <message-uid>`
112
200
 
113
- engagelab-email-cli emails receiving listen \
114
- --limit 10 \
115
- --interval 5 \
116
- --json
201
+ Show one inbound message.
117
202
 
118
- engagelab-email-cli emails receiving listen \
119
- --after 1500 \
120
- --limit 10 \
121
- --interval 5
203
+ | Argument/Option | Description |
204
+ | --- | --- |
205
+ | `<message-uid>` | Message UID. |
206
+ | `--json` | Output raw JSON. |
207
+
208
+ Example:
209
+
210
+ ```bash
211
+ engagelab-email-cli emails receiving get 7e2b2de6-14c5-4ef1-a1e2-f4337e4606e2 --json
122
212
  ```
123
213
 
124
- `emails receiving listen` follows the Resend-style CLI polling model:
214
+ ### `emails receiving listen`
125
215
 
126
- - It seeds the cursor from the latest message when `--after` is not provided, so historical messages are not printed on startup.
127
- - It polls `GET /v1/message/listen` every `--interval` seconds; the default is `5`, and the minimum is `2`.
128
- - It sends `after=<cursor>` on later polls and updates the cursor from the newest returned message.
129
- - It keeps running until `Ctrl+C` or process termination.
130
- - In `--json` mode, each new message is printed as one compact JSON line.
216
+ Poll for new inbound messages. This command keeps running until you stop it with `Ctrl+C`.
131
217
 
132
- ## Reply
218
+ | Option | Description |
219
+ | --- | --- |
220
+ | `--after <id>` | Start after a known cursor ID. |
221
+ | `--limit <number>` | Maximum messages per poll. Default: `10`. |
222
+ | `--interval <seconds>` | Polling interval. Default: `5`; minimum: `2`. |
223
+ | `--json` | Output one JSON message per line. |
133
224
 
134
- Short manual reply:
225
+ Example:
135
226
 
136
227
  ```bash
137
- engagelab-email-cli emails receiving reply <message-uid> \
138
- --text "您好，您的邮件已收到。" \
139
- --json
228
+ engagelab-email-cli emails receiving listen --limit 10 --interval 5 --json
140
229
  ```
141
230
 
142
- Skill-friendly reply:
231
+ Continue from a known cursor:
143
232
 
144
233
  ```bash
145
- engagelab-email-cli emails receiving reply <message-uid> --body-file reply.json --json
234
+ engagelab-email-cli emails receiving listen --after 1500 --limit 10 --interval 5 --json
146
235
  ```
147
236
 
148
- `reply.json`:
237
+ ### `emails receiving reply <message-uid>`
149
238
 
150
- ```json
151
- {
152
- "subject": "Re: Refund request",
153
- "text": "您好，您的退款申请已收到。",
154
- "html": "<p>您好，您的退款申请已收到。</p>",
155
- "cc": ["ops@example.com"],
156
- "bcc": []
157
- }
239
+ Reply to an inbound message.
240
+
241
+ | Argument/Option | Description |
242
+ | --- | --- |
243
+ | `<message-uid>` | Message UID to reply to. |
244
+ | `--subject <text>` | Reply subject. |
245
+ | `--text <text>` | Plain text reply content. |
246
+ | `--html <html>` | HTML reply content. |
247
+ | `--text-file <path>` | Read plain text reply content from a file. |
248
+ | `--html-file <path>` | Read HTML reply content from a file. |
249
+ | `--cc <email>` | CC address. Can be repeated. |
250
+ | `--bcc <email>` | BCC address. Can be repeated. |
251
+ | `--reply-to <email>` | Reply-To address. Can be repeated. |
252
+ | `--preview-text <text>` | Preview text. |
253
+ | `--attachment <path>` | Attach a file. Can be repeated. |
254
+ | `--sandbox` | Send in sandbox mode. |
255
+ | `--json` | Output raw JSON. |
256
+
257
+ Example:
258
+
259
+ ```bash
260
+ engagelab-email-cli emails receiving reply 7e2b2de6-14c5-4ef1-a1e2-f4337e4606e2 \
261
+ --text "Thanks, we received your message." \
262
+ --attachment ./receipt.pdf
158
263
  ```
159
264
 
160
- ## Send
265
+ ### `emails send`
161
266
 
162
- Manual send:
267
+ Send a new email.
268
+
269
+ | Option | Description |
270
+ | --- | --- |
271
+ | `--mailbox-id <id>` | Mailbox ID to send from. Required. |
272
+ | `--from <email>` | Sender address. |
273
+ | `--to <email>` | Recipient address. Can be repeated. Required. |
274
+ | `--subject <text>` | Email subject. Required. |
275
+ | `--text <text>` | Plain text email content. |
276
+ | `--html <html>` | HTML email content. |
277
+ | `--text-file <path>` | Read plain text email content from a file. |
278
+ | `--html-file <path>` | Read HTML email content from a file. |
279
+ | `--cc <email>` | CC address. Can be repeated. |
280
+ | `--bcc <email>` | BCC address. Can be repeated. |
281
+ | `--reply-to <email>` | Reply-To address. Can be repeated. |
282
+ | `--preview-text <text>` | Preview text. |
283
+ | `--attachment <path>` | Attach a file. Can be repeated. |
284
+ | `--sandbox` | Send in sandbox mode. |
285
+ | `--json` | Output raw JSON. |
286
+
287
+ Example:
163
288
 
164
289
  ```bash
165
290
  engagelab-email-cli emails send \
166
291
  --mailbox-id 1001 \
167
292
  --to alice@example.com \
293
+ --to bob@example.com \
168
294
  --subject "Refund update" \
169
- --text "您的退款申请已经处理完成。" \
170
- --json
295
+ --text "Your refund has been processed." \
296
+ --attachment ./receipt.pdf
171
297
  ```
172
298
 
173
- Skill-friendly send:
299
+ Send HTML content from a file:
174
300
 
175
301
  ```bash
176
- engagelab-email-cli emails send --body-file send.json --json
302
+ engagelab-email-cli emails send \
303
+ --mailbox-id 1001 \
304
+ --to alice@example.com \
305
+ --subject "Monthly report" \
306
+ --html-file ./report.html
177
307
  ```
178
308
 
179
- `send.json`:
180
-
181
- ```json
182
- {
183
- "mailboxId": 1001,
184
- "to": ["alice@example.com"],
185
- "subject": "Refund update",
186
- "text": "您的退款申请已经处理完成。",
187
- "html": "<p>您的退款申请已经处理完成。</p>",
188
- "cc": [],
189
- "bcc": []
190
- }
191
- ```
309
+ ## Output
192
310
 
193
- ## Body Input Rules
311
+ By default, the CLI prints readable tables or summaries and shows a short loading message while requests are running.
194
312
 
195
- - `--body-file` and `--body-json` are mutually exclusive.
196
- - `--body-file` / `--body-json` cannot be combined with field-level body options.
197
- - `--text` and `--text-file` are mutually exclusive.
198
- - `--html` and `--html-file` are mutually exclusive.
199
- - `emails send` requires `mailboxId`, at least one `to`, `subject`, and at least one of `text` or `html`.
200
- - `emails receiving reply` requires at least one of `text` or `html`.
313
+ Use `--json` when another tool or script needs to parse the result.
201
314
 
202
- ## Exit Codes
315
+ ```bash
316
+ engagelab-email-cli emails receiving get <message-uid> --json
317
+ ```
203
318
 
204
- | Code | Meaning |
205
- | --- | --- |
206
- | `0` | Success |
207
- | `1` | Invalid arguments or missing config |
208
- | `2` | Authentication failure |
209
- | `3` | Resource not found |
210
- | `4` | State conflict |
211
- | `5` | Server, network, invalid JSON, or unknown request failure |
319
+ `emails receiving listen --json` prints one message JSON object per line.