@suphark/notify 0.3.1 → 0.5.0

package/dist/index.d.ts

@@ -1,172 +1,5 @@
-/** ที่อยู่อีเมล: "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[];
-}
+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';
 
 /** แปลง "ชื่อ <a@b.com>" / "a@b.com" / { name, email } → { name, email } */
 declare function parseAddress(input: Address): ParsedAddress;
@@ -469,102 +302,133 @@ declare function classifyError(err: unknown): {
     retryAfterSec?: number;
 };
 
+/**
+ * รูปแบบของ body ที่ใช้ร่วมทุกช่องทาง (อีเมล, Telegram, LINE ที่จะมาทีหลัง, push)
+ * ช่องทางที่ไม่รองรับ HTML ใช้ `toPlainText` ตัวเดียวกัน — แหล่งความจริงเดียวของ Pi Notify (hub import จากแพ็กเกจนี้)
+ */
+type BodyFormat = "text" | "html";
+/**
+ * ดูว่าข้อความน่าจะเป็น HTML หรือข้อความล้วน — นับเฉพาะแท็กที่รู้จัก
+ * ("บัตร <KBank>" หรือ "a < b" ถือเป็นข้อความล้วน; แอปที่แน่ใจให้ส่ง format มาแทนการเดา)
+ */
+declare function looksLikeHtml(s: string): boolean;
+declare function resolveFormat(body: string, format?: string): BodyFormat;
+/** ตัดแท็กทั้งหมดเป็นข้อความล้วน (Telegram ใช้ส่งซ้ำเมื่อ parse HTML ไม่ผ่าน; LINE/อีเมล/push ใช้เป็นเนื้อหลัก) */
+declare function toPlainText(html: string): string;
+
 /** เวลาพัก (วินาที) ต่อ error แต่ละแบบ ก่อนกลับมาลอง provider นั้นอีก — คูณสองทุกครั้งที่พังซ้ำ */
 declare const DEFAULT_COOLDOWN: Record<ErrorKind, number>;
 
-/** ช่องทางแจ้งเตือนที่ hub รองรับ — ผู้รับผูกแชทเองที่ hub (/me) หรือผ่านลิงก์ที่แอปขอจาก hub */
-type NotifyChannel = "telegram" | "line" | "email";
-interface NotifyInput {
-    /** อีเมลผู้รับ (ตรงกับบัญชี Pi Auth) — ระบุได้สูงสุด 50 คน */
-    to: string | string[];
+/** ผู้ใช้ที่ล็อกอินอยู่ในแอป — **ต้องมาจาก session ฝั่ง server เท่านั้น** ห้ามรับอีเมลจาก client */
+interface PushUser {
+    email: string;
+    /** user id ใน Pi Auth (sub) — ให้ Pi Notify ลบ subscription ตามบัญชีที่ถูกลบ */
+    id?: string;
+}
+/** รูปที่ `PushSubscription.toJSON()` ของเบราว์เซอร์ส่งมา (field optional ตาม DOM type) */
+interface BrowserPushSubscription {
+    endpoint?: string;
+    keys?: Record<string, string | undefined>;
+}
+interface PushHandlersOptions extends NotifyOptions {
+    /** ดึงผู้ใช้จาก session ของแอป — คืน null/undefined = ยังไม่ล็อกอิน */
+    getUser: () => PushUser | null | undefined | Promise<PushUser | null | undefined>;
+}
+interface PushHandlers {
+    /** VAPID public key สำหรับ `pushManager.subscribe({ applicationServerKey })` */
+    getPublicKey(): Promise<string>;
+    subscribe(subscription: BrowserPushSubscription, opts?: {
+        label?: string;
+    }): Promise<{
+        ok: true;
+        created: boolean;
+    }>;
+    unsubscribe(endpoint: string): Promise<{
+        ok: true;
+        deleted: number;
+    }>;
+    listDevices(): Promise<{
+        devices: PushDevice[];
+    }>;
+}
+/**
+ * ชุดฟังก์ชันสำหรับ Server Actions ของ `<WebPushRow />` — แอปส่งแค่ `getUser`
+ * (ใน `"use server"` ห่อเป็น `export async function` ทีละตัว; ห้าม import SDK ใน Client Component)
+ */
+declare function createPushHandlers(options: PushHandlersOptions): PushHandlers;
+interface PushServiceWorkerOptions {
+    /** ไอคอนของการแจ้งเตือน (path ในแอป) ค่าเริ่มต้น /icon-192.png */
+    icon?: string;
+    /** ลิงก์ที่เปิดเมื่อ payload ไม่มี link ค่าเริ่มต้น / */
+    defaultLink?: string;
+}
+/** ซอร์ส service worker ที่รับ push ของ Pi Notify (payload { title, body, link? }) — เปิดเฉพาะลิงก์ใน origin ของแอป */
+declare function pushServiceWorkerSource(options?: PushServiceWorkerOptions): string;
+/**
+ * Route Handler ที่เสิร์ฟ service worker จากตัวแพ็กเกจเอง (same-origin, ล็อกเวอร์ชันผ่าน npm)
+ * @example // app/sw.js/route.ts
+ * export const GET = pushServiceWorker();
+ * ไม่แนะนำให้ importScripts จากโดเมนอื่น: service worker คุมทั้ง origin ของแอปและดักทุก request
+ */
+declare function pushServiceWorker(options?: PushServiceWorkerOptions): () => Response;
+
+interface NotifyEmailInput {
     title: string;
-    /** ข้อความล้วน หรือ HTML จำกัดแท็ก (b/i/u/s/a/code/pre) — ระบุ format เมื่อไม่อยากให้ hub เดา */
     body: string;
-    /** text = แสดงตามตัวอักษร (hub escape ให้), html = ตีความแท็ก; ไม่ระบุ = hub เดาจากเนื้อหา */
-    format?: "text" | "html";
-    /** ลิงก์ท้ายข้อความ (Telegram = ปุ่ม "เปิดลิงก์", อีเมล = ปุ่ม) */
+    /** ไม่ระบุ = เดาจากเนื้อหา (นับเฉพาะแท็กที่รู้จัก) */
+    format?: "text" | "html" | (string & {});
     link?: string;
-    /**
-     * ไม่ระบุ = ส่งทุกแชทที่ผู้รับผูกไว้; ไม่มีแชท → อีเมล
-     * ระบุ = เฉพาะที่ขอ; แชทที่ขอแต่ไม่ได้ผูก (และไม่ได้ขอ email) → skipped
-     */
-    channels?: NotifyChannel[];
-    /** ชื่อ provider ฝั่ง hub ที่อยากให้ลองก่อน */
-    prefer?: string;
+    /** ข้อความบนปุ่ม/หน้าลิงก์ในอีเมล ค่าเริ่มต้น "เปิดลิงก์" */
+    linkLabel?: string;
+    /** ชื่อแอป แสดงท้ายอีเมล */
+    appName?: string;
+    /** สีปุ่ม (hex เท่านั้น — ค่าอื่นถูกเมินกัน CSS injection) ค่าเริ่มต้น #1d4ed8 */
+    accent?: string;
 }
-interface NotifyResultItem {
-    to: string;
-    channel: NotifyChannel;
-    status: "sent" | "failed" | "skipped";
-    provider?: string;
-    id?: string;
-    failedOver?: boolean;
-    error?: string;
-    /** app_daily_cap = แอปส่งอีเมลแทนแชทครบเพดานรายวันที่ตั้งใน Pi Notify แล้ว */
-    reason?: "no_link" | "channel_not_linked" | "no_chat_provider" | "app_daily_cap";
-    /** (status failed) คำขอหมดงบเวลาก่อนได้เริ่มส่งรายการนี้ — ส่งซ้ำเฉพาะรายการนี้ได้ */
-    deferred?: boolean;
-}
-interface NotifyResult {
-    results: NotifyResultItem[];
+/**
+ * แปลงแจ้งเตือน (title/body/link) เป็นอีเมล — layout เดียวกับที่ Pi Notify ใช้ส่งแทนแชท (หัวข้อ ย่อหน้า ปุ่มเดียว)
+ * ใช้คู่ sendMail เมื่อแอปอยากได้หน้าตาเดียวกันโดยไม่ต้องเขียน HTML เอง:
+ * `sendMail({ to, ...renderNotifyEmail({ title, body, link }) })` — body เป็นข้อความล้วนเสมอ ถูก escape ให้
+ */
+declare function renderNotifyEmail(input: NotifyEmailInput): {
+    subject: string;
+    text: string;
+    html: string;
+};
+
+interface NotifySafeResult {
+    /** ไม่มี error และไม่มีรายการ failed — skipped (เช่นยังไม่ผูกช่องทาง) ไม่นับเป็นความล้มเหลว */
+    ok: boolean;
     sent: number;
     failed: number;
     skipped: number;
-    /** จำนวนที่ยังไม่ได้ส่งเพราะหมดงบเวลา (นับซ้อนอยู่ใน failed; Pi Notify รุ่นเก่าไม่ส่งมา) */
     deferred?: number;
+    /** ผลรายผู้รับ/ช่องทาง (มีแม้ Pi Notify ตอบ 502 — ดึงจาก body) */
+    results: NotifyResultItem[];
+    /** ข้อความ error (ไม่มีอีเมลผู้รับ/เนื้อหา) */
+    error?: string;
+    /** ไม่มี PI_NOTIFY_KEY — แอปตั้งใจปิดแจ้งเตือน (dev/test) จึงไม่ส่งและไม่ถือเป็น error */
+    disabled?: boolean;
 }
-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;
-};
-/** ช่องทางที่ผู้รับผูกไว้ (จาก 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;
-}
+/** ใช้ในเทสต์: ให้คำเตือน "ปิดอยู่" ครั้งเดียวของโหมด dev/test ออกมาอีกรอบ */
+declare function resetSafeWarnings(): void;
 /**
- * แจ้งเตือนผู้รับผ่าน Pi Notify hub — Telegram (ที่ผู้รับผูกไว้) หรืออีเมล
- * ใช้ env เดียวกับ sendMail(): PI_NOTIFY_KEY (+ PI_NOTIFY_URL)
- * โยน MailError เมื่อ hub ตอบ non-2xx (502 = ไม่มีช่องทางไหนส่งสำเร็จเลย; results อยู่ใน err.cause)
+ * notify() ที่ไม่โยนเด็ดขาด — ไว้ใช้ตรงที่การแจ้งเตือนเป็นแค่ผลพลอยได้ของงานหลัก (best-effort)
+ * ต้องรู้ผลแน่ชัดหรืออยากให้ cron ลองใหม่ → ใช้ notify() ที่โยน
+ * ไม่มี PI_NOTIFY_KEY → { ok: false, disabled: true } ไม่ส่ง
  */
-declare function notify(input: NotifyInput, opts?: NotifyOptions): Promise<NotifyResult>;
-/** ช่องทางที่ผู้รับผูกไว้ — ไว้แสดง "ผูกแล้ว/ยังไม่ผูก" ในหน้าตั้งค่าของแอป */
-declare function getRecipient(email: string, 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: string, channel?: Exclude<NotifyChannel, "email">, opts?: NotifyOptions & {
-    piUserId?: string;
-}): Promise<{
-    channel: string;
-    url: string;
-    expiresAt: string;
-}>;
+declare function notifySafe(input: NotifyInput, opts?: NotifyOptions): Promise<NotifySafeResult>;
+interface SendMailSafeResult {
+    ok: boolean;
+    provider?: string;
+    id?: string;
+    failedOver?: boolean;
+    error?: string;
+    /** ไม่มี provider ให้ส่งเลย (ไม่ได้ตั้ง PI_NOTIFY_KEY หรือ provider อื่น) — แอปตั้งใจปิดอีเมล (dev/test) */
+    disabled?: boolean;
+}
+/** sendMail() ที่ไม่โยนเด็ดขาด — ไม่มี provider เลย → { ok: false, disabled: true } */
+declare function sendMailSafe(message: Message): Promise<SendMailSafeResult>;
 
 /** Store ใน memory ของ process (ค่าเริ่มต้น) — state หายเมื่อ restart และไม่แชร์ข้าม instance */
 declare function createMemoryStore(): Store;
@@ -589,4 +453,4 @@ declare function createRedisStore(client: RedisLike, opts?: {
     prefix?: string;
 }): Store;
 
-export { type Address, AllProvidersFailedError, type Attachment, type Attempt, type ConsoleOptions, DEFAULT_COOLDOWN, DEFAULT_HUB_URL, type Env, type ErrorKind, type HubErrorResponse, type HubOptions, type HubSendRequest, type HubSendResponse, MailError, type Mailer, type MailerEvent, type MailerOptions, type Message, NOTIFY_TIMEOUT_MS, type NormalizedMessage, type NotifyChannel, type NotifyInput, type NotifyOptions, type NotifyResult, type NotifyResultItem, type ParsedAddress, type Provider, type ProviderConfig, type ProviderInfo, type ProviderStatus, type Quota, type QuotaUsage, type RecipientChannelInfo, type RecipientInfo, type RedisLike, type ResendOptions, SMTP_PRESETS, type SendResult, type SkipReason, type SmtpOptions, type SmtpPreset, type Store, type ZeptoMailOptions, classifyError, configureMailer, createConsoleProvider, createHubProvider, createLink, createMailer, createMemoryStore, createPresetSmtpProvider, createRedisStore, createResendProvider, createSmtpProvider, createZeptoMailProvider, formatAddress, getMailer, getRecipient, listProviders, notify, parseAddress, parseAddressList, providersFromEnv, requireFrom, resetMailer, sendMail };
+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 };