@suphark/notify 0.7.0 → 0.10.0

package/README.md

@@ -41,6 +41,81 @@ 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`
+
+### อีเมลล็อกอินมาตรฐาน + ข้อความสำรองเมื่อ Pi Notify ล่ม (0.10.0)
+
+```ts
+await sendMail({
+  to: user.email,
+  template: "auth.magic-link", // หรือ auth.reset-password / auth.verify-email
+  data: { url: magicLinkUrl, expiresIn: "15 นาที" }, // appName ไม่ต้องส่ง — hub เติมชื่อแอปให้
+});
+```
+
+- ใช้ได้ทุกแอปทันทีโดยไม่ต้องสร้างเทมเพลต (ฉบับสวยอยู่ที่ Pi Notify) — อยากปรับข้อความเฉพาะแอป สร้างเทมเพลตชื่อเดียวกันทับ (คอนโซล: แอป → เทมเพลตอีเมล → "ปรับสำหรับแอป")
+- **ติดต่อ Pi Notify ไม่ได้** (ล่ม/เครือข่าย/ไม่ตอบ) และแอปตั้ง provider ในเครื่องไว้ (SMTP/Resend) → SDK ส่งข้อความพื้นฐาน (หัวเรื่อง + ลิงก์ + อายุลิงก์) ผ่าน provider ในเครื่องแทน ผล `fallback: true` — ผู้ใช้ยังล็อกอินได้
+- Pi Notify ตอบว่าข้อมูลผิด (เช่นไม่ส่ง `url`) → โยน error ไม่ส่งข้อความสำรอง
+- เทมเพลตของแอปเองใส่ข้อความสำรองได้: `sendMail({ template: "po-approved", data, fallback: { subject, text, html? } })`
+- ข้อความที่ส่งทางสำรองไม่มีใน log ของ Pi Notify (ดูจาก `onEvent` type `"fallback"`)
+
+### อีเมลที่ต้องถึงแน่: `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 ไปตัวถัดไปเอง:
@@ -428,6 +503,17 @@ Pi Notify มี contract test (`apps/notify/src/test/contract/`) เก็บ b
 
 ## Changelog
 
+- 0.10.0 — **อีเมลล็อกอินมาตรฐาน + ข้อความสำรอง** (เพิ่มอย่างเดียว; ต้องใช้ Pi Notify 2026-11-11+)
+  - เทมเพลตมาตรฐาน `auth.magic-link` / `auth.reset-password` / `auth.verify-email` ใช้ได้ทุกแอปโดยไม่ต้องสร้าง (สร้างชื่อเดียวกันเพื่อปรับ)
+  - ติดต่อ hub ไม่ได้ → ส่งข้อความพื้นฐานผ่าน provider ในเครื่อง (`SendResult.fallback`, event `"fallback"`) · `Message.fallback` สำหรับเทมเพลตของแอปเอง
+  - `listTemplates()` / `getTemplate()` คืนเทมเพลตมาตรฐานด้วย (`builtin: true`) · hub เติม `appName` ให้ทุกเทมเพลต
+- 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 ของแอป

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

@@ -1,3 +1,7 @@
+import {
+  builtinFallback
+} from "./chunk-NNMV7FZ3.js";
+
 // src/address.ts
 var NAMED_RE = /^\s*(?:"?([^"<]*?)"?\s*)?<([^<>\s]+@[^<>\s]+)>\s*$/;
 var EMAIL_RE = /^[^\s@<>]+@[^\s@<>]+\.[^\s@<>]+$/;
@@ -483,17 +487,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 +521,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"), {
@@ -798,6 +811,9 @@ function debugLogger(e) {
         `${tag} ${e.provider} cooldown [${e.kind}] until ${new Date(e.untilMs).toISOString()} (failures=${e.failures})`
       );
       break;
+    case "fallback":
+      console.warn(`${tag} hub unreachable \u2192 sent fallback text for template ${e.template}`);
+      break;
     case "recovered":
       console.log(`${tag} ${e.provider} recovered`);
       break;
@@ -851,7 +867,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 +877,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 });
@@ -900,12 +920,49 @@ function createMailer(options = {}) {
     return pick;
   }
   async function send(message) {
+    if (!message?.template) return sendVia(message, "all");
+    const fallback = message.fallback ?? builtinFallback(message.template, message.data);
+    const hasHub = entries.some((e) => e.provider.type === "hub");
+    const hasLocal = entries.some((e) => e.provider.type !== "hub" && !e.disabled);
+    const asFallback = (fb) => ({
+      ...message,
+      template: void 0,
+      data: void 0,
+      fallback: void 0,
+      subject: fb.subject,
+      text: fb.text,
+      html: fb.html
+    });
+    if (!hasHub) {
+      if (fallback && hasLocal)
+        return { ...await sendVia(asFallback(fallback), "local"), fallback: true };
+      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" }
+      );
+    }
+    try {
+      return await sendVia(message, "hub");
+    } catch (err) {
+      const attempts = err instanceof AllProvidersFailedError ? err.attempts : [];
+      const invalid = err instanceof MailError && err.kind === "invalid" && attempts.length === 0 || attempts.some((a) => a.kind === "invalid");
+      if (!fallback || !hasLocal || invalid) throw err;
+      emit({ type: "fallback", template: message.template });
+      const r = await sendVia(asFallback(fallback), "local");
+      return { ...r, failedOver: true, fallback: true, attempts: [...attempts, ...r.attempts] };
+    }
+  }
+  async function sendVia(message, via) {
     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 (via !== "all")
+      candidates = candidates.filter((e) => e.provider.type === "hub" === (via === "hub"));
     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 +979,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 +1011,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;
@@ -1145,6 +1203,18 @@ 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,
@@ -1292,8 +1362,10 @@ export {
   toEmails,
   NOTIFY_TIMEOUT_MS,
   hasNotifyKey,
+  hubRequest,
   notify,
   notifyTopic,
+  getRequestStatus,
   getRecipient,
   createLink,
   getChannelStatus,

package/dist/chunk-NNMV7FZ3.js

@@ -0,0 +1,284 @@
+// 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 };
+}
+var BUILTIN_TEMPLATE_KEYS = [
+  "auth.magic-link",
+  "auth.reset-password",
+  "auth.verify-email"
+];
+function isBuiltinTemplate(key) {
+  return BUILTIN_TEMPLATE_KEYS.includes(key);
+}
+var AUTH_VARIABLES = [
+  {
+    name: "url",
+    label: "\u0E25\u0E34\u0E07\u0E01\u0E4C\u0E17\u0E35\u0E48\u0E1C\u0E39\u0E49\u0E43\u0E0A\u0E49\u0E15\u0E49\u0E2D\u0E07\u0E01\u0E14",
+    sample: "https://app.example.com/auth/verify?token=abc",
+    required: true
+  },
+  { name: "appName", label: "\u0E0A\u0E37\u0E48\u0E2D\u0E41\u0E2D\u0E1B (hub \u0E40\u0E15\u0E34\u0E21\u0E43\u0E2B\u0E49\u0E16\u0E49\u0E32\u0E44\u0E21\u0E48\u0E2A\u0E48\u0E07)", sample: "ESTAR Supply Chain" },
+  { name: "expiresIn", label: "\u0E2D\u0E32\u0E22\u0E38\u0E25\u0E34\u0E07\u0E01\u0E4C \u0E40\u0E0A\u0E48\u0E19 15 \u0E19\u0E32\u0E17\u0E35", sample: "15 \u0E19\u0E32\u0E17\u0E35" }
+];
+var BUTTON = "display:inline-block;background:#1d4ed8;color:#ffffff;text-decoration:none;padding:12px 20px;border-radius:8px;font-weight:600";
+function authHtml(heading, lead, button, note) {
+  return `<h2 style="margin:0 0 12px;font-size:20px">${heading}</h2>
+<p style="margin:0 0 20px">${lead}</p>
+<p style="margin:0 0 20px"><a href="{{url}}" style="${BUTTON}">${button}</a></p>
+<p style="margin:0 0 8px;font-size:13px;color:#475569">${note}{{#if expiresIn}} \u0E25\u0E34\u0E07\u0E01\u0E4C\u0E2B\u0E21\u0E14\u0E2D\u0E32\u0E22\u0E38\u0E43\u0E19 {{expiresIn}}{{/if}}</p>
+<p style="margin:0 0 8px;font-size:13px;color:#475569">\u0E16\u0E49\u0E32\u0E1B\u0E38\u0E48\u0E21\u0E01\u0E14\u0E44\u0E21\u0E48\u0E44\u0E14\u0E49 \u0E43\u0E2B\u0E49\u0E04\u0E31\u0E14\u0E25\u0E2D\u0E01\u0E25\u0E34\u0E07\u0E01\u0E4C\u0E19\u0E35\u0E49\u0E44\u0E1B\u0E40\u0E1B\u0E34\u0E14\u0E43\u0E19\u0E40\u0E1A\u0E23\u0E32\u0E27\u0E4C\u0E40\u0E0B\u0E2D\u0E23\u0E4C:<br><span style="word-break:break-all">{{url}}</span></p>
+<p style="margin:16px 0 0;font-size:13px;color:#475569">\u0E16\u0E49\u0E32\u0E04\u0E38\u0E13\u0E44\u0E21\u0E48\u0E44\u0E14\u0E49\u0E40\u0E1B\u0E47\u0E19\u0E04\u0E19\u0E02\u0E2D \u0E44\u0E21\u0E48\u0E15\u0E49\u0E2D\u0E07\u0E17\u0E33\u0E2D\u0E30\u0E44\u0E23 \u2014 \u0E1A\u0E31\u0E0D\u0E0A\u0E35\u0E02\u0E2D\u0E07\u0E04\u0E38\u0E13\u0E22\u0E31\u0E07\u0E1B\u0E25\u0E2D\u0E14\u0E20\u0E31\u0E22</p>`;
+}
+var BUILTIN_TEMPLATES = {
+  "auth.magic-link": {
+    name: "\u0E25\u0E34\u0E07\u0E01\u0E4C\u0E40\u0E02\u0E49\u0E32\u0E2A\u0E39\u0E48\u0E23\u0E30\u0E1A\u0E1A (\u0E21\u0E32\u0E15\u0E23\u0E10\u0E32\u0E19)",
+    subject: "\u0E25\u0E34\u0E07\u0E01\u0E4C\u0E40\u0E02\u0E49\u0E32\u0E2A\u0E39\u0E48\u0E23\u0E30\u0E1A\u0E1A{{#if appName}} {{appName}}{{/if}}",
+    html: authHtml(
+      "\u0E40\u0E02\u0E49\u0E32\u0E2A\u0E39\u0E48\u0E23\u0E30\u0E1A\u0E1A{{#if appName}} {{appName}}{{/if}}",
+      "\u0E01\u0E14\u0E1B\u0E38\u0E48\u0E21\u0E14\u0E49\u0E32\u0E19\u0E25\u0E48\u0E32\u0E07\u0E40\u0E1E\u0E37\u0E48\u0E2D\u0E40\u0E02\u0E49\u0E32\u0E2A\u0E39\u0E48\u0E23\u0E30\u0E1A\u0E1A \u0E44\u0E21\u0E48\u0E15\u0E49\u0E2D\u0E07\u0E43\u0E0A\u0E49\u0E23\u0E2B\u0E31\u0E2A\u0E1C\u0E48\u0E32\u0E19",
+      "\u0E40\u0E02\u0E49\u0E32\u0E2A\u0E39\u0E48\u0E23\u0E30\u0E1A\u0E1A",
+      "\u0E25\u0E34\u0E07\u0E01\u0E4C\u0E19\u0E35\u0E49\u0E43\u0E0A\u0E49\u0E44\u0E14\u0E49\u0E04\u0E23\u0E31\u0E49\u0E07\u0E40\u0E14\u0E35\u0E22\u0E27"
+    ),
+    variables: AUTH_VARIABLES
+  },
+  "auth.reset-password": {
+    name: "\u0E15\u0E31\u0E49\u0E07\u0E23\u0E2B\u0E31\u0E2A\u0E1C\u0E48\u0E32\u0E19\u0E43\u0E2B\u0E21\u0E48 (\u0E21\u0E32\u0E15\u0E23\u0E10\u0E32\u0E19)",
+    subject: "\u0E15\u0E31\u0E49\u0E07\u0E23\u0E2B\u0E31\u0E2A\u0E1C\u0E48\u0E32\u0E19\u0E43\u0E2B\u0E21\u0E48{{#if appName}} {{appName}}{{/if}}",
+    html: authHtml(
+      "\u0E15\u0E31\u0E49\u0E07\u0E23\u0E2B\u0E31\u0E2A\u0E1C\u0E48\u0E32\u0E19\u0E43\u0E2B\u0E21\u0E48",
+      "\u0E21\u0E35\u0E04\u0E33\u0E02\u0E2D\u0E15\u0E31\u0E49\u0E07\u0E23\u0E2B\u0E31\u0E2A\u0E1C\u0E48\u0E32\u0E19\u0E43\u0E2B\u0E21\u0E48\u0E2A\u0E33\u0E2B\u0E23\u0E31\u0E1A\u0E1A\u0E31\u0E0D\u0E0A\u0E35\u0E02\u0E2D\u0E07\u0E04\u0E38\u0E13{{#if appName}} \u0E43\u0E19 {{appName}}{{/if}} \u0E01\u0E14\u0E1B\u0E38\u0E48\u0E21\u0E14\u0E49\u0E32\u0E19\u0E25\u0E48\u0E32\u0E07\u0E40\u0E1E\u0E37\u0E48\u0E2D\u0E15\u0E31\u0E49\u0E07\u0E23\u0E2B\u0E31\u0E2A\u0E1C\u0E48\u0E32\u0E19\u0E43\u0E2B\u0E21\u0E48",
+      "\u0E15\u0E31\u0E49\u0E07\u0E23\u0E2B\u0E31\u0E2A\u0E1C\u0E48\u0E32\u0E19\u0E43\u0E2B\u0E21\u0E48",
+      "\u0E25\u0E34\u0E07\u0E01\u0E4C\u0E19\u0E35\u0E49\u0E43\u0E0A\u0E49\u0E44\u0E14\u0E49\u0E04\u0E23\u0E31\u0E49\u0E07\u0E40\u0E14\u0E35\u0E22\u0E27"
+    ),
+    variables: AUTH_VARIABLES
+  },
+  "auth.verify-email": {
+    name: "\u0E22\u0E37\u0E19\u0E22\u0E31\u0E19\u0E2D\u0E35\u0E40\u0E21\u0E25 (\u0E21\u0E32\u0E15\u0E23\u0E10\u0E32\u0E19)",
+    subject: "\u0E22\u0E37\u0E19\u0E22\u0E31\u0E19\u0E2D\u0E35\u0E40\u0E21\u0E25\u0E02\u0E2D\u0E07\u0E04\u0E38\u0E13{{#if appName}} \u2014 {{appName}}{{/if}}",
+    html: authHtml(
+      "\u0E22\u0E37\u0E19\u0E22\u0E31\u0E19\u0E2D\u0E35\u0E40\u0E21\u0E25\u0E02\u0E2D\u0E07\u0E04\u0E38\u0E13",
+      "\u0E01\u0E14\u0E1B\u0E38\u0E48\u0E21\u0E14\u0E49\u0E32\u0E19\u0E25\u0E48\u0E32\u0E07\u0E40\u0E1E\u0E37\u0E48\u0E2D\u0E22\u0E37\u0E19\u0E22\u0E31\u0E19\u0E27\u0E48\u0E32\u0E2D\u0E35\u0E40\u0E21\u0E25\u0E19\u0E35\u0E49\u0E40\u0E1B\u0E47\u0E19\u0E02\u0E2D\u0E07\u0E04\u0E38\u0E13{{#if appName}} \u0E41\u0E25\u0E30\u0E40\u0E23\u0E34\u0E48\u0E21\u0E43\u0E0A\u0E49 {{appName}}{{/if}}",
+      "\u0E22\u0E37\u0E19\u0E22\u0E31\u0E19\u0E2D\u0E35\u0E40\u0E21\u0E25",
+      "\u0E22\u0E37\u0E19\u0E22\u0E31\u0E19\u0E04\u0E23\u0E31\u0E49\u0E07\u0E40\u0E14\u0E35\u0E22\u0E27\u0E01\u0E47\u0E1E\u0E2D"
+    ),
+    variables: AUTH_VARIABLES
+  }
+};
+var FALLBACK_SUBJECT = {
+  "auth.magic-link": "\u0E25\u0E34\u0E07\u0E01\u0E4C\u0E40\u0E02\u0E49\u0E32\u0E2A\u0E39\u0E48\u0E23\u0E30\u0E1A\u0E1A",
+  "auth.reset-password": "\u0E15\u0E31\u0E49\u0E07\u0E23\u0E2B\u0E31\u0E2A\u0E1C\u0E48\u0E32\u0E19\u0E43\u0E2B\u0E21\u0E48",
+  "auth.verify-email": "\u0E22\u0E37\u0E19\u0E22\u0E31\u0E19\u0E2D\u0E35\u0E40\u0E21\u0E25"
+};
+function builtinFallback(key, data) {
+  if (!isBuiltinTemplate(key)) return null;
+  const url = typeof data?.url === "string" ? data.url : "";
+  if (!url) return null;
+  const app = typeof data?.appName === "string" && data.appName ? data.appName : "";
+  const expires = typeof data?.expiresIn === "string" && data.expiresIn ? data.expiresIn : "";
+  const subject = `${FALLBACK_SUBJECT[key]}${app ? ` ${app}` : ""}`;
+  const lines = [
+    `${FALLBACK_SUBJECT[key]}${app ? ` (${app})` : ""}`,
+    "",
+    "\u0E40\u0E1B\u0E34\u0E14\u0E25\u0E34\u0E07\u0E01\u0E4C\u0E19\u0E35\u0E49:",
+    url,
+    "",
+    ...expires ? [`\u0E25\u0E34\u0E07\u0E01\u0E4C\u0E2B\u0E21\u0E14\u0E2D\u0E32\u0E22\u0E38\u0E43\u0E19 ${expires}`] : [],
+    "\u0E16\u0E49\u0E32\u0E04\u0E38\u0E13\u0E44\u0E21\u0E48\u0E44\u0E14\u0E49\u0E40\u0E1B\u0E47\u0E19\u0E04\u0E19\u0E02\u0E2D \u0E44\u0E21\u0E48\u0E15\u0E49\u0E2D\u0E07\u0E17\u0E33\u0E2D\u0E30\u0E44\u0E23"
+  ];
+  const text = lines.join("\n");
+  const html = `<p>${escapeHtml(lines[0])}</p><p><a href="${escapeHtml(url)}">${escapeHtml(url)}</a></p>${expires ? `<p>\u0E25\u0E34\u0E07\u0E01\u0E4C\u0E2B\u0E21\u0E14\u0E2D\u0E32\u0E22\u0E38\u0E43\u0E19 ${escapeHtml(expires)}</p>` : ""}<p>\u0E16\u0E49\u0E32\u0E04\u0E38\u0E13\u0E44\u0E21\u0E48\u0E44\u0E14\u0E49\u0E40\u0E1B\u0E47\u0E19\u0E04\u0E19\u0E02\u0E2D \u0E44\u0E21\u0E48\u0E15\u0E49\u0E2D\u0E07\u0E17\u0E33\u0E2D\u0E30\u0E44\u0E23</p>`;
+  return { subject, text, html };
+}
+
+export {
+  looksLikeHtml,
+  resolveFormat,
+  toPlainText,
+  TemplateError,
+  parseTemplate,
+  renderTemplate,
+  templateVariableNames,
+  sampleData,
+  wrapEmailLayout,
+  renderEmailTemplate,
+  BUILTIN_TEMPLATE_KEYS,
+  isBuiltinTemplate,
+  BUILTIN_TEMPLATES,
+  builtinFallback
+};

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, 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';
+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-D-PhiDzT.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-D-PhiDzT.js';
+import { TemplateVariable } from './template.js';
+export { BUILTIN_TEMPLATE_KEYS, BuiltinTemplateKey, TemplateError, builtinFallback, isBuiltinTemplate, 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 {
@@ -457,5 +468,54 @@ declare function createRedisStore(client: RedisLike, opts?: {
     prefix?: string;
 }): Store;
 
-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 };
+/** (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;
+    /** (0.10.0) true = เทมเพลตมาตรฐานของ Pi Notify (auth.*) ที่แอปยังไม่ได้สร้างทับ */
+    builtin?: boolean;
+}
+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,7 +22,9 @@ import {
   getMailer,
   getPushConfig,
   getRecipient,
+  getRequestStatus,
   hasNotifyKey,
+  hubRequest,
   listProviders,
   listPushDevices,
   notify,
@@ -39,20 +41,17 @@ import {
   sendMail,
   sendMailSafe,
   toEmails
-} 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;
-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-CWZP54ZN.js";
+import {
+  BUILTIN_TEMPLATE_KEYS,
+  TemplateError,
+  builtinFallback,
+  isBuiltinTemplate,
+  looksLikeHtml,
+  renderEmailTemplate,
+  resolveFormat,
+  toPlainText
+} from "./chunk-NNMV7FZ3.js";
 
 // src/push.ts
 function createPushHandlers(options) {
@@ -189,13 +188,56 @@ 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,
+  BUILTIN_TEMPLATE_KEYS,
   DEFAULT_COOLDOWN,
   DEFAULT_HUB_URL,
   MailError,
   NOTIFY_TIMEOUT_MS,
   SMTP_PRESETS,
+  TemplateError,
+  builtinFallback,
   classifyError,
   configureMailer,
   createConsoleProvider,
@@ -210,14 +252,19 @@ export {
   createSmtpProvider,
   createZeptoMailProvider,
   deletePushSubscription,
+  deleteTemplate,
   formatAddress,
   getChannelStatus,
   getMailer,
   getPushConfig,
   getRecipient,
+  getRequestStatus,
+  getTemplate,
   hasNotifyKey,
+  isBuiltinTemplate,
   listProviders,
   listPushDevices,
+  listTemplates,
   looksLikeHtml,
   notify,
   notifySafe,
@@ -225,15 +272,18 @@ export {
   notifyTopicSafe,
   parseAddress,
   parseAddressList,
+  previewTemplate,
   providersFromEnv,
   pushServiceWorker,
   pushServiceWorkerSource,
+  renderEmailTemplate,
   renderNotifyEmail,
   requireFrom,
   resetMailer,
   resetSafeWarnings,
   resolveFormat,
   savePushSubscription,
+  saveTemplate,
   sendMail,
   sendMailSafe,
   toEmails,

package/dist/next.js

@@ -2,7 +2,8 @@ import {
   notifySafe,
   notifyTopicSafe,
   sendMailSafe
-} from "./chunk-2RXN5HXT.js";
+} from "./chunk-CWZP54ZN.js";
+import "./chunk-NNMV7FZ3.js";
 
 // src/next.ts
 import { after } from "next/server";

package/dist/{notify-D4auDRfk.d.ts → notify-D-PhiDzT.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,32 @@ 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>;
+    /**
+     * (0.10.0) ข้อความสำรองเมื่อติดต่อ Pi Notify ไม่ได้ — ส่งผ่าน provider ในเครื่อง (SMTP/Resend)
+     * เทมเพลตมาตรฐาน `auth.*` มีข้อความสำรองในตัวแล้ว ไม่ต้องใส่
+     */
+    fallback?: {
+        subject: string;
+        text: string;
+        html?: string;
+    };
 }
 /** ข้อมูลตัวเลือกที่แอปควรรู้ — แค่ชื่อ/ประเภท/พร้อมใช้ไหม */
 interface ProviderInfo {
@@ -61,6 +88,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 +120,10 @@ interface SendResult {
     /** true ถ้าตัวแรกที่ควรใช้ล้ม/ถูกข้าม แล้วไปสำเร็จที่ตัวสำรอง */
     failedOver: boolean;
     attempts: Attempt[];
+    /** (0.8.0) hub รับไว้ส่งซ้ำเอง (ส่ง deliverWithin) — ยังไม่ถึงผู้รับ, `id` = deliveryId ในคิวของ hub */
+    queued?: boolean;
+    /** (0.10.0) ส่งข้อความสำรองของเทมเพลตผ่าน provider ในเครื่อง เพราะติดต่อ Pi Notify ไม่ได้ */
+    fallback?: boolean;
 }
 interface Quota {
     perHour?: number;
@@ -103,6 +140,7 @@ interface Provider {
     readonly optionalFrom?: boolean;
     send(msg: NormalizedMessage): Promise<{
         id?: string;
+        queued?: boolean;
     }>;
     /** ทดสอบการเชื่อมต่อ/credential (ไม่ส่งอีเมล) */
     verify?(): Promise<void>;
@@ -151,6 +189,11 @@ type MailerEvent = {
 } | {
     type: "exhausted";
     attempts: Attempt[];
+}
+/** (0.10.0) ติดต่อ hub ไม่ได้ จึงส่งข้อความสำรองของเทมเพลตผ่าน provider ในเครื่อง */
+ | {
+    type: "fallback";
+    template: string;
 };
 interface QuotaUsage {
     window: "hour" | "day" | "month";
@@ -322,6 +365,32 @@ declare function notify(input: NotifyInput, opts?: NotifyOptions): Promise<Notif
  * @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>;
 /**
@@ -377,5 +446,5 @@ declare function listPushDevices(email: string, opts?: NotifyOptions): Promise<{
     devices: PushDevice[];
 }>;
 
-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 };
+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,96 @@
+/**
+ * (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;
+};
+/** ชื่อเทมเพลตมาตรฐาน — ทุกแอปใช้ได้โดยไม่ต้องสร้าง (สร้างชื่อเดียวกันใน Pi Notify เพื่อปรับเฉพาะแอป) */
+declare const BUILTIN_TEMPLATE_KEYS: readonly ["auth.magic-link", "auth.reset-password", "auth.verify-email"];
+type BuiltinTemplateKey = (typeof BUILTIN_TEMPLATE_KEYS)[number];
+declare function isBuiltinTemplate(key: string): key is BuiltinTemplateKey;
+/** ฉบับเต็ม (hub ใช้เมื่อแอปไม่ได้สร้างเทมเพลตชื่อนี้เอง) */
+declare const BUILTIN_TEMPLATES: Record<BuiltinTemplateKey, EmailTemplateSource & {
+    name: string;
+}>;
+/**
+ * ข้อความสำรองแบบพื้นฐาน (ไม่สวย แต่ใช้ล็อกอินได้) — SDK ส่งผ่าน provider ในเครื่องเมื่อติดต่อ Pi Notify ไม่ได้
+ * คืน null เมื่อไม่ใช่เทมเพลตมาตรฐานหรือไม่มี url
+ */
+declare function builtinFallback(key: string, data: Record<string, unknown> | undefined): {
+    subject: string;
+    text: string;
+    html: string;
+} | null;
+
+export { BUILTIN_TEMPLATES, BUILTIN_TEMPLATE_KEYS, TemplateError, builtinFallback, isBuiltinTemplate, parseTemplate, renderEmailTemplate, renderTemplate, sampleData, templateVariableNames, wrapEmailLayout };
+export type { BuiltinTemplateKey, EmailTemplateSource, TemplateVariable };

package/dist/template.js

@@ -0,0 +1,26 @@
+import {
+  BUILTIN_TEMPLATES,
+  BUILTIN_TEMPLATE_KEYS,
+  TemplateError,
+  builtinFallback,
+  isBuiltinTemplate,
+  parseTemplate,
+  renderEmailTemplate,
+  renderTemplate,
+  sampleData,
+  templateVariableNames,
+  wrapEmailLayout
+} from "./chunk-NNMV7FZ3.js";
+export {
+  BUILTIN_TEMPLATES,
+  BUILTIN_TEMPLATE_KEYS,
+  TemplateError,
+  builtinFallback,
+  isBuiltinTemplate,
+  parseTemplate,
+  renderEmailTemplate,
+  renderTemplate,
+  sampleData,
+  templateVariableNames,
+  wrapEmailLayout
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suphark/notify",
-  "version": "0.7.0",
+  "version": "0.10.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": [