w-email 1.1.2 → 1.1.4

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 (12) hide show
  1. package/dist/w-email.umd.js +2 -2
  2. package/dist/w-email.umd.js.map +1 -1
  3. package/docs/WEmail.mjs.html +389 -156
  4. package/docs/global.html +88 -17
  5. package/docs/index.html +1 -1
  6. package/package.json +4 -3
  7. package/src/WEmail.mjs +388 -155
  8. package/test/api-WEmail-smtp.test.mjs +388 -0
  9. package/test/tools/fakeSmtp.mjs +310 -0
  10. package/test/tools/genCert.mjs +101 -0
  11. package/test/unit-WEmail-opt.test.mjs +316 -0
  12. package/test/all.test.mjs +0 -10
package/docs/global.html CHANGED
@@ -140,13 +140,49 @@
140
140
  <dl class="details">
141
141
 
142
142
  <dt class="tag-description">Description:</dt>
143
- <dd class="tag-description"><ul class="dummy"><li><p>寄送email</p></li></ul></dd>
143
+ <dd class="tag-description"><ul class="dummy"><li><p>寄送email</p>
144
+ <p>opt各欄位給予undefined或null時皆視為未給定而使用預設值；欄位型別或值不合規時，不連線即reject錯誤訊息字串(見下方「錯誤訊息」)。</p>
145
+ <p><strong>email檢核規則</strong>(srcEmail，以及toEmails、toEmailsCC、toEmailsBCC之每一筆皆適用)：</p>
146
+ <ol>
147
+ <li>須為字串，先去除前後空白。</li>
148
+ <li>網域(@之後)含非ASCII字元者視為國際化網域，先自動轉為punycode再檢核，並以轉換後之值寄送，例如<code>user@例子.測試</code>寄至<code>user@xn--fsqu00a.xn--g6w251d</code>；國際化網域內不得含空白、控制字元與<code>/</code>、<code>\</code>、<code>?</code>、<code>#</code>、<code>%</code>、<code>:</code>、<code>@</code>、<code>[</code>、<code>]</code>。</li>
149
+ <li>再以wsemi之isEmail檢核，須同時符合：
150
+ <ul>
151
+ <li>全長至多254字元，帳號部分(@之前)至多64字元。</li>
152
+ <li>帳號部分僅限ASCII之英數字與特殊字元 ! # $ % &amp; ' * + / = ? ^ _ { | } ~ - 及反引號，點只能作為分隔，不得位於開頭、結尾或連續出現。</li>
153
+ <li>網域為一段以上之主機名稱(英數字與中間之連字號，每段至多63字元，不得以連字號開頭或結尾)加頂級網域，頂級網域須為2字元以上之英文字母，或xn--開頭之punycode。</li>
154
+ </ul>
155
+ </li>
156
+ <li>因此以下格式一律拒收：帶顯示名稱或角括號(<code>Alice &lt;alice@example.com&gt;</code>、<code>&lt;alice@example.com&gt;</code>)、帶註解(<code>bob@example.com (Bob)</code>)、一個字串內含多筆(以逗號、分號或空白分隔)、引號形式之帳號(<code>&quot;john..doe&quot;@example.com</code>)、非ASCII之帳號(<code>張三@example.com</code>)、無頂級網域(<code>user@localhost</code>)、IP位址(<code>user@[127.0.0.1]</code>)、網域含底線。</li>
157
+ </ol>
158
+ <p><strong>收件人規則</strong>(toEmails、toEmailsCC、toEmailsBCC)：</p>
159
+ <ul>
160
+ <li>可為一個email字串(僅一位收件人)或email字串陣列，多位收件人須以陣列給予。</li>
161
+ <li>給予null、undefined、false、0或空字串時，視為該欄無收件人；陣列內為falsy或空白字串之元素略過。</li>
162
+ <li>三欄合計至少須有一位收件人。密件副本(toEmailsBCC)不出現於信件標頭。</li>
163
+ </ul>
164
+ <p><strong>附件規則</strong>(emAttachments)：</p>
165
+ <ul>
166
+ <li>可為附件物件或附件物件陣列；給予null、undefined、false、0或空字串時視為無附件，陣列內為falsy或空白字串之元素略過。</li>
167
+ <li>每個附件物件須具下列內容來源之一：<code>raw</code>(非空)、<code>path</code>(非空字串，本機路徑或網址)、<code>href</code>(非空字串網址)、<code>content</code>(字串、Buffer或可讀串流)；<code>filename</code>若給予須為字串，或給予false表示不帶檔名。</li>
168
+ <li>path與href會讀取本機檔案或連線下載，不可直接採用不可信任之輸入。</li>
169
+ </ul>
170
+ <p><strong>錯誤訊息</strong>(輸入檢核失敗時reject之字串，皆於連線前發生)：</p>
171
+ <ul>
172
+ <li><code>srcEmail is not email</code></li>
173
+ <li><code>srcName is not string</code>、<code>srcPW is not string</code>、<code>emTitle is not string</code>、<code>emContent is not string</code></li>
174
+ <li><code>srcHost is not effective string</code></li>
175
+ <li><code>srcPort is not valid port</code></li>
176
+ <li><code>toEmails is not string or array</code>、<code>toEmails is not email</code>(以字串給予時)、<code>toEmails[i] is not email</code>(以陣列給予時，i為元素索引)；toEmailsCC與toEmailsBCC同，僅欄位名不同</li>
177
+ <li><code>no recipients</code></li>
178
+ <li><code>emAttachments is not object or array</code>、<code>emAttachments is not valid attachment</code>(以物件給予時)、<code>emAttachments[i] is not valid attachment</code>(以陣列給予時)</li>
179
+ </ul></li></ul></dd>
144
180
 
145
181
 
146
182
 
147
183
  <dt class="tag-source">Source:</dt>
148
184
  <dd class="tag-source"><ul class="dummy"><li>
149
- <a href="WEmail.mjs.html">WEmail.mjs</a>, <a href="WEmail.mjs.html#line53">line 53</a>
185
+ <a href="WEmail.mjs.html">WEmail.mjs</a>, <a href="WEmail.mjs.html#line241">line 241</a>
150
186
  </li></ul></dd>
151
187
 
152
188
 
@@ -193,7 +229,32 @@
193
229
 
194
230
  <h5 class="h5-examples">Example</h5>
195
231
 
196
- <pre class="prettyprint"><code>import WEmail from 'w-email'
197
232
  srcName: 'test name',
198
233
  srcEmail: 'your email',
199
234
  srcPW: 'your password',
200
235
  emTitle: 'test title',
201
236
  emContent: '&lt;h4>test head&lt;/h4>'+'&lt;div>test content&lt;/div>',
202
237
  toEmails: 'to email',
203
238
  //toEmailsCC: 'to email',
204
239
  //toEmailsBCC: 'to email',
205
240
  emAttachments: {
206
241
  filename: 'your filename',
207
242
  path: 'your filepath'
208
243
  }
209
244
  .then((msg)=>{
210
245
  console.log('then',msg)
211
246
  })
212
247
  .catch((err)=>{
213
248
  console.log('catch',err)
214
249
  })</code></pre>
250
+ <pre class="prettyprint"><code>import WEmail from 'w-email'
251
+
252
+ //opt
253
+ let opt = {
254
+ srcName: 'test name',
255
+ srcEmail: 'your email',
256
+ srcPW: 'your password',
257
+ emTitle: 'test title',
258
+ emContent: '&lt;h4>test head&lt;/h4>'+'&lt;div>test content&lt;/div>',
259
+ toEmails: 'to email',
260
+ //toEmailsCC: 'to email',
261
+ //toEmailsBCC: 'to email',
262
+ emAttachments: {
263
+ filename: 'your filename',
264
+ path: 'your filepath'
265
+ }
266
+ }
267
+
268
+ //WEmail
269
+ new WEmail(opt)
270
+ .then((msg)=>{
271
+ console.log('then',msg)
272
+ })
273
+ .catch((err)=>{
274
+ console.log('catch',err)
275
+ })</code></pre>
215
276
 
216
277
 
217
278
 
@@ -233,7 +294,7 @@
233
294
  <td class="type">
234
295
 
235
296
 
236
- <span class="param-type">*</span>
297
+ <span class="param-type">Object</span>
237
298
 
238
299
 
239
300
 
@@ -323,7 +384,7 @@
323
384
  </td>
324
385
 
325
386
 
326
- <td class="description last"><p>輸入寄件人顯示名稱字串，預設'system by w-email'</p></td>
387
+ <td class="description last"><p>輸入寄件人顯示名稱字串，可為數字，換行字元轉為空白並去除前後空白，給予空字串則不顯示名稱，預設'system by w-email'</p></td>
327
388
  </tr>
328
389
 
329
390
 
@@ -359,7 +420,7 @@
359
420
  </td>
360
421
 
361
422
 
362
- <td class="description last"><p>輸入寄件人email信箱字串</p></td>
423
+ <td class="description last"><p>輸入寄件人email信箱字串，亦作為登入郵件伺服器之帳號，須符合email檢核規則</p></td>
363
424
  </tr>
364
425
 
365
426
 
@@ -382,6 +443,8 @@
382
443
 
383
444
  <td class="attributes">
384
445
 
446
+ &lt;optional><br>
447
+
385
448
 
386
449
 
387
450
 
@@ -392,10 +455,12 @@
392
455
 
393
456
  <td class="default">
394
457
 
458
+ <code>''</code>
459
+
395
460
  </td>
396
461
 
397
462
 
398
- <td class="description last"><p>輸入寄件人email密碼字串</p></td>
463
+ <td class="description last"><p>輸入寄件人email密碼字串，可為數字，郵件伺服器未要求登入時可為空字串，預設''</p></td>
399
464
  </tr>
400
465
 
401
466
 
@@ -435,7 +500,7 @@
435
500
  </td>
436
501
 
437
502
 
438
- <td class="description last"><p>輸入郵件伺服器位址，預設'smtp.gmail.com'</p></td>
503
+ <td class="description last"><p>輸入郵件伺服器位址字串，去除前後空白後不可為空，預設'smtp.gmail.com'</p></td>
439
504
  </tr>
440
505
 
441
506
 
@@ -448,6 +513,9 @@
448
513
  <td class="type">
449
514
 
450
515
 
516
+ <span class="param-type">Number</span>
517
+ |
518
+
451
519
  <span class="param-type">String</span>
452
520
 
453
521
 
@@ -475,7 +543,7 @@
475
543
  </td>
476
544
 
477
545
 
478
- <td class="description last"><p>輸入郵件伺服器連接埠，預設587</p></td>
546
+ <td class="description last"><p>輸入郵件伺服器連接埠，可為正整數或其字串，範圍1至65535，465使用SSL/TLS連線，其他連接埠於伺服器支援時使用STARTTLS(伺服器未宣告STARTTLS時以明文連線與登入)，預設587</p></td>
479
547
  </tr>
480
548
 
481
549
 
@@ -515,7 +583,7 @@
515
583
  </td>
516
584
 
517
585
 
518
- <td class="description last"><p>輸入郵件名稱字串，預設''</p></td>
586
+ <td class="description last"><p>輸入郵件名稱字串，可為數字，預設''</p></td>
519
587
  </tr>
520
588
 
521
589
 
@@ -529,6 +597,9 @@
529
597
 
530
598
 
531
599
  <span class="param-type">String</span>
600
+ |
601
+
602
+ <span class="param-type">Buffer</span>
532
603
 
533
604
 
534
605
 
@@ -555,7 +626,7 @@
555
626
  </td>
556
627
 
557
628
 
558
- <td class="description last"><p>輸入郵件訊息字串，預設''</p></td>
629
+ <td class="description last"><p>輸入郵件訊息字串，以html寄送，可為數字或Buffer，預設''</p></td>
559
630
  </tr>
560
631
 
561
632
 
@@ -598,7 +669,7 @@
598
669
  </td>
599
670
 
600
671
 
601
- <td class="description last"><p>輸入收件人email字串或陣列，預設[]</p></td>
672
+ <td class="description last"><p>輸入收件人email字串或陣列，須符合email檢核規則與收件人規則，預設[]</p></td>
602
673
  </tr>
603
674
 
604
675
 
@@ -641,7 +712,7 @@
641
712
  </td>
642
713
 
643
714
 
644
- <td class="description last"><p>輸入副本收件人email字串或陣列，預設[]</p></td>
715
+ <td class="description last"><p>輸入副本收件人email字串或陣列，規則同toEmails，預設[]</p></td>
645
716
  </tr>
646
717
 
647
718
 
@@ -684,7 +755,7 @@
684
755
  </td>
685
756
 
686
757
 
687
- <td class="description last"><p>輸入密件副本收件人email字串或陣列，預設[]</p></td>
758
+ <td class="description last"><p>輸入密件副本收件人email字串或陣列，規則同toEmails，預設[]</p></td>
688
759
  </tr>
689
760
 
690
761
 
@@ -727,7 +798,7 @@
727
798
  </td>
728
799
 
729
800
 
730
- <td class="description last"><p>輸入附件物件或陣列，預設[]，物件內需包含filename與path</p></td>
801
+ <td class="description last"><p>輸入附件物件或陣列，須符合附件規則，預設[]</p></td>
731
802
  </tr>
732
803
 
733
804
 
@@ -760,7 +831,7 @@
760
831
 
761
832
 
762
833
  <div class="param-desc">
763
- <p>回傳Promise，resolve回傳成功訊息，reject回傳錯誤訊息</p>
834
+ <p>回傳Promise，resolve回傳郵件伺服器回應字串，部分收件人被伺服器拒收時仍為resolve且不回傳被拒名單；reject回傳錯誤，輸入檢核失敗時為錯誤訊息字串，其餘為Error物件(通常帶code，伺服器回應之錯誤另帶responseCode)；toEmails、toEmailsCC、toEmailsBCC合計至少須有一位收件人；郵件伺服器無回應時依nodemailer預設逾時(連線2分鐘、招呼30秒、閒置10分鐘)後reject</p>
764
835
  </div>
765
836
 
766
837
 
@@ -802,7 +873,7 @@
802
873
  <br class="clear">
803
874
 
804
875
  <footer>
805
- Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Sep 18 2026 18:00:14 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
876
+ Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Thu Oct 01 2026 23:06:13 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
806
877
  </footer>
807
878
 
808
879
  <script>prettyPrint();</script>
package/docs/index.html CHANGED
@@ -71,7 +71,7 @@
71
71
  <br class="clear">
72
72
 
73
73
  <footer>
74
- Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Sep 18 2026 18:00:14 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
74
+ Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Thu Oct 01 2026 23:06:13 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
75
75
  </footer>
76
76
 
77
77
  <script>prettyPrint();</script>
package/package.json CHANGED
@@ -1,12 +1,13 @@
1
1
  {
2
2
  "name": "w-email",
3
- "version": "1.1.2",
3
+ "version": "1.1.4",
4
4
  "main": "dist/w-email.umd.js",
5
5
  "dependencies": {
6
- "nodemailer": "^9.0.3",
7
- "wsemi": "^1.9.1"
6
+ "nodemailer": "^10.0.13",
7
+ "wsemi": "^1.9.3"
8
8
  },
9
9
  "devDependencies": {
10
+ "mailparser": "^3.9.33",
10
11
  "w-package-tools": "^1.1.16"
11
12
  },
12
13
  "scripts": {