@suphark/notify 0.3.0 → 0.3.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Suphark
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Suphark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,200 +1,246 @@
-# @suphark/notify
-
-SDK ส่งอีเมล + แจ้งเตือน (Telegram) ของแอปทุกตัว — ค่าเริ่มต้นส่งผ่าน **Pi Notify hub** (`https://notify.suphark.com`) ซึ่งเป็นคนถือ credential ของ Resend/SMTP/Zoho/Telegram bot ทำ failover นับโควต้า เก็บ log และเก็บว่าผู้รับผูกแชทไหนไว้ แอปใส่แค่ key ตัวเดียว
-
-```bash
-pnpm add @suphark/notify   # หรือ npm i / bun add
-```
-
-## ใช้งาน (โหมด hub — แนะนำ)
-
-```env
-PI_NOTIFY_KEY=pn_xxx        # ออกจากหน้า Apps & keys ของ Pi Notify
-```
-
-```ts
-import { sendMail } from "@suphark/notify";
-
-await sendMail({
-  to: "user@example.com",
-  subject: "ยินดีต้อนรับ",
-  html: "<p>สวัสดี</p>",
-});
-```
-
-จบ — ไม่ต้องใส่ `from` (hub ใช้ from เริ่มต้นของแอป), ไม่ต้องรู้ว่าข้างหลังเป็น Resend หรือ SMTP, provider ล่มหรือโควต้าหมด hub ย้ายให้เอง
-
-- `PI_NOTIFY_URL` override ได้เมื่อรัน hub ที่อื่น (เช่น `http://localhost:3300` ตอน dev)
-- ผลลัพธ์ `{ id, provider: "hub", failedOver, attempts }`; ส่งไม่ได้เลยโยน `AllProvidersFailedError` (hub ตอบ 429 = โควต้าหมดทุกตัว, 502 = provider ล้มทุกตัว, 422 = ข้อความผิด)
-
-### ดูว่ามีตัวเลือกอะไร / ขอให้ส่งผ่านตัวไหนก่อน
-
-```ts
-import { listProviders, sendMail } from "@suphark/notify";
-
-await listProviders();
-// [{ name: "resend", type: "resend", available: true, via: "hub" },
-//  { name: "company-smtp", type: "smtp", available: false, via: "hub" }]   ← แค่นี้ ไม่มี config/โควต้า
-
-await sendMail({ to, subject, html, prefer: "company-smtp" });  // ลองตัวนี้ก่อน ไม่ได้ค่อย failover ตามลำดับปกติ
-```
-
-### สำรองเผื่อ hub ล่ม (ไม่บังคับ)
-
-ใส่ provider local ต่อท้ายได้ — hub มาก่อนเสมอ ถ้า hub ตอบไม่ได้ SDK จะ failover ไปตัวถัดไปเอง:
-
-```env
-PI_NOTIFY_KEY=pn_xxx
-MAIL_FROM="My App <noreply@example.com>"
-MAIL_PROVIDERS=resend
-MAIL_RESEND_API_KEY=re_xxx
-```
-
-## แจ้งเตือน (Telegram / อีเมล fallback)
-
-ผู้รับระบุด้วย **อีเมล** (บัญชี Pi Auth) — hub ดูเองว่าคนนั้นผูก Telegram ไว้ไหม ผูกไว้ส่งแชท ไม่ผูกส่งอีเมล แอปไม่ต้องเก็บ chat id
-
-```ts
-import { notify } from "@suphark/notify";
-
-const r = await notify({
-  to: "user@example.com",          // หรือ array ≤ 50
-  title: "บิลใกล้ครบกำหนด",
-  body: "ค่าเน็ต 599 บาท ครบกำหนดพรุ่งนี้",   // ข้อความล้วน หรือ HTML จำกัดแท็ก b/i/u/s/a/code/pre
-  link: "https://duebell.app/alerts",     // ปุ่ม "เปิดลิงก์"
-});
-// r = { sent: 1, failed: 0, skipped: 0, results: [{ to, channel: "telegram", status: "sent", provider, id }] }
-```
-
-- `format: "text"` เมื่อ body เป็นข้อความล้วนที่อาจมี `<` `&` (เช่นชื่อรายการ "บัตร <KBank>") — ไม่ระบุ hub จะเดาจากแท็กที่รู้จัก; `"html"` = ตีความแท็ก b/i/u/s/a/code/pre
-- `channels: ["telegram"]` = ส่งเฉพาะแชท ไม่ผูก → `status: "skipped", reason: "channel_not_linked"` (ไม่ตกไปอีเมล) · `["email"]` = อีเมลอย่างเดียว · `["telegram", "email"]` = ทั้งคู่
-- failover ไม่ข้ามช่องทาง (Telegram ส่งพังไม่ได้แปลว่าส่งอีเมลแทน) — แอปดู `results` แล้วตัดสินใจเอง
-- hub ตอบ 502 เมื่อไม่มีช่องทางไหนสำเร็จเลย → โยน `MailError` (`err.cause.error.results` มีรายละเอียด)
-
-**ให้ผู้ใช้ผูก Telegram จากหน้าตั้งค่าของแอป** (ไม่ต้องเด้งไป hub):
-
-```ts
-import { createLink, getRecipient } from "@suphark/notify";
-
-const { url, expiresAt } = await createLink(user.email);   // https://t.me/<bot>?start=<code> (10 นาที)
-// แสดงปุ่ม/QR → ผู้ใช้กด Start ในแชท → โพล
-const { channels } = await getRecipient(user.email);       // [{ type: "telegram", label: "@bob", enabled: true, linkedAt }]
-```
-
-หรือส่งผู้ใช้ไปผูกเองที่ `https://notify.suphark.com/me` (ล็อกอิน Pi Auth) — ผูกครั้งเดียวใช้ได้ทุกแอป
-
-## โหมด local (ไม่ผ่าน hub)
-
-ไม่มี `PI_NOTIFY_KEY` = SDK ส่งตรงด้วย provider ที่ตั้งใน env ของแอปเอง (engine เดียวกับที่ hub ใช้)
-
-```env
-MAIL_FROM="My App <noreply@example.com>"
-MAIL_PROVIDERS=resend,company,zoho      # ลำดับ = ลำดับความสำคัญ
-
-MAIL_RESEND_API_KEY=re_xxx
-MAIL_RESEND_QUOTA_DAY=100               # เพดานที่ตั้งเอง → ถึงแล้วข้ามไปตัวถัดไปทันที
-
-MAIL_COMPANY_TYPE=smtp
-MAIL_COMPANY_HOST=mail.example.com
-MAIL_COMPANY_PORT=587
-MAIL_COMPANY_USER=noreply@example.com
-MAIL_COMPANY_PASS=secret
-
-MAIL_ZOHO_USER=me@example.com           # ชื่อตรงกับ preset ไม่ต้องใส่ _TYPE
-MAIL_ZOHO_PASS=app-password
-```
-
-หรือตั้งค่าในโค้ด:
-
-```ts
-import { createMailer } from "@suphark/notify";
-
-export const mailer = createMailer({
-  from: "My App <noreply@example.com>",
-  providers: [
-    { type: "hub", apiKey: process.env.PI_NOTIFY_KEY! },
-    { type: "resend", apiKey: process.env.RESEND_API_KEY!, quota: { perDay: 100 } },
-    { type: "smtp", name: "company", host: "mail.example.com", port: 587, user: "…", pass: "…" },
-    { type: "zoho", user: "me@example.com", pass: "…" },
-    { type: "console" }, // dev: พิมพ์ลง console
-  ],
-  strategy: "priority", // หรือ "round-robin"
-  onEvent: (e) => logger.info(e), // sent / failed / skipped / cooldown / recovered / exhausted
-});
-```
-
-`configureMailer(options)` ครั้งเดียวตอนบูตถ้าอยากใช้ `sendMail()` แบบ global กับ options เอง
-
-### เกิดอะไรขึ้นตอนส่ง
-
-1. ไล่ provider ตามลำดับ ข้ามตัวที่อยู่ใน **cooldown** (เพิ่งพัง) หรือ **โควต้าที่ตั้งเต็ม**
-2. ตัวที่ลองแล้วพัง → จำแนก error แล้วพัก (backoff คูณสองเมื่อพังซ้ำ)
-
-| error | kind | พัก (ค่าเริ่มต้น) |
-|---|---|---|
-| ต่อไม่ติด / timeout | `network` | 1 นาที |
-| 5xx, SMTP 421/45x | `server` | 1 นาที |
-| 429 | `rate_limit` | 2 นาที |
-| 401/403, SMTP 535, domain not verified | `auth` | 15 นาที |
-| quota / sending limit / SMTP 552 | `quota` | 1 ชั่วโมง |
-| 400/422, SMTP 550 recipient rejected | `invalid` | ไม่พัก |
-
-3. คืน `{ id, provider, failedOver, attempts }` หรือโยน `AllProvidersFailedError` (มี `attempts`)
-
-### provider type
-
-| type | ต้องใส่ |
-|---|---|
-| `hub` | `apiKey` (`url` optional) |
-| `resend` | `apiKey` |
-| `smtp` | `host` (+ `port` `secure` `user` `pass` `rejectUnauthorized` `pool`) |
-| `zoho` `zohopro` `gmail` `office365` `brevo` `mailtrap` | `user`, `pass` (SMTP preset) |
-| `zeptomail` | `apiKey` (+ `region`) |
-| `console` | – |
-| `custom` | `provider` (object ที่ implement `Provider`) |
-
-ทุก type รับ `name` `from` `senderDomains` `quota: { perHour, perDay, perMonth }` `disabled`
-
-**ตัวตนผู้ส่ง**: provider ที่ตั้ง `from` ไว้จะส่งจากที่อยู่นั้นเสมอ เว้นแต่ `message.from` อยู่ใน `senderDomains` (หรือเป็นที่อยู่เดียวกัน) — ถ้าไม่ผ่านจะใช้ที่อยู่ของ provider แต่คงชื่อจาก message (`Pi Auth <noreply@hub.example>`) เพราะ SMTP/Resend ปฏิเสธ from ที่ไม่ใช่ของตัวเอง; provider ที่ไม่ตั้ง `from` (hub, console) ส่งจากที่อยู่ที่ message ขอ
-
-env: `MAIL_<NAME>_<FIELD>` — `TYPE FROM QUOTA_HOUR QUOTA_DAY QUOTA_MONTH DISABLED` · `API_KEY BASE_URL REGION URL` · `HOST PORT SECURE USER PASS POOL TIMEOUT_MS REJECT_UNAUTHORIZED`
-
-## Message
-
-```ts
-{
-  to: Address | Address[];         // "a@b.com" | "ชื่อ <a@b.com>" | { name, email }
-  subject: string;
-  html?: string; text?: string;    // อย่างน้อยหนึ่ง
-  from?: Address;                  // ชนะ from ของ provider/แอป
-  cc?, bcc?, replyTo?;
-  attachments?: { filename, content: Buffer | string, contentType?, encoding?: "base64" }[];
-  headers?: Record<string, string>;
-  tags?: Record<string, string>;   // Resend เท่านั้น
-  prefer?: string;                 // ลองตัวนี้ก่อน (ชื่อจาก listProviders) ยัง failover
-  provider?: string;               // บังคับตัวนี้ตัวเดียว ไม่ failover (โหมด local เท่านั้น)
-}
-```
-
-## อื่น ๆ
-
-```ts
-await mailer.verify();   // ทดสอบเชื่อมต่อทุกตัว (hub: เช็ค key)
-await mailer.status();   // cooldown / โควต้าที่ใช้ไป
-await mailer.reset();    // ล้าง cooldown
-```
-
-- โหมด local หลาย instance แชร์ cooldown/โควต้า: `createMailer({ store: createRedisStore(redis) })`
-- provider เอง: implement `{ name, type, send(msg) }` แล้วโยน `MailError` พร้อม `kind`
-- ESM only, Node ≥ 20
-
-## Changelog
-
-- 0.3.0 — **เปลี่ยนชื่อ Pi Mail → Pi Notify** (breaking): แพ็กเกจย้ายจาก `@suphark/mailer` เป็น `@suphark/notify` (API เดิมทุกตัว เปลี่ยนแค่ import), env `PI_MAIL_KEY`/`PI_MAIL_URL` → `PI_NOTIFY_KEY`/`PI_NOTIFY_URL` (ชื่อเดิมไม่อ่านแล้ว), hub เริ่มต้น `https://notify.suphark.com`; key ใหม่ขึ้นต้น `pn_` (key `pm_` เดิมยังใช้ได้)
-
-- 0.2.1 — `notify()` เพิ่ม `format?: "text" | "html"` ระบุชนิด body ชัดเจน (hub 2026-09-19+ ; ไม่ระบุยังเดาให้ แต่เดาเข้มขึ้น: นับเฉพาะแท็กที่รู้จัก)
-
-- 0.2.0 — **Pi Notify**: `notify()` ส่งแจ้งเตือนถึงอีเมลผู้รับผ่าน hub (Telegram ที่ผู้รับผูกไว้ / อีเมล fallback), `createLink()` ขอ deep link ผูก Telegram, `getRecipient()` ดูช่องทางที่ผูก — ใช้ `PI_MAIL_KEY`/`PI_MAIL_URL` เดิม; `sendMail()` ไม่เปลี่ยน
-
-- 0.1.1 — **fix**: โควต้าจองก่อนส่ง (คำขอพร้อมกันไม่ทะลุเพดาน, ส่งพังคืนโควต้า — Store มี `decr` optional), from ผิดรูปแบบโยน invalid ทันที, `hub` ใน MAIL_PROVIDERS ใช้ PI_MAIL_KEY/PI_MAIL_URL ได้, Resend `verify()` ไม่ต้องใช้สิทธิ์ list domains; nodemailer ^10 (ปิด advisory ของ 7.x); **from policy**: provider ที่มี `from` เป็นตัวตนผู้ส่ง, `senderDomains` อนุญาตทั้งโดเมน (message.from นอกโดเมนถูกแทนที่แต่คงชื่อ); config `custom` รับ `from`/`name` override
-- 0.1.0 — รุ่นแรก: hub (`PI_MAIL_KEY`), resend, smtp + presets, zeptomail, console, custom; failover/โควต้า/cooldown; `listProviders()` + `prefer`
+# @suphark/notify
+
+SDK ส่งอีเมล + แจ้งเตือน (Telegram) ของแอปทุกตัว — ค่าเริ่มต้นส่งผ่าน **Pi Notify hub** (`https://notify.suphark.com`) ซึ่งเป็นคนถือ credential ของ Resend/SMTP/Zoho/Telegram bot ทำ failover นับโควต้า เก็บ log และเก็บว่าผู้รับผูกแชทไหนไว้ แอปใส่แค่ key ตัวเดียว
+
+```bash
+pnpm add @suphark/notify   # หรือ npm i / bun add
+```
+
+## ใช้งาน (โหมด hub — แนะนำ)
+
+```env
+PI_NOTIFY_KEY=pn_xxx        # ออกจากหน้า Apps & keys ของ Pi Notify
+```
+
+```ts
+import { sendMail } from "@suphark/notify";
+
+await sendMail({
+  to: "user@example.com",
+  subject: "ยินดีต้อนรับ",
+  html: "<p>สวัสดี</p>",
+});
+```
+
+จบ — ไม่ต้องใส่ `from` (hub ใช้ from เริ่มต้นของแอป), ไม่ต้องรู้ว่าข้างหลังเป็น Resend หรือ SMTP, provider ล่มหรือโควต้าหมด hub ย้ายให้เอง
+
+- `PI_NOTIFY_URL` override ได้เมื่อรัน hub ที่อื่น (เช่น `http://localhost:3300` ตอน dev)
+- ผลลัพธ์ `{ id, provider: "hub", failedOver, attempts }`; ส่งไม่ได้เลยโยน `AllProvidersFailedError` (hub ตอบ 429 = โควต้าหมดทุกตัว, 502 = provider ล้มทุกตัว, 422 = ข้อความผิด)
+
+### ดูว่ามีตัวเลือกอะไร / ขอให้ส่งผ่านตัวไหนก่อน
+
+```ts
+import { listProviders, sendMail } from "@suphark/notify";
+
+await listProviders();
+// [{ name: "resend", type: "resend", available: true, via: "hub" },
+//  { name: "company-smtp", type: "smtp", available: false, via: "hub" }]   ← แค่นี้ ไม่มี config/โควต้า
+
+await sendMail({ to, subject, html, prefer: "company-smtp" });  // ลองตัวนี้ก่อน ไม่ได้ค่อย failover ตามลำดับปกติ
+```
+
+### สำรองเผื่อ hub ล่ม (ไม่บังคับ)
+
+ใส่ provider local ต่อท้ายได้ — hub มาก่อนเสมอ ถ้า hub ตอบไม่ได้ SDK จะ failover ไปตัวถัดไปเอง:
+
+```env
+PI_NOTIFY_KEY=pn_xxx
+MAIL_FROM="My App <noreply@example.com>"
+MAIL_PROVIDERS=resend
+MAIL_RESEND_API_KEY=re_xxx
+```
+
+## แจ้งเตือน (Telegram / อีเมล fallback)
+
+ผู้รับระบุด้วย **อีเมล** (บัญชี Pi Auth) — hub ดูเองว่าคนนั้นผูก Telegram ไว้ไหม ผูกไว้ส่งแชท ไม่ผูกส่งอีเมล แอปไม่ต้องเก็บ chat id
+
+```ts
+import { notify } from "@suphark/notify";
+
+const r = await notify({
+  to: "user@example.com",          // หรือ array ≤ 50
+  title: "บิลใกล้ครบกำหนด",
+  body: "ค่าเน็ต 599 บาท ครบกำหนดพรุ่งนี้",   // ข้อความล้วน หรือ HTML จำกัดแท็ก b/i/u/s/a/code/pre
+  link: "https://duebell.app/alerts",     // ปุ่ม "เปิดลิงก์"
+});
+// r = { sent: 1, failed: 0, skipped: 0, results: [{ to, channel: "telegram", status: "sent", provider, id }] }
+```
+
+- `format: "text"` เมื่อ body เป็นข้อความล้วนที่อาจมี `<` `&` (เช่นชื่อรายการ "บัตร <KBank>") — ไม่ระบุ hub จะเดาจากแท็กที่รู้จัก; `"html"` = ตีความแท็ก b/i/u/s/a/code/pre
+- `channels: ["telegram"]` = ส่งเฉพาะแชท ไม่ผูก → `status: "skipped", reason: "channel_not_linked"` (ไม่ตกไปอีเมล) · `["email"]` = อีเมลอย่างเดียว · `["telegram", "email"]` = ทั้งคู่
+- failover ไม่ข้ามช่องทาง (Telegram ส่งพังไม่ได้แปลว่าส่งอีเมลแทน) — แอปดู `results` แล้วตัดสินใจเอง
+- hub ตอบ 502 เมื่อไม่มีช่องทางไหนสำเร็จเลย → โยน `MailError` (`err.cause.error.results` มีรายละเอียด)
+- timeout: `notify()` รอสูงสุด 65 วิ, `getRecipient()`/`createLink()` 10 วิ (เปลี่ยนด้วย `{ timeoutMs }`) หมดเวลาโยน `MailError` kind `network` — hub อาจส่งไปแล้ว อย่ายิงซ้ำทั้งก้อนทันที
+- 429/503 มี `err.retryAfterSec` (จาก `Retry-After`) บอกว่าควรรอกี่วินาทีก่อนลองใหม่
+
+**ให้ผู้ใช้ผูก Telegram จากหน้าตั้งค่าของแอป** (ไม่ต้องเด้งไป hub):
+
+```ts
+import { createLink, getRecipient } from "@suphark/notify";
+
+const { url, expiresAt } = await createLink(user.email);   // https://t.me/<bot>?start=<code> (10 นาที)
+// แสดงปุ่ม/QR → ผู้ใช้กด Start ในแชท → โพล
+const { channels } = await getRecipient(user.email);       // [{ type: "telegram", label: "@bob", enabled: true, linkedAt }]
+```
+
+หรือส่งผู้ใช้ไปผูกเองที่ `https://notify.suphark.com/me` (ล็อกอิน Pi Auth) — ผูกครั้งเดียวใช้ได้ทุกแอป
+
+## โหมด local (ไม่ผ่าน hub)
+
+ไม่มี `PI_NOTIFY_KEY` = SDK ส่งตรงด้วย provider ที่ตั้งใน env ของแอปเอง (engine เดียวกับที่ hub ใช้)
+
+```env
+MAIL_FROM="My App <noreply@example.com>"
+MAIL_PROVIDERS=resend,company,zoho      # ลำดับ = ลำดับความสำคัญ
+
+MAIL_RESEND_API_KEY=re_xxx
+MAIL_RESEND_QUOTA_DAY=100               # เพดานที่ตั้งเอง → ถึงแล้วข้ามไปตัวถัดไปทันที
+
+MAIL_COMPANY_TYPE=smtp
+MAIL_COMPANY_HOST=mail.example.com
+MAIL_COMPANY_PORT=587
+MAIL_COMPANY_USER=noreply@example.com
+MAIL_COMPANY_PASS=secret
+
+MAIL_ZOHO_USER=me@example.com           # ชื่อตรงกับ preset ไม่ต้องใส่ _TYPE
+MAIL_ZOHO_PASS=app-password
+```
+
+หรือตั้งค่าในโค้ด:
+
+```ts
+import { createMailer } from "@suphark/notify";
+
+export const mailer = createMailer({
+  from: "My App <noreply@example.com>",
+  providers: [
+    { type: "hub", apiKey: process.env.PI_NOTIFY_KEY! },
+    { type: "resend", apiKey: process.env.RESEND_API_KEY!, quota: { perDay: 100 } },
+    { type: "smtp", name: "company", host: "mail.example.com", port: 587, user: "…", pass: "…" },
+    { type: "zoho", user: "me@example.com", pass: "…" },
+    { type: "console" }, // dev: พิมพ์ลง console
+  ],
+  strategy: "priority", // หรือ "round-robin"
+  onEvent: (e) => logger.info(e), // sent / failed / skipped / cooldown / recovered / exhausted
+});
+```
+
+`configureMailer(options)` ครั้งเดียวตอนบูตถ้าอยากใช้ `sendMail()` แบบ global กับ options เอง
+
+### เกิดอะไรขึ้นตอนส่ง
+
+1. ไล่ provider ตามลำดับ ข้ามตัวที่อยู่ใน **cooldown** (เพิ่งพัง) หรือ **โควต้าที่ตั้งเต็ม**
+2. ตัวที่ลองแล้วพัง → จำแนก error แล้วพัก (backoff คูณสองเมื่อพังซ้ำ)
+
+| error | kind | พัก (ค่าเริ่มต้น) |
+|---|---|---|
+| ต่อไม่ติด / timeout | `network` | 1 นาที |
+| 5xx, SMTP 421/45x | `server` | 1 นาที |
+| 429 | `rate_limit` | 2 นาที |
+| 401/403, SMTP 535, domain not verified | `auth` | 15 นาที |
+| quota / sending limit / SMTP 552 | `quota` | 1 ชั่วโมง |
+| 400/422, SMTP 550 recipient rejected | `invalid` | ไม่พัก |
+
+3. ปลายทางตอบ `Retry-After` (Pi Notify ตอบมากับ 429/503) → พักเท่าที่ขอ ไม่คูณสอง (ไม่เกิน 1 ชม.)
+4. ทุกตัวติด cooldown จนไม่ได้ลองส่งสักตัว → **half-open**: ลองตัวที่ cooldown จะหมดเร็วสุด 1 ครั้ง (เฉพาะที่พักเพราะ `network`/`server`/`unknown`, ไม่เกิน 1 ครั้งต่อ 30 วิต่อ provider, ยังจองโควต้าตามปกติ) สำเร็จ = ล้าง cooldown ทันที — แอปที่มี hub ตัวเดียวจึงไม่ต้องรอ cooldown 30 นาทีหลัง Pi Notify กลับมา
+5. คืน `{ id, provider, failedOver, attempts }` หรือโยน `AllProvidersFailedError` (มี `attempts`)
+
+**`maxCooldownSec`** — ไม่ตั้ง = backoff ไม่เกิน 30 นาที แต่ไม่ต่ำกว่าค่าพื้นของ kind (quota ยังพัก 1 ชม.) · ตั้งเอง = เพดานจริงของทุก kind รวม Retry-After เช่นแอปที่พึ่ง Pi Notify ตัวเดียว (Pi Auth) ตั้ง `maxCooldownSec: 300` ให้พักไม่เกิน 5 นาที
+
+**`timeoutMs`** (ค่าเริ่มต้น 20 วิ) หมดเวลาแล้ว mailer ยกเลิกคำขอด้วย `AbortSignal` ที่ส่งให้ provider (`msg.signal` — provider `hub` ส่งต่อเข้า fetch) แล้ว failover ต่อ; provider ที่เขียนเองควรส่ง `msg.signal` ต่อเข้า fetch เช่นกัน
+
+### provider type
+
+| type | ต้องใส่ |
+|---|---|
+| `hub` | `apiKey` (`url` optional) |
+| `resend` | `apiKey` |
+| `smtp` | `host` (+ `port` `secure` `user` `pass` `rejectUnauthorized` `pool`) |
+| `zoho` `zohopro` `gmail` `office365` `brevo` `mailtrap` | `user`, `pass` (SMTP preset) |
+| `zeptomail` | `apiKey` (+ `region`) |
+| `console` | – |
+| `custom` | `provider` (object ที่ implement `Provider`) |
+
+ทุก type รับ `name` `from` `senderDomains` `quota: { perHour, perDay, perMonth }` `disabled`
+
+**ตัวตนผู้ส่ง**: provider ที่ตั้ง `from` ไว้จะส่งจากที่อยู่นั้นเสมอ เว้นแต่ `message.from` อยู่ใน `senderDomains` (หรือเป็นที่อยู่เดียวกัน) — ถ้าไม่ผ่านจะใช้ที่อยู่ของ provider แต่คงชื่อจาก message (`Pi Auth <noreply@hub.example>`) เพราะ SMTP/Resend ปฏิเสธ from ที่ไม่ใช่ของตัวเอง; provider ที่ไม่ตั้ง `from` (hub, console) ส่งจากที่อยู่ที่ message ขอ
+
+env: `MAIL_<NAME>_<FIELD>` — `TYPE FROM QUOTA_HOUR QUOTA_DAY QUOTA_MONTH DISABLED` · `API_KEY BASE_URL REGION URL` · `HOST PORT SECURE USER PASS POOL TIMEOUT_MS REJECT_UNAUTHORIZED`
+
+## Message
+
+```ts
+{
+  to: Address | Address[];         // "a@b.com" | "ชื่อ <a@b.com>" | { name, email }
+  subject: string;
+  html?: string; text?: string;    // อย่างน้อยหนึ่ง
+  from?: Address;                  // ชนะ from ของ provider/แอป
+  cc?, bcc?, replyTo?;
+  attachments?: { filename, content: Buffer | string, contentType?, encoding?: "base64" }[];
+  headers?: Record<string, string>;
+  tags?: Record<string, string>;   // Resend เท่านั้น
+  prefer?: string;                 // ลองตัวนี้ก่อน (ชื่อจาก listProviders) ยัง failover
+  provider?: string;               // บังคับตัวนี้ตัวเดียว ไม่ failover (โหมด local เท่านั้น)
+}
+```
+
+## อื่น ๆ
+
+```ts
+await mailer.verify();   // ทดสอบเชื่อมต่อทุกตัว (hub: เช็ค key)
+await mailer.status();   // cooldown / โควต้าที่ใช้ไป
+await mailer.reset();    // ล้าง cooldown
+```
+
+- โหมด local หลาย instance แชร์ cooldown/โควต้า: `createMailer({ store: createRedisStore(redis) })`
+- provider เอง: implement `{ name, type, send(msg) }` แล้วโยน `MailError` พร้อม `kind`
+- ESM only, Node ≥ 20
+
+## การออกเวอร์ชัน
+
+แอปที่ใช้แพ็กเกจนี้: **auth** (pnpm), **pdf** (bun), **duebell** (npm), **pi-done** (npm) — ทุกรอบต้อง bump + deploy ทั้ง 4 แอป จึงมีกติกา:
+
+1. **แก้ที่ Pi Notify ก่อนเสมอ** อะไรแก้ฝั่ง server ได้ไม่ต้องออก SDK
+2. **รวมการแก้ SDK ไว้ออกรอบเดียว** (ไม่ออกทีละ fix)
+3. **เปลี่ยนได้แค่แบบเพิ่ม** ระหว่าง SDK รุ่นที่แอปยังใช้อยู่กับ Pi Notify:
+   - field ใหม่ใน request/response เป็น optional เสมอ
+   - ค่า enum ใหม่ใน response ออกได้เฉพาะเมื่อ request ขอ (opt-in)
+   - ห้ามเปลี่ยน HTTP status ของกรณีเดิม
+   - `error.kind` ที่ server ส่งต้องเป็นค่าที่ `ErrorKind` ของรุ่นเก่ารู้จัก (ค่าที่ไม่รู้จัก = SDK ไม่พัก provider เลย) — แก้ kind ที่จัดผิดได้
+   - ต้องรับ key `pm_` ต่อไป และชื่อ provider type `hub` คงเดิม
+4. additive ทั้งหมด → **0.3.x**; ใช้ 0.4.0 เมื่อรูปของ type ที่แอปใช้อยู่ต้องเปลี่ยนเท่านั้น
+5. **ห้ามเปลี่ยน `DEFAULT_HUB_URL`** และห้ามถอด hostname ที่ SDK รุ่นใดเคยใช้เป็นค่าเริ่มต้น — โดเมนใหม่เพิ่มเป็น alias (บทเรียนจาก `mail.suphark.com` ที่ถอดแล้วแอปรุ่นเก่าส่งไม่ออก)
+6. ถอดของเก่าได้ก็ต่อเมื่อ lockfile ของทั้ง 4 แอปเป็นรุ่นใหม่และ deploy แล้ว
+
+Pi Notify มี contract test (`apps/notify/src/test/contract/`) เก็บ body จริงของ SDK 0.3.0 ไว้ — แดง = เปลี่ยน API แบบไม่ additive ให้แก้ฝั่ง Pi Notify ไม่ใช่แก้ fixture
+
+**ขั้นตอนออกรุ่น**
+
+1. แก้ `version` ใน `packages/notify/package.json` + หัวข้อ Changelog ด้านล่าง → `pnpm --filter @suphark/notify verify` → `npm pack --dry-run` ดูไฟล์ใน tarball
+2. เจ้าของ: `npm publish` จาก `packages/notify` (prepack build ให้, ต้องใช้ 2FA)
+3. bump ทีละแอป เริ่มจาก pdf / duebell แล้ว pi-done และ **Pi Auth เป็นตัวสุดท้าย** — ยก range ขึ้นด้วยกัน lockfile ย้อนรุ่น:
+   - pdf: `bun add @suphark/notify@^<ver>`
+   - duebell, pi-done: `npm install @suphark/notify@^<ver>`
+   - auth: `pnpm --filter @pi/auth add @suphark/notify@^<ver>` (จาก root ของ repo auth)
+4. ตรวจ: lockfile ทั้ง 4 แอปเป็นรุ่นใหม่, magic link ของ Pi Auth มาถึง, DueBell ส่งทดสอบ notify ได้, คำเชิญของ Pi Done ส่งออก
+
+## Changelog
+
+- 0.3.1 (additive ทั้งหมด — แอปที่ตั้ง `^0.3.0` รับได้เลย, ใช้ร่วมกับ Pi Notify ที่ deploy อยู่ได้ทันที)
+  - **timeout**: `notify()` 65 วิ, `getRecipient()`/`createLink()` 10 วิ (`NotifyOptions.timeoutMs`, ค่าเริ่มต้นที่ `NOTIFY_TIMEOUT_MS`) — เดิมไม่มี timeout เลย
+  - **abort**: mailer หมด `timeoutMs` แล้วยกเลิก fetch ของ provider `hub` ผ่าน `NormalizedMessage.signal` (field ใหม่ optional) ไม่ปล่อยคำขอค้าง
+  - **half-open cooldown**: ทุกตัวติด cooldown (network/server/unknown) → ลองตัวที่ใกล้หมดเวลาพัก 1 ครั้ง/30 วิ — แอปที่มี hub ตัวเดียวกลับมาส่งได้ทันทีที่ Pi Notify กลับมา
+  - **Retry-After**: 429/503 ของ Pi Notify พักตาม `Retry-After` (ไม่คูณสอง, ไม่เกิน 1 ชม.) และมี `MailError.retryAfterSec`
+  - **`maxCooldownSec` ที่ตั้งเอง = เพดานจริง** ทุก kind (ไม่ตั้ง = พฤติกรรมเดิมทุกอย่าง)
+  - `createLink(email, "telegram", { piUserId })` ส่ง user id ของ Pi Auth ให้ Pi Notify ลบการผูกเมื่อบัญชีถูกลบ/ย้ายตามอีเมลใหม่
+  - `NotifyResultItem.reason` เพิ่ม `"app_daily_cap"`, `deferred?` + `NotifyResult.deferred?` (หมดงบเวลา 40 วิของ `/api/v1/notify`)
+  - engine: ส่งสำเร็จแล้วไม่ failover ส่งซ้ำเมื่อ store (เช่น KvEntry บน DB) เขียน state ไม่ได้; store ล่มตอนบันทึกความล้มเหลวไม่หยุด failover
+
+- 0.3.0 — **เปลี่ยนชื่อ Pi Mail → Pi Notify** (breaking): แพ็กเกจย้ายจาก `@suphark/mailer` เป็น `@suphark/notify` (API เดิมทุกตัว เปลี่ยนแค่ import), env `PI_MAIL_KEY`/`PI_MAIL_URL` → `PI_NOTIFY_KEY`/`PI_NOTIFY_URL` (ชื่อเดิมไม่อ่านแล้ว), hub เริ่มต้น `https://notify.suphark.com`; key ใหม่ขึ้นต้น `pn_` (key `pm_` เดิมยังใช้ได้)
+
+- 0.2.1 — `notify()` เพิ่ม `format?: "text" | "html"` ระบุชนิด body ชัดเจน (hub 2026-09-19+ ; ไม่ระบุยังเดาให้ แต่เดาเข้มขึ้น: นับเฉพาะแท็กที่รู้จัก)
+
+- 0.2.0 — **Pi Notify**: `notify()` ส่งแจ้งเตือนถึงอีเมลผู้รับผ่าน hub (Telegram ที่ผู้รับผูกไว้ / อีเมล fallback), `createLink()` ขอ deep link ผูก Telegram, `getRecipient()` ดูช่องทางที่ผูก — ใช้ `PI_MAIL_KEY`/`PI_MAIL_URL` เดิม; `sendMail()` ไม่เปลี่ยน
+
+- 0.1.1 — **fix**: โควต้าจองก่อนส่ง (คำขอพร้อมกันไม่ทะลุเพดาน, ส่งพังคืนโควต้า — Store มี `decr` optional), from ผิดรูปแบบโยน invalid ทันที, `hub` ใน MAIL_PROVIDERS ใช้ PI_MAIL_KEY/PI_MAIL_URL ได้, Resend `verify()` ไม่ต้องใช้สิทธิ์ list domains; nodemailer ^10 (ปิด advisory ของ 7.x); **from policy**: provider ที่มี `from` เป็นตัวตนผู้ส่ง, `senderDomains` อนุญาตทั้งโดเมน (message.from นอกโดเมนถูกแทนที่แต่คงชื่อ); config `custom` รับ `from`/`name` override
+- 0.1.0 — รุ่นแรก: hub (`PI_MAIL_KEY`), resend, smtp + presets, zeptomail, console, custom; failover/โควต้า/cooldown; `listProviders()` + `prefer`

package/dist/index.d.ts

@@ -61,6 +61,11 @@ interface NormalizedMessage {
     headers: Record<string, string>;
     tags: Record<string, string>;
     prefer?: string;
+    /**
+     * ยกเลิกเมื่อ mailer หมดเวลา (timeoutMs) — provider ที่ใช้ fetch ควรส่งต่อเข้า fetch
+     * เพื่อไม่ให้คำขอค้างต่อหลัง mailer ไป failover แล้ว (ไม่ส่งมา = provider เขียนเองรุ่นเก่า ใช้ได้ตามเดิม)
+     */
+    signal?: AbortSignal;
 }
 /** ประเภทความผิดพลาด — ใช้ตัดสินใจว่าจะพัก provider นานแค่ไหน */
 type ErrorKind = "quota" | "rate_limit" | "auth" | "network" | "server" | "invalid" | "unknown";
@@ -219,12 +224,13 @@ interface HubSendResponse {
     provider: string;
     failedOver: boolean;
 }
-/** error body ของ hub: { error: { kind, message, attempts? } } */
+/** error body ของ hub: { error: { kind, message, attempts?, retryAfterSec? } } */
 interface HubErrorResponse {
     error: {
         kind?: ErrorKind;
         message: string;
         attempts?: unknown[];
+        retryAfterSec?: number;
     };
 }
 /**
@@ -440,11 +446,14 @@ declare class MailError extends Error {
     readonly kind: ErrorKind;
     readonly provider?: string;
     readonly status?: number;
+    /** เวลาที่ปลายทางขอให้รอก่อนลองใหม่ (วินาที จาก Retry-After) — mailer ใช้เป็นเวลาพักแทน backoff */
+    readonly retryAfterSec?: number;
     constructor(message: string, opts?: {
         kind?: ErrorKind;
         provider?: string;
         status?: number;
         cause?: unknown;
+        retryAfterSec?: number;
     });
 }
 /** ส่งไม่สำเร็จเลยสักตัว — ดู attempts ว่าแต่ละตัวพังเพราะอะไร */
@@ -457,6 +466,7 @@ declare function classifyError(err: unknown): {
     kind: ErrorKind;
     message: string;
     status?: number;
+    retryAfterSec?: number;
 };
 
 /** เวลาพัก (วินาที) ต่อ error แต่ละแบบ ก่อนกลับมาลอง provider นั้นอีก — คูณสองทุกครั้งที่พังซ้ำ */
@@ -490,13 +500,18 @@ interface NotifyResultItem {
     id?: string;
     failedOver?: boolean;
     error?: string;
-    reason?: "no_link" | "channel_not_linked" | "no_chat_provider";
+    /** app_daily_cap = แอปส่งอีเมลแทนแชทครบเพดานรายวันที่ตั้งใน Pi Notify แล้ว */
+    reason?: "no_link" | "channel_not_linked" | "no_chat_provider" | "app_daily_cap";
+    /** (status failed) คำขอหมดงบเวลาก่อนได้เริ่มส่งรายการนี้ — ส่งซ้ำเฉพาะรายการนี้ได้ */
+    deferred?: boolean;
 }
 interface NotifyResult {
     results: NotifyResultItem[];
     sent: number;
     failed: number;
     skipped: number;
+    /** จำนวนที่ยังไม่ได้ส่งเพราะหมดงบเวลา (นับซ้อนอยู่ใน failed; Pi Notify รุ่นเก่าไม่ส่งมา) */
+    deferred?: number;
 }
 interface NotifyOptions {
     /** ค่าเริ่มต้น PI_NOTIFY_KEY */
@@ -505,7 +520,17 @@ interface NotifyOptions {
     url?: string;
     fetch?: typeof fetch;
     env?: Record<string, string | undefined>;
+    /**
+     * เวลารอ Pi Notify สูงสุด (ms) หมดแล้วโยน MailError kind "network"
+     * ค่าเริ่มต้น notify() 65000 (ยาวกว่า maxDuration 60 วิของ /api/v1/notify เล็กน้อย) · getRecipient()/createLink() 10000
+     */
+    timeoutMs?: number;
 }
+/** เวลารอเริ่มต้นของแต่ละคำสั่ง (ms) */
+declare const NOTIFY_TIMEOUT_MS: {
+    readonly notify: 65000;
+    readonly recipient: 10000;
+};
 /** ช่องทางที่ผู้รับผูกไว้ (จาก GET /api/v1/recipients/:email) — ไม่มี chat id */
 interface RecipientChannelInfo {
     type: string;
@@ -531,8 +556,11 @@ declare function getRecipient(email: string, opts?: NotifyOptions): Promise<Reci
 /**
  * ขอลิงก์ผูก Telegram ให้ผู้รับ (t.me/<bot>?start=<code>, หมดอายุ 10 นาที)
  * แอปวางเป็นปุ่ม/QR ในหน้าตั้งค่าของตัวเอง แล้วโพล getRecipient() จนเห็น telegram
+ * `opts.piUserId` = user id ใน Pi Auth (sub) ของผู้ใช้ — ให้ Pi Notify ลบการผูกเมื่อบัญชีถูกลบ
  */
-declare function createLink(email: string, channel?: Exclude<NotifyChannel, "email">, opts?: NotifyOptions): Promise<{
+declare function createLink(email: string, channel?: Exclude<NotifyChannel, "email">, opts?: NotifyOptions & {
+    piUserId?: string;
+}): Promise<{
     channel: string;
     url: string;
     expiresAt: string;
@@ -561,4 +589,4 @@ declare function createRedisStore(client: RedisLike, opts?: {
     prefix?: string;
 }): Store;
 
-export { type Address, AllProvidersFailedError, type Attachment, type Attempt, type ConsoleOptions, DEFAULT_COOLDOWN, DEFAULT_HUB_URL, type Env, type ErrorKind, type HubErrorResponse, type HubOptions, type HubSendRequest, type HubSendResponse, MailError, type Mailer, type MailerEvent, type MailerOptions, type Message, type NormalizedMessage, type NotifyChannel, type NotifyInput, type NotifyOptions, type NotifyResult, type NotifyResultItem, type ParsedAddress, type Provider, type ProviderConfig, type ProviderInfo, type ProviderStatus, type Quota, type QuotaUsage, type RecipientChannelInfo, type RecipientInfo, type RedisLike, type ResendOptions, SMTP_PRESETS, type SendResult, type SkipReason, type SmtpOptions, type SmtpPreset, type Store, type ZeptoMailOptions, classifyError, configureMailer, createConsoleProvider, createHubProvider, createLink, createMailer, createMemoryStore, createPresetSmtpProvider, createRedisStore, createResendProvider, createSmtpProvider, createZeptoMailProvider, formatAddress, getMailer, getRecipient, listProviders, notify, parseAddress, parseAddressList, providersFromEnv, requireFrom, resetMailer, sendMail };
+export { type Address, AllProvidersFailedError, type Attachment, type Attempt, type ConsoleOptions, DEFAULT_COOLDOWN, DEFAULT_HUB_URL, type Env, type ErrorKind, type HubErrorResponse, type HubOptions, type HubSendRequest, type HubSendResponse, MailError, type Mailer, type MailerEvent, type MailerOptions, type Message, NOTIFY_TIMEOUT_MS, type NormalizedMessage, type NotifyChannel, type NotifyInput, type NotifyOptions, type NotifyResult, type NotifyResultItem, type ParsedAddress, type Provider, type ProviderConfig, type ProviderInfo, type ProviderStatus, type Quota, type QuotaUsage, type RecipientChannelInfo, type RecipientInfo, type RedisLike, type ResendOptions, SMTP_PRESETS, type SendResult, type SkipReason, type SmtpOptions, type SmtpPreset, type Store, type ZeptoMailOptions, classifyError, configureMailer, createConsoleProvider, createHubProvider, createLink, createMailer, createMemoryStore, createPresetSmtpProvider, createRedisStore, createResendProvider, createSmtpProvider, createZeptoMailProvider, formatAddress, getMailer, getRecipient, listProviders, notify, parseAddress, parseAddressList, providersFromEnv, requireFrom, resetMailer, sendMail };

package/dist/index.js

@@ -219,14 +219,24 @@ var MailError = class extends Error {
   kind;
   provider;
   status;
+  /** เวลาที่ปลายทางขอให้รอก่อนลองใหม่ (วินาที จาก Retry-After) — mailer ใช้เป็นเวลาพักแทน backoff */
+  retryAfterSec;
   constructor(message, opts = {}) {
     super(message, opts.cause === void 0 ? void 0 : { cause: opts.cause });
     this.name = "MailError";
     this.kind = opts.kind ?? "unknown";
     this.provider = opts.provider;
     this.status = opts.status;
+    this.retryAfterSec = opts.retryAfterSec;
   }
 };
+function retryAfterOf(res, body) {
+  if (res.status !== 429 && res.status !== 503) return void 0;
+  const fromHeader = Number(res.headers?.get?.("Retry-After")?.trim() ?? "");
+  if (Number.isFinite(fromHeader) && fromHeader > 0) return Math.ceil(fromHeader);
+  const fromBody = body?.error?.retryAfterSec;
+  return typeof fromBody === "number" && fromBody > 0 ? Math.ceil(fromBody) : void 0;
+}
 var AllProvidersFailedError = class extends MailError {
   attempts;
   constructor(attempts) {
@@ -246,7 +256,13 @@ var NET_CODE_RE = /^(ECONN|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|EPIPE|ESOCKET|EDNS|ECON
 var NET_RE = /ECONN|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|socket|timed? ?out|network|fetch failed/i;
 var INVALID_RE = /invalid.*(email|address|recipient)|no recipients|recipient.*(rejected|invalid)|malformed|missing.*(to|subject|from)/i;
 function classifyError(err) {
-  if (err instanceof MailError) return { kind: err.kind, message: err.message, status: err.status };
+  if (err instanceof MailError)
+    return {
+      kind: err.kind,
+      message: err.message,
+      status: err.status,
+      retryAfterSec: err.retryAfterSec
+    };
   const e = typeof err === "object" && err !== null ? err : {};
   const message = String(e.message ?? e.response ?? err ?? "unknown error");
   const code = typeof e.code === "string" ? e.code : void 0;
@@ -291,15 +307,20 @@ function windowId(window, now = /* @__PURE__ */ new Date()) {
   if (window === "day") return iso.slice(0, 10);
   return iso.slice(0, 7);
 }
+var MAX_RETRY_AFTER_SEC = 60 * 60;
+var PROBE_INTERVAL_SEC = 30;
 var Health = class {
   store;
   cooldown;
   maxCooldownSec;
+  /** ค่าที่แอปตั้งเอง (ไม่ตั้ง = undefined) — แยกจากค่าเริ่มต้นเพื่อไม่เปลี่ยนพฤติกรรมของแอปที่ไม่ได้ตั้ง */
+  userMaxCooldownSec;
   emit;
   constructor(opts) {
     this.store = opts.store;
     this.cooldown = { ...DEFAULT_COOLDOWN, ...opts.cooldown };
     this.maxCooldownSec = opts.maxCooldownSec ?? 30 * 60;
+    this.userMaxCooldownSec = opts.maxCooldownSec;
     this.emit = opts.onEvent ?? (() => {
     });
   }
@@ -308,8 +329,12 @@ var Health = class {
    * จองก่อนส่ง (incr แล้วดูค่าที่ได้) เพื่อให้คำขอพร้อมกันหลายตัวไม่ทะลุเพดาน — ส่งพังต้องเรียก release
    */
   async check(p, quota) {
-    const cd = await this.getCooldown(p.name);
+    const cd = await this.cooldownOf(p.name);
     if (cd) return "cooldown";
+    return this.reserve(p, quota);
+  }
+  /** จองโควต้าอย่างเดียว (ไม่ดู cooldown) — ใช้ตอน half-open ที่ตั้งใจลองตัวที่ติด cooldown */
+  async reserve(p, quota) {
     const reserved = [];
     for (const w of WINDOWS) {
       const limit = quota?.[w.key];
@@ -343,14 +368,17 @@ var Health = class {
       this.emit({ type: "recovered", provider: p.name });
     }
   }
-  async recordFailure(p, kind) {
+  /**
+   * พักหลังพัง: ปลายทางบอก Retry-After มา = พักเท่านั้น (ไม่คูณสอง, ไม่เกิน 1 ชม.)
+   * ไม่บอก = backoff base, 2x, 4x, ... · แอปตั้ง maxCooldownSec เอง = เพดานของทั้งสองแบบ
+   */
+  async recordFailure(p, kind, retryAfterSec) {
     const base = this.cooldown[kind];
     if (!base) return;
     const failures = await this.store.incr(`fail:${p.name}`, 86400);
-    const sec = Math.min(
-      base * 2 ** Math.min(failures - 1, 10),
-      Math.max(base, this.maxCooldownSec)
-    );
+    let sec = retryAfterSec && retryAfterSec > 0 ? Math.min(retryAfterSec, MAX_RETRY_AFTER_SEC) : this.userMaxCooldownSec !== void 0 ? base * 2 ** Math.min(failures - 1, 10) : Math.min(base * 2 ** Math.min(failures - 1, 10), Math.max(base, this.maxCooldownSec));
+    if (this.userMaxCooldownSec !== void 0) sec = Math.min(sec, this.userMaxCooldownSec);
+    if (sec <= 0) return;
     const until = Date.now() + sec * 1e3;
     await this.store.set(
       `cd:${p.name}`,
@@ -364,8 +392,15 @@ var Health = class {
     await this.store.del(`cd:${name}`);
     await this.store.del(`fail:${name}`);
   }
+  /**
+   * half-open: อนุญาตให้ลองตัวที่ติด cooldown ได้ 1 ครั้งต่อ PROBE_INTERVAL_SEC (แชร์ข้าม instance ถ้า store แชร์)
+   * true = ได้สิทธิ์ลองรอบนี้
+   */
+  async allowProbe(name) {
+    return await this.store.incr(`probe:${name}`, PROBE_INTERVAL_SEC) === 1;
+  }
   async status(p, quota) {
-    const cd = await this.getCooldown(p.name);
+    const cd = await this.cooldownOf(p.name);
     const usage = await this.usage(p, quota);
     const failures = Number(await this.store.get(`fail:${p.name}`) ?? 0);
     return {
@@ -378,7 +413,8 @@ var Health = class {
       quota: usage
     };
   }
-  async getCooldown(name) {
+  /** cooldown ที่ยังไม่หมด (null = ใช้ได้) */
+  async cooldownOf(name) {
     const raw = await this.store.get(`cd:${name}`);
     if (!raw) return null;
     try {
@@ -458,7 +494,9 @@ function createHubProvider(opts) {
       const res = await doFetch(url, {
         method: "POST",
         headers: { Authorization: `Bearer ${opts.apiKey}`, "Content-Type": "application/json" },
-        body: JSON.stringify(body)
+        body: JSON.stringify(body),
+        // mailer หมดเวลา → abort คำขอนี้ทิ้ง (Pi Notify อาจส่งไปแล้ว — แอปที่มีตัวสำรองในเครื่องอาจได้เมลซ้ำ ยอมรับได้)
+        signal: msg.signal
       });
       const data = await res.json().catch(() => ({}));
       if (!res.ok) {
@@ -468,7 +506,8 @@ function createHubProvider(opts) {
           kind,
           provider: name,
           status: res.status,
-          cause: data
+          cause: data,
+          retryAfterSec: retryAfterOf(res, data)
         });
       }
       return { id: data.id };
@@ -713,11 +752,17 @@ function createMemoryStore() {
 }
 
 // src/mailer.ts
+var PROBE_KINDS = /* @__PURE__ */ new Set(["network", "server", "unknown"]);
 var timeoutError = (name, ms) => new MailError(`${name}: send timed out after ${ms}ms`, { kind: "network", provider: name });
-function withTimeout(p, ms, name) {
+function withTimeout(run, ms, name) {
+  const ac = new AbortController();
   return new Promise((resolve2, reject) => {
-    const t = setTimeout(() => reject(timeoutError(name, ms)), ms);
-    p.then(
+    const t = setTimeout(() => {
+      const err = timeoutError(name, ms);
+      reject(err);
+      ac.abort(err);
+    }, ms);
+    Promise.resolve().then(() => run(ac.signal)).then(
       (v) => {
         clearTimeout(t);
         resolve2(v);
@@ -839,6 +884,21 @@ function createMailer(options = {}) {
     if (allowed) return requested;
     return requested.name ? { name: requested.name, email: p.from.email } : p.from;
   };
+  async function pickProbe(candidates, attempts) {
+    const cooled = candidates.filter(
+      (e) => attempts.some((a) => a.provider === e.provider.name && a.skipped === "cooldown")
+    );
+    const ranked = [];
+    for (const entry of cooled) {
+      const cd = await health.cooldownOf(entry.provider.name);
+      if (cd && PROBE_KINDS.has(cd.kind)) ranked.push({ entry, until: cd.until });
+    }
+    ranked.sort((a, b) => a.until - b.until);
+    const pick = ranked[0]?.entry;
+    if (!pick || !await health.allowProbe(pick.provider.name)) return null;
+    if (await health.reserve(pick.provider, pick.quota)) return null;
+    return pick;
+  }
   async function send(message) {
     if (!message?.to || Array.isArray(message.to) && message.to.length === 0)
       throw new MailError("Message has no recipients (to)", { kind: "invalid" });
@@ -857,9 +917,46 @@ function createMailer(options = {}) {
     }
     const { requested, ...base } = normalizeBase(message);
     const attempts = [];
+    const forced = message.provider !== void 0;
+    const attempt = async (entry, opts) => {
+      const p = entry.provider;
+      const started = Date.now();
+      let id;
+      try {
+        ({ id } = await withTimeout(
+          (signal) => {
+            const normalized = {
+              ...base,
+              from: resolveFrom(requested, entry),
+              signal
+            };
+            return p.send(normalized);
+          },
+          timeoutMs,
+          p.name
+        ));
+      } catch (err) {
+        const ms2 = Date.now() - started;
+        const { kind, message: error, retryAfterSec } = classifyError(err);
+        attempts.push({ provider: p.name, ok: false, error, kind, ms: ms2 });
+        emit({ type: "failed", provider: p.name, kind, error, ms: ms2 });
+        try {
+          if (opts.reserved) await health.release(p, entry.quota);
+          await health.recordFailure(p, kind, retryAfterSec);
+        } catch {
+        }
+        return null;
+      }
+      const ms = Date.now() - started;
+      attempts.push({ provider: p.name, ok: true, ms });
+      await health.recordSuccess(p).catch(() => {
+      });
+      const failedOver = opts.failedOver();
+      emit({ type: "sent", provider: p.name, id, ms, failedOver });
+      return { id, provider: p.name, failedOver, attempts };
+    };
     for (const entry of candidates) {
       const p = entry.provider;
-      const forced = message.provider !== void 0;
       if (entry.disabled) {
         attempts.push({ provider: p.name, ok: false, skipped: "disabled", ms: 0 });
         emit({ type: "skipped", provider: p.name, reason: "disabled" });
@@ -871,23 +968,21 @@ function createMailer(options = {}) {
         emit({ type: "skipped", provider: p.name, reason: skip });
         continue;
       }
-      const started = Date.now();
-      try {
-        const normalized = { ...base, from: resolveFrom(requested, entry) };
-        const { id } = await withTimeout(p.send(normalized), timeoutMs, p.name);
-        const ms = Date.now() - started;
-        attempts.push({ provider: p.name, ok: true, ms });
-        await health.recordSuccess(p);
-        const failedOver = attempts.length > 1;
-        emit({ type: "sent", provider: p.name, id, ms, failedOver });
-        return { id, provider: p.name, failedOver, attempts };
-      } catch (err) {
-        const ms = Date.now() - started;
-        const { kind, message: error } = classifyError(err);
-        attempts.push({ provider: p.name, ok: false, error, kind, ms });
-        emit({ type: "failed", provider: p.name, kind, error, ms });
-        if (!forced) await health.release(p, entry.quota);
-        await health.recordFailure(p, kind);
+      const result = await attempt(entry, {
+        reserved: !forced,
+        failedOver: () => attempts.length > 1
+      });
+      if (result) return result;
+    }
+    if (!forced && attempts.every((a) => a.skipped)) {
+      const probe = await pickProbe(candidates, attempts).catch(() => null);
+      if (probe) {
+        const first = candidates.find((e) => !e.disabled)?.provider.name;
+        const result = await attempt(probe, {
+          reserved: true,
+          failedOver: () => probe.provider.name !== first
+        });
+        if (result) return result;
       }
     }
     emit({ type: "exhausted", attempts });
@@ -918,8 +1013,8 @@ function createMailer(options = {}) {
       await Promise.all(
         entries.map(async (e) => {
           try {
-            if (e.provider.verify)
-              await withTimeout(e.provider.verify(), timeoutMs, e.provider.name);
+            const verify = e.provider.verify?.bind(e.provider);
+            if (verify) await withTimeout(() => verify(), timeoutMs, e.provider.name);
             out[e.provider.name] = { ok: true };
           } catch (err) {
             out[e.provider.name] = { ok: false, error: classifyError(err).message };
@@ -959,6 +1054,7 @@ function resetMailer() {
 }
 
 // src/notify.ts
+var NOTIFY_TIMEOUT_MS = { notify: 65e3, recipient: 1e4 };
 function resolve(opts) {
   const env = opts.env ?? process.env;
   const apiKey = opts.apiKey ?? env.PI_NOTIFY_KEY;
@@ -966,17 +1062,32 @@ function resolve(opts) {
   const base = (opts.url ?? env.PI_NOTIFY_URL ?? DEFAULT_HUB_URL).replace(/\/$/, "");
   return { apiKey, base, doFetch: opts.fetch ?? globalThis.fetch };
 }
-async function hubRequest(opts, path, init = {}) {
+async function hubRequest(opts, path, init) {
   const { apiKey, base, doFetch } = resolve(opts);
-  const res = await doFetch(`${base}${path}`, {
-    method: init.method ?? "GET",
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-      ...init.body !== void 0 ? { "Content-Type": "application/json" } : {}
-    },
-    body: init.body !== void 0 ? JSON.stringify(init.body) : void 0
-  });
-  const data = await res.json().catch(() => ({}));
+  const ms = opts.timeoutMs ?? init.timeoutMs;
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), ms);
+  const timedOut = () => new MailError(`Pi Notify timeout after ${ms}ms`, { kind: "network", provider: "hub" });
+  let res;
+  let data;
+  try {
+    res = await doFetch(`${base}${path}`, {
+      method: init.method ?? "GET",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        ...init.body !== void 0 ? { "Content-Type": "application/json" } : {}
+      },
+      body: init.body !== void 0 ? JSON.stringify(init.body) : void 0,
+      signal: ac.signal
+    });
+    data = await res.json().catch(() => ({}));
+  } catch (err) {
+    if (ac.signal.aborted) throw timedOut();
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+  if (ac.signal.aborted) throw timedOut();
   if (!res.ok) {
     const err = data?.error;
     const kind = err?.kind ?? (res.status === 401 || res.status === 403 ? "auth" : res.status === 429 ? "rate_limit" : res.status === 400 || res.status === 422 ? "invalid" : "server");
@@ -984,22 +1095,31 @@ async function hubRequest(opts, path, init = {}) {
       kind,
       provider: "hub",
       status: res.status,
-      cause: data
+      cause: data,
+      retryAfterSec: retryAfterOf(res, data)
     });
   }
   return data;
 }
 async function notify(input, opts = {}) {
-  const data = await hubRequest(opts, "/api/v1/notify", { method: "POST", body: input });
+  const data = await hubRequest(opts, "/api/v1/notify", {
+    method: "POST",
+    body: input,
+    timeoutMs: NOTIFY_TIMEOUT_MS.notify
+  });
   return { results: data.results, ...data.summary };
 }
 async function getRecipient(email, opts = {}) {
-  return hubRequest(opts, `/api/v1/recipients/${encodeURIComponent(email)}`);
+  return hubRequest(opts, `/api/v1/recipients/${encodeURIComponent(email)}`, {
+    timeoutMs: NOTIFY_TIMEOUT_MS.recipient
+  });
 }
 async function createLink(email, channel = "telegram", opts = {}) {
-  return hubRequest(opts, `/api/v1/recipients/${encodeURIComponent(email)}/link`, {
+  const { piUserId, ...rest } = opts;
+  return hubRequest(rest, `/api/v1/recipients/${encodeURIComponent(email)}/link`, {
     method: "POST",
-    body: { channel }
+    body: { channel, ...piUserId ? { piUserId } : {} },
+    timeoutMs: NOTIFY_TIMEOUT_MS.recipient
   });
 }
 
@@ -1035,6 +1155,7 @@ export {
   DEFAULT_COOLDOWN,
   DEFAULT_HUB_URL,
   MailError,
+  NOTIFY_TIMEOUT_MS,
   SMTP_PRESETS,
   classifyError,
   configureMailer,

package/package.json

@@ -1,64 +1,64 @@
-{
-  "name": "@suphark/notify",
-  "version": "0.3.0",
-  "private": false,
-  "type": "module",
-  "description": "ส่งอีเมล + แจ้งเตือน Telegram ผ่าน Pi Notify hub (notify.suphark.com) หรือส่งอีเมลตรงไป Resend/SMTP/Zoho/ZeptoMail ใน API เดียว พร้อม failover อัตโนมัติ",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "packageManager": "pnpm@12.4.1",
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "verify": "pnpm typecheck && pnpm test && pnpm build",
-    "send:test": "node --env-file-if-exists=.env scripts/send-test.mjs",
-    "prepack": "pnpm run build"
-  },
-  "dependencies": {
-    "nodemailer": "^10.0.9"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.5.13",
-    "@types/node": "^24.13.4",
-    "@types/nodemailer": "^8.0.1",
-    "tsup": "^8.5.1",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.11",
-    "@pi/config": "workspace:*"
-  },
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/suphark/notify",
-    "directory": "packages/notify"
-  },
-  "keywords": [
-    "email",
-    "mailer",
-    "resend",
-    "smtp",
-    "nodemailer",
-    "zoho",
-    "zeptomail",
-    "failover",
-    "telegram",
-    "notify",
-    "notification"
-  ]
-}
+{
+  "name": "@suphark/notify",
+  "version": "0.3.1",
+  "private": false,
+  "type": "module",
+  "description": "ส่งอีเมล + แจ้งเตือน Telegram ผ่าน Pi Notify hub (notify.suphark.com) หรือส่งอีเมลตรงไป Resend/SMTP/Zoho/ZeptoMail ใน API เดียว พร้อม failover อัตโนมัติ",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@12.4.1",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify": "pnpm typecheck && pnpm test && pnpm build",
+    "send:test": "node --env-file-if-exists=.env scripts/send-test.mjs",
+    "prepack": "pnpm run build"
+  },
+  "dependencies": {
+    "nodemailer": "^10.0.14"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.15",
+    "@pi/config": "workspace:*",
+    "@types/node": "^24.13.4",
+    "@types/nodemailer": "^8.0.1",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.11"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/suphark/notify.git",
+    "directory": "packages/notify"
+  },
+  "keywords": [
+    "email",
+    "mailer",
+    "resend",
+    "smtp",
+    "nodemailer",
+    "zoho",
+    "zeptomail",
+    "failover",
+    "telegram",
+    "notify",
+    "notification"
+  ]
+}