@suphark/notify 0.6.0 → 0.9.0

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)
 
@@ -41,6 +41,65 @@ await listProviders();
 await sendMail({ to, subject, html, prefer: "company-smtp" });  // ลองตัวนี้ก่อน ไม่ได้ค่อย failover ตามลำดับปกติ
 ```
 
+### เทมเพลตอีเมล: `sendMail({ template, data })` (0.9.0)
+
+เก็บเทมเพลตไว้ที่ Pi Notify (แยกต่อแอป) — แก้ข้อความได้โดยไม่ต้อง deploy แอป และทุกแอปได้ layout เดียวกัน
+
+```ts
+import { saveTemplate, sendMail } from "@suphark/notify";
+
+// สร้าง/แก้จากแอป (หรือแก้ที่หน้า "เทมเพลตอีเมล" ในคอนโซลของ Pi Notify)
+await saveTemplate("po-approved", {
+  name: "แจ้ง PO อนุมัติ",
+  subject: "PO {{po.no}} อนุมัติแล้ว",
+  html: `<p>เรียน {{name}}</p>
+{{#each items}}<p>{{@number}}. {{name}} x{{qty}}</p>{{/each}}
+{{#if note}}<p>หมายเหตุ: {{note}}</p>{{/if}}`,
+  variables: [
+    { name: "po.no", label: "เลขที่ PO", sample: "PO-001", required: true },
+    { name: "items", sample: '[{"name":"ปากกา","qty":2}]' },
+  ],
+});
+
+// ส่ง — hub render หัวเรื่อง/HTML/ข้อความล้วนให้ (ใช้คู่ deliverWithin / idempotencyKey ได้)
+await sendMail({ to, template: "po-approved", data: { name, po: { no: "PO-9" }, items } });
+```
+
+- ไวยากรณ์: `{{name}}` `{{a.b}}` (HTML ถูก escape เสมอ) · `{{#if x}}…{{else}}…{{/if}}` · `{{#each items}}…{{/each}}` (ข้างในใช้ฟิลด์ของรายการตรง ๆ, `{{this}}`, `{{@index}}`, `{{@number}}`)
+- HTML ที่ไม่มี `<html>` จะถูกครอบด้วย layout มาตรฐาน (กว้าง 600px + "ส่งจาก <ชื่อแอป>") · ไม่ใส่ `text` = สร้างจาก HTML
+- ตัวแปร `required` ที่ไม่ได้ส่งมา → `MailError` invalid (422) ไม่ส่งอีเมล · ไม่พบเทมเพลต/ปิดอยู่ → 404
+- จัดการ: `listTemplates()` / `getTemplate(key)` / `saveTemplate(key, input)` / `deleteTemplate(key)` / `previewTemplate(key, { data })`
+- render เองฝั่งแอป (เช่นหน้าดูตัวอย่าง): `import { renderEmailTemplate } from "@suphark/notify/template"` — ตัวเดียวกับที่ hub ใช้ ไม่พึ่ง node
+- `template` ส่งได้เฉพาะผ่าน hub — provider ในเครื่องไม่ถูกใช้ (ไม่มีทางสำรองเมื่อ hub ล่ม) อีเมลสำคัญที่ต้องมีสำรองให้ render เองแล้วส่ง `html`
+
+### อีเมลที่ต้องถึงแน่: `deliverWithin` + `idempotencyKey` กับ `sendMail` (0.8.0)
+
+```ts
+import { getRequestStatus, sendMail } from "@suphark/notify";
+
+const key = `memo:${memo.id}:final-pdf`; // ผูกกับเหตุการณ์ ไม่สุ่มใหม่ทุกครั้ง
+const r = await sendMail({
+  to: approvers,
+  subject: `Memo ${memo.no} ฉบับสุดท้าย`,
+  html,
+  attachments: [{ filename: "memo.pdf", content: pdfBuffer }],
+  deliverWithin: 6 * 3600, // ส่งไม่สำเร็จชั่วคราว → hub เก็บเข้าคิวส่งซ้ำเองภายใน 6 ชม.
+  idempotencyKey: key,      // เรียกซ้ำ (cron/กดซ้ำ) ด้วยเนื้อหาเดิม = ได้ผลเดิม ไม่ส่งอีเมลซ้ำ
+});
+r.queued; // true = hub รับไว้ส่งซ้ำแล้ว (r.id = deliveryId) — แอปไม่ต้องมีคิวของตัวเอง
+
+// หน้าแอปแสดงสถานะ — ไม่ต้องส่งเนื้อหา/ไฟล์แนบซ้ำ
+const s = await getRequestStatus(key); // null = ไม่รู้จัก key (หรือเกิน 7 วัน)
+s?.status; // "queued" | "sent" | "failed" | "partial" | "processing"
+```
+
+- ใช้ได้เฉพาะเมื่อส่งผ่าน hub (`PI_NOTIFY_KEY`) — provider ในเครื่องไม่สนสองค่านี้
+- เข้าคิวเฉพาะความผิดพลาดชั่วคราว (เครือข่าย, 5xx, rate limit, provider ล้มทุกตัว) — ข้อความผิด/ที่อยู่ผิดโยน error ทันทีเหมือนเดิม
+- `queued` นับเป็นสำเร็จฝั่งแอป: mailer **ไม่** failover ไป provider สำรองในเครื่อง (กันอีเมลซ้ำ)
+- เนื้ออีเมลและไฟล์แนบเก็บใน hub เฉพาะระหว่างรอส่งซ้ำ ส่งได้/เลิกส่งแล้วลบทิ้ง เหลือแค่สถานะ
+- ขนาดคำขอทั้งหมด (รวมไฟล์แนบ base64) ต้องไม่เกิน ~4.5MB (เพดานของ Vercel) → ไฟล์แนบดิบรวมราว 3MB
+- `getRequestStatus(key)` ใช้กับ `notify()` / `notifyTopic()` ที่ส่ง `idempotencyKey` ได้ด้วย
+
 ### สำรองเผื่อ hub ล่ม (ไม่บังคับ)
 
 ใส่ provider local ต่อท้ายได้ — hub มาก่อนเสมอ ถ้า hub ตอบไม่ได้ SDK จะ failover ไปตัวถัดไปเอง:
@@ -94,6 +153,43 @@ 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
@@ -391,6 +487,18 @@ Pi Notify มี contract test (`apps/notify/src/test/contract/`) เก็บ b
 
 ## Changelog
 
+- 0.9.0 — **เทมเพลตอีเมลที่ hub** (เพิ่มอย่างเดียว; ต้องใช้ Pi Notify 2026-11-11+)
+  - `sendMail({ to, template, data })` — hub render เทมเพลตของแอป (`subject` ไม่บังคับเมื่อใช้ template)
+  - `listTemplates` / `getTemplate` / `saveTemplate` / `deleteTemplate` / `previewTemplate` — จัดการเทมเพลตจากแอป
+  - `@suphark/notify/template`: `renderEmailTemplate`, `renderTemplate`, `sampleData`, `templateVariableNames`, `TemplateError`
+- 0.8.0 — **อีเมลส่งซ้ำผ่าน hub + ถามสถานะ** (เพิ่มอย่างเดียว; ต้องใช้ Pi Notify 2026-11-11+)
+  - `sendMail({ …, deliverWithin, idempotencyKey })` — hub เก็บเข้าคิวส่งซ้ำเมื่อล้มชั่วคราว (`SendResult.queued`) และกันส่งซ้ำด้วย key
+  - `getRequestStatus(key)` — สถานะล่าสุดของคำขอ sendMail / notify / notifyTopic ที่ส่ง key (`GET /api/v1/requests/:key`)
+- 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)

package/dist/{chunk-AQWFHD5T.js → chunk-AAB6GK3Z.js}

@@ -483,17 +483,24 @@ function createHubProvider(opts) {
         cc: msg.cc.length ? msg.cc : void 0,
         bcc: msg.bcc.length ? msg.bcc : void 0,
         replyTo: msg.replyTo.length ? msg.replyTo : void 0,
-        subject: msg.subject,
+        subject: msg.subject || (msg.template ? void 0 : msg.subject),
         html: msg.html,
         text: msg.text,
         attachments: msg.attachments.length ? msg.attachments : void 0,
         headers: Object.keys(msg.headers).length ? msg.headers : void 0,
         tags: Object.keys(msg.tags).length ? msg.tags : void 0,
-        prefer: msg.prefer
+        prefer: msg.prefer,
+        deliverWithin: msg.deliverWithin,
+        template: msg.template,
+        data: msg.template ? msg.data ?? {} : void 0
       };
       const res = await doFetch(url, {
         method: "POST",
-        headers: { Authorization: `Bearer ${opts.apiKey}`, "Content-Type": "application/json" },
+        headers: {
+          Authorization: `Bearer ${opts.apiKey}`,
+          "Content-Type": "application/json",
+          ...msg.idempotencyKey ? { "Idempotency-Key": msg.idempotencyKey } : {}
+        },
         body: JSON.stringify(body),
         // mailer หมดเวลา → abort คำขอนี้ทิ้ง (Pi Notify อาจส่งไปแล้ว — แอปที่มีตัวสำรองในเครื่องอาจได้เมลซ้ำ ยอมรับได้)
         signal: msg.signal
@@ -510,7 +517,9 @@ function createHubProvider(opts) {
           retryAfterSec: retryAfterOf(res, data)
         });
       }
-      return { id: data.id };
+      const ok = data;
+      if (ok.status === "queued") return { id: ok.deliveryId, queued: true };
+      return { id: ok.id };
     },
     async listProviders() {
       const res = await doFetch(url.replace(/\/send$/, "/providers"), {
@@ -851,7 +860,7 @@ function createMailer(options = {}) {
         cc: parseAddressList(m.cc),
         bcc: parseAddressList(m.bcc),
         replyTo: parseAddressList(m.replyTo),
-        subject: m.subject,
+        subject: m.subject ?? "",
         html: m.html,
         text: m.text,
         attachments: (m.attachments ?? []).map((a) => ({
@@ -861,7 +870,11 @@ function createMailer(options = {}) {
         })),
         headers: m.headers ?? {},
         tags: m.tags ?? {},
-        prefer: m.prefer
+        prefer: m.prefer,
+        deliverWithin: m.deliverWithin,
+        idempotencyKey: m.idempotencyKey,
+        template: m.template,
+        data: m.data
       };
     } catch (err) {
       throw new MailError(err.message, { kind: "invalid", cause: err });
@@ -902,10 +915,20 @@ function createMailer(options = {}) {
   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" });
-    if (!message.subject) throw new MailError("Message has no subject", { kind: "invalid" });
-    if (message.html === void 0 && message.text === void 0)
-      throw new MailError("Message needs html or text", { kind: "invalid" });
+    if (!message.template) {
+      if (!message.subject) throw new MailError("Message has no subject", { kind: "invalid" });
+      if (message.html === void 0 && message.text === void 0)
+        throw new MailError("Message needs html or text", { kind: "invalid" });
+    }
     let candidates = order();
+    if (message.template) {
+      candidates = candidates.filter((e) => e.provider.type === "hub");
+      if (candidates.length === 0)
+        throw new MailError(
+          `template "${message.template}" \u0E15\u0E49\u0E2D\u0E07\u0E2A\u0E48\u0E07\u0E1C\u0E48\u0E32\u0E19 Pi Notify hub \u2014 \u0E15\u0E31\u0E49\u0E07 PI_NOTIFY_KEY`,
+          { kind: "invalid" }
+        );
+    }
     if (message.prefer) {
       const i = candidates.findIndex((e) => e.provider.name === message.prefer);
       if (i > 0) candidates = [candidates[i], ...candidates.filter((_, j) => j !== i)];
@@ -922,8 +945,9 @@ function createMailer(options = {}) {
       const p = entry.provider;
       const started = Date.now();
       let id;
+      let queued;
       try {
-        ({ id } = await withTimeout(
+        ({ id, queued } = await withTimeout(
           (signal) => {
             const normalized = {
               ...base,
@@ -953,7 +977,7 @@ function createMailer(options = {}) {
       });
       const failedOver = opts.failedOver();
       emit({ type: "sent", provider: p.name, id, ms, failedOver });
-      return { id, provider: p.name, failedOver, attempts };
+      return { id, provider: p.name, failedOver, attempts, ...queued ? { queued: true } : {} };
     };
     for (const entry of candidates) {
       const p = entry.provider;
@@ -1128,16 +1152,35 @@ async function hubRequest(opts, path, init) {
   }
   return data;
 }
-async function notify(input, opts = {}) {
-  const { idempotencyKey, ...body } = input;
+async function postNotify(body, idempotencyKey, opts) {
   const data = await hubRequest(opts, "/api/v1/notify", {
     method: "POST",
-    body: { ...body, 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 getRequestStatus(idempotencyKey, opts = {}) {
+  try {
+    return await hubRequest(
+      opts,
+      `/api/v1/requests/${encodeURIComponent(idempotencyKey)}`,
+      { timeoutMs: NOTIFY_TIMEOUT_MS.recipient }
+    );
+  } catch (err) {
+    if (err instanceof MailError && err.status === 404) return null;
+    throw err;
+  }
+}
 async function getRecipient(email, opts = {}) {
   return hubRequest(
     opts,
@@ -1216,13 +1259,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;
@@ -1279,7 +1328,10 @@ export {
   toEmails,
   NOTIFY_TIMEOUT_MS,
   hasNotifyKey,
+  hubRequest,
   notify,
+  notifyTopic,
+  getRequestStatus,
   getRecipient,
   createLink,
   getChannelStatus,
@@ -1289,5 +1341,6 @@ export {
   listPushDevices,
   resetSafeWarnings,
   notifySafe,
+  notifyTopicSafe,
   sendMailSafe
 };

package/dist/chunk-XVD6P4HN.js

@@ -0,0 +1,193 @@
+// 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;
+function looksLikeHtml(s) {
+  return KNOWN_TAG_RE.test(s);
+}
+function resolveFormat(body, format) {
+  if (format === "text" || format === "html") return format;
+  return looksLikeHtml(body) ? "html" : "text";
+}
+function toPlainText(html) {
+  return html.replace(/<br\s*\/?>/gi, "\n").replace(/<[^>]+>/g, "").replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", '"').replaceAll("&amp;", "&").trim();
+}
+
+// src/template.ts
+var TemplateError = class extends Error {
+  constructor(message, missing = []) {
+    super(message);
+    this.missing = missing;
+    this.name = "TemplateError";
+  }
+  missing;
+};
+var TAG = /\{\{\s*([#/]?)\s*(?:(if|each|else)(?![\w฀-๿.-]))?\s*([^}]*?)\s*\}\}/g;
+var PATH = /^(@?[A-Za-z_฀-๿][\w฀-๿-]*|this)(\.[\w฀-๿-]+)*$/;
+function parseTemplate(source) {
+  const root = [];
+  const stack = [];
+  const target = () => {
+    const top = stack.at(-1);
+    if (!top) return root;
+    if (top.node.t === "each") return top.node.body;
+    return top.inElse ? top.node.no : top.node.yes;
+  };
+  let last = 0;
+  for (const m of source.matchAll(TAG)) {
+    const [raw, sigil, keyword, rest] = m;
+    const at = m.index ?? 0;
+    if (at > last) target().push({ t: "text", v: source.slice(last, at) });
+    last = at + raw.length;
+    const path = (rest ?? "").trim();
+    if (sigil === "#") {
+      if (keyword !== "if" && keyword !== "each")
+        throw new TemplateError(`\u0E44\u0E21\u0E48\u0E23\u0E39\u0E49\u0E08\u0E31\u0E01 {{#${keyword ?? path}}} \u0E17\u0E35\u0E48\u0E15\u0E33\u0E41\u0E2B\u0E19\u0E48\u0E07 ${at}`);
+      if (!PATH.test(path))
+        throw new TemplateError(`{{#${keyword}}} \u0E15\u0E49\u0E2D\u0E07\u0E15\u0E32\u0E21\u0E14\u0E49\u0E27\u0E22\u0E0A\u0E37\u0E48\u0E2D\u0E15\u0E31\u0E27\u0E41\u0E1B\u0E23 (\u0E15\u0E33\u0E41\u0E2B\u0E19\u0E48\u0E07 ${at})`);
+      const node = keyword === "if" ? { t: "if", path, yes: [], no: [] } : { t: "each", path, body: [] };
+      target().push(node);
+      stack.push({ node, inElse: false });
+    } else if (sigil === "/") {
+      const top = stack.pop();
+      if (!top || top.node.t !== keyword)
+        throw new TemplateError(`{{/${keyword ?? path}}} \u0E44\u0E21\u0E48\u0E21\u0E35\u0E41\u0E17\u0E47\u0E01\u0E40\u0E1B\u0E34\u0E14\u0E17\u0E35\u0E48\u0E15\u0E23\u0E07\u0E01\u0E31\u0E19 (\u0E15\u0E33\u0E41\u0E2B\u0E19\u0E48\u0E07 ${at})`);
+    } else if (keyword === "else" && !path) {
+      const top = stack.at(-1);
+      if (!top || top.node.t !== "if" || top.inElse)
+        throw new TemplateError(`{{else}} \u0E15\u0E49\u0E2D\u0E07\u0E2D\u0E22\u0E39\u0E48\u0E43\u0E19 {{#if}} (\u0E15\u0E33\u0E41\u0E2B\u0E19\u0E48\u0E07 ${at})`);
+      top.inElse = true;
+    } else {
+      const name = `${keyword ?? ""}${keyword && path ? " " : ""}${path}`.trim();
+      if (!PATH.test(name)) throw new TemplateError(`\u0E0A\u0E37\u0E48\u0E2D\u0E15\u0E31\u0E27\u0E41\u0E1B\u0E23 "{{${name}}}" \u0E44\u0E21\u0E48\u0E16\u0E39\u0E01\u0E15\u0E49\u0E2D\u0E07 (\u0E15\u0E33\u0E41\u0E2B\u0E19\u0E48\u0E07 ${at})`);
+      target().push({ t: "var", path: name });
+    }
+  }
+  if (last < source.length) target().push({ t: "text", v: source.slice(last) });
+  const open = stack.at(-1);
+  if (open) throw new TemplateError(`{{#${open.node.t} ${open.node.path}}} \u0E44\u0E21\u0E48\u0E44\u0E14\u0E49\u0E1B\u0E34\u0E14`);
+  return root;
+}
+function escapeHtml(s) {
+  return s.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+}
+function lookup(scopes, path) {
+  const parts = path.split(".");
+  const head = parts[0];
+  for (let i = scopes.length - 1; i >= 0; i--) {
+    const scope = scopes[i];
+    let value;
+    if (head === "this") value = scope;
+    else if (scope && typeof scope === "object" && head in scope)
+      value = scope[head];
+    else continue;
+    for (const p of parts.slice(1)) {
+      if (value && typeof value === "object" && p in value) value = value[p];
+      else return void 0;
+    }
+    return value;
+  }
+  return void 0;
+}
+function truthy(v) {
+  if (Array.isArray(v)) return v.length > 0;
+  return v !== void 0 && v !== null && v !== false && v !== "" && v !== 0;
+}
+function stringify(v) {
+  if (v === void 0 || v === null) return "";
+  if (v instanceof Date) return v.toISOString();
+  if (typeof v === "object") return JSON.stringify(v);
+  return String(v);
+}
+function renderNodes(nodes, scopes, esc, used) {
+  let out = "";
+  for (const n of nodes) {
+    if (n.t === "text") out += n.v;
+    else if (n.t === "var") {
+      used.add(n.path);
+      const s = stringify(lookup(scopes, n.path));
+      out += esc ? escapeHtml(s) : s;
+    } else if (n.t === "if") {
+      used.add(n.path);
+      out += renderNodes(truthy(lookup(scopes, n.path)) ? n.yes : n.no, scopes, esc, used);
+    } else {
+      used.add(n.path);
+      const list = lookup(scopes, n.path);
+      if (!Array.isArray(list)) continue;
+      list.forEach((item, i) => {
+        out += renderNodes(n.body, [...scopes, { "@index": i, "@number": i + 1 }, item], esc, used);
+      });
+    }
+  }
+  return out;
+}
+function renderTemplate(source, data, opts) {
+  return renderNodes(parseTemplate(source), [data], opts.escape, /* @__PURE__ */ new Set());
+}
+function templateVariableNames(...sources) {
+  const names = /* @__PURE__ */ new Set();
+  const walk = (nodes) => {
+    for (const n of nodes) {
+      if (n.t === "text") continue;
+      if (!n.path.startsWith("@") && n.path !== "this") names.add(n.path);
+      if (n.t === "if") {
+        walk(n.yes);
+        walk(n.no);
+      }
+    }
+  };
+  for (const s of sources) walk(parseTemplate(s));
+  return [...names];
+}
+function sampleData(variables) {
+  const out = {};
+  for (const v of variables ?? []) {
+    if (v.sample === void 0) continue;
+    const parts = v.name.split(".");
+    let cur = out;
+    parts.slice(0, -1).forEach((p) => {
+      if (!cur[p] || typeof cur[p] !== "object") cur[p] = {};
+      cur = cur[p];
+    });
+    let sample = v.sample;
+    if (/^\s*[[{]/.test(v.sample)) {
+      try {
+        sample = JSON.parse(v.sample);
+      } catch {
+      }
+    }
+    cur[parts.at(-1)] = sample;
+  }
+  return out;
+}
+function wrapEmailLayout(body, opts = {}) {
+  const footer = opts.appName ? `<p style="margin:24px 0 0;font-size:12px;color:#64748b">\u0E2A\u0E48\u0E07\u0E08\u0E32\u0E01 ${escapeHtml(opts.appName)}</p>` : "";
+  return `<!doctype html>
+<html lang="th"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">${opts.title ? `<title>${escapeHtml(opts.title)}</title>` : ""}</head>
+<body style="margin:0;padding:24px 12px;background:#f8fafc">
+<div style="max-width:600px;margin:0 auto;background:#ffffff;border:1px solid #e2e8f0;border-radius:12px;padding:24px;font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:15px;line-height:1.6;color:#0f172a">
+${body}
+${footer}
+</div>
+</body></html>`;
+}
+function renderEmailTemplate(t, data, opts = {}) {
+  const missing = (t.variables ?? []).filter((v) => v.required && !truthy(lookup([data], v.name)) && lookup([data], v.name) !== 0).map((v) => v.name);
+  if (missing.length) throw new TemplateError(`\u0E02\u0E49\u0E2D\u0E21\u0E39\u0E25\u0E44\u0E21\u0E48\u0E04\u0E23\u0E1A: ${missing.join(", ")}`, missing);
+  const subject = renderTemplate(t.subject, data, { escape: false }).replace(/\s+/g, " ").trim();
+  const body = renderTemplate(t.html, data, { escape: true });
+  const html = /<html[\s>]/i.test(body) ? body : wrapEmailLayout(body, { ...opts, title: subject });
+  const text = t.text?.trim() ? renderTemplate(t.text, data, { escape: false }) : toPlainText(body);
+  return { subject, html, text };
+}
+
+export {
+  looksLikeHtml,
+  resolveFormat,
+  toPlainText,
+  TemplateError,
+  parseTemplate,
+  renderTemplate,
+  templateVariableNames,
+  sampleData,
+  wrapEmailLayout,
+  renderEmailTemplate
+};

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-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-BM6FBQVP.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-BM6FBQVP.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-Dgzxhh-U.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 RequestStatus, u as SkipReason, v as createLink, w as deletePushSubscription, x as getChannelStatus, y as getPushConfig, z as getRecipient, B as getRequestStatus, D as hasNotifyKey, F as listPushDevices, G as notify, H as notifyTopic, I as savePushSubscription, J as toEmails } from './notify-Dgzxhh-U.js';
+import { TemplateVariable } from './template.js';
+export { TemplateError, renderEmailTemplate } from './template.js';
 
 /** แปลง "ชื่อ <a@b.com>" / "a@b.com" / { name, email } → { name, email } */
 declare function parseAddress(input: Address): ParsedAddress;
@@ -39,7 +41,8 @@ interface HubSendRequest {
     cc?: ParsedAddress[];
     bcc?: ParsedAddress[];
     replyTo?: ParsedAddress[];
-    subject: string;
+    /** ไม่ส่งเมื่อใช้ template */
+    subject?: string;
     html?: string;
     text?: string;
     attachments?: {
@@ -51,11 +54,19 @@ interface HubSendRequest {
     tags?: Record<string, string>;
     /** ชื่อ provider ที่อยากให้ hub ลองก่อน */
     prefer?: string;
+    /** (0.8.0) วินาที — ล้มชั่วคราวแล้วให้ hub ส่งซ้ำเอง */
+    deliverWithin?: number;
+    /** (0.9.0) เทมเพลตของแอป — hub render subject/html/text จาก data */
+    template?: string;
+    data?: Record<string, unknown>;
 }
 interface HubSendResponse {
     id?: string;
     provider: string;
     failedOver: boolean;
+    /** (0.8.0) "queued" = hub รับไว้ส่งซ้ำเอง (HTTP 202) */
+    status?: "sent" | "queued";
+    deliveryId?: string;
 }
 /** error body ของ hub: { error: { kind, message, attempts?, retryAfterSec? } } */
 interface HubErrorResponse {
@@ -420,6 +431,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;
@@ -455,4 +468,52 @@ 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 };
+/** (0.9.0) เทมเพลตอีเมลของแอปที่เก็บใน Pi Notify */
+interface EmailTemplateInfo {
+    key: string;
+    name: string;
+    subject: string;
+    html: string;
+    text: string | null;
+    variables: TemplateVariable[];
+    enabled: boolean;
+    version: number;
+    updatedAt: string;
+}
+interface EmailTemplateInput {
+    name: string;
+    /** ใส่ {{ตัวแปร}} ได้ */
+    subject: string;
+    /** {{ตัวแปร}} ถูก escape เสมอ · {{#if}} / {{#each}} ได้ · ไม่มี <html> = hub ครอบ layout มาตรฐานให้ */
+    html: string;
+    /** ว่าง = สร้างจาก HTML */
+    text?: string | null;
+    variables?: TemplateVariable[];
+    enabled?: boolean;
+}
+/** (0.9.0) เทมเพลตทั้งหมดของแอป */
+declare function listTemplates(opts?: NotifyOptions): Promise<EmailTemplateInfo[]>;
+/** (0.9.0) เทมเพลตหนึ่งตัว — ไม่มี = null */
+declare function getTemplate(key: string, opts?: NotifyOptions): Promise<EmailTemplateInfo | null>;
+/**
+ * (0.9.0) สร้าง/แก้เทมเพลต (upsert ตาม key) — hub ตรวจไวยากรณ์ก่อนบันทึก (ผิด = MailError invalid 422)
+ * @example await saveTemplate("po-approved", { name: "PO อนุมัติ", subject: "PO {{po}} อนุมัติแล้ว", html })
+ */
+declare function saveTemplate(key: string, input: EmailTemplateInput, opts?: NotifyOptions): Promise<EmailTemplateInfo>;
+/** (0.9.0) ลบเทมเพลต — คืน false เมื่อไม่มีอยู่แล้ว */
+declare function deleteTemplate(key: string, opts?: NotifyOptions): Promise<boolean>;
+/**
+ * (0.9.0) ดูตัวอย่างอีเมลที่ render แล้ว (ไม่ส่ง) — ไม่ส่ง data = ใช้ค่าตัวอย่าง (`variables[].sample`)
+ * ส่ง `template` = ลองเนื้อหาที่ยังไม่บันทึก
+ */
+declare function previewTemplate(key: string, input?: {
+    data?: Record<string, unknown>;
+    template?: EmailTemplateInput;
+}, opts?: NotifyOptions): Promise<{
+    subject: string;
+    html: string;
+    text: string;
+}>;
+
+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, TemplateVariable, classifyError, configureMailer, createConsoleProvider, createHubProvider, createMailer, createMemoryStore, createPresetSmtpProvider, createPushHandlers, createRedisStore, createResendProvider, createSmtpProvider, createZeptoMailProvider, deleteTemplate, formatAddress, getMailer, getTemplate, listProviders, listTemplates, looksLikeHtml, notifySafe, notifyTopicSafe, parseAddress, parseAddressList, previewTemplate, providersFromEnv, pushServiceWorker, pushServiceWorkerSource, renderNotifyEmail, requireFrom, resetMailer, resetSafeWarnings, resolveFormat, saveTemplate, sendMail, sendMailSafe, toPlainText };
+export type { BodyFormat, BrowserPushSubscription, ConsoleOptions, EmailTemplateInfo, EmailTemplateInput, Env, HubErrorResponse, HubOptions, HubSendRequest, HubSendResponse, Mailer, MailerOptions, NotifyEmailInput, NotifySafeResult, ProviderConfig, PushHandlers, PushHandlersOptions, PushServiceWorkerOptions, PushUser, RedisLike, ResendOptions, SendMailSafeResult, SmtpOptions, SmtpPreset, ZeptoMailOptions };

package/dist/index.js

@@ -22,11 +22,15 @@ import {
   getMailer,
   getPushConfig,
   getRecipient,
+  getRequestStatus,
   hasNotifyKey,
+  hubRequest,
   listProviders,
   listPushDevices,
   notify,
   notifySafe,
+  notifyTopic,
+  notifyTopicSafe,
   parseAddress,
   parseAddressList,
   providersFromEnv,
@@ -37,20 +41,14 @@ import {
   sendMail,
   sendMailSafe,
   toEmails
-} from "./chunk-AQWFHD5T.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;
-function looksLikeHtml(s) {
-  return KNOWN_TAG_RE.test(s);
-}
-function resolveFormat(body, format) {
-  if (format === "text" || format === "html") return format;
-  return looksLikeHtml(body) ? "html" : "text";
-}
-function toPlainText(html) {
-  return html.replace(/<br\s*\/?>/gi, "\n").replace(/<[^>]+>/g, "").replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", '"').replaceAll("&amp;", "&").trim();
-}
+} from "./chunk-AAB6GK3Z.js";
+import {
+  TemplateError,
+  looksLikeHtml,
+  renderEmailTemplate,
+  resolveFormat,
+  toPlainText
+} from "./chunk-XVD6P4HN.js";
 
 // src/push.ts
 function createPushHandlers(options) {
@@ -187,6 +185,46 @@ function createRedisStore(client, opts = {}) {
     }
   };
 }
+
+// src/templates-api.ts
+var path = (key) => `/api/v1/templates/${encodeURIComponent(key)}`;
+async function listTemplates(opts = {}) {
+  const data = await hubRequest(opts, "/api/v1/templates", {
+    timeoutMs: NOTIFY_TIMEOUT_MS.recipient
+  });
+  return data.templates;
+}
+async function getTemplate(key, opts = {}) {
+  try {
+    return await hubRequest(opts, path(key), {
+      timeoutMs: NOTIFY_TIMEOUT_MS.recipient
+    });
+  } catch (err) {
+    if (err instanceof MailError && err.status === 404) return null;
+    throw err;
+  }
+}
+async function saveTemplate(key, input, opts = {}) {
+  return hubRequest(opts, path(key), {
+    method: "PUT",
+    body: input,
+    timeoutMs: NOTIFY_TIMEOUT_MS.recipient
+  });
+}
+async function deleteTemplate(key, opts = {}) {
+  const data = await hubRequest(opts, path(key), {
+    method: "DELETE",
+    timeoutMs: NOTIFY_TIMEOUT_MS.recipient
+  });
+  return data.deleted;
+}
+async function previewTemplate(key, input = {}, opts = {}) {
+  return hubRequest(opts, `${path(key)}/preview`, {
+    method: "POST",
+    body: input,
+    timeoutMs: NOTIFY_TIMEOUT_MS.recipient
+  });
+}
 export {
   AllProvidersFailedError,
   DEFAULT_COOLDOWN,
@@ -194,6 +232,7 @@ export {
   MailError,
   NOTIFY_TIMEOUT_MS,
   SMTP_PRESETS,
+  TemplateError,
   classifyError,
   configureMailer,
   createConsoleProvider,
@@ -208,28 +247,37 @@ export {
   createSmtpProvider,
   createZeptoMailProvider,
   deletePushSubscription,
+  deleteTemplate,
   formatAddress,
   getChannelStatus,
   getMailer,
   getPushConfig,
   getRecipient,
+  getRequestStatus,
+  getTemplate,
   hasNotifyKey,
   listProviders,
   listPushDevices,
+  listTemplates,
   looksLikeHtml,
   notify,
   notifySafe,
+  notifyTopic,
+  notifyTopicSafe,
   parseAddress,
   parseAddressList,
+  previewTemplate,
   providersFromEnv,
   pushServiceWorker,
   pushServiceWorkerSource,
+  renderEmailTemplate,
   renderNotifyEmail,
   requireFrom,
   resetMailer,
   resetSafeWarnings,
   resolveFormat,
   savePushSubscription,
+  saveTemplate,
   sendMail,
   sendMailSafe,
   toEmails,

package/dist/next.d.ts

@@ -1,4 +1,4 @@
-import { N as NotifyOptions, i as NotifyInput, M as Message } from './notify-BM6FBQVP.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-AQWFHD5T.js";
+} from "./chunk-AAB6GK3Z.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-BM6FBQVP.d.ts → notify-Dgzxhh-U.d.ts}

@@ -13,7 +13,8 @@ interface Attachment {
 /** ข้อความที่แอปส่งเข้ามา (ไม่ผูกกับ provider ใด ๆ) */
 interface Message {
     to: Address | Address[];
-    subject: string;
+    /** ไม่ต้องใส่เมื่อใช้ `template` (หัวเรื่องมาจากเทมเพลต) */
+    subject?: string;
     html?: string;
     text?: string;
     /** override from ของ provider/ค่าเริ่มต้น */
@@ -29,6 +30,23 @@ interface Message {
     provider?: string;
     /** อยากให้ลองตัวนี้ก่อน (ยัง failover ตามปกติถ้าไม่ได้) — ส่งต่อไป hub ด้วย */
     prefer?: string;
+    /**
+     * (0.8.0, hub เท่านั้น) วินาที 60–86400 — ส่งไม่สำเร็จชั่วคราวแล้วให้ Pi Notify เก็บเข้าคิวส่งซ้ำเองภายในเวลานี้
+     * ผล `queued: true` (`id` = deliveryId) · provider ในเครื่อง (SMTP/Resend ตรง) ไม่สนค่านี้
+     */
+    deliverWithin?: number;
+    /**
+     * (0.8.0, hub เท่านั้น) กันส่งซ้ำ: เรียกซ้ำด้วย key + เนื้อหาเดิมได้ผลเดิม ไม่ส่งอีเมลซ้ำ (1–200 ตัวอักษร)
+     * ดูสถานะล่าสุดด้วย `getRequestStatus(key)`
+     */
+    idempotencyKey?: string;
+    /**
+     * (0.9.0, hub เท่านั้น) ชื่อเทมเพลตอีเมลของแอปใน Pi Notify — hub render หัวเรื่อง/HTML/ข้อความจาก `data`
+     * ไม่ต้องใส่ subject/html/text · ส่งผ่าน provider ในเครื่องไม่ได้ (mailer ใช้เฉพาะ hub)
+     */
+    template?: string;
+    /** ค่าตัวแปรของเทมเพลต (`{{name}}`, `{{#each items}}` …) */
+    data?: Record<string, unknown>;
 }
 /** ข้อมูลตัวเลือกที่แอปควรรู้ — แค่ชื่อ/ประเภท/พร้อมใช้ไหม */
 interface ProviderInfo {
@@ -61,6 +79,12 @@ interface NormalizedMessage {
     headers: Record<string, string>;
     tags: Record<string, string>;
     prefer?: string;
+    /** (0.8.0) ส่งต่อไป hub — provider อื่นไม่ใช้ */
+    deliverWithin?: number;
+    idempotencyKey?: string;
+    /** (0.9.0) ส่งต่อไป hub — hub render เทมเพลตเอง */
+    template?: string;
+    data?: Record<string, unknown>;
     /**
      * ยกเลิกเมื่อ mailer หมดเวลา (timeoutMs) — provider ที่ใช้ fetch ควรส่งต่อเข้า fetch
      * เพื่อไม่ให้คำขอค้างต่อหลัง mailer ไป failover แล้ว (ไม่ส่งมา = provider เขียนเองรุ่นเก่า ใช้ได้ตามเดิม)
@@ -87,6 +111,8 @@ interface SendResult {
     /** true ถ้าตัวแรกที่ควรใช้ล้ม/ถูกข้าม แล้วไปสำเร็จที่ตัวสำรอง */
     failedOver: boolean;
     attempts: Attempt[];
+    /** (0.8.0) hub รับไว้ส่งซ้ำเอง (ส่ง deliverWithin) — ยังไม่ถึงผู้รับ, `id` = deliveryId ในคิวของ hub */
+    queued?: boolean;
 }
 interface Quota {
     perHour?: number;
@@ -103,6 +129,7 @@ interface Provider {
     readonly optionalFrom?: boolean;
     send(msg: NormalizedMessage): Promise<{
         id?: string;
+        queued?: boolean;
     }>;
     /** ทดสอบการเชื่อมต่อ/credential (ไม่ส่งอีเมล) */
     verify?(): Promise<void>;
@@ -217,7 +244,18 @@ interface NotifyInput {
      */
     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;
     /** `queued` (0.6.0) = hub รับไว้ส่งซ้ำเอง — เกิดเฉพาะเมื่อแอปส่ง `deliverWithin` */
@@ -229,12 +267,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[];
@@ -296,16 +337,51 @@ 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>;
+/** (0.8.0) สถานะล่าสุดของคำขอที่ส่ง Idempotency-Key (ทั้ง sendMail และ notify/notifyTopic) */
+interface RequestStatus {
+    key: string;
+    /** mail = sendMail, notify = notify()/notifyTopic() */
+    type: "mail" | "notify";
+    /** processing = ยังตอบคำขอแรกไม่เสร็จ · queued = ยังมีรายการรอส่งซ้ำ · partial = สำเร็จบางรายการ */
+    status: "processing" | "queued" | "sent" | "failed" | "partial";
+    /** รายการต่อผู้รับ/ช่องทาง — รายการที่เคย queued แสดงสถานะล่าสุดจริง (sent/failed/queued) */
+    results: NotifyResultItem[];
+    summary: {
+        sent: number;
+        failed: number;
+        skipped: number;
+        queued?: number;
+        deferred?: number;
+    };
+    createdAt: string;
+    /** เส้นตายการส่ง (createdAt + deliverWithin) */
+    expiresAt: string;
+}
+/**
+ * (0.8.0) ถามสถานะล่าสุดของคำขอจาก Idempotency-Key — ไว้แสดง "ส่งแล้ว/รอส่งซ้ำ/ส่งไม่สำเร็จ" ในหน้าแอป
+ * โดยไม่ต้องยิงคำขอเดิม (ไฟล์แนบ) ซ้ำ · ไม่รู้จัก key (หรือเกิน 7 วัน hub ลบแล้ว) → `null`
+ * @example const s = await getRequestStatus(`memo-${memo.id}-final`); s?.status === "sent"
+ */
+declare function getRequestStatus(idempotencyKey: string, opts?: NotifyOptions): Promise<RequestStatus | null>;
 /** ช่องทางที่ผู้รับผูกไว้ — ไว้แสดง "ผูกแล้ว/ยังไม่ผูก" ในหน้าตั้งค่าของแอป */
 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 & {
@@ -354,4 +430,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 { getRequestStatus as B, hasNotifyKey as D, listPushDevices as F, notify as G, notifyTopic as H, savePushSubscription as I, toEmails as J, NOTIFY_TIMEOUT_MS as l, createLink as v, deletePushSubscription as w, getChannelStatus as x, getPushConfig as y, getRecipient 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, RequestStatus as t, SkipReason as u };

package/dist/template.d.ts

@@ -0,0 +1,79 @@
+/**
+ * (0.9.0) ตัว render เทมเพลตอีเมล — ตัวเดียวกับที่ Pi Notify hub ใช้ (import จาก "@suphark/notify/template"
+ * ได้ทั้งฝั่ง server และ browser เพราะไม่พึ่ง node) ไวยากรณ์แบบ Mustache อย่างย่อ ไม่มีโค้ดรันได้:
+ *
+ *   {{name}}  {{po.no}}                 แทนค่า (HTML ถูก escape เสมอ — ใส่ HTML ดิบจากข้อมูลไม่ได้โดยตั้งใจ)
+ *   {{#if note}}…{{else}}…{{/if}}       แสดงเมื่อมีค่า (สตริงว่าง/0/false/null/array ว่าง = ไม่มี)
+ *   {{#each items}}{{name}} {{@number}}{{/each}}   วนรายการ — ข้างในอ้างฟิลด์ของรายการตรง ๆ หรือ {{this}}
+ *                                       {{@index}} เริ่ม 0, {{@number}} เริ่ม 1; ชื่อที่ไม่มีในรายการหาจากข้อมูลชั้นนอก
+ */
+interface TemplateVariable {
+    /** ชื่อตัวแปร (path แบบ a.b ได้) */
+    name: string;
+    /** คำอธิบายสำหรับคนแก้เทมเพลต */
+    label?: string;
+    /** ค่าตัวอย่างตอนดูตัวอย่าง */
+    sample?: string;
+    /** true = ส่งมาไม่ครบ → TemplateError (ไม่ส่งอีเมลที่ข้อมูลหาย) */
+    required?: boolean;
+}
+interface EmailTemplateSource {
+    subject: string;
+    html: string;
+    /** ว่าง = สร้างจาก HTML ที่ render แล้ว */
+    text?: string | null;
+    variables?: TemplateVariable[] | null;
+}
+declare class TemplateError extends Error {
+    /** ตัวแปรที่จำเป็นแต่ไม่ได้ส่งมา */
+    readonly missing: string[];
+    constructor(message: string, 
+    /** ตัวแปรที่จำเป็นแต่ไม่ได้ส่งมา */
+    missing?: string[]);
+}
+type Data = Record<string, unknown>;
+type Node = {
+    t: "text";
+    v: string;
+} | {
+    t: "var";
+    path: string;
+} | {
+    t: "if";
+    path: string;
+    yes: Node[];
+    no: Node[];
+} | {
+    t: "each";
+    path: string;
+    body: Node[];
+};
+/** แยกเทมเพลตเป็นต้นไม้ — แท็กเปิด/ปิดไม่ครบหรือชื่อแปลกโยน TemplateError พร้อมตำแหน่ง */
+declare function parseTemplate(source: string): Node[];
+/** render เทมเพลตหนึ่งช่อง — `escape: true` สำหรับ HTML, false สำหรับหัวเรื่อง/ข้อความล้วน */
+declare function renderTemplate(source: string, data: Data, opts: {
+    escape: boolean;
+}): string;
+/** ชื่อตัวแปรชั้นบนสุดที่เทมเพลตใช้ (ไม่รวมที่อยู่ใน {{#each}}) — ไว้ช่วยกรอกรายการตัวแปร */
+declare function templateVariableNames(...sources: string[]): string[];
+/** ค่าตัวอย่างจากรายการตัวแปร (path a.b → ซ้อน object) */
+declare function sampleData(variables: TemplateVariable[] | null | undefined): Data;
+/** layout มาตรฐานเมื่อ HTML ไม่มี <html> ของตัวเอง — กว้าง 600px อ่านง่ายทุกโปรแกรมอีเมล */
+declare function wrapEmailLayout(body: string, opts?: {
+    appName?: string;
+    title?: string;
+}): string;
+/**
+ * render อีเมลทั้งฉบับจากเทมเพลต: หัวเรื่อง (ไม่ escape) · HTML (escape + ครอบ layout ถ้าไม่มี <html>) · ข้อความล้วน
+ * ตัวแปร `required` ที่ไม่มีค่า → TemplateError (`missing`) — ไม่ส่งอีเมลที่ข้อมูลหาย
+ */
+declare function renderEmailTemplate(t: EmailTemplateSource, data: Data, opts?: {
+    appName?: string;
+}): {
+    subject: string;
+    html: string;
+    text: string;
+};
+
+export { TemplateError, parseTemplate, renderEmailTemplate, renderTemplate, sampleData, templateVariableNames, wrapEmailLayout };
+export type { EmailTemplateSource, TemplateVariable };

package/dist/template.js

@@ -0,0 +1,18 @@
+import {
+  TemplateError,
+  parseTemplate,
+  renderEmailTemplate,
+  renderTemplate,
+  sampleData,
+  templateVariableNames,
+  wrapEmailLayout
+} from "./chunk-XVD6P4HN.js";
+export {
+  TemplateError,
+  parseTemplate,
+  renderEmailTemplate,
+  renderTemplate,
+  sampleData,
+  templateVariableNames,
+  wrapEmailLayout
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suphark/notify",
-  "version": "0.6.0",
+  "version": "0.9.0",
   "private": false,
   "type": "module",
   "description": "ส่งอีเมล + แจ้งเตือน Telegram ผ่าน Pi Notify hub (notify.suphark.com) หรือส่งอีเมลตรงไป Resend/SMTP/Zoho/ZeptoMail ใน API เดียว พร้อม failover อัตโนมัติ",
@@ -14,6 +14,11 @@
       "types": "./dist/next.d.ts",
       "import": "./dist/next.js",
       "default": "./dist/next.js"
+    },
+    "./template": {
+      "types": "./dist/template.d.ts",
+      "import": "./dist/template.js",
+      "default": "./dist/template.js"
     }
   },
   "files": [
@@ -36,7 +41,7 @@
     "prepack": "pnpm run build"
   },
   "dependencies": {
-    "nodemailer": "^10.0.14"
+    "nodemailer": "^10.2.1"
   },
   "peerDependencies": {
     "next": ">=15"
@@ -47,14 +52,14 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.15",
+    "@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": {