@h-ai/reach 0.1.0-alpha5

package/dist/index.d.ts

@@ -0,0 +1,468 @@
+import { z } from 'zod';
+import * as _h_ai_core from '@h-ai/core';
+import { HaiResult } from '@h-ai/core';
+
+/**
+ * @h-ai/reach — 配置 Schema
+ *
+ * 本文件定义触达模块的错误码、Zod Schema 和配置类型。
+ * @module reach-config
+ */
+
+/**
+ * Console Provider 配置（开发/测试用，将消息输出到日志）
+ */
+declare const ConsoleProviderConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"console">;
+}, z.core.$strip>;
+/**
+ * SMTP 邮件 Provider 配置
+ *
+ * @example
+ * ```ts
+ * {
+ *   name: 'email',
+ *   type: 'smtp',
+ *   host: 'smtp.example.com',
+ *   port: 465,
+ *   secure: true,
+ *   user: 'noreply@example.com',
+ *   pass: 'password',
+ *   from: 'noreply@example.com'
+ * }
+ * ```
+ */
+declare const SmtpProviderConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"smtp">;
+    host: z.ZodString;
+    port: z.ZodDefault<z.ZodNumber>;
+    secure: z.ZodDefault<z.ZodBoolean>;
+    user: z.ZodOptional<z.ZodString>;
+    pass: z.ZodOptional<z.ZodString>;
+    from: z.ZodString;
+}, z.core.$strip>;
+/**
+ * 阿里云短信 Provider 配置（通过 HTTP API 调用，无需 SDK）
+ *
+ * @example
+ * ```ts
+ * {
+ *   name: 'sms',
+ *   type: 'aliyun-sms',
+ *   accessKeyId: 'LTAI...',
+ *   accessKeySecret: '...',
+ *   signName: '某某科技',
+ *   endpoint: 'dysmsapi.aliyuncs.com'
+ * }
+ * ```
+ */
+declare const AliyunSmsProviderConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"aliyun-sms">;
+    accessKeyId: z.ZodString;
+    accessKeySecret: z.ZodString;
+    signName: z.ZodString;
+    endpoint: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * API 回调 Provider 配置（通用 HTTP 回调）
+ *
+ * @example
+ * ```ts
+ * {
+ *   name: 'webhook',
+ *   type: 'api',
+ *   url: 'https://api.example.com/notify',
+ *   method: 'POST',
+ *   headers: { 'Authorization': 'Bearer xxx' }
+ * }
+ * ```
+ */
+declare const ApiProviderConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"api">;
+    url: z.ZodString;
+    method: z.ZodDefault<z.ZodEnum<{
+        POST: "POST";
+        PUT: "PUT";
+    }>>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeout: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * 单个 Provider 配置 Schema（判别联合体）
+ */
+declare const ProviderConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"console">;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"smtp">;
+    host: z.ZodString;
+    port: z.ZodDefault<z.ZodNumber>;
+    secure: z.ZodDefault<z.ZodBoolean>;
+    user: z.ZodOptional<z.ZodString>;
+    pass: z.ZodOptional<z.ZodString>;
+    from: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"aliyun-sms">;
+    accessKeyId: z.ZodString;
+    accessKeySecret: z.ZodString;
+    signName: z.ZodString;
+    endpoint: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"api">;
+    url: z.ZodString;
+    method: z.ZodDefault<z.ZodEnum<{
+        POST: "POST";
+        PUT: "PUT";
+    }>>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeout: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>], "type">;
+/** 单个 Provider 配置类型（parse 后） */
+type ProviderConfig = z.infer<typeof ProviderConfigSchema>;
+/** Console 配置类型 */
+type ConsoleProviderConfig = z.infer<typeof ConsoleProviderConfigSchema>;
+/** SMTP 配置类型 */
+type SmtpProviderConfig = z.infer<typeof SmtpProviderConfigSchema>;
+/** 阿里云短信配置类型 */
+type AliyunSmsProviderConfig = z.infer<typeof AliyunSmsProviderConfigSchema>;
+/** API 回调配置类型 */
+type ApiProviderConfig = z.infer<typeof ApiProviderConfigSchema>;
+/**
+ * 免打扰时间段配置
+ *
+ * 在指定的时间段内，根据策略处理消息：
+ * - `discard`：直接丢弃，返回 DND_BLOCKED 错误
+ * - `delay`：暂存到数据库（状态为 pending），DND 结束后由定时任务集中发送
+ *
+ * 时间使用 HH:mm 格式（24 小时制），支持跨午夜（如 22:00-08:00）。
+ *
+ * @example
+ * ```ts
+ * {
+ *   enabled: true,
+ *   strategy: 'delay',
+ *   start: '22:00',
+ *   end: '08:00'
+ * }
+ * ```
+ */
+declare const DndConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    strategy: z.ZodDefault<z.ZodEnum<{
+        discard: "discard";
+        delay: "delay";
+    }>>;
+    start: z.ZodDefault<z.ZodString>;
+    end: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/** DND 配置类型 */
+type DndConfig = z.infer<typeof DndConfigSchema>;
+/**
+ * 模板配置 Schema（通过配置文件定义模板）
+ *
+ * @example
+ * ```yaml
+ * templates:
+ *   - name: verification_code
+ *     provider: email
+ *     subject: "验证码: {code}"
+ *     body: "您的验证码是 {code}，有效期 {minutes} 分钟。"
+ * ```
+ */
+declare const TemplateConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    provider: z.ZodString;
+    subject: z.ZodOptional<z.ZodString>;
+    body: z.ZodString;
+}, z.core.$strip>;
+/** 模板配置类型 */
+type TemplateConfig = z.infer<typeof TemplateConfigSchema>;
+/**
+ * 触达模块配置 Schema
+ *
+ * 接受一个 Provider 配置数组，支持同时注册多个 Provider。
+ * 支持通过配置文件定义模板和免打扰时间段。
+ */
+declare const ReachConfigSchema: z.ZodObject<{
+    providers: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodLiteral<"console">;
+    }, z.core.$strip>, z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodLiteral<"smtp">;
+        host: z.ZodString;
+        port: z.ZodDefault<z.ZodNumber>;
+        secure: z.ZodDefault<z.ZodBoolean>;
+        user: z.ZodOptional<z.ZodString>;
+        pass: z.ZodOptional<z.ZodString>;
+        from: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodLiteral<"aliyun-sms">;
+        accessKeyId: z.ZodString;
+        accessKeySecret: z.ZodString;
+        signName: z.ZodString;
+        endpoint: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodLiteral<"api">;
+        url: z.ZodString;
+        method: z.ZodDefault<z.ZodEnum<{
+            POST: "POST";
+            PUT: "PUT";
+        }>>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        timeout: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>], "type">>;
+    templates: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        provider: z.ZodString;
+        subject: z.ZodOptional<z.ZodString>;
+        body: z.ZodString;
+    }, z.core.$strip>>>;
+    dnd: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        strategy: z.ZodDefault<z.ZodEnum<{
+            discard: "discard";
+            delay: "delay";
+        }>>;
+        start: z.ZodDefault<z.ZodString>;
+        end: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** 触达模块配置类型（parse 后） */
+type ReachConfig = z.infer<typeof ReachConfigSchema>;
+/**
+ * 触达模块配置输入类型
+ */
+type ReachConfigInput = z.input<typeof ReachConfigSchema>;
+
+declare const HaiReachError: {
+    readonly SEND_FAILED: _h_ai_core.HaiErrorDef;
+    readonly TEMPLATE_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly TEMPLATE_RENDER_FAILED: _h_ai_core.HaiErrorDef;
+    readonly INVALID_RECIPIENT: _h_ai_core.HaiErrorDef;
+    readonly PROVIDER_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly DND_BLOCKED: _h_ai_core.HaiErrorDef;
+    readonly DND_DEFERRED: _h_ai_core.HaiErrorDef;
+    readonly NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
+    readonly UNSUPPORTED_TYPE: _h_ai_core.HaiErrorDef;
+    readonly CONFIG_ERROR: _h_ai_core.HaiErrorDef;
+};
+/**
+ * 触达渠道类型
+ *
+ * - `email` — 邮件
+ * - `sms` — 短信
+ * - `api` — API 回调
+ */
+type ReachChannel = 'email' | 'sms' | 'api';
+/**
+ * 触达消息（发送请求）
+ *
+ * 通过 `provider` 字段指定目标 Provider，通过 `template` 字段指定模板。
+ *
+ * @example
+ * ```ts
+ * // 使用模板发送邮件
+ * const msg: ReachMessage = {
+ *   provider: 'email',
+ *   to: 'user@example.com',
+ *   template: 'welcome',
+ *   vars: { userName: '张三' },
+ * }
+ *
+ * // 使用模板发送短信
+ * const msg: ReachMessage = {
+ *   provider: 'sms',
+ *   to: '13800138000',
+ *   template: 'verification_code',
+ *   vars: { code: '123456' },
+ * }
+ * ```
+ */
+interface ReachMessage {
+    /** 目标 Provider 名称（对应 Provider 配置中的 name） */
+    provider: string;
+    /** 接收方（邮箱地址或手机号） */
+    to: string;
+    /** 邮件主题（直接发送时使用） */
+    subject?: string;
+    /** 消息正文（直接发送时使用） */
+    body?: string;
+    /** 模板名称（使用模板发送时指定） */
+    template?: string;
+    /** 模板变量（使用模板发送时传入） */
+    vars?: Record<string, string>;
+    /** Provider 扩展参数（如短信 Provider 的模板编码、签名等） */
+    extra?: Record<string, unknown>;
+}
+/**
+ * 发送结果
+ */
+interface SendResult {
+    /** 是否发送成功 */
+    success: boolean;
+    /** Provider 返回的消息 ID（如有） */
+    messageId?: string;
+    /** 是否被延时（DND delay 策略暂存，待 DND 结束后发送） */
+    deferred?: boolean;
+}
+/**
+ * 触达模板定义
+ *
+ * 每个模板绑定到一个 Provider，发送时按模板中的 `provider` 路由。
+ *
+ * @example
+ * ```ts
+ * const template: ReachTemplate = {
+ *   name: 'verification_code',
+ *   provider: 'email',
+ *   subject: '验证码: {code}',
+ *   body: '您的验证码是 {code}，有效期 {minutes} 分钟。',
+ * }
+ * ```
+ */
+interface ReachTemplate {
+    /** 模板名称（唯一标识） */
+    name: string;
+    /** 绑定的 Provider 名称 */
+    provider: string;
+    /** 邮件主题模板（支持 `{var}` 占位符，仅 email） */
+    subject?: string;
+    /** 消息正文模板（支持 `{var}` 占位符） */
+    body: string;
+}
+/**
+ * 渲染后的模板
+ */
+interface RenderedTemplate {
+    /** 渲染后的主题 */
+    subject?: string;
+    /** 渲染后的正文 */
+    body: string;
+}
+/**
+ * 发送操作接口
+ */
+interface SendOperations {
+    /**
+     * 发送触达消息
+     *
+     * @param message - 触达消息
+     * @returns 发送结果
+     *
+     * @example
+     * ```ts
+     * const result = await reach.send({
+     *   provider: 'email',
+     *   to: 'user@example.com',
+     *   template: 'welcome',
+     *   vars: { userName: '张三' },
+     * })
+     * ```
+     */
+    send: (message: ReachMessage) => Promise<HaiResult<SendResult>>;
+}
+/**
+ * 模板注册表接口
+ *
+ * 所有模板通过数据库持久化存储，避免节点间状态不一致。
+ * 配置文件中的模板在 init 时写入数据库。
+ */
+interface ReachTemplateRegistry {
+    /** 按名称解析模板 */
+    resolve: (name: string) => Promise<HaiResult<ReachTemplate>>;
+    /** 保存模板到数据库（upsert） */
+    save: (template: ReachTemplate) => Promise<HaiResult<void>>;
+    /** 批量保存模板到数据库 */
+    saveBatch: (templates: ReachTemplate[]) => Promise<HaiResult<void>>;
+    /** 从数据库删除模板 */
+    remove: (name: string) => Promise<HaiResult<void>>;
+    /** 列出所有模板 */
+    list: () => Promise<HaiResult<ReachTemplate[]>>;
+    /** 渲染模板（从数据库解析后渲染） */
+    render: (name: string, vars: Record<string, string>) => Promise<HaiResult<RenderedTemplate>>;
+}
+/**
+ * 触达模块函数接口
+ *
+ * @example
+ * ```ts
+ * import { reach } from '@h-ai/reach'
+ *
+ * // 初始化（同时注册多个 Provider）
+ * await reach.init({
+ *   providers: [
+ *     { name: 'email', type: 'smtp', host: 'smtp.example.com', from: 'no-reply@example.com' },
+ *     { name: 'sms', type: 'aliyun-sms', accessKeyId: '...', accessKeySecret: '...', signName: '...' },
+ *   ],
+ * })
+ *
+ * // 保存模板（绑定到 Provider）
+ * await reach.template.save({
+ *   name: 'welcome',
+ *   provider: 'email',
+ *   subject: '欢迎 {userName}',
+ *   body: '亲爱的 {userName}，欢迎使用我们的服务！',
+ * })
+ *
+ * // 发送（指定 Provider）
+ * await reach.send({ provider: 'email', to: 'user@example.com', template: 'welcome', vars: { userName: '张三' } })
+ *
+ * // 关闭
+ * await reach.close()
+ * ```
+ */
+interface ReachFunctions extends SendOperations {
+    /** 初始化触达模块（注册多个 Provider） */
+    init: (config: ReachConfigInput) => Promise<HaiResult<void>>;
+    /** 当前配置（未初始化时为 null） */
+    readonly config: ReachConfig | null;
+    /** 是否已初始化 */
+    readonly isInitialized: boolean;
+    /** 模板注册表 */
+    readonly template: ReachTemplateRegistry;
+    /** 关闭连接并释放资源 */
+    close: () => Promise<void>;
+}
+/**
+ * 触达 Provider 接口
+ *
+ * 由具体实现（console / smtp / aliyun-sms / api）提供。
+ */
+interface ReachProvider {
+    /** Provider 名称 */
+    readonly name: string;
+    /** 连接/初始化 Provider */
+    connect: (config: ProviderConfig) => Promise<HaiResult<void>>;
+    /** 发送消息 */
+    send: (message: ReachMessage) => Promise<HaiResult<SendResult>>;
+    /** 关闭连接 */
+    close: () => Promise<void>;
+    /** 是否已连接 */
+    isConnected: () => boolean;
+}
+
+/**
+ * @h-ai/reach — 触达服务主入口
+ *
+ * 本文件提供统一的 `reach` 对象，聚合模块生命周期管理。
+ * @module reach-main
+ */
+
+/**
+ * 触达服务对象
+ *
+ * 统一的用户触达入口，支持同时使用邮件、短信、API 回调等多种 Provider。
+ */
+declare const reach: ReachFunctions;
+
+export { type AliyunSmsProviderConfig, AliyunSmsProviderConfigSchema, type ApiProviderConfig, ApiProviderConfigSchema, type ConsoleProviderConfig, ConsoleProviderConfigSchema, type DndConfig, DndConfigSchema, HaiReachError, type ProviderConfig, ProviderConfigSchema, type ReachChannel, type ReachConfig, type ReachConfigInput, ReachConfigSchema, type ReachFunctions, type ReachMessage, type ReachProvider, type ReachTemplate, type ReachTemplateRegistry, type RenderedTemplate, type SendOperations, type SendResult, type SmtpProviderConfig, SmtpProviderConfigSchema, type TemplateConfig, TemplateConfigSchema, reach };