@suphark/notify 0.5.0 → 0.7.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,6 @@
 # @suphark/notify
 
-SDK ส่งอีเมล + แจ้งเตือน (Telegram / Web Push) ของแอปทุกตัว — ค่าเริ่มต้นส่งผ่าน **Pi Notify hub** (`https://notify.suphark.com`) ซึ่งเป็นคนถือ credential ของ Resend/SMTP/Zoho/Telegram bot ทำ failover นับโควต้า เก็บ log และเก็บว่าผู้รับผูกแชทไหนไว้ แอปใส่แค่ key ตัวเดียว
+SDK ส่งอีเมล + แจ้งเตือน (Telegram / LINE / Web Push) ของแอปทุกตัว — ค่าเริ่มต้นส่งผ่าน **Pi Notify hub** (`https://notify.suphark.com`) ซึ่งเป็นคนถือ credential ของ Resend/SMTP/Zoho/Telegram bot/LINE OA ทำ failover นับโควต้า เก็บ log และเก็บว่าผู้รับผูกแชทไหนไว้ แอปใส่แค่ key ตัวเดียว
 
 > 📖 **คู่มือการใช้งานและสูตรการเขียนโค้ดฉบับเต็ม:** ดูที่ [docs/guide.md](../../docs/guide.md)
 
@@ -94,6 +94,61 @@ const { url, code } = await createLink(user);                   // รับ use
 const { linked, label, manageUrl } = await getChannelStatus(user, "telegram");
 ```
 
+### LINE (0.7.0)
+
+ใช้เหมือน Telegram ทุกอย่าง — ผู้รับผูก LINE ของตัวเองครั้งเดียว (ที่ `/me` ของ hub หรือปุ่มในแอป) แล้วส่งด้วยอีเมล:
+
+```ts
+const { url, code } = await createLink(user, "line");
+// url เปิดแชทกับ OA พร้อมพิมพ์ "ผูก Pi Notify <code>" ไว้ — ผู้ใช้กดส่ง (ยังไม่เป็นเพื่อนกับ OA ให้เพิ่มเพื่อนด้วย)
+const { linked } = await getChannelStatus(user, "line");
+await notify({ to: user, title: "PO รออนุมัติ", body: "…", link, channels: ["line"] });
+```
+
+- ข้อความ LINE เป็น text ล้วน: หัวเรื่อง / เนื้อหา / ลิงก์บรรทัดสุดท้าย (กดได้) — body ที่เป็น HTML ถูกแปลงเป็นข้อความ, ยาวเกิน 5,000 ตัดเนื้อหาแต่คงลิงก์
+- ผู้ใช้บล็อก OA → hub ปิดการผูกให้เอง (ปลดบล็อกแล้วกลับมาเอง) · พิมพ์ "หยุดแจ้งเตือน" ในแชท OA = เลิกรับ
+
+### ส่งเข้ากลุ่ม: `notifyTopic()` (0.7.0)
+
+แอปไม่ต้องถือ group id — admin เชิญ OA/bot เข้ากลุ่ม LINE/Telegram (hub เห็นกลุ่มเองจาก webhook) แล้วผูกกลุ่มกับ **topic ของแอป** ที่หน้า Topics ของ Pi Notify
+
+```ts
+import { notifyTopic } from "@suphark/notify";
+
+const r = await notifyTopic({
+  topic: "po-overdue",              // topic ของแอปนี้ (a-z 0-9 . _ -)
+  title: "PO เกินกำหนด 3 รายการ",
+  body: "PO-2611-001, …",
+  link: "https://app.example.com/po?status=overdue",
+  deliverWithin: 3600,              // ใช้ได้เหมือน notify()
+  idempotencyKey: `po-overdue:${date}`,
+});
+// r.results = [{ to: "topic:po-overdue", channel: "line", status: "sent", target: "ทีมจัดซื้อ" }, …] (รายกลุ่ม)
+```
+
+- topic ไม่พบ → `MailError` `invalid` (404) · topic ถูกปิด/ยังไม่ผูกกลุ่ม → `status: "skipped", reason: "no_target"` (ไม่โยน)
+- `channels: ["line"]` = เฉพาะกลุ่ม LINE ของ topic · ไม่ระบุ = ทุกกลุ่ม
+- แบบไม่โยน/เบื้องหลัง: `notifyTopicSafe()` และ `notifyTopicLater()` จาก `@suphark/notify/next`
+- LINE คิดโควต้าตามข้อความ push — ยอดของเดือนดูที่หน้า Providers ของ Pi Notify
+
+### ให้ hub ส่งซ้ำเอง: `deliverWithin` + `idempotencyKey` (0.6.0)
+
+```ts
+const r = await notify({
+  to: user,
+  title: "ถึงกำหนดงาน",
+  body: "…",
+  channels: ["telegram"],
+  deliverWithin: 3600, // ให้ hub พยายามส่งภายใน 1 ชม.
+  idempotencyKey: `pi-done:reminder:${user.id}:${runId}`, // cron รันซ้ำก็ไม่เตือนซ้ำ
+});
+// r.results[i].status: "sent" | "queued" (hub รับไว้ส่งซ้ำเอง) | "failed" | "skipped"
+```
+
+- นับ `queued` เป็น "รับไว้แล้ว" — แอปไม่ต้องส่งซ้ำเอง; ดูสถานะที่หน้า Logs / คิวส่งซ้ำของ Pi Notify
+- `failed` = ผิดถาวร / ลองครบแล้ว / เลยเวลา — แอปตัดสินใจเอง (อย่าสลับไปอีเมลถ้าผู้ใช้ไม่ได้ขอ)
+- ใช้ `idempotencyKey` ที่ผูกกับเหตุการณ์ (ไม่ใช่สุ่มใหม่ทุกครั้ง) จึงกันซ้ำได้ — ส่งเนื้อหาเดิมด้วย key เดิมซ้ำจะได้ผลเดิมกลับมา
+
 ### เขียนให้สั้น: ส่งแบบไม่โยน / ส่งเบื้องหลัง / `to` เป็น user object (0.5.0)
 
 `to` ของ `notify()` รับ **user object ที่มี `email`** (และ array ของมัน) ได้เลย — ไม่ต้องแกะ `.email` เอง
@@ -373,6 +428,16 @@ Pi Notify มี contract test (`apps/notify/src/test/contract/`) เก็บ b
 
 ## Changelog
 
+- 0.7.0 — **LINE + ส่งเข้ากลุ่มด้วย topic** (เพิ่มอย่างเดียว; ต้องใช้ Pi Notify 2026-11-11+)
+  - `createLink(email, "line")` / `getChannelStatus(email, "line")` / `notify({ channels: ["line"] })` — ช่องทาง LINE รายคน
+  - `notifyTopic({ topic, title, body, … })` + `notifyTopicSafe()` + `notifyTopicLater()` (`/next`) — ส่งเข้าทุกกลุ่ม LINE/Telegram ที่ admin ผูกกับ topic ของแอป
+  - `NotifyResultItem.target?` (ชื่อกลุ่ม) และ `reason` เพิ่ม `"no_target"` (ออกเป็น minor เพราะ union ของ `reason` ที่แอปอาจ switch)
+
+- 0.6.0 — **hub ส่งซ้ำเอง** (เพิ่มอย่างเดียว — แอปที่ไม่ส่งตัวเลือกใหม่ได้พฤติกรรมเดิมทุกอย่าง; ต้องใช้ Pi Notify 2026-10-14+)
+  - `notify({ deliverWithin })` (วินาที 60–86400): รายการที่ค้างหรือพลาดชั่วคราวเข้าคิวถาวรของ hub แล้วส่งซ้ำตาม backoff (1 นาที → 5 นาที → 30 นาที → 2 ชม., สูงสุด 5 ครั้ง) · ผิดถาวรไม่ส่งซ้ำ · เลยเวลาแล้วไม่ส่ง · ไม่สลับช่องทาง
+  - `notify({ idempotencyKey })` → หัว `Idempotency-Key`: key+เนื้อหาเดิมได้ผลเดิม ไม่ส่งซ้ำ (จำ 7 วัน) · เนื้อหาต่างแต่ key เดิม = `invalid` (422) · คำขอเดิมยังทำอยู่ = `rate_limit` (409, `retryAfterSec` 5)
+  - `NotifyResultItem.status` เพิ่ม `"queued"` (+ `deliveryId`), `NotifyResult.queued?` / `NotifySafeResult.queued?` — `queued` นับเป็น "รับไว้แล้ว" ไม่ใช่ failed (`notifySafe().ok` เป็น true) · `status` ใหม่เกิดเฉพาะเมื่อแอปส่ง `deliverWithin` (ออกเป็น minor เพราะ union ของ `status` ที่แอปอาจ switch)
+
 - 0.5.0 — **เขียนฝั่งแอปให้สั้นลง** (เพิ่มอย่างเดียว — ฟอร์มของ 0.4.0 ใช้ได้ทุกแบบ; Pi Notify รุ่นเก่าใช้ได้ ยกเว้น `code` ที่แกะจาก url ให้เอง)
   - `notify({ to })` รับ user object `{ email }` และ array (กรอง null); ผู้รับเดี่ยวไม่มีอีเมล = `MailError` `invalid`
   - `notifySafe()` / `sendMailSafe()` ไม่โยน; ไม่มี key/provider = `disabled`

package/dist/{chunk-FL5ZV3S2.js → chunk-2RXN5HXT.js}

@@ -1101,6 +1101,7 @@ async function hubRequest(opts, path, init) {
       method: init.method ?? "GET",
       headers: {
         Authorization: `Bearer ${apiKey}`,
+        ...init.headers,
         ...init.body !== void 0 ? { "Content-Type": "application/json" } : {}
       },
       body: init.body !== void 0 ? JSON.stringify(init.body) : void 0,
@@ -1127,14 +1128,23 @@ async function hubRequest(opts, path, init) {
   }
   return data;
 }
-async function notify(input, opts = {}) {
+async function postNotify(body, idempotencyKey, opts) {
   const data = await hubRequest(opts, "/api/v1/notify", {
     method: "POST",
-    body: { ...input, to: toEmails(input.to) },
+    body,
+    headers: idempotencyKey ? { "Idempotency-Key": idempotencyKey } : void 0,
     timeoutMs: NOTIFY_TIMEOUT_MS.notify
   });
   return { results: data.results, ...data.summary };
 }
+async function notify(input, opts = {}) {
+  const { idempotencyKey, ...body } = input;
+  return postNotify({ ...body, to: toEmails(input.to) }, idempotencyKey, opts);
+}
+async function notifyTopic(input, opts = {}) {
+  const { idempotencyKey, ...body } = input;
+  return postNotify(body, idempotencyKey, opts);
+}
 async function getRecipient(email, opts = {}) {
   return hubRequest(
     opts,
@@ -1213,13 +1223,19 @@ function resetSafeWarnings() {
 }
 var messageOf = (err) => err instanceof Error ? err.message : String(err);
 async function notifySafe(input, opts = {}) {
+  return safely("notify()", () => notify(input, opts), opts);
+}
+async function notifyTopicSafe(input, opts = {}) {
+  return safely("notifyTopic()", () => notifyTopic(input, opts), opts);
+}
+async function safely(what, run, opts) {
   const none = { sent: 0, failed: 0, skipped: 0, results: [] };
   if (!hasNotifyKey(opts)) {
-    warnDisabled("notify()", opts.env ?? process.env);
+    warnDisabled(what, opts.env ?? process.env);
     return { ok: false, disabled: true, ...none };
   }
   try {
-    const r = await notify(input, opts);
+    const r = await run();
     return { ok: r.failed === 0, ...r };
   } catch (err) {
     const body = err instanceof MailError ? err.cause : void 0;
@@ -1277,6 +1293,7 @@ export {
   NOTIFY_TIMEOUT_MS,
   hasNotifyKey,
   notify,
+  notifyTopic,
   getRecipient,
   createLink,
   getChannelStatus,
@@ -1286,5 +1303,6 @@ export {
   listPushDevices,
   resetSafeWarnings,
   notifySafe,
+  notifyTopicSafe,
   sendMailSafe
 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { P as ParsedAddress, A as Address, a as Provider, E as ErrorKind, Q as Quota, M as Message, S as SendResult, b as ProviderStatus, c as ProviderInfo, d as Store, e as MailerEvent, f as Attempt, g as PushDevice, N as NotifyOptions, h as NotifyResultItem, i as NotifyInput } from './notify-L7JnpG0t.js';
-export { j as Attachment, C as ChannelStatus, k as NOTIFY_TIMEOUT_MS, l as NormalizedMessage, m as NotifyChannel, n as NotifyResult, o as PushSubscriptionJson, p as QuotaUsage, R as Recipient, q as RecipientChannelInfo, r as RecipientInfo, s as SkipReason, t as createLink, u as deletePushSubscription, v as getChannelStatus, w as getPushConfig, x as getRecipient, y as hasNotifyKey, z as listPushDevices, B as notify, D as savePushSubscription, F as toEmails } from './notify-L7JnpG0t.js';
+import { P as ParsedAddress, A as Address, a as Provider, E as ErrorKind, Q as Quota, M as Message, S as SendResult, b as ProviderStatus, c as ProviderInfo, d as Store, e as MailerEvent, f as Attempt, g as PushDevice, N as NotifyOptions, h as NotifyResultItem, i as NotifyInput, j as NotifyTopicInput } from './notify-D4auDRfk.js';
+export { k as Attachment, C as ChannelStatus, l as NOTIFY_TIMEOUT_MS, m as NormalizedMessage, n as NotifyChannel, o as NotifyResult, p as PushSubscriptionJson, q as QuotaUsage, R as Recipient, r as RecipientChannelInfo, s as RecipientInfo, t as SkipReason, u as createLink, v as deletePushSubscription, w as getChannelStatus, x as getPushConfig, y as getRecipient, z as hasNotifyKey, B as listPushDevices, D as notify, F as notifyTopic, G as savePushSubscription, H as toEmails } from './notify-D4auDRfk.js';
 
 /** แปลง "ชื่อ <a@b.com>" / "a@b.com" / { name, email } → { name, email } */
 declare function parseAddress(input: Address): ParsedAddress;
@@ -403,6 +403,8 @@ interface NotifySafeResult {
     failed: number;
     skipped: number;
     deferred?: number;
+    /** (0.6.0) hub รับไว้ส่งซ้ำเอง — ไม่นับเป็นความล้มเหลว */
+    queued?: number;
     /** ผลรายผู้รับ/ช่องทาง (มีแม้ Pi Notify ตอบ 502 — ดึงจาก body) */
     results: NotifyResultItem[];
     /** ข้อความ error (ไม่มีอีเมลผู้รับ/เนื้อหา) */
@@ -418,6 +420,8 @@ declare function resetSafeWarnings(): void;
  * ไม่มี PI_NOTIFY_KEY → { ok: false, disabled: true } ไม่ส่ง
  */
 declare function notifySafe(input: NotifyInput, opts?: NotifyOptions): Promise<NotifySafeResult>;
+/** (0.7.0) notifyTopic() ที่ไม่โยนเด็ดขาด (ดู notifySafe) — topic ไม่พบก็คืน { ok: false, error } */
+declare function notifyTopicSafe(input: NotifyTopicInput, opts?: NotifyOptions): Promise<NotifySafeResult>;
 interface SendMailSafeResult {
     ok: boolean;
     provider?: string;
@@ -453,4 +457,5 @@ declare function createRedisStore(client: RedisLike, opts?: {
     prefix?: string;
 }): Store;
 
-export { Address, AllProvidersFailedError, Attempt, type BodyFormat, type BrowserPushSubscription, type ConsoleOptions, DEFAULT_COOLDOWN, DEFAULT_HUB_URL, type Env, ErrorKind, type HubErrorResponse, type HubOptions, type HubSendRequest, type HubSendResponse, MailError, type Mailer, MailerEvent, type MailerOptions, Message, type NotifyEmailInput, NotifyInput, NotifyOptions, NotifyResultItem, type NotifySafeResult, ParsedAddress, Provider, type ProviderConfig, ProviderInfo, ProviderStatus, PushDevice, type PushHandlers, type PushHandlersOptions, type PushServiceWorkerOptions, type PushUser, Quota, type RedisLike, type ResendOptions, SMTP_PRESETS, type SendMailSafeResult, SendResult, type SmtpOptions, type SmtpPreset, Store, type ZeptoMailOptions, classifyError, configureMailer, createConsoleProvider, createHubProvider, createMailer, createMemoryStore, createPresetSmtpProvider, createPushHandlers, createRedisStore, createResendProvider, createSmtpProvider, createZeptoMailProvider, formatAddress, getMailer, listProviders, looksLikeHtml, notifySafe, parseAddress, parseAddressList, providersFromEnv, pushServiceWorker, pushServiceWorkerSource, renderNotifyEmail, requireFrom, resetMailer, resetSafeWarnings, resolveFormat, sendMail, sendMailSafe, toPlainText };
+export { Address, AllProvidersFailedError, Attempt, DEFAULT_COOLDOWN, DEFAULT_HUB_URL, ErrorKind, MailError, MailerEvent, Message, NotifyInput, NotifyOptions, NotifyResultItem, NotifyTopicInput, ParsedAddress, Provider, ProviderInfo, ProviderStatus, PushDevice, Quota, SMTP_PRESETS, SendResult, Store, classifyError, configureMailer, createConsoleProvider, createHubProvider, createMailer, createMemoryStore, createPresetSmtpProvider, createPushHandlers, createRedisStore, createResendProvider, createSmtpProvider, createZeptoMailProvider, formatAddress, getMailer, listProviders, looksLikeHtml, notifySafe, notifyTopicSafe, parseAddress, parseAddressList, providersFromEnv, pushServiceWorker, pushServiceWorkerSource, renderNotifyEmail, requireFrom, resetMailer, resetSafeWarnings, resolveFormat, sendMail, sendMailSafe, toPlainText };
+export type { BodyFormat, BrowserPushSubscription, ConsoleOptions, Env, HubErrorResponse, HubOptions, HubSendRequest, HubSendResponse, Mailer, MailerOptions, NotifyEmailInput, NotifySafeResult, ProviderConfig, PushHandlers, PushHandlersOptions, PushServiceWorkerOptions, PushUser, RedisLike, ResendOptions, SendMailSafeResult, SmtpOptions, SmtpPreset, ZeptoMailOptions };

package/dist/index.js

@@ -27,6 +27,8 @@ import {
   listPushDevices,
   notify,
   notifySafe,
+  notifyTopic,
+  notifyTopicSafe,
   parseAddress,
   parseAddressList,
   providersFromEnv,
@@ -37,7 +39,7 @@ import {
   sendMail,
   sendMailSafe,
   toEmails
-} from "./chunk-FL5ZV3S2.js";
+} from "./chunk-2RXN5HXT.js";
 
 // src/format.ts
 var KNOWN_TAG_RE = /<\/?(b|strong|i|em|u|ins|s|strike|del|a|code|pre|p|br|div|span|ul|ol|li|h[1-6]|table|tr|td)(?=[\s/>])[^>]*>/i;
@@ -219,6 +221,8 @@ export {
   looksLikeHtml,
   notify,
   notifySafe,
+  notifyTopic,
+  notifyTopicSafe,
   parseAddress,
   parseAddressList,
   providersFromEnv,

package/dist/next.d.ts

@@ -1,4 +1,4 @@
-import { N as NotifyOptions, i as NotifyInput, M as Message } from './notify-L7JnpG0t.js';
+import { NotifyOptions, NotifyInput, NotifyTopicInput, Message } from './index.js';
 
 /**
  * ส่งหลังตอบ response แล้ว (`after()` ของ Next.js) — entry แยก `@suphark/notify/next` เพราะ core ของ SDK
@@ -19,10 +19,16 @@ declare const LATER_TIMEOUT_MS = 20000;
  * @example notifyLater({ to: user, title: "บันทึกแล้ว", body: "ระบบอัปเดตงานแล้ว" });
  */
 declare function notifyLater(input: NotifyInput, opts?: LaterOptions): void;
+/**
+ * (0.7.0) notifyTopic() เบื้องหลัง (ดู notifyLater) — คืน void
+ * @example notifyTopicLater({ topic: "po-overdue", title: "PO เกินกำหนด", body: "…" });
+ */
+declare function notifyTopicLater(input: NotifyTopicInput, opts?: LaterOptions): void;
 /**
  * sendMail() เบื้องหลัง (ดู notifyLater) — คืน void
  * @example sendMailLater({ to: user.email, subject: "ยินดีต้อนรับ", html: "<p>…</p>" });
  */
 declare function sendMailLater(message: Message, opts?: Pick<LaterOptions, "onError">): void;
 
-export { LATER_TIMEOUT_MS, type LaterOptions, notifyLater, sendMailLater };
+export { LATER_TIMEOUT_MS, notifyLater, notifyTopicLater, sendMailLater };
+export type { LaterOptions };

package/dist/next.js

@@ -1,7 +1,8 @@
 import {
   notifySafe,
+  notifyTopicSafe,
   sendMailSafe
-} from "./chunk-FL5ZV3S2.js";
+} from "./chunk-2RXN5HXT.js";
 
 // src/next.ts
 import { after } from "next/server";
@@ -27,6 +28,20 @@ function notifyLater(input, opts = {}) {
     report("notify()", r.error ?? (r.failed > 0 ? `${r.failed} \u0E23\u0E32\u0E22\u0E01\u0E32\u0E23\u0E25\u0E49\u0E21\u0E40\u0E2B\u0E25\u0E27` : void 0), onError);
   });
 }
+function notifyTopicLater(input, opts = {}) {
+  const { onError, ...rest } = opts;
+  runLater(async () => {
+    const r = await notifyTopicSafe(input, {
+      timeoutMs: LATER_TIMEOUT_MS,
+      ...rest
+    });
+    report(
+      "notifyTopic()",
+      r.error ?? (r.failed > 0 ? `${r.failed} \u0E23\u0E32\u0E22\u0E01\u0E32\u0E23\u0E25\u0E49\u0E21\u0E40\u0E2B\u0E25\u0E27` : void 0),
+      onError
+    );
+  });
+}
 function sendMailLater(message, opts = {}) {
   runLater(async () => {
     const r = await sendMailSafe(message);
@@ -36,5 +51,6 @@ function sendMailLater(message, opts = {}) {
 export {
   LATER_TIMEOUT_MS,
   notifyLater,
+  notifyTopicLater,
   sendMailLater
 };

package/dist/{notify-L7JnpG0t.d.ts → notify-D4auDRfk.d.ts}

@@ -204,11 +204,35 @@ interface NotifyInput {
     channels?: NotifyChannel[];
     /** ชื่อ provider ฝั่ง hub ที่อยากให้ลองก่อน */
     prefer?: string;
+    /**
+     * (0.6.0) วินาที 60–86400 — ให้ hub รับผิดชอบส่งให้ถึงภายในเวลานี้: รายการที่ค้างหรือพลาดชั่วคราว (network/5xx/429)
+     * hub เก็บในคิวแล้วส่งซ้ำเองตาม backoff (ผลเป็น `status: "queued"` นับเป็น "รับไว้แล้ว") · ผิดถาวร (ผู้รับบล็อก ฯลฯ) ไม่ส่งซ้ำ
+     * เลยเวลาแล้วไม่ส่ง · ไม่สลับช่องทาง (ขอ telegram จะไม่ตกไปอีเมล) · ไม่ระบุ = พฤติกรรมเดิม (แอปส่งซ้ำเอง)
+     */
+    deliverWithin?: number;
+    /**
+     * (0.6.0) กันส่งซ้ำ — ส่งเป็นหัว `Idempotency-Key` (1–200 ตัวอักษร ต่อแอป) เรียกซ้ำด้วย key และเนื้อหาเดิม
+     * ได้ผลเดิมโดย hub ไม่ส่งอะไรอีก (เนื้อหาต่างแต่ key เดิม = MailError `invalid` 422) · จำไว้ 7 วัน
+     * ควรเป็นค่าที่ผูกกับเหตุการณ์ เช่น `pi-done:reminder:<userId>:<runId>`
+     */
+    idempotencyKey?: string;
+}
+/**
+ * (0.7.0) ส่งเข้า "topic" ของแอป — กลุ่ม/ห้อง LINE หรือกลุ่ม Telegram ที่ admin ผูกไว้ที่หน้า Topics ของ Pi Notify
+ * แอปไม่ต้องรู้ group id: เชิญ OA/bot เข้ากลุ่ม → hub เห็นกลุ่ม → admin ผูกกับ topic
+ */
+interface NotifyTopicInput extends Omit<NotifyInput, "to" | "channels" | "prefer"> {
+    /** ชื่อ topic ของแอปนี้ (a-z 0-9 . _ -) เช่น "po-overdue" — ไม่พบ = MailError invalid (404) */
+    topic: string;
+    /** ไม่ระบุ = ทุกปลายทางของ topic · ระบุ = เฉพาะแพลตฟอร์มนี้ */
+    channels?: ("line" | "telegram")[];
 }
 interface NotifyResultItem {
+    /** อีเมลผู้รับ หรือ "topic:<key>" เมื่อส่งด้วย notifyTopic() */
     to: string;
     channel: NotifyChannel;
-    status: "sent" | "failed" | "skipped";
+    /** `queued` (0.6.0) = hub รับไว้ส่งซ้ำเอง — เกิดเฉพาะเมื่อแอปส่ง `deliverWithin` */
+    status: "sent" | "failed" | "skipped" | "queued";
     provider?: string;
     id?: string;
     failedOver?: boolean;
@@ -216,10 +240,15 @@ interface NotifyResultItem {
     /**
      * app_daily_cap = แอปส่งอีเมลแทนแชทครบเพดานรายวันที่ตั้งใน Pi Notify แล้ว
      * no_push_provider = hub ยังไม่ได้ตั้ง provider web push
+     * no_target (0.7.0) = topic ถูกปิด หรือยังไม่มีกลุ่มที่ใช้ได้ผูกอยู่
      */
-    reason?: "no_link" | "channel_not_linked" | "no_chat_provider" | "no_push_provider" | "app_daily_cap";
+    reason?: "no_link" | "channel_not_linked" | "no_chat_provider" | "no_push_provider" | "app_daily_cap" | "no_target";
     /** (status failed) คำขอหมดงบเวลาก่อนได้เริ่มส่งรายการนี้ — ส่งซ้ำเฉพาะรายการนี้ได้ */
     deferred?: boolean;
+    /** (0.6.0) id ของรายการในคิวส่งซ้ำของ hub — มีเมื่อ status เป็น queued */
+    deliveryId?: string;
+    /** (0.7.0) notifyTopic(): ชื่อกลุ่ม/ปลายทางของรายการนี้ */
+    target?: string;
 }
 interface NotifyResult {
     results: NotifyResultItem[];
@@ -228,6 +257,8 @@ interface NotifyResult {
     skipped: number;
     /** จำนวนที่ยังไม่ได้ส่งเพราะหมดงบเวลา (นับซ้อนอยู่ใน failed; Pi Notify รุ่นเก่าไม่ส่งมา) */
     deferred?: number;
+    /** (0.6.0) จำนวนที่ hub รับไว้ส่งซ้ำเอง (ไม่นับใน failed) — Pi Notify รุ่นเก่าไม่ส่งมา */
+    queued?: number;
 }
 interface NotifyOptions {
     /** ค่าเริ่มต้น PI_NOTIFY_KEY */
@@ -279,16 +310,25 @@ interface RecipientInfo {
 /** มี PI_NOTIFY_KEY (ใน opts หรือ env) หรือไม่ — ให้ helper แบบ safe/later ใช้ตัดสินว่า "ปิดอยู่" */
 declare function hasNotifyKey(opts?: NotifyOptions): boolean;
 /**
- * แจ้งเตือนผู้รับผ่าน Pi Notify hub — Telegram (ที่ผู้รับผูกไว้) หรืออีเมล
+ * แจ้งเตือนผู้รับผ่าน Pi Notify hub — แชทที่ผู้รับผูกไว้ (Telegram / LINE / web push) หรืออีเมล
  * ใช้ env เดียวกับ sendMail(): PI_NOTIFY_KEY (+ PI_NOTIFY_URL)
  * โยน MailError เมื่อ hub ตอบ non-2xx (502 = ไม่มีช่องทางไหนส่งสำเร็จเลย; results อยู่ใน err.cause)
  */
 declare function notify(input: NotifyInput, opts?: NotifyOptions): Promise<NotifyResult>;
+/**
+ * (0.7.0) ส่งเข้า topic ของแอป — hub กระจายไปทุกกลุ่ม LINE/Telegram ที่ admin ผูกไว้ (ผลรายกลุ่มมี `target`)
+ * topic ไม่พบ → MailError invalid (404) · topic ปิด/ยังไม่ผูกกลุ่ม → ผล skipped reason "no_target" (ไม่โยน)
+ * ใช้ deliverWithin / idempotencyKey ได้เหมือน notify()
+ * @example await notifyTopic({ topic: "po-overdue", title: "PO เกินกำหนด 3 รายการ", body: "…", link });
+ */
+declare function notifyTopic(input: NotifyTopicInput, opts?: NotifyOptions): Promise<NotifyResult>;
 /** ช่องทางที่ผู้รับผูกไว้ — ไว้แสดง "ผูกแล้ว/ยังไม่ผูก" ในหน้าตั้งค่าของแอป */
 declare function getRecipient(email: Recipient, opts?: NotifyOptions): Promise<RecipientInfo>;
 /**
- * ขอลิงก์ผูก Telegram ให้ผู้รับ (t.me/<bot>?start=<code>, หมดอายุ 10 นาที)
- * แอปวางเป็นปุ่ม/QR ในหน้าตั้งค่าของตัวเอง แล้วโพล getRecipient() จนเห็น telegram
+ * ขอลิงก์ผูกแชทให้ผู้รับ (หมดอายุ 10 นาที) — แอปวางเป็นปุ่ม/QR ในหน้าตั้งค่าของตัวเอง แล้วโพล getRecipient() จนเห็นช่องทางโผล่
+ * - telegram: `t.me/<bot>?start=<code>` (ผู้ใช้กด Start)
+ * - line (0.7.0): `line.me/R/oaMessage/@<oa>/?ผูก Pi Notify <code>` — เปิดแชท OA พร้อมพิมพ์ข้อความไว้ ผู้ใช้กดส่ง
+ *   (ยังไม่เป็นเพื่อนกับ OA ต้องเพิ่มเพื่อนด้วยจึงจะรับ push ได้) · `code` ใช้แสดงให้พิมพ์ "ผูก Pi Notify <code>" เอง
  * `opts.piUserId` = user id ใน Pi Auth (sub) ของผู้ใช้ — ให้ Pi Notify ลบการผูกเมื่อบัญชีถูกลบ
  */
 declare function createLink(email: Recipient, channel?: Exclude<NotifyChannel, "email">, opts?: NotifyOptions & {
@@ -337,4 +377,5 @@ declare function listPushDevices(email: string, opts?: NotifyOptions): Promise<{
     devices: PushDevice[];
 }>;
 
-export { type Address as A, notify as B, type ChannelStatus as C, savePushSubscription as D, type ErrorKind as E, toEmails as F, type Message as M, type NotifyOptions as N, type ParsedAddress as P, type Quota as Q, type Recipient as R, type SendResult as S, type Provider as a, type ProviderStatus as b, type ProviderInfo as c, type Store as d, type MailerEvent as e, type Attempt as f, type PushDevice as g, type NotifyResultItem as h, type NotifyInput as i, type Attachment as j, NOTIFY_TIMEOUT_MS as k, type NormalizedMessage as l, type NotifyChannel as m, type NotifyResult as n, type PushSubscriptionJson as o, type QuotaUsage as p, type RecipientChannelInfo as q, type RecipientInfo as r, type SkipReason as s, createLink as t, deletePushSubscription as u, getChannelStatus as v, getPushConfig as w, getRecipient as x, hasNotifyKey as y, listPushDevices as z };
+export { listPushDevices as B, notify as D, notifyTopic as F, savePushSubscription as G, toEmails as H, NOTIFY_TIMEOUT_MS as l, createLink as u, deletePushSubscription as v, getChannelStatus as w, getPushConfig as x, getRecipient as y, hasNotifyKey as z };
+export type { Address as A, ChannelStatus as C, ErrorKind as E, Message as M, NotifyOptions as N, ParsedAddress as P, Quota as Q, Recipient as R, SendResult as S, Provider as a, ProviderStatus as b, ProviderInfo as c, Store as d, MailerEvent as e, Attempt as f, PushDevice as g, NotifyResultItem as h, NotifyInput as i, NotifyTopicInput as j, Attachment as k, NormalizedMessage as m, NotifyChannel as n, NotifyResult as o, PushSubscriptionJson as p, QuotaUsage as q, RecipientChannelInfo as r, RecipientInfo as s, SkipReason as t };

package/package.json

@@ -1,12 +1,9 @@
 {
   "name": "@suphark/notify",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "private": false,
   "type": "module",
   "description": "ส่งอีเมล + แจ้งเตือน Telegram ผ่าน Pi Notify hub (notify.suphark.com) หรือส่งอีเมลตรงไป Resend/SMTP/Zoho/ZeptoMail ใน API เดียว พร้อม failover อัตโนมัติ",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -39,7 +36,7 @@
     "prepack": "pnpm run build"
   },
   "dependencies": {
-    "nodemailer": "^10.0.14"
+    "nodemailer": "^10.2.1"
   },
   "peerDependencies": {
     "next": ">=15"
@@ -50,14 +47,14 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.15",
-    "@pi/config": "workspace:*",
+    "@biomejs/biome": "^2.6.2",
+    "@pi/tsconfig": "workspace:*",
     "@types/node": "^24.13.4",
     "@types/nodemailer": "^8.0.1",
-    "next": "^16.3.8",
-    "tsup": "^8.5.1",
+    "next": "^16.4.2",
+    "tsup": "^9.0.0",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.5"
   },
   "license": "MIT",
   "repository": {