@suphark/notify 0.3.1 → 0.5.0

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,6 +1,8 @@
 # @suphark/notify
 
-SDK ส่งอีเมล + แจ้งเตือน (Telegram) ของแอปทุกตัว — ค่าเริ่มต้นส่งผ่าน **Pi Notify hub** (`https://notify.suphark.com`) ซึ่งเป็นคนถือ credential ของ Resend/SMTP/Zoho/Telegram bot ทำ failover นับโควต้า เก็บ log และเก็บว่าผู้รับผูกแชทไหนไว้ แอปใส่แค่ key ตัวเดียว
+SDK ส่งอีเมล + แจ้งเตือน (Telegram / Web Push) ของแอปทุกตัว — ค่าเริ่มต้นส่งผ่าน **Pi Notify hub** (`https://notify.suphark.com`) ซึ่งเป็นคนถือ credential ของ Resend/SMTP/Zoho/Telegram bot ทำ failover นับโควต้า เก็บ log และเก็บว่าผู้รับผูกแชทไหนไว้ แอปใส่แค่ key ตัวเดียว
+
+> 📖 **คู่มือการใช้งานและสูตรการเขียนโค้ดฉบับเต็ม:** ดูที่ [docs/guide.md](../../docs/guide.md)
 
 ```bash
 pnpm add @suphark/notify   # หรือ npm i / bun add
@@ -85,6 +87,151 @@ const { channels } = await getRecipient(user.email);       // [{ type: "telegram
 
 หรือส่งผู้ใช้ไปผูกเองที่ `https://notify.suphark.com/me` (ล็อกอิน Pi Auth) — ผูกครั้งเดียวใช้ได้ทุกแอป
 
+`createLink()` คืน `code` ด้วย (รหัสเดียวกับ `?start=` ใน url — ไว้ให้ผู้ใช้พิมพ์ `/start <code>` เองเมื่อเปิด deep link ไม่ได้) และ `getChannelStatus()` ตอบสถานะการผูกเลยโดยไม่ต้อง find เอง:
+
+```ts
+const { url, code } = await createLink(user);                   // รับ user object ได้
+const { linked, label, manageUrl } = await getChannelStatus(user, "telegram");
+```
+
+### เขียนให้สั้น: ส่งแบบไม่โยน / ส่งเบื้องหลัง / `to` เป็น user object (0.5.0)
+
+`to` ของ `notify()` รับ **user object ที่มี `email`** (และ array ของมัน) ได้เลย — ไม่ต้องแกะ `.email` เอง
+ผู้รับเดี่ยวที่ไม่มีอีเมลโยน `MailError` kind `invalid` (เป็น bug ของแอป ไม่เงียบ); ใน array กรอง `null`/`undefined` ทิ้งให้
+
+```ts
+await notify({ to: user, title: "งานเสร็จแล้ว", body: "โปรเจกต์ A พร้อมส่งมอบ" });
+await notify({ to: [owner, assignee], title: "มีการอัปเดต", body: "…" });   // null ใน array ถูกกรอง
+```
+
+เลือกตามว่า **ต้องรู้ผลหรือไม่**:
+
+| ต้องการ | ใช้ | พฤติกรรม |
+|---|---|---|
+| ต้องรู้ผล / ให้ cron บันทึก FAILED แล้วลองใหม่ | `notify()` / `sendMail()` | โยน `MailError` เมื่อล้มเหลว |
+| แจ้งเตือนเป็นผลพลอยได้ของงานหลัก (ไม่ให้งานหลักพัง) | `notifySafe()` / `sendMailSafe()` | **ไม่โยน** คืน `{ ok, sent, failed, skipped, results, error?, disabled? }` |
+| เหมือนข้างบน และไม่อยากให้หน้าเว็บรอ (Next.js) | `notifyLater()` / `sendMailLater()` จาก `@suphark/notify/next` | ส่งหลังตอบ response ด้วย `after()` คืน `void` |
+
+```ts
+import { notifySafe } from "@suphark/notify";
+const { ok } = await notifySafe({ to: user, title: "แจ้งเตือน", body: "เนื้อหา" });
+
+import { notifyLater } from "@suphark/notify/next";        // Next.js เท่านั้น (next เป็น optional peer)
+notifyLater({ to: user, title: "บันทึกแล้ว", body: "ระบบอัปเดตงานแล้ว" });
+```
+
+- **ไม่มี `PI_NOTIFY_KEY`** → `{ ok: false, disabled: true }` ไม่ส่งและไม่ถือเป็น error (dev/test ไม่ต้องมี key) — เตือนครั้งเดียวใน dev, ทุกครั้งใน production เพื่อให้เห็นว่าลืมตั้ง
+- `ok` = ไม่มี error และไม่มีรายการ `failed` — `skipped` (เช่นยังไม่ผูก Telegram) **ไม่ใช่** ความล้มเหลว; ดูรายตัวที่ `results`
+- `notifyLater` ใช้ timeout 20 วิ (งานใน `after()` นับรวม `maxDuration` ของ function) และ log เมื่อล้มเหลวโดยไม่มีอีเมลผู้รับ — ส่งต่อเข้า logger ของแอปได้ด้วย `{ onError }`; นอก request scope (test/script) รันแบบ detached
+- **ห้ามใช้ `…Later` เมื่อต้องรู้ผล** (เช่น cron digest ที่บันทึกสถานะ) — ใช้ `await notify()`
+
+**อีเมลหน้าตาเดียวกับที่ Pi Notify ส่งแทนแชท** โดยไม่ต้องเขียน HTML เอง — `renderNotifyEmail()` (หัวข้อ + ย่อหน้า + ปุ่มเดียว; body เป็นข้อความล้วน ถูก escape ให้):
+
+```ts
+import { renderNotifyEmail, sendMail } from "@suphark/notify";
+
+await sendMail({
+  to: user.email,
+  ...renderNotifyEmail({
+    title: "บัญชีของคุณพร้อมใช้งานแล้ว",
+    body: "ผู้ดูแลอนุมัติบัญชีของคุณแล้ว",
+    link: "https://app.example/",
+    linkLabel: "เข้าสู่ระบบ",   // ค่าเริ่มต้น "เปิดลิงก์"
+    accent: "#0f766e",        // สีปุ่ม (hex เท่านั้น) ค่าเริ่มต้น #1d4ed8
+    appName: "Pi PDF",        // ท้ายอีเมล
+  }),
+});
+```
+
+### แจ้งเตือนบนเบราว์เซอร์ (web push)
+
+hub ถือคู่กุญแจ VAPID ให้ (ไม่ต้องใช้ Firebase) — แอปเหลือแค่ service worker ของตัวเองกับปุ่มขอสิทธิ์
+**subscription ผูกกับแอปที่เรียกเสมอ** เพราะ service worker อยู่ที่โดเมนของแอป ใช้ข้ามแอปไม่ได้
+
+> **แพ็กเกจนี้รันฝั่งเซิร์ฟเวอร์เท่านั้น** เพราะถือ `PI_NOTIFY_KEY` — ห้าม import ใน component ที่ส่งถึงเบราว์เซอร์
+> เบราว์เซอร์คุยกับเซิร์ฟเวอร์ของแอปตัวเอง (server action / route) แล้วเซิร์ฟเวอร์ค่อยคุยกับ hub
+
+**ทางลัด (0.5.0):** `createPushHandlers({ getUser })` ทำ 3 ฟังก์ชันข้างล่างให้ — แอปส่งแค่วิธีดึงผู้ใช้จาก session
+(อีเมลต้องมาจาก session เท่านั้น; ตรวจรูป subscription จากเบราว์เซอร์ให้; ไม่ล็อกอิน = `MailError` kind `auth`) ใช้คู่กับ `<WebPushRow />` ของ `@suphark/ui/pwa`:
+
+```ts
+"use server";
+import { createPushHandlers } from "@suphark/notify";
+
+const push = createPushHandlers({
+  getUser: async () => {
+    const u = await getCurrentUser();                     // ของแต่ละแอป
+    return u?.email ? { email: u.email, id: u.id } : null;
+  },
+});
+// ห่อเป็น async function ทีละตัว (ไฟล์ "use server" export ได้เฉพาะ async function)
+export async function getVapidPublicKey() { return push.getPublicKey(); }
+export async function registerPush(sub: PushSubscriptionJSON) { return push.subscribe(sub); }
+export async function unregisterPush(endpoint: string) { return push.unsubscribe(endpoint); }
+```
+
+**Service worker เสิร์ฟจากแพ็กเกจเอง** — ไม่ต้องเขียน `public/sw.js` และ **ไม่ควร `importScripts` จากโดเมนอื่น**
+(service worker คุมทั้ง origin ของแอปและดักทุก request — โค้ดจากโดเมนอื่นรันเข้ามาได้ทุกแอปพร้อมกัน):
+
+```ts
+// app/sw.js/route.ts
+import { pushServiceWorker } from "@suphark/notify";
+export const GET = pushServiceWorker({ icon: "/icon-192.png" });   // เปิดเฉพาะลิงก์ใน origin ของแอป
+```
+
+เขียนเองทีละฟังก์ชันก็ได้ (ตัวอย่างเดิม):
+
+```ts
+// ---- ฝั่งเซิร์ฟเวอร์ของแอป (server action) ----
+"use server";
+import { getPushConfig, savePushSubscription, deletePushSubscription, listPushDevices } from "@suphark/notify";
+
+export async function pushPublicKey() {
+  const { publicKey } = await getPushConfig();   // VAPID public key (ค่าสาธารณะ ส่งให้ client ได้)
+  return publicKey;
+}
+export async function savePush(subscription: PushSubscriptionJson, label?: string) {
+  const user = await requireAuth();              // อีเมลมาจาก session เท่านั้น ห้ามรับจาก client
+  return savePushSubscription(user.email, subscription, { label, piUserId: user.id });
+}
+export async function removePush(endpoint: string) {
+  const user = await requireAuth();
+  return deletePushSubscription(user.email, endpoint);
+}
+export async function myDevices() {
+  const user = await requireAuth();
+  return listPushDevices(user.email);            // { devices: [{ id, label, enabled, endpointTail }] }
+}
+```
+
+```ts
+// ---- ฝั่งเบราว์เซอร์ (component ของแอป) ----
+const reg = await navigator.serviceWorker.register("/sw.js");
+const sub = await reg.pushManager.subscribe({
+  userVisibleOnly: true,
+  applicationServerKey: await pushPublicKey(),
+});
+await savePush(sub.toJSON(), `${navigator.userAgent}`);
+```
+
+**ไม่ใช้ SDK ก็ได้** — ทั้งหมดเป็น REST ธรรมดา เรียกจากเซิร์ฟเวอร์ของแอปด้วย `fetch` ได้เลย
+(`Authorization: Bearer $PI_NOTIFY_KEY`): `GET /api/v1/push/config` · `POST`/`GET`/`DELETE /api/v1/recipients/:email/push`
+SDK ให้เพิ่มแค่ timeout, การแปลง error เป็น `MailError` พร้อม `kind`, type และค่าเริ่มต้นของ URL/คีย์
+
+ส่งด้วย `notify({ channels: ["push"] })` (ไม่ระบุ channels = ส่งทุกช่องทางที่ผูกไว้ รวม push ทุกเครื่อง)
+service worker ของแอปจะได้ payload JSON `{ title, body, link? }` — `body` เป็นข้อความล้วนเสมอ:
+
+```js
+self.addEventListener("push", (event) => {
+  const { title, body, link } = event.data.json();
+  event.waitUntil(self.registration.showNotification(title, { body, data: { link } }));
+});
+```
+
+- ไม่มีเครื่องไหนเปิดไว้ → `status: "skipped", reason: "channel_not_linked"` · hub ยังไม่ตั้ง provider → `no_push_provider`
+- เบราว์เซอร์ถอนสิทธิ์ (404/410) → hub ปิด subscription นั้นให้เอง ไม่ต้องตามลบ
+- เปลี่ยนคู่กุญแจ VAPID ที่ hub = ผู้ใช้ทุกคนต้องกดอนุญาตใหม่ (subscription ผูกกับกุญแจที่ใช้ตอน subscribe)
+
 ## โหมด local (ไม่ผ่าน hub)
 
 ไม่มี `PI_NOTIFY_KEY` = SDK ส่งตรงด้วย provider ที่ตั้งใน env ของแอปเอง (engine เดียวกับที่ hub ใช้)
@@ -226,6 +373,17 @@ Pi Notify มี contract test (`apps/notify/src/test/contract/`) เก็บ b
 
 ## Changelog
 
+- 0.5.0 — **เขียนฝั่งแอปให้สั้นลง** (เพิ่มอย่างเดียว — ฟอร์มของ 0.4.0 ใช้ได้ทุกแบบ; Pi Notify รุ่นเก่าใช้ได้ ยกเว้น `code` ที่แกะจาก url ให้เอง)
+  - `notify({ to })` รับ user object `{ email }` และ array (กรอง null); ผู้รับเดี่ยวไม่มีอีเมล = `MailError` `invalid`
+  - `notifySafe()` / `sendMailSafe()` ไม่โยน; ไม่มี key/provider = `disabled`
+  - `@suphark/notify/next`: `notifyLater()` / `sendMailLater()` ส่งหลังตอบด้วย `after()` (optional peer `next >= 15`; core ไม่ import next)
+  - `getChannelStatus()`; `createLink()` คืน `code`
+  - `createPushHandlers({ getUser })` + `pushServiceWorker()` สำหรับ web push
+  - `renderNotifyEmail()` (+ `resolveFormat` / `toPlainText` / `looksLikeHtml`) — เทมเพลตอีเมลเดียวกับที่ Pi Notify ใช้ แอปไม่ต้องเขียน HTML "หัวข้อ + ย่อหน้า + ปุ่ม" เอง
+  - `getRecipient()` / `createLink()` รับ user object; `toEmails()`, `hasNotifyKey()`, type `Recipient`
+
+- 0.4.0 — **web push ผ่าน hub**: `getPushConfig()`, `savePushSubscription()`, `deletePushSubscription()`, `listPushDevices()` และ `notify({ channels: ["push"] })`; hub ถือคู่กุญแจ VAPID (มาตรฐาน ไม่ใช้ Firebase) subscription ผูกต่อแอป · `NotifyChannel` เพิ่ม `"push"` และ `reason` เพิ่ม `"no_push_provider"` (เพิ่มอย่างเดียว แต่ `NotifyChannel` เป็น type ที่แอปใช้ในลายเซ็นของตัวเอง จึงออกเป็น minor ตามกติกาข้อ 4)
+
 - 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) ไม่ปล่อยคำขอค้าง