@suphark/notify 0.3.1 → 0.4.0

package/README.md

@@ -85,6 +85,38 @@ const { channels } = await getRecipient(user.email);       // [{ type: "telegram
 
 หรือส่งผู้ใช้ไปผูกเองที่ `https://notify.suphark.com/me` (ล็อกอิน Pi Auth) — ผูกครั้งเดียวใช้ได้ทุกแอป
 
+### แจ้งเตือนบนเบราว์เซอร์ (web push)
+
+hub ถือคู่กุญแจ VAPID ให้ (ไม่ต้องใช้ Firebase) — แอปเหลือแค่ service worker ของตัวเองกับปุ่มขอสิทธิ์
+**subscription ผูกกับแอปที่เรียกเสมอ** เพราะ service worker อยู่ที่โดเมนของแอป ใช้ข้ามแอปไม่ได้
+
+```ts
+import { getPushConfig, savePushSubscription, deletePushSubscription, listPushDevices } from "@suphark/notify";
+
+// ฝั่ง client: ขอสิทธิ์แล้วส่ง subscription ไปเก็บที่ hub ผ่าน server action ของแอป
+const { publicKey } = await getPushConfig();                       // VAPID public key (ค่าสาธารณะ)
+const reg = await navigator.serviceWorker.register("/sw.js");
+const sub = await reg.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: publicKey });
+await savePushSubscription(user.email, sub.toJSON(), { label: "Chrome บน Windows", piUserId: user.id });
+
+await listPushDevices(user.email);        // { devices: [{ id, label, enabled, endpointTail }] }
+await deletePushSubscription(user.email, sub.endpoint);   // ผู้ใช้ปิดที่เครื่องนั้น
+```
+
+ส่งด้วย `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 +258,8 @@ Pi Notify มี contract test (`apps/notify/src/test/contract/`) เก็บ b
 
 ## Changelog
 
+- 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) ไม่ปล่อยคำขอค้าง

package/dist/index.d.ts

@@ -472,8 +472,11 @@ declare function classifyError(err: unknown): {
 /** เวลาพัก (วินาที) ต่อ error แต่ละแบบ ก่อนกลับมาลอง provider นั้นอีก — คูณสองทุกครั้งที่พังซ้ำ */
 declare const DEFAULT_COOLDOWN: Record<ErrorKind, number>;
 
-/** ช่องทางแจ้งเตือนที่ hub รองรับ — ผู้รับผูกแชทเองที่ hub (/me) หรือผ่านลิงก์ที่แอปขอจาก hub */
-type NotifyChannel = "telegram" | "line" | "email";
+/**
+ * ช่องทางแจ้งเตือนที่ hub รองรับ — ผู้รับผูกแชทเองที่ hub (/me) หรือผ่านลิงก์ที่แอปขอจาก hub
+ * `push` = web push ของเบราว์เซอร์ ผูกต่อแอป (service worker อยู่ที่โดเมนของแอปเอง)
+ */
+type NotifyChannel = "telegram" | "line" | "push" | "email";
 interface NotifyInput {
     /** อีเมลผู้รับ (ตรงกับบัญชี Pi Auth) — ระบุได้สูงสุด 50 คน */
     to: string | string[];
@@ -500,8 +503,11 @@ interface NotifyResultItem {
     id?: string;
     failedOver?: boolean;
     error?: string;
-    /** app_daily_cap = แอปส่งอีเมลแทนแชทครบเพดานรายวันที่ตั้งใน Pi Notify แล้ว */
-    reason?: "no_link" | "channel_not_linked" | "no_chat_provider" | "app_daily_cap";
+    /**
+     * app_daily_cap = แอปส่งอีเมลแทนแชทครบเพดานรายวันที่ตั้งใน Pi Notify แล้ว
+     * no_push_provider = hub ยังไม่ได้ตั้ง provider web push
+     */
+    reason?: "no_link" | "channel_not_linked" | "no_chat_provider" | "no_push_provider" | "app_daily_cap";
     /** (status failed) คำขอหมดงบเวลาก่อนได้เริ่มส่งรายการนี้ — ส่งซ้ำเฉพาะรายการนี้ได้ */
     deferred?: boolean;
 }
@@ -531,6 +537,21 @@ declare const NOTIFY_TIMEOUT_MS: {
     readonly notify: 65000;
     readonly recipient: 10000;
 };
+/** subscription จากเบราว์เซอร์ (`PushSubscription.toJSON()`) */
+interface PushSubscriptionJson {
+    endpoint: string;
+    keys: {
+        p256dh: string;
+        auth: string;
+    };
+}
+interface PushDevice {
+    id: string;
+    label: string | null;
+    enabled: boolean;
+    /** ท่อนท้ายของ endpoint ไว้แยกเครื่อง (ไม่คืนค่าเต็ม) */
+    endpointTail: string;
+}
 /** ช่องทางที่ผู้รับผูกไว้ (จาก GET /api/v1/recipients/:email) — ไม่มี chat id */
 interface RecipientChannelInfo {
     type: string;
@@ -565,6 +586,33 @@ declare function createLink(email: string, channel?: Exclude<NotifyChannel, "ema
     url: string;
     expiresAt: string;
 }>;
+/**
+ * VAPID public key ของ hub — ใช้เป็น `applicationServerKey` ตอน `pushManager.subscribe()`
+ * (ค่าสาธารณะ แคชฝั่งแอปได้) · hub ยังไม่ได้ตั้ง provider push → MailError kind "server"
+ */
+declare function getPushConfig(opts?: NotifyOptions): Promise<{
+    publicKey: string;
+}>;
+/**
+ * เก็บ subscription ของเบราว์เซอร์หนึ่งเครื่องไว้ที่ hub (ผูกกับแอปที่เรียกเสมอ)
+ * เรียกซ้ำด้วย endpoint เดิมได้ = อัปเดตกุญแจ/เปิดใช้คืน · `piUserId` ให้ hub ลบตามบัญชีที่ถูกลบได้
+ */
+declare function savePushSubscription(email: string, subscription: PushSubscriptionJson, opts?: NotifyOptions & {
+    label?: string;
+    piUserId?: string;
+}): Promise<{
+    ok: true;
+    created: boolean;
+}>;
+/** ผู้ใช้ปิดแจ้งเตือนที่เครื่องนั้น (ลบได้เฉพาะ subscription ของแอปตัวเอง) */
+declare function deletePushSubscription(email: string, endpoint: string, opts?: NotifyOptions): Promise<{
+    ok: true;
+    deleted: number;
+}>;
+/** เครื่องที่ผู้รับเปิดแจ้งเตือนไว้กับแอปนี้ — ไว้แสดงรายการในหน้าตั้งค่า */
+declare function listPushDevices(email: string, opts?: NotifyOptions): Promise<{
+    devices: PushDevice[];
+}>;
 
 /** Store ใน memory ของ process (ค่าเริ่มต้น) — state หายเมื่อ restart และไม่แชร์ข้าม instance */
 declare function createMemoryStore(): Store;
@@ -589,4 +637,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, 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 };
+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 PushDevice, type PushSubscriptionJson, 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, deletePushSubscription, formatAddress, getMailer, getPushConfig, getRecipient, listProviders, listPushDevices, notify, parseAddress, parseAddressList, providersFromEnv, requireFrom, resetMailer, savePushSubscription, sendMail };

package/dist/index.js

@@ -1122,6 +1122,29 @@ async function createLink(email, channel = "telegram", opts = {}) {
     timeoutMs: NOTIFY_TIMEOUT_MS.recipient
   });
 }
+async function getPushConfig(opts = {}) {
+  return hubRequest(opts, "/api/v1/push/config", { timeoutMs: NOTIFY_TIMEOUT_MS.recipient });
+}
+async function savePushSubscription(email, subscription, opts = {}) {
+  const { label, piUserId, ...rest } = opts;
+  return hubRequest(rest, `/api/v1/recipients/${encodeURIComponent(email)}/push`, {
+    method: "POST",
+    body: { subscription, ...label ? { label } : {}, ...piUserId ? { piUserId } : {} },
+    timeoutMs: NOTIFY_TIMEOUT_MS.recipient
+  });
+}
+async function deletePushSubscription(email, endpoint, opts = {}) {
+  return hubRequest(opts, `/api/v1/recipients/${encodeURIComponent(email)}/push`, {
+    method: "DELETE",
+    body: { endpoint },
+    timeoutMs: NOTIFY_TIMEOUT_MS.recipient
+  });
+}
+async function listPushDevices(email, opts = {}) {
+  return hubRequest(opts, `/api/v1/recipients/${encodeURIComponent(email)}/push`, {
+    timeoutMs: NOTIFY_TIMEOUT_MS.recipient
+  });
+}
 
 // src/stores/redis.ts
 function createRedisStore(client, opts = {}) {
@@ -1169,15 +1192,19 @@ export {
   createResendProvider,
   createSmtpProvider,
   createZeptoMailProvider,
+  deletePushSubscription,
   formatAddress,
   getMailer,
+  getPushConfig,
   getRecipient,
   listProviders,
+  listPushDevices,
   notify,
   parseAddress,
   parseAddressList,
   providersFromEnv,
   requireFrom,
   resetMailer,
+  savePushSubscription,
   sendMail
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suphark/notify",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "description": "ส่งอีเมล + แจ้งเตือน Telegram ผ่าน Pi Notify hub (notify.suphark.com) หรือส่งอีเมลตรงไป Resend/SMTP/Zoho/ZeptoMail ใน API เดียว พร้อม failover อัตโนมัติ",