@ubean/server 0.1.13 → 0.2.0

package/dist/email-BvpEuNn_.d.ts

@@ -0,0 +1,226 @@
+//#region src/email.d.ts
+/**
+ * P9-25 邮件发送原语 —— Email sending primitives
+ *
+ * 内置邮件发送原语,提供 provider 抽象层。支持三种内置 provider:
+ * - `log`   开发环境,将邮件内容输出到 console(或自定义 logger)
+ * - `smtp`  生产环境,通过 nodemailer(可选 peer dependency)配置 SMTP/sendmail
+ * - `mock`  测试环境,捕获发送的邮件以便断言
+ *
+ * 设计对齐 `storage.ts` 的 driver 抽象与 `queue.ts` 的全局 driver 注册模式:
+ * - `defineEmailProvider(options)` 定义并注册一个 provider
+ * - `createEmailTransport(provider)` 从 provider 配置创建 transport
+ * - `sendEmail(options)` 使用全局默认 transport 发送邮件
+ * - `renderEmailTemplate(template, data)` 简单字符串插值渲染
+ *
+ * 用法:
+ * ```typescript
+ * import { defineEmailProvider, sendEmail, renderEmailTemplate } from '@ubean/server';
+ *
+ * // 定义默认 provider(开发环境用 log)
+ * defineEmailProvider({ type: 'log', default: true });
+ *
+ * // 发送邮件
+ * await sendEmail({
+ *   to: 'user@example.com',
+ *   from: 'noreply@example.com',
+ *   subject: 'Welcome',
+ *   html: renderEmailTemplate('<h1>Hello {{name}}</h1>', { name: 'Alice' }),
+ *   text: 'Hello Alice'
+ * });
+ * ```
+ */
+/**
+ * 邮件附件
+ */
+interface EmailAttachment {
+  filename: string;
+  content: string | Buffer | Uint8Array;
+  contentType?: string;
+  /** 当 content 为字符串时的编码方式(如 'base64') */
+  encoding?: string;
+  /** 内联附件的 content-id(用于在 HTML 中引用) */
+  cid?: string;
+}
+/**
+ * 发送邮件选项
+ */
+interface EmailOptions {
+  to: string | string[];
+  from: string;
+  subject: string;
+  html?: string;
+  text?: string;
+  cc?: string | string[];
+  bcc?: string | string[];
+  replyTo?: string;
+  attachments?: EmailAttachment[];
+  headers?: Record<string, string>;
+}
+/**
+ * 发送邮件结果
+ */
+interface EmailResult {
+  messageId: string;
+  response?: string;
+  provider: string;
+}
+/**
+ * 邮件传输层接口
+ */
+interface EmailTransport {
+  send(options: EmailOptions): Promise<EmailResult>;
+  verify?(): Promise<boolean>;
+  close?(): Promise<void>;
+}
+/**
+ * Mock transport —— 额外暴露已发送邮件列表,用于测试断言
+ */
+interface MockEmailTransport extends EmailTransport {
+  readonly sent: EmailOptions[];
+  clear(): void;
+}
+type EmailProviderType = 'log' | 'smtp' | 'mock' | 'sendmail';
+/**
+ * Log provider 配置(开发环境)
+ */
+interface LogEmailProviderConfig {
+  type: 'log';
+  logger?: (message: string) => void;
+}
+/**
+ * SMTP provider 配置(生产环境,nodemailer)
+ */
+interface SmtpEmailProviderConfig {
+  type: 'smtp';
+  host: string;
+  port: number;
+  secure?: boolean;
+  auth?: {
+    user: string;
+    pass: string;
+  };
+  /** 透传给 nodemailer 的额外选项 */
+  extra?: Record<string, unknown>;
+}
+/**
+ * Mock provider 配置(测试环境)
+ */
+interface MockEmailProviderConfig {
+  type: 'mock';
+}
+/**
+ * Sendmail provider 配置(本地 sendmail 命令)
+ */
+interface SendmailEmailProviderConfig {
+  type: 'sendmail';
+  path?: string;
+  args?: string[];
+}
+/**
+ * provider 配置联合类型(判别联合,以 `type` 字段区分)
+ */
+type EmailProviderConfig = LogEmailProviderConfig | SmtpEmailProviderConfig | MockEmailProviderConfig | SendmailEmailProviderConfig;
+/**
+ * `defineEmailProvider` 的选项 —— 在 provider 配置基础上增加 `name` 和 `default`
+ */
+type DefineEmailProviderOptions = EmailProviderConfig & {
+  name?: string;
+  default?: boolean;
+};
+/**
+ * 邮件 provider 定义
+ */
+interface EmailProvider {
+  readonly type: EmailProviderType;
+  readonly name?: string;
+  readonly config: EmailProviderConfig;
+}
+/**
+ * 定义并注册一个邮件 provider
+ *
+ * @example
+ * ```typescript
+ * // 开发环境
+ * defineEmailProvider({ type: 'log', default: true });
+ *
+ * // 生产环境
+ * defineEmailProvider({
+ *   type: 'smtp',
+ *   name: 'primary',
+ *   default: true,
+ *   host: 'smtp.example.com',
+ *   port: 587,
+ *   auth: { user: 'postmaster', pass: 'secret' }
+ * });
+ * ```
+ */
+declare function defineEmailProvider(options: DefineEmailProviderOptions): EmailProvider;
+/**
+ * 从 provider 配置创建 transport
+ */
+declare function createEmailTransport(provider: EmailProvider): EmailTransport;
+/**
+ * 设置全局默认 provider(并立即创建其 transport)
+ */
+declare function setDefaultEmailProvider(provider: EmailProvider): void;
+/**
+ * 获取全局默认 provider。若尚未设置,则惰性创建一个 `log` provider。
+ */
+declare function useEmailProvider(): EmailProvider;
+/**
+ * 获取全局默认 transport。若尚未设置,则惰性创建一个 `log` transport。
+ */
+declare function getEmailTransport(): EmailTransport;
+/**
+ * 按名称获取已注册的 provider
+ */
+declare function getEmailProvider(name: string): EmailProvider | undefined;
+/**
+ * 获取所有已注册的 provider 名称
+ */
+declare function getEmailProviderNames(): string[];
+/**
+ * 使用全局默认 transport 发送邮件
+ *
+ * @example
+ * ```typescript
+ * await sendEmail({
+ *   to: 'user@example.com',
+ *   from: 'noreply@example.com',
+ *   subject: 'Welcome',
+ *   html: '<h1>Welcome!</h1>',
+ *   text: 'Welcome!'
+ * });
+ * ```
+ */
+declare function sendEmail(options: EmailOptions): Promise<EmailResult>;
+/**
+ * 简单模板渲染 —— `{{key}}` 字符串插值,支持点号嵌套路径
+ *
+ * @example
+ * ```typescript
+ * renderEmailTemplate('Hello {{user.name}}, your code is {{code}}', {
+ *   user: { name: 'Alice' },
+ *   code: '123456'
+ * });
+ * // => 'Hello Alice, your code is 123456'
+ * ```
+ */
+declare function renderEmailTemplate(template: string, data: Record<string, unknown>): string;
+/**
+ * 获取全局 mock transport 捕获的已发送邮件。
+ * 若全局 transport 不是 mock,则返回空数组。
+ */
+declare function getSentEmails(): EmailOptions[];
+/**
+ * 清空全局 mock transport 捕获的已发送邮件。
+ * 若全局 transport 不是 mock,则不做任何操作。
+ */
+declare function clearSentEmails(): void;
+/**
+ * 清除所有 provider 注册表与全局状态(主要用于测试隔离)
+ */
+declare function clearEmailProviders(): void;
+//#endregion
+export { sendEmail as C, renderEmailTemplate as S, useEmailProvider as T, defineEmailProvider as _, EmailProviderConfig as a, getEmailTransport as b, EmailTransport as c, MockEmailTransport as d, SendmailEmailProviderConfig as f, createEmailTransport as g, clearSentEmails as h, EmailProvider as i, LogEmailProviderConfig as l, clearEmailProviders as m, EmailAttachment as n, EmailProviderType as o, SmtpEmailProviderConfig as p, EmailOptions as r, EmailResult as s, DefineEmailProviderOptions as t, MockEmailProviderConfig as u, getEmailProvider as v, setDefaultEmailProvider as w, getSentEmails as x, getEmailProviderNames as y };

package/dist/email.d.ts

@@ -0,0 +1,2 @@
+import { C as sendEmail, S as renderEmailTemplate, T as useEmailProvider, _ as defineEmailProvider, a as EmailProviderConfig, b as getEmailTransport, c as EmailTransport, d as MockEmailTransport, f as SendmailEmailProviderConfig, g as createEmailTransport, h as clearSentEmails, i as EmailProvider, l as LogEmailProviderConfig, m as clearEmailProviders, n as EmailAttachment, o as EmailProviderType, p as SmtpEmailProviderConfig, r as EmailOptions, s as EmailResult, t as DefineEmailProviderOptions, u as MockEmailProviderConfig, v as getEmailProvider, w as setDefaultEmailProvider, x as getSentEmails, y as getEmailProviderNames } from "./email-BvpEuNn_.js";
+export { DefineEmailProviderOptions, EmailAttachment, EmailOptions, EmailProvider, EmailProviderConfig, EmailProviderType, EmailResult, EmailTransport, LogEmailProviderConfig, MockEmailProviderConfig, MockEmailTransport, SendmailEmailProviderConfig, SmtpEmailProviderConfig, clearEmailProviders, clearSentEmails, createEmailTransport, defineEmailProvider, getEmailProvider, getEmailProviderNames, getEmailTransport, getSentEmails, renderEmailTemplate, sendEmail, setDefaultEmailProvider, useEmailProvider };

package/dist/email.js

@@ -0,0 +1,2 @@
+import { a as getEmailProvider, c as getSentEmails, d as setDefaultEmailProvider, f as useEmailProvider, i as defineEmailProvider, l as renderEmailTemplate, n as clearSentEmails, o as getEmailProviderNames, r as createEmailTransport, s as getEmailTransport, t as clearEmailProviders, u as sendEmail } from "./email-BjfRiR9b.js";
+export { clearEmailProviders, clearSentEmails, createEmailTransport, defineEmailProvider, getEmailProvider, getEmailProviderNames, getEmailTransport, getSentEmails, renderEmailTemplate, sendEmail, setDefaultEmailProvider, useEmailProvider };