@suphark/notify 0.4.0 → 0.5.0

package/dist/next.d.ts

@@ -0,0 +1,28 @@
+import { N as NotifyOptions, i as NotifyInput, M as Message } from './notify-L7JnpG0t.js';
+
+/**
+ * ส่งหลังตอบ response แล้ว (`after()` ของ Next.js) — entry แยก `@suphark/notify/next` เพราะ core ของ SDK
+ * ถูกใช้นอก Next ด้วย (hub, auth, สคริปต์) จึงต้องไม่ import `next/*`
+ */
+interface LaterOptions extends NotifyOptions {
+    /** เรียกเมื่อส่งไม่สำเร็จ (ไม่เรียกเมื่อ disabled) — ไว้ส่งเข้า logger/monitor ของแอป */
+    onError?: (error: string) => void;
+}
+/**
+ * งานใน after() นับรวมใน maxDuration ของ function — ค่าเริ่มต้นของ notify() 65 วิจะถูกแพลตฟอร์มตัดก่อนมี log
+ * จึงใช้ 20 วิ (เท่ากับที่ Pi Auth ใช้); ตั้ง timeoutMs เองได้
+ */
+declare const LATER_TIMEOUT_MS = 20000;
+/**
+ * notify() เบื้องหลัง ไม่บล็อกหน้าเว็บและไม่ทำให้ Server Action/Route พัง — คืน void
+ * ใช้เมื่อการแจ้งเตือนเป็นผลพลอยได้ (best-effort); ถ้าต้องรู้ผลหรือให้ cron บันทึกสถานะ → await notify()
+ * @example notifyLater({ to: user, title: "บันทึกแล้ว", body: "ระบบอัปเดตงานแล้ว" });
+ */
+declare function notifyLater(input: NotifyInput, 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 };

package/dist/next.js

@@ -0,0 +1,40 @@
+import {
+  notifySafe,
+  sendMailSafe
+} from "./chunk-FL5ZV3S2.js";
+
+// src/next.ts
+import { after } from "next/server";
+var LATER_TIMEOUT_MS = 2e4;
+function report(what, error, onError) {
+  if (!error) return;
+  console.error(`[pi-notify] ${what} \u0E2A\u0E48\u0E07\u0E44\u0E21\u0E48\u0E2A\u0E33\u0E40\u0E23\u0E47\u0E08: ${error}`);
+  onError?.(error);
+}
+function runLater(task) {
+  const run = () => task().catch(() => {
+  });
+  try {
+    after(run);
+  } catch {
+    void run();
+  }
+}
+function notifyLater(input, opts = {}) {
+  const { onError, ...rest } = opts;
+  runLater(async () => {
+    const r = await notifySafe(input, { timeoutMs: LATER_TIMEOUT_MS, ...rest });
+    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 sendMailLater(message, opts = {}) {
+  runLater(async () => {
+    const r = await sendMailSafe(message);
+    report("sendMail()", r.error, opts.onError);
+  });
+}
+export {
+  LATER_TIMEOUT_MS,
+  notifyLater,
+  sendMailLater
+};

package/dist/notify-L7JnpG0t.d.ts

@@ -0,0 +1,340 @@
+/** ที่อยู่อีเมล: "a@b.com" | "ชื่อ <a@b.com>" | { name, email } */
+type Address = string | {
+    name?: string;
+    email: string;
+};
+interface Attachment {
+    filename: string;
+    /** Buffer หรือ string (utf8) — ถ้าเป็น base64 อยู่แล้วให้ระบุ encoding: "base64" */
+    content: Buffer | string;
+    contentType?: string;
+    encoding?: "base64" | "utf8";
+}
+/** ข้อความที่แอปส่งเข้ามา (ไม่ผูกกับ provider ใด ๆ) */
+interface Message {
+    to: Address | Address[];
+    subject: string;
+    html?: string;
+    text?: string;
+    /** override from ของ provider/ค่าเริ่มต้น */
+    from?: Address;
+    cc?: Address | Address[];
+    bcc?: Address | Address[];
+    replyTo?: Address | Address[];
+    attachments?: Attachment[];
+    headers?: Record<string, string>;
+    /** metadata แนบไปกับอีเมล (provider ที่รองรับ เช่น Resend tags) */
+    tags?: Record<string, string>;
+    /** บังคับใช้ provider ตัวนี้ตัวเดียว (ไม่ failover) — โหมด local เท่านั้น */
+    provider?: string;
+    /** อยากให้ลองตัวนี้ก่อน (ยัง failover ตามปกติถ้าไม่ได้) — ส่งต่อไป hub ด้วย */
+    prefer?: string;
+}
+/** ข้อมูลตัวเลือกที่แอปควรรู้ — แค่ชื่อ/ประเภท/พร้อมใช้ไหม */
+interface ProviderInfo {
+    name: string;
+    type: string;
+    available: boolean;
+    /** ชื่อ provider ที่เป็นทางผ่าน (เช่น "hub") เมื่อรายการนี้อยู่หลัง hub */
+    via?: string;
+}
+interface ParsedAddress {
+    name?: string;
+    email: string;
+}
+/** ข้อความหลัง normalize แล้ว — ทุก provider ได้รับรูปแบบนี้ */
+interface NormalizedMessage {
+    /** ไม่มีได้เฉพาะ provider ที่ประกาศ optionalFrom (hub เติมให้เอง) */
+    from?: ParsedAddress;
+    to: ParsedAddress[];
+    cc: ParsedAddress[];
+    bcc: ParsedAddress[];
+    replyTo: ParsedAddress[];
+    subject: string;
+    html?: string;
+    text?: string;
+    attachments: {
+        filename: string;
+        base64: string;
+        contentType?: string;
+    }[];
+    headers: Record<string, string>;
+    tags: Record<string, string>;
+    prefer?: string;
+    /**
+     * ยกเลิกเมื่อ mailer หมดเวลา (timeoutMs) — provider ที่ใช้ fetch ควรส่งต่อเข้า fetch
+     * เพื่อไม่ให้คำขอค้างต่อหลัง mailer ไป failover แล้ว (ไม่ส่งมา = provider เขียนเองรุ่นเก่า ใช้ได้ตามเดิม)
+     */
+    signal?: AbortSignal;
+}
+/** ประเภทความผิดพลาด — ใช้ตัดสินใจว่าจะพัก provider นานแค่ไหน */
+type ErrorKind = "quota" | "rate_limit" | "auth" | "network" | "server" | "invalid" | "unknown";
+type SkipReason = "cooldown" | "quota" | "disabled";
+interface Attempt {
+    provider: string;
+    ok: boolean;
+    /** ข้ามเพราะ circuit เปิด/โควต้าเต็ม (ไม่ได้ลองส่งจริง) */
+    skipped?: SkipReason;
+    error?: string;
+    kind?: ErrorKind;
+    ms: number;
+}
+interface SendResult {
+    /** id จาก provider (ถ้ามี) */
+    id?: string;
+    /** ชื่อ provider ที่ส่งสำเร็จ */
+    provider: string;
+    /** true ถ้าตัวแรกที่ควรใช้ล้ม/ถูกข้าม แล้วไปสำเร็จที่ตัวสำรอง */
+    failedOver: boolean;
+    attempts: Attempt[];
+}
+interface Quota {
+    perHour?: number;
+    perDay?: number;
+    perMonth?: number;
+}
+/** สิ่งที่ provider ต้อง implement — เท่านี้พอ ที่เหลือ mailer จัดการ */
+interface Provider {
+    readonly name: string;
+    readonly type: string;
+    /** from เริ่มต้นของ provider นี้ (ชนะ from ของ mailer) */
+    readonly from?: ParsedAddress;
+    /** true = ส่งได้แม้ไม่มี from (provider ปลายทางเติมค่าเริ่มต้นให้ เช่น hub) */
+    readonly optionalFrom?: boolean;
+    send(msg: NormalizedMessage): Promise<{
+        id?: string;
+    }>;
+    /** ทดสอบการเชื่อมต่อ/credential (ไม่ส่งอีเมล) */
+    verify?(): Promise<void>;
+    /** provider ตัวนี้เป็นทางผ่านไปยังตัวอื่น (hub) — คืนรายการข้างหลัง */
+    listProviders?(): Promise<ProviderInfo[]>;
+}
+/**
+ * state ที่ mailer ต้องจำข้ามคำขอ (นับโควต้า, cooldown)
+ * default เก็บใน memory ของ process; ต่อ Redis ได้เพื่อแชร์ข้ามแอป/instance (ดู createRedisStore)
+ */
+interface Store {
+    get(key: string): Promise<string | null>;
+    /** ตั้งค่า พร้อมอายุ (วินาที) */
+    set(key: string, value: string, ttlSec: number): Promise<void>;
+    /** เพิ่มค่าทีละ 1 (สร้างเป็น 1 ถ้ายังไม่มี) พร้อมอายุ (วินาที) คืนค่าใหม่ */
+    incr(key: string, ttlSec: number): Promise<number>;
+    /** ลดค่าทีละ 1 (ไม่ต่ำกว่า 0) — คืนโควต้าที่จองไว้เมื่อส่งไม่สำเร็จ; store ที่ไม่ implement จะนับความล้มเหลวเป็นโควต้าด้วย */
+    decr?(key: string): Promise<void>;
+    del(key: string): Promise<void>;
+}
+type MailerEvent = {
+    type: "sent";
+    provider: string;
+    id?: string;
+    ms: number;
+    failedOver: boolean;
+} | {
+    type: "failed";
+    provider: string;
+    kind: ErrorKind;
+    error: string;
+    ms: number;
+} | {
+    type: "skipped";
+    provider: string;
+    reason: SkipReason;
+} | {
+    type: "cooldown";
+    provider: string;
+    kind: ErrorKind;
+    untilMs: number;
+    failures: number;
+} | {
+    type: "recovered";
+    provider: string;
+} | {
+    type: "exhausted";
+    attempts: Attempt[];
+};
+interface QuotaUsage {
+    window: "hour" | "day" | "month";
+    used: number;
+    limit: number;
+}
+interface ProviderStatus {
+    name: string;
+    type: string;
+    /** พร้อมใช้ (ไม่อยู่ใน cooldown และโควต้ายังไม่เต็ม) */
+    available: boolean;
+    cooldownUntil?: number;
+    cooldownKind?: ErrorKind;
+    failures: number;
+    quota: QuotaUsage[];
+}
+
+/** ผู้รับที่แอปมีอยู่ในมือ: อีเมล หรือ user object (session/DB) ที่มี `email` — null/undefined ได้เพื่อไม่ต้องเช็กก่อนเรียก */
+type Recipient = string | {
+    email?: string | null;
+} | null | undefined;
+/**
+ * แปลงผู้รับหลายรูปแบบเป็นอีเมลที่ Pi Notify รับ — คงรูปเดิม: ผู้รับเดี่ยว → string, array → array (ไม่ซ้ำ)
+ * - ผู้รับเดี่ยวที่ไม่มีอีเมล → โยน MailError "invalid": ผู้ใช้ที่ไม่มีอีเมลเป็น bug ของแอป อย่าให้เงียบ
+ * - ใน array กรอง null/undefined/ไม่มีอีเมลทิ้งได้ แต่ถ้าไม่เหลือสักคนก็ "invalid" เช่นกัน
+ */
+declare function toEmails(to: Recipient | Recipient[]): string | string[];
+
+/**
+ * ช่องทางแจ้งเตือนที่ hub รองรับ — ผู้รับผูกแชทเองที่ hub (/me) หรือผ่านลิงก์ที่แอปขอจาก hub
+ * `push` = web push ของเบราว์เซอร์ ผูกต่อแอป (service worker อยู่ที่โดเมนของแอปเอง)
+ */
+type NotifyChannel = "telegram" | "line" | "push" | "email";
+interface NotifyInput {
+    /**
+     * ผู้รับ (อีเมลตรงกับบัญชี Pi Auth) — ระบุได้สูงสุด 50 คน; ส่ง user object ที่มี `email` ได้เลย
+     * ผู้รับเดี่ยวที่ไม่มีอีเมลโยน MailError "invalid"; ใน array กรอง null/undefined ทิ้งให้
+     */
+    to: Recipient | Recipient[];
+    title: string;
+    /** ข้อความล้วน หรือ HTML จำกัดแท็ก (b/i/u/s/a/code/pre) — ระบุ format เมื่อไม่อยากให้ hub เดา */
+    body: string;
+    /** text = แสดงตามตัวอักษร (hub escape ให้), html = ตีความแท็ก; ไม่ระบุ = hub เดาจากเนื้อหา */
+    format?: "text" | "html";
+    /** ลิงก์ท้ายข้อความ (Telegram = ปุ่ม "เปิดลิงก์", อีเมล = ปุ่ม) */
+    link?: string;
+    /**
+     * ไม่ระบุ = ส่งทุกแชทที่ผู้รับผูกไว้; ไม่มีแชท → อีเมล
+     * ระบุ = เฉพาะที่ขอ; แชทที่ขอแต่ไม่ได้ผูก (และไม่ได้ขอ email) → skipped
+     */
+    channels?: NotifyChannel[];
+    /** ชื่อ provider ฝั่ง hub ที่อยากให้ลองก่อน */
+    prefer?: string;
+}
+interface NotifyResultItem {
+    to: string;
+    channel: NotifyChannel;
+    status: "sent" | "failed" | "skipped";
+    provider?: string;
+    id?: string;
+    failedOver?: boolean;
+    error?: string;
+    /**
+     * app_daily_cap = แอปส่งอีเมลแทนแชทครบเพดานรายวันที่ตั้งใน Pi Notify แล้ว
+     * no_push_provider = hub ยังไม่ได้ตั้ง provider web push
+     */
+    reason?: "no_link" | "channel_not_linked" | "no_chat_provider" | "no_push_provider" | "app_daily_cap";
+    /** (status failed) คำขอหมดงบเวลาก่อนได้เริ่มส่งรายการนี้ — ส่งซ้ำเฉพาะรายการนี้ได้ */
+    deferred?: boolean;
+}
+interface NotifyResult {
+    results: NotifyResultItem[];
+    sent: number;
+    failed: number;
+    skipped: number;
+    /** จำนวนที่ยังไม่ได้ส่งเพราะหมดงบเวลา (นับซ้อนอยู่ใน failed; Pi Notify รุ่นเก่าไม่ส่งมา) */
+    deferred?: number;
+}
+interface NotifyOptions {
+    /** ค่าเริ่มต้น PI_NOTIFY_KEY */
+    apiKey?: string;
+    /** ค่าเริ่มต้น PI_NOTIFY_URL หรือ https://notify.suphark.com */
+    url?: string;
+    fetch?: typeof fetch;
+    env?: Record<string, string | undefined>;
+    /**
+     * เวลารอ Pi Notify สูงสุด (ms) หมดแล้วโยน MailError kind "network"
+     * ค่าเริ่มต้น notify() 65000 (ยาวกว่า maxDuration 60 วิของ /api/v1/notify เล็กน้อย) · getRecipient()/createLink() 10000
+     */
+    timeoutMs?: number;
+}
+/** เวลารอเริ่มต้นของแต่ละคำสั่ง (ms) */
+declare const NOTIFY_TIMEOUT_MS: {
+    readonly notify: 65000;
+    readonly recipient: 10000;
+};
+/** subscription จากเบราว์เซอร์ (`PushSubscription.toJSON()`) */
+interface PushSubscriptionJson {
+    endpoint: string;
+    keys: {
+        p256dh: string;
+        auth: string;
+    };
+}
+interface PushDevice {
+    id: string;
+    label: string | null;
+    enabled: boolean;
+    /** ท่อนท้ายของ endpoint ไว้แยกเครื่อง (ไม่คืนค่าเต็ม) */
+    endpointTail: string;
+}
+/** ช่องทางที่ผู้รับผูกไว้ (จาก GET /api/v1/recipients/:email) — ไม่มี chat id */
+interface RecipientChannelInfo {
+    type: string;
+    label: string | null;
+    enabled: boolean;
+    disabledReason: string | null;
+    linkedAt: string;
+}
+interface RecipientInfo {
+    email: string;
+    channels: RecipientChannelInfo[];
+    /** หน้า hub ให้ผู้รับผูกเอง */
+    linkUrl: string;
+}
+/** มี PI_NOTIFY_KEY (ใน opts หรือ env) หรือไม่ — ให้ helper แบบ safe/later ใช้ตัดสินว่า "ปิดอยู่" */
+declare function hasNotifyKey(opts?: NotifyOptions): boolean;
+/**
+ * แจ้งเตือนผู้รับผ่าน Pi Notify hub — Telegram (ที่ผู้รับผูกไว้) หรืออีเมล
+ * ใช้ 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>;
+/** ช่องทางที่ผู้รับผูกไว้ — ไว้แสดง "ผูกแล้ว/ยังไม่ผูก" ในหน้าตั้งค่าของแอป */
+declare function getRecipient(email: Recipient, opts?: NotifyOptions): Promise<RecipientInfo>;
+/**
+ * ขอลิงก์ผูก Telegram ให้ผู้รับ (t.me/<bot>?start=<code>, หมดอายุ 10 นาที)
+ * แอปวางเป็นปุ่ม/QR ในหน้าตั้งค่าของตัวเอง แล้วโพล getRecipient() จนเห็น telegram
+ * `opts.piUserId` = user id ใน Pi Auth (sub) ของผู้ใช้ — ให้ Pi Notify ลบการผูกเมื่อบัญชีถูกลบ
+ */
+declare function createLink(email: Recipient, channel?: Exclude<NotifyChannel, "email">, opts?: NotifyOptions & {
+    piUserId?: string;
+}): Promise<{
+    channel: string;
+    url: string;
+    code: string;
+    expiresAt: string;
+}>;
+/** สถานะการผูกช่องทางหนึ่งของผู้รับ — แทนการ find ใน `getRecipient().channels` เองในแต่ละแอป */
+interface ChannelStatus {
+    linked: boolean;
+    label: string | null;
+    linkedAt: string | null;
+    /** หน้า Pi Notify ที่ผู้รับจัดการช่องทางเอง */
+    manageUrl: string;
+}
+/** ผู้รับที่ Pi Notify ยังไม่รู้จัก = channels ว่าง (`linked: false`) ไม่ใช่ error */
+declare function getChannelStatus(email: Recipient, channel?: Exclude<NotifyChannel, "email">, opts?: NotifyOptions): Promise<ChannelStatus>;
+/**
+ * VAPID public key ของ hub — ใช้เป็น `applicationServerKey` ตอน `pushManager.subscribe()`
+ * (ค่าสาธารณะ แคชฝั่งแอปได้) · hub ยังไม่ได้ตั้ง provider push → MailError kind "server"
+ */
+declare function getPushConfig(opts?: NotifyOptions): Promise<{
+    publicKey: string;
+}>;
+/**
+ * เก็บ subscription ของเบราว์เซอร์หนึ่งเครื่องไว้ที่ hub (ผูกกับแอปที่เรียกเสมอ)
+ * เรียกซ้ำด้วย endpoint เดิมได้ = อัปเดตกุญแจ/เปิดใช้คืน · `piUserId` ให้ hub ลบตามบัญชีที่ถูกลบได้
+ */
+declare function savePushSubscription(email: string, subscription: PushSubscriptionJson, opts?: NotifyOptions & {
+    label?: string;
+    piUserId?: string;
+}): Promise<{
+    ok: true;
+    created: boolean;
+}>;
+/** ผู้ใช้ปิดแจ้งเตือนที่เครื่องนั้น (ลบได้เฉพาะ subscription ของแอปตัวเอง) */
+declare function deletePushSubscription(email: string, endpoint: string, opts?: NotifyOptions): Promise<{
+    ok: true;
+    deleted: number;
+}>;
+/** เครื่องที่ผู้รับเปิดแจ้งเตือนไว้กับแอปนี้ — ไว้แสดงรายการในหน้าตั้งค่า */
+declare function listPushDevices(email: string, opts?: NotifyOptions): Promise<{
+    devices: PushDevice[];
+}>;
+
+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 };

package/package.json

@@ -1,14 +1,22 @@
 {
   "name": "@suphark/notify",
-  "version": "0.4.0",
+  "version": "0.5.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",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js",
+      "default": "./dist/next.js"
     }
   },
   "files": [
@@ -33,11 +41,20 @@
   "dependencies": {
     "nodemailer": "^10.0.14"
   },
+  "peerDependencies": {
+    "next": ">=15"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@biomejs/biome": "^2.5.15",
     "@pi/config": "workspace:*",
     "@types/node": "^24.13.4",
     "@types/nodemailer": "^8.0.1",
+    "next": "^16.3.8",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.11"