@suphark/notify 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,564 @@
+/** ที่อยู่อีเมล: "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;
+}
+/** ประเภทความผิดพลาด — ใช้ตัดสินใจว่าจะพัก 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[];
+}
+
+/** แปลง "ชื่อ <a@b.com>" / "a@b.com" / { name, email } → { name, email } */
+declare function parseAddress(input: Address): ParsedAddress;
+/** provider ที่ต้องมี from เสมอเรียกตัวนี้ (mailer รับประกันให้อยู่แล้ว ยกเว้น optionalFrom) */
+declare function requireFrom(msg: {
+    from?: ParsedAddress;
+}, provider: string): ParsedAddress;
+declare function parseAddressList(input: Address | Address[] | undefined): ParsedAddress[];
+/** { name, email } → "ชื่อ <a@b.com>" (สำหรับ API ที่รับ string) */
+declare function formatAddress(a: ParsedAddress): string;
+
+interface ConsoleOptions {
+    name?: string;
+    from?: ParsedAddress;
+    /** พิมพ์เนื้อหา html/text ด้วย (ค่าเริ่มต้น: แค่หัวอีเมล) */
+    body?: boolean;
+    log?: (line: string) => void;
+}
+/** ไม่ส่งจริง — พิมพ์ลง console (ใช้ตอน dev/test) */
+declare function createConsoleProvider(opts?: ConsoleOptions): Provider;
+
+/** Pi Notify hub ที่ deploy ไว้ — ฝังไว้เพื่อให้แอปใส่แค่ PI_NOTIFY_KEY */
+declare const DEFAULT_HUB_URL = "https://notify.suphark.com";
+interface HubOptions {
+    name?: string;
+    /** API key ของแอป (pn_...) ออกจากหน้า admin ของ Pi Notify */
+    apiKey: string;
+    /** override เมื่อรัน hub ที่อื่น (localhost, staging) */
+    url?: string;
+    from?: ParsedAddress;
+    fetch?: typeof fetch;
+}
+/** payload ที่ SDK ส่งให้ hub (POST /api/v1/send) — hub ใช้ schema เดียวกันตรวจ */
+interface HubSendRequest {
+    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>;
+    /** ชื่อ provider ที่อยากให้ hub ลองก่อน */
+    prefer?: string;
+}
+interface HubSendResponse {
+    id?: string;
+    provider: string;
+    failedOver: boolean;
+}
+/** error body ของ hub: { error: { kind, message, attempts? } } */
+interface HubErrorResponse {
+    error: {
+        kind?: ErrorKind;
+        message: string;
+        attempts?: unknown[];
+    };
+}
+/**
+ * ส่งผ่าน Pi Notify hub — hub เป็นคนถือ credential ของ Resend/SMTP/... และทำ failover เอง
+ * ถ้า hub ล่ม mailer ฝั่งแอปจะ failover ไป provider local ตัวถัดไป (ถ้าตั้งไว้)
+ */
+declare function createHubProvider(opts: HubOptions): Provider;
+
+interface ResendOptions {
+    name?: string;
+    apiKey: string;
+    from?: ParsedAddress;
+    /** ค่าเริ่มต้น https://api.resend.com */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+/** Resend (HTTP API) — https://resend.com/docs/api-reference/emails/send-email */
+declare function createResendProvider(opts: ResendOptions): Provider;
+
+interface SmtpOptions {
+    name?: string;
+    host: string;
+    /** ค่าเริ่มต้น 465 ถ้า secure, ไม่งั้น 587 */
+    port?: number;
+    /** true = TLS ทันที (465) · false = STARTTLS (587) · ไม่ระบุ = เดาจาก port */
+    secure?: boolean;
+    user?: string;
+    pass?: string;
+    from?: ParsedAddress;
+    /** ใช้ connection pool (เหมาะกับส่งเยอะ) */
+    pool?: boolean;
+    /** timeout ต่อการเชื่อมต่อ (ms) ค่าเริ่มต้น 15000 */
+    timeoutMs?: number;
+    /** ยอมรับ cert ที่ไม่ผ่านการตรวจ (self-signed) — ใช้เฉพาะ SMTP ภายในองค์กร */
+    rejectUnauthorized?: boolean;
+    /** ชื่อ type ที่รายงาน (smtp/zoho/gmail/...) */
+    type?: string;
+}
+/** SMTP ทั่วไป ผ่าน nodemailer — ใช้กับ SMTP บริษัท, Zoho, Gmail, Office 365 ฯลฯ */
+declare function createSmtpProvider(opts: SmtpOptions): Provider;
+/** preset ของผู้ให้บริการที่ใช้บ่อย — ใส่แค่ user/pass */
+declare const SMTP_PRESETS: {
+    readonly zoho: {
+        readonly host: "smtp.zoho.com";
+        readonly port: 465;
+        readonly secure: true;
+    };
+    /** Zoho Mail แบบองค์กร (custom domain) — บาง region ต้องใช้ smtppro.zoho.com */
+    readonly zohopro: {
+        readonly host: "smtppro.zoho.com";
+        readonly port: 465;
+        readonly secure: true;
+    };
+    readonly gmail: {
+        readonly host: "smtp.gmail.com";
+        readonly port: 465;
+        readonly secure: true;
+    };
+    readonly office365: {
+        readonly host: "smtp.office365.com";
+        readonly port: 587;
+        readonly secure: false;
+    };
+    /** Brevo (Sendinblue) SMTP */
+    readonly brevo: {
+        readonly host: "smtp-relay.brevo.com";
+        readonly port: 587;
+        readonly secure: false;
+    };
+    /** Mailtrap sandbox (ทดสอบ) */
+    readonly mailtrap: {
+        readonly host: "sandbox.smtp.mailtrap.io";
+        readonly port: 2525;
+        readonly secure: false;
+    };
+};
+type SmtpPreset = keyof typeof SMTP_PRESETS;
+declare function createPresetSmtpProvider(preset: SmtpPreset, opts: Omit<SmtpOptions, "host" | "type"> & {
+    host?: string;
+}): Provider;
+
+interface ZeptoMailOptions {
+    name?: string;
+    /** Send Mail token (ไม่ต้องใส่คำว่า Zoho-enczapikey) */
+    apiKey: string;
+    from?: ParsedAddress;
+    /** region ของบัญชี Zoho: com (default), eu, in, com.au, jp, ... หรือระบุ baseUrl เอง */
+    region?: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+/** Zoho ZeptoMail (transactional email API) — https://www.zoho.com/zeptomail/help/api/email-sending.html */
+declare function createZeptoMailProvider(opts: ZeptoMailOptions): Provider;
+
+interface Common {
+    /** ชื่อไว้อ้างอิงใน log/status (ค่าเริ่มต้น = type) */
+    name?: string;
+    /**
+     * ตัวตนผู้ส่งของ provider นี้ — ถ้า message.from ไม่อยู่ใน senderDomains จะใช้ที่อยู่นี้แทน (คงชื่อจาก message)
+     * ไม่ตั้ง = provider ส่งจากที่อยู่ไหนก็ได้ (hub, console) และใช้ from ของ message/mailer ตามลำดับ
+     */
+    from?: Address;
+    /**
+     * โดเมนที่ provider นี้ส่งได้ (เช่น Resend ที่ verify หลายโดเมน) — ค่าเริ่มต้น = ต้องตรงที่อยู่ของ from เป๊ะ
+     * (SMTP ส่วนใหญ่บังคับ From ให้ตรงบัญชีที่ล็อกอิน)
+     */
+    senderDomains?: string[];
+    /** เพดานที่เราตั้งเอง — ถึงแล้ว mailer จะข้ามไปตัวถัดไปโดยไม่ต้องรอ provider ตอบ error */
+    quota?: Quota;
+    /** ปิดชั่วคราวโดยไม่ต้องลบ config */
+    disabled?: boolean;
+}
+type Opt<T> = Omit<T, "name" | "from">;
+type ProviderConfig = ({
+    type: "hub";
+} & Common & Opt<HubOptions>) | ({
+    type: "resend";
+} & Common & Opt<ResendOptions>) | ({
+    type: "smtp";
+} & Common & Opt<SmtpOptions>) | ({
+    type: SmtpPreset;
+} & Common & Opt<Omit<SmtpOptions, "host" | "type">> & {
+    host?: string;
+}) | ({
+    type: "zeptomail";
+} & Common & Opt<ZeptoMailOptions>) | ({
+    type: "console";
+} & Common & Opt<ConsoleOptions>)
+/** provider ที่เขียนเอง (implement interface Provider) */
+ | ({
+    type: "custom";
+    provider: Provider;
+} & Common);
+
+type Env = Record<string, string | undefined>;
+/**
+ * อ่าน provider จาก env — รูปแบบ:
+ *
+ *   MAIL_PROVIDERS=resend,company,zoho        ← ลำดับ = ลำดับความสำคัญ
+ *   MAIL_RESEND_API_KEY=re_xxx                ← ชื่อที่ตรงกับ type ไม่ต้องใส่ _TYPE
+ *   MAIL_COMPANY_TYPE=smtp                    ← ชื่ออื่นต้องบอก _TYPE (หรือมี _HOST → smtp)
+ *   MAIL_COMPANY_HOST=... _PORT _SECURE _USER _PASS _FROM _QUOTA_DAY ...
+ *
+ * PI_NOTIFY_KEY=pn_xxx → ใส่ Pi Notify hub เป็นตัวแรกเสมอ (PI_NOTIFY_URL override ได้) ตัวอื่นเป็นสำรอง
+ * ไม่มี MAIL_PROVIDERS → เดาจาก PI_NOTIFY_KEY / RESEND_API_KEY / SMTP_HOST (zero-config)
+ */
+declare function providersFromEnv(env?: Env): ProviderConfig[];
+
+interface MailerOptions {
+    /** รายการ provider เรียงตามลำดับความสำคัญ — ไม่ใส่ = อ่านจาก env (ดู providersFromEnv) */
+    providers?: (ProviderConfig | Provider)[];
+    /** from เริ่มต้นเมื่อ message และ provider ไม่ได้ระบุ (env: MAIL_FROM) */
+    from?: Address;
+    /**
+     * priority (ค่าเริ่มต้น) = ใช้ตัวแรกเสมอ ตัวถัดไปเป็นสำรอง
+     * round-robin = หมุนเวียนทุกตัวที่พร้อมใช้ (กระจายโควต้า)
+     */
+    strategy?: "priority" | "round-robin";
+    /** ที่เก็บ state โควต้า/cooldown — ค่าเริ่มต้น memory; ใช้ createRedisStore เพื่อแชร์ข้ามแอป */
+    store?: Store;
+    /** เวลาพัก (วินาที) ต่อ error แต่ละแบบ (override DEFAULT_COOLDOWN บางค่าได้) */
+    cooldown?: Partial<Record<ErrorKind, number>>;
+    maxCooldownSec?: number;
+    /** timeout ต่อการส่ง 1 ครั้งต่อ provider (ms) ค่าเริ่มต้น 20000 */
+    timeoutMs?: number;
+    /** รับ event (sent/failed/cooldown/...) ไปต่อ logger ของแอป */
+    onEvent?: (e: MailerEvent) => void;
+    /** พิมพ์ event ลง console (env: MAIL_DEBUG=1) */
+    debug?: boolean;
+    /** env ที่ใช้อ่าน config (ค่าเริ่มต้น process.env) */
+    env?: Env;
+}
+interface Mailer {
+    /** ส่งอีเมล — ลองตาม provider ทีละตัวจนกว่าจะสำเร็จ; โยน AllProvidersFailedError ถ้าไม่สำเร็จเลย */
+    send(message: Message): Promise<SendResult>;
+    /** สถานะ provider ทุกตัว (cooldown, โควต้าที่ใช้ไป) */
+    status(): Promise<ProviderStatus[]>;
+    /** ตัวเลือกที่มีแบบย่อ (ชื่อ/ประเภท/พร้อมใช้) — ถ้ามี hub จะถามรายการข้างหลัง hub มาให้ด้วย */
+    listProviders(): Promise<ProviderInfo[]>;
+    /** ทดสอบการเชื่อมต่อของทุก provider (ไม่ส่งอีเมล) */
+    verify(): Promise<Record<string, {
+        ok: boolean;
+        error?: string;
+    }>>;
+    /** ล้าง cooldown ของ provider (ไม่ระบุ = ทุกตัว) */
+    reset(name?: string): Promise<void>;
+    /** ชื่อ provider ตามลำดับ */
+    readonly providers: string[];
+}
+declare function createMailer(options?: MailerOptions): Mailer;
+
+/**
+ * ตั้งค่า mailer กลางของแอป (เรียกครั้งเดียวตอนบูต) — ไม่เรียกก็ได้ ถ้าใช้ env ล้วน
+ * @example configureMailer({ providers: [...], onEvent: (e) => logger.info(e) })
+ */
+declare function configureMailer(options: MailerOptions): Mailer;
+/** mailer กลาง (สร้างจาก env ครั้งแรกที่เรียก) */
+declare function getMailer(): Mailer;
+/**
+ * ทางลัดที่สั้นที่สุด — อ่าน config จาก env แล้วส่งเลย
+ * @example await sendMail({ to: "a@b.com", subject: "สวัสดี", html: "<p>...</p>" })
+ */
+declare function sendMail(message: Message): Promise<SendResult>;
+/**
+ * ตัวเลือกที่มี (ชื่อ/ประเภท/พร้อมใช้) — ใช้แสดงให้ผู้ใช้เลือกแล้วส่งด้วย { prefer: name }
+ * @example (await listProviders()) → [{ name: "resend", type: "resend", available: true, via: "hub" }, ...]
+ */
+declare function listProviders(): Promise<ProviderInfo[]>;
+/** ใช้ในเทสต์: ทิ้ง instance กลางเพื่อสร้างใหม่ด้วย env/options อื่น */
+declare function resetMailer(): void;
+
+declare class MailError extends Error {
+    readonly kind: ErrorKind;
+    readonly provider?: string;
+    readonly status?: number;
+    constructor(message: string, opts?: {
+        kind?: ErrorKind;
+        provider?: string;
+        status?: number;
+        cause?: unknown;
+    });
+}
+/** ส่งไม่สำเร็จเลยสักตัว — ดู attempts ว่าแต่ละตัวพังเพราะอะไร */
+declare class AllProvidersFailedError extends MailError {
+    readonly attempts: Attempt[];
+    constructor(attempts: Attempt[]);
+}
+/** เดา ErrorKind จาก error ของ nodemailer / fetch / provider API (ไม่มีทางแม่น 100% แต่ครอบคลุมเคสหลัก) */
+declare function classifyError(err: unknown): {
+    kind: ErrorKind;
+    message: string;
+    status?: number;
+};
+
+/** เวลาพัก (วินาที) ต่อ 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[];
+    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;
+    reason?: "no_link" | "channel_not_linked" | "no_chat_provider";
+}
+interface NotifyResult {
+    results: NotifyResultItem[];
+    sent: number;
+    failed: number;
+    skipped: 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>;
+}
+/** ช่องทางที่ผู้รับผูกไว้ (จาก 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 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: string, opts?: NotifyOptions): Promise<RecipientInfo>;
+/**
+ * ขอลิงก์ผูก Telegram ให้ผู้รับ (t.me/<bot>?start=<code>, หมดอายุ 10 นาที)
+ * แอปวางเป็นปุ่ม/QR ในหน้าตั้งค่าของตัวเอง แล้วโพล getRecipient() จนเห็น telegram
+ */
+declare function createLink(email: string, channel?: Exclude<NotifyChannel, "email">, opts?: NotifyOptions): Promise<{
+    channel: string;
+    url: string;
+    expiresAt: string;
+}>;
+
+/** Store ใน memory ของ process (ค่าเริ่มต้น) — state หายเมื่อ restart และไม่แชร์ข้าม instance */
+declare function createMemoryStore(): Store;
+
+/** client ขั้นต่ำที่ต้องมี — ioredis, node-redis (v4+) และ @upstash/redis ใช้ได้เลย */
+interface RedisLike {
+    get(key: string): Promise<string | number | null>;
+    set(key: string, value: string): Promise<unknown>;
+    incr(key: string): Promise<number>;
+    decr(key: string): Promise<number>;
+    expire(key: string, seconds: number): Promise<unknown>;
+    del(key: string): Promise<unknown>;
+}
+/**
+ * Store บน Redis — ใช้เมื่อรันหลาย instance หรืออยากให้หลายแอปแชร์โควต้า/cooldown ของ provider เดียวกัน
+ *
+ * @example
+ *   import Redis from "ioredis";
+ *   createMailer({ store: createRedisStore(new Redis(process.env.REDIS_URL)) })
+ */
+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, 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 };