@suphark/notify 0.3.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,200 @@
+# @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`