@suphark/notify 0.5.0 → 0.6.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Suphark
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Suphark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -94,6 +94,24 @@ const { url, code } = await createLink(user);                   // รับ use
 const { linked, label, manageUrl } = await getChannelStatus(user, "telegram");
 ```
 
+### ให้ hub ส่งซ้ำเอง: `deliverWithin` + `idempotencyKey` (0.6.0)
+
+```ts
+const r = await notify({
+  to: user,
+  title: "ถึงกำหนดงาน",
+  body: "…",
+  channels: ["telegram"],
+  deliverWithin: 3600, // ให้ hub พยายามส่งภายใน 1 ชม.
+  idempotencyKey: `pi-done:reminder:${user.id}:${runId}`, // cron รันซ้ำก็ไม่เตือนซ้ำ
+});
+// r.results[i].status: "sent" | "queued" (hub รับไว้ส่งซ้ำเอง) | "failed" | "skipped"
+```
+
+- นับ `queued` เป็น "รับไว้แล้ว" — แอปไม่ต้องส่งซ้ำเอง; ดูสถานะที่หน้า Logs / คิวส่งซ้ำของ Pi Notify
+- `failed` = ผิดถาวร / ลองครบแล้ว / เลยเวลา — แอปตัดสินใจเอง (อย่าสลับไปอีเมลถ้าผู้ใช้ไม่ได้ขอ)
+- ใช้ `idempotencyKey` ที่ผูกกับเหตุการณ์ (ไม่ใช่สุ่มใหม่ทุกครั้ง) จึงกันซ้ำได้ — ส่งเนื้อหาเดิมด้วย key เดิมซ้ำจะได้ผลเดิมกลับมา
+
 ### เขียนให้สั้น: ส่งแบบไม่โยน / ส่งเบื้องหลัง / `to` เป็น user object (0.5.0)
 
 `to` ของ `notify()` รับ **user object ที่มี `email`** (และ array ของมัน) ได้เลย — ไม่ต้องแกะ `.email` เอง
@@ -373,6 +391,11 @@ Pi Notify มี contract test (`apps/notify/src/test/contract/`) เก็บ b
 
 ## Changelog
 
+- 0.6.0 — **hub ส่งซ้ำเอง** (เพิ่มอย่างเดียว — แอปที่ไม่ส่งตัวเลือกใหม่ได้พฤติกรรมเดิมทุกอย่าง; ต้องใช้ Pi Notify 2026-10-14+)
+  - `notify({ deliverWithin })` (วินาที 60–86400): รายการที่ค้างหรือพลาดชั่วคราวเข้าคิวถาวรของ hub แล้วส่งซ้ำตาม backoff (1 นาที → 5 นาที → 30 นาที → 2 ชม., สูงสุด 5 ครั้ง) · ผิดถาวรไม่ส่งซ้ำ · เลยเวลาแล้วไม่ส่ง · ไม่สลับช่องทาง
+  - `notify({ idempotencyKey })` → หัว `Idempotency-Key`: key+เนื้อหาเดิมได้ผลเดิม ไม่ส่งซ้ำ (จำ 7 วัน) · เนื้อหาต่างแต่ key เดิม = `invalid` (422) · คำขอเดิมยังทำอยู่ = `rate_limit` (409, `retryAfterSec` 5)
+  - `NotifyResultItem.status` เพิ่ม `"queued"` (+ `deliveryId`), `NotifyResult.queued?` / `NotifySafeResult.queued?` — `queued` นับเป็น "รับไว้แล้ว" ไม่ใช่ failed (`notifySafe().ok` เป็น true) · `status` ใหม่เกิดเฉพาะเมื่อแอปส่ง `deliverWithin` (ออกเป็น minor เพราะ union ของ `status` ที่แอปอาจ switch)
+
 - 0.5.0 — **เขียนฝั่งแอปให้สั้นลง** (เพิ่มอย่างเดียว — ฟอร์มของ 0.4.0 ใช้ได้ทุกแบบ; Pi Notify รุ่นเก่าใช้ได้ ยกเว้น `code` ที่แกะจาก url ให้เอง)
   - `notify({ to })` รับ user object `{ email }` และ array (กรอง null); ผู้รับเดี่ยวไม่มีอีเมล = `MailError` `invalid`
   - `notifySafe()` / `sendMailSafe()` ไม่โยน; ไม่มี key/provider = `disabled`

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

@@ -1101,6 +1101,7 @@ async function hubRequest(opts, path, init) {
       method: init.method ?? "GET",
       headers: {
         Authorization: `Bearer ${apiKey}`,
+        ...init.headers,
         ...init.body !== void 0 ? { "Content-Type": "application/json" } : {}
       },
       body: init.body !== void 0 ? JSON.stringify(init.body) : void 0,
@@ -1128,9 +1129,11 @@ async function hubRequest(opts, path, init) {
   return data;
 }
 async function notify(input, opts = {}) {
+  const { idempotencyKey, ...body } = input;
   const data = await hubRequest(opts, "/api/v1/notify", {
     method: "POST",
-    body: { ...input, to: toEmails(input.to) },
+    body: { ...body, to: toEmails(input.to) },
+    headers: idempotencyKey ? { "Idempotency-Key": idempotencyKey } : void 0,
     timeoutMs: NOTIFY_TIMEOUT_MS.notify
   });
   return { results: data.results, ...data.summary };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { P as ParsedAddress, A as Address, a as Provider, E as ErrorKind, Q as Quota, M as Message, S as SendResult, b as ProviderStatus, c as ProviderInfo, d as Store, e as MailerEvent, f as Attempt, g as PushDevice, N as NotifyOptions, h as NotifyResultItem, i as NotifyInput } from './notify-L7JnpG0t.js';
-export { j as Attachment, C as ChannelStatus, k as NOTIFY_TIMEOUT_MS, l as NormalizedMessage, m as NotifyChannel, n as NotifyResult, o as PushSubscriptionJson, p as QuotaUsage, R as Recipient, q as RecipientChannelInfo, r as RecipientInfo, s as SkipReason, t as createLink, u as deletePushSubscription, v as getChannelStatus, w as getPushConfig, x as getRecipient, y as hasNotifyKey, z as listPushDevices, B as notify, D as savePushSubscription, F as toEmails } from './notify-L7JnpG0t.js';
+import { P as ParsedAddress, A as Address, a as Provider, E as ErrorKind, Q as Quota, M as Message, S as SendResult, b as ProviderStatus, c as ProviderInfo, d as Store, e as MailerEvent, f as Attempt, g as PushDevice, N as NotifyOptions, h as NotifyResultItem, i as NotifyInput } 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';
 
 /** แปลง "ชื่อ <a@b.com>" / "a@b.com" / { name, email } → { name, email } */
 declare function parseAddress(input: Address): ParsedAddress;
@@ -403,6 +403,8 @@ interface NotifySafeResult {
     failed: number;
     skipped: number;
     deferred?: number;
+    /** (0.6.0) hub รับไว้ส่งซ้ำเอง — ไม่นับเป็นความล้มเหลว */
+    queued?: number;
     /** ผลรายผู้รับ/ช่องทาง (มีแม้ Pi Notify ตอบ 502 — ดึงจาก body) */
     results: NotifyResultItem[];
     /** ข้อความ error (ไม่มีอีเมลผู้รับ/เนื้อหา) */

package/dist/index.js

@@ -37,7 +37,7 @@ import {
   sendMail,
   sendMailSafe,
   toEmails
-} from "./chunk-FL5ZV3S2.js";
+} 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;

package/dist/next.d.ts

@@ -1,4 +1,4 @@
-import { N as NotifyOptions, i as NotifyInput, M as Message } from './notify-L7JnpG0t.js';
+import { N as NotifyOptions, i as NotifyInput, M as Message } from './notify-BM6FBQVP.js';
 
 /**
  * ส่งหลังตอบ response แล้ว (`after()` ของ Next.js) — entry แยก `@suphark/notify/next` เพราะ core ของ SDK

package/dist/next.js

@@ -1,7 +1,7 @@
 import {
   notifySafe,
   sendMailSafe
-} from "./chunk-FL5ZV3S2.js";
+} from "./chunk-AQWFHD5T.js";
 
 // src/next.ts
 import { after } from "next/server";

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

@@ -204,11 +204,24 @@ interface NotifyInput {
     channels?: NotifyChannel[];
     /** ชื่อ provider ฝั่ง hub ที่อยากให้ลองก่อน */
     prefer?: string;
+    /**
+     * (0.6.0) วินาที 60–86400 — ให้ hub รับผิดชอบส่งให้ถึงภายในเวลานี้: รายการที่ค้างหรือพลาดชั่วคราว (network/5xx/429)
+     * hub เก็บในคิวแล้วส่งซ้ำเองตาม backoff (ผลเป็น `status: "queued"` นับเป็น "รับไว้แล้ว") · ผิดถาวร (ผู้รับบล็อก ฯลฯ) ไม่ส่งซ้ำ
+     * เลยเวลาแล้วไม่ส่ง · ไม่สลับช่องทาง (ขอ telegram จะไม่ตกไปอีเมล) · ไม่ระบุ = พฤติกรรมเดิม (แอปส่งซ้ำเอง)
+     */
+    deliverWithin?: number;
+    /**
+     * (0.6.0) กันส่งซ้ำ — ส่งเป็นหัว `Idempotency-Key` (1–200 ตัวอักษร ต่อแอป) เรียกซ้ำด้วย key และเนื้อหาเดิม
+     * ได้ผลเดิมโดย hub ไม่ส่งอะไรอีก (เนื้อหาต่างแต่ key เดิม = MailError `invalid` 422) · จำไว้ 7 วัน
+     * ควรเป็นค่าที่ผูกกับเหตุการณ์ เช่น `pi-done:reminder:<userId>:<runId>`
+     */
+    idempotencyKey?: string;
 }
 interface NotifyResultItem {
     to: string;
     channel: NotifyChannel;
-    status: "sent" | "failed" | "skipped";
+    /** `queued` (0.6.0) = hub รับไว้ส่งซ้ำเอง — เกิดเฉพาะเมื่อแอปส่ง `deliverWithin` */
+    status: "sent" | "failed" | "skipped" | "queued";
     provider?: string;
     id?: string;
     failedOver?: boolean;
@@ -220,6 +233,8 @@ interface NotifyResultItem {
     reason?: "no_link" | "channel_not_linked" | "no_chat_provider" | "no_push_provider" | "app_daily_cap";
     /** (status failed) คำขอหมดงบเวลาก่อนได้เริ่มส่งรายการนี้ — ส่งซ้ำเฉพาะรายการนี้ได้ */
     deferred?: boolean;
+    /** (0.6.0) id ของรายการในคิวส่งซ้ำของ hub — มีเมื่อ status เป็น queued */
+    deliveryId?: string;
 }
 interface NotifyResult {
     results: NotifyResultItem[];
@@ -228,6 +243,8 @@ interface NotifyResult {
     skipped: number;
     /** จำนวนที่ยังไม่ได้ส่งเพราะหมดงบเวลา (นับซ้อนอยู่ใน failed; Pi Notify รุ่นเก่าไม่ส่งมา) */
     deferred?: number;
+    /** (0.6.0) จำนวนที่ hub รับไว้ส่งซ้ำเอง (ไม่นับใน failed) — Pi Notify รุ่นเก่าไม่ส่งมา */
+    queued?: number;
 }
 interface NotifyOptions {
     /** ค่าเริ่มต้น PI_NOTIFY_KEY */

package/package.json

@@ -1,12 +1,9 @@
 {
   "name": "@suphark/notify",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "private": false,
   "type": "module",
   "description": "ส่งอีเมล + แจ้งเตือน Telegram ผ่าน Pi Notify hub (notify.suphark.com) หรือส่งอีเมลตรงไป Resend/SMTP/Zoho/ZeptoMail ใน API เดียว พร้อม failover อัตโนมัติ",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -51,7 +48,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.15",
-    "@pi/config": "workspace:*",
+    "@pi/tsconfig": "workspace:*",
     "@types/node": "^24.13.4",
     "@types/nodemailer": "^8.0.1",
     "next": "^16.3.8",