@hz-9/a5-mail 0.2.0-alpha.26

package/README.md

@@ -0,0 +1,130 @@
+# @hz-9/a5-mail
+
+Mail module for the @hz-9/a5-* series of repositories, based on [nodemailer](https://nodemailer.com/).
+
+## Features
+
+- ✅ 基于 nodemailer v7.x
+- ✅ 支持多种传输方式（SMTP、Gmail、SES 等）
+- ✅ 提供统一的邮件发送接口
+- ✅ 支持同步和异步配置
+- ✅ TypeScript 完整类型支持
+- ✅ 全局模块支持
+
+## Installation
+
+```bash
+pnpm add @hz-9/a5-mail nodemailer
+```
+
+## Quick Start
+
+### 1. 基础使用
+
+```typescript
+import { Module } from '@nestjs/common'
+import { A5MailModule } from '@hz-9/a5-mail'
+
+@Module({
+  imports: [
+    A5MailModule.forRoot({
+      host: 'smtp.gmail.com',
+      port: 587,
+      secure: false,
+      auth: {
+        user: 'your-email@gmail.com',
+        pass: 'your-app-password',
+      },
+      isGlobal: true,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### 2. 使用邮件服务
+
+```typescript
+import { Injectable } from '@nestjs/common'
+import { A5Mail } from '@hz-9/a5-mail'
+
+@Injectable()
+export class UserService {
+  constructor(private readonly mail: A5Mail) {}
+
+  async sendWelcomeEmail(email: string, name: string) {
+    return this.mail.send({
+      from: 'noreply@example.com',
+      to: email,
+      subject: '欢迎加入',
+      html: `<h1>欢迎, ${name}!</h1>`,
+    })
+  }
+}
+```
+
+### 3. 异步配置
+
+```typescript
+import { Module } from '@nestjs/common'
+import { A5MailModule } from '@hz-9/a5-mail'
+import { ConfigService } from '@nestjs/config'
+
+@Module({
+  imports: [
+    A5MailModule.forRootAsync({
+      useFactory: (configService: ConfigService) => ({
+        host: configService.get('MAIL_HOST'),
+        port: configService.get('MAIL_PORT'),
+        secure: configService.get('MAIL_SECURE'),
+        auth: {
+          user: configService.get('MAIL_USER'),
+          pass: configService.get('MAIL_PASS'),
+        },
+      }),
+      inject: [ConfigService],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## API Documentation
+
+### A5Mail
+
+主要邮件服务类，提供以下方法：
+
+#### `send(options: A5MailSendOptions): Promise<A5MailSendResponse>`
+发送邮件。
+
+#### `verify(): Promise<boolean>`
+验证邮件传输配置是否正确。
+
+#### `getInstance(): A5MailInstance`
+获取原始 nodemailer Transporter 实例。
+
+## Configuration Options
+
+### A5MailConstructorOptions
+
+邮件模块配置选项与 nodemailer.createTransport 的参数保持一致。
+
+例如：
+
+```typescript
+interface A5MailConstructorOptions {
+  host?: string              // SMTP 服务器地址
+  port?: number              // SMTP 端口
+  secure?: boolean           // 是否使用 TLS
+  auth?: {                   // 认证信息
+    user: string
+    pass: string
+  }
+  isGlobal?: boolean         // 是否全局模块（默认：true）
+}
+```
+
+## License
+
+MIT

package/dist/all.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @packageDocumentation
+ * A5 Mail Module - Mail sending for A5 framework based on nodemailer
+ */
+
+/// <reference types="node" />
+
+import { ConfigurableModuleCls } from '@nestjs/common';
+import { createTransport } from 'nodemailer';
+import type { Transport } from 'nodemailer';
+import type { TransportOptions } from 'nodemailer';
+
+/**
+ * @public
+ */
+export declare const A5_MAIL_MODULE_OPTIONS: string | symbol;
+
+/**
+ * A5 邮件服务类
+ *
+ * 提供统一的邮件发送接口，基于 nodemailer
+ *
+ * @public
+ */
+export declare class A5Mail {
+    private readonly instance;
+    constructor(options: A5MailConstructorOptions);
+    /**
+     * 发送邮件
+     *
+     * @param options - 邮件发送选项
+     * @returns 邮件发送响应
+     */
+    send(options: A5MailSendOptions): Promise<A5MailSendResponse>;
+    /**
+     * 验证邮件传输配置
+     *
+     * @returns 是否验证成功
+     */
+    verify(): Promise<boolean>;
+    /**
+     * 获取原始邮件传输实例
+     *
+     * @returns 邮件传输实例
+     */
+    getInstance(): A5MailInstance;
+}
+
+/**
+ * @public
+ */
+export declare const A5MailConfigurableModule: ConfigurableModuleCls<A5MailConstructorOptions, "forRoot", "createOptions", {
+isGlobal: boolean;
+}>;
+
+/**
+ * A5 邮件模块构造选项接口
+ *
+ * 参数保持与 nodemailer.createTransport 一致
+ *
+ * @public
+ */
+export declare type A5MailConstructorOptions = TransportOptions | Transport;
+
+/**
+ * A5 邮件传输实例接口
+ *
+ * 基于 nodemailer 的 Transporter 类型
+ *
+ * @public
+ */
+export declare type A5MailInstance = ReturnType<createTransport>;
+
+/**
+ * @public
+ */
+export declare class A5MailModule extends A5MailConfigurableModule {
+}
+
+/**
+ * A5 缓存模块异步配置选项接口
+ *
+ * @public
+ */
+export declare interface A5MailModuleAsyncOptions {
+    /**
+     * 工厂函数，返回 A5MailModuleOptions 配置对象
+     */
+    useFactory?: (...args: unknown[]) => Promise<A5MailModuleOptions> | A5MailModuleOptions;
+    /**
+     * 需要注入到 useFactory 函数中的依赖项
+     */
+    inject?: unknown[];
+    /**
+     * 需要导入的模块列表
+     */
+    imports?: unknown[];
+}
+
+/**
+ * A5 缓存模块配置选项
+ *
+ * @public
+ */
+export declare type A5MailModuleOptions = A5MailConstructorOptions;
+
+/**
+ * A5 邮件发送选项接口
+ *
+ * @public
+ */
+export declare interface A5MailSendOptions {
+    /**
+     * 发件人邮箱地址
+     */
+    from?: string;
+    /**
+     * 收件人邮箱地址（单个或多个）
+     */
+    to: string | string[];
+    /**
+     * 抄送收件人（可选）
+     */
+    cc?: string | string[];
+    /**
+     * 密送收件人（可选）
+     */
+    bcc?: string | string[];
+    /**
+     * 邮件主题
+     */
+    subject: string;
+    /**
+     * 邮件正文（纯文本）
+     */
+    text?: string;
+    /**
+     * 邮件正文（HTML）
+     */
+    html?: string;
+    /**
+     * 附件数组
+     */
+    attachments?: Array<{
+        filename: string;
+        content?: string | Buffer;
+        path?: string;
+        [key: string]: any;
+    }>;
+    /**
+     * 其他邮件选项
+     */
+    [key: string]: any;
+}
+
+/**
+ * A5 邮件发送响应接口
+ *
+ * @public
+ */
+export declare interface A5MailSendResponse {
+    /**
+     * 响应消息 ID
+     */
+    messageId?: string;
+    /**
+     * 响应状态
+     */
+    response?: string;
+    /**
+     * 响应信息
+     */
+    [key: string]: any;
+}
+
+export { }

package/dist/const/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/const/index.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/dist/core/a5-mail.d.ts

@@ -0,0 +1,31 @@
+import type { A5MailConstructorOptions, A5MailInstance, A5MailSendOptions, A5MailSendResponse } from '../interfaces/mail';
+/**
+ * A5 邮件服务类
+ *
+ * 提供统一的邮件发送接口，基于 nodemailer
+ *
+ * @public
+ */
+export declare class A5Mail {
+    private readonly instance;
+    constructor(options: A5MailConstructorOptions);
+    /**
+     * 发送邮件
+     *
+     * @param options - 邮件发送选项
+     * @returns 邮件发送响应
+     */
+    send(options: A5MailSendOptions): Promise<A5MailSendResponse>;
+    /**
+     * 验证邮件传输配置
+     *
+     * @returns 是否验证成功
+     */
+    verify(): Promise<boolean>;
+    /**
+     * 获取原始邮件传输实例
+     *
+     * @returns 邮件传输实例
+     */
+    getInstance(): A5MailInstance;
+}

package/dist/core/a5-mail.js

@@ -0,0 +1,57 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A5Mail = void 0;
+const common_1 = require("@nestjs/common");
+const nodemailer_1 = require("nodemailer");
+/**
+ * A5 邮件服务类
+ *
+ * 提供统一的邮件发送接口，基于 nodemailer
+ *
+ * @public
+ */
+let A5Mail = class A5Mail {
+    constructor(options) {
+        this.instance = (0, nodemailer_1.createTransport)(options);
+    }
+    /**
+     * 发送邮件
+     *
+     * @param options - 邮件发送选项
+     * @returns 邮件发送响应
+     */
+    async send(options) {
+        return this.instance.sendMail(options);
+    }
+    /**
+     * 验证邮件传输配置
+     *
+     * @returns 是否验证成功
+     */
+    async verify() {
+        return this.instance.verify();
+    }
+    /**
+     * 获取原始邮件传输实例
+     *
+     * @returns 邮件传输实例
+     */
+    getInstance() {
+        return this.instance;
+    }
+};
+exports.A5Mail = A5Mail;
+exports.A5Mail = A5Mail = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object])
+], A5Mail);
+//# sourceMappingURL=a5-mail.js.map

package/dist/core/a5-mail.module.d.ts

@@ -0,0 +1,6 @@
+import { A5MailConfigurableModule } from './module-definition';
+/**
+ * @public
+ */
+export declare class A5MailModule extends A5MailConfigurableModule {
+}

package/dist/core/a5-mail.module.js

@@ -0,0 +1,26 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A5MailModule = void 0;
+const common_1 = require("@nestjs/common");
+const a5_mail_1 = require("./a5-mail");
+const module_definition_1 = require("./module-definition");
+/**
+ * @public
+ */
+let A5MailModule = class A5MailModule extends module_definition_1.A5MailConfigurableModule {
+};
+exports.A5MailModule = A5MailModule;
+exports.A5MailModule = A5MailModule = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({
+        providers: [a5_mail_1.A5Mail],
+        exports: [a5_mail_1.A5Mail],
+    })
+], A5MailModule);
+//# sourceMappingURL=a5-mail.module.js.map

package/dist/core/index.d.ts

@@ -0,0 +1,3 @@
+export * from './a5-mail';
+export * from './a5-mail.module';
+export * from './module-definition';

package/dist/core/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./a5-mail"), exports);
+__exportStar(require("./a5-mail.module"), exports);
+__exportStar(require("./module-definition"), exports);
+//# sourceMappingURL=index.js.map

package/dist/core/module-definition.d.ts

@@ -0,0 +1,11 @@
+import type { A5MailConstructorOptions } from '../interfaces';
+/**
+ * @public
+ */
+export declare const A5MailConfigurableModule: import("@nestjs/common").ConfigurableModuleCls<A5MailConstructorOptions, "forRoot", "createOptions", {
+    isGlobal: boolean;
+}>;
+/**
+ * @public
+ */
+export declare const A5_MAIL_MODULE_OPTIONS: string | symbol;

package/dist/core/module-definition.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A5_MAIL_MODULE_OPTIONS = exports.A5MailConfigurableModule = void 0;
+const common_1 = require("@nestjs/common");
+// eslint-disable-next-line @rushstack/typedef-var
+const moduleDefinition = new common_1.ConfigurableModuleBuilder({
+    moduleName: 'A5Mail',
+})
+    .setExtras({
+    isGlobal: true,
+}, (definition, options) => ({
+    ...definition,
+    global: options.isGlobal,
+}))
+    .setClassMethodName('forRoot')
+    .setFactoryMethodName('createOptions')
+    .build();
+/**
+ * @public
+ */
+// eslint-disable-next-line @rushstack/typedef-var
+exports.A5MailConfigurableModule = moduleDefinition.ConfigurableModuleClass;
+/**
+ * @public
+ */
+// eslint-disable-next-line @rushstack/typedef-var
+exports.A5_MAIL_MODULE_OPTIONS = moduleDefinition.MODULE_OPTIONS_TOKEN;
+//# sourceMappingURL=module-definition.js.map

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @packageDocumentation
+ * A5 Mail Module - Mail sending for A5 framework based on nodemailer
+ */
+export * from './const';
+export * from './core';
+export * from './interfaces';

package/dist/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * @packageDocumentation
+ * A5 Mail Module - Mail sending for A5 framework based on nodemailer
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./const"), exports);
+__exportStar(require("./core"), exports);
+__exportStar(require("./interfaces"), exports);
+//# sourceMappingURL=index.js.map

package/dist/interfaces/index.d.ts

@@ -0,0 +1,2 @@
+export * from './mail';
+export * from './module';

package/dist/interfaces/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./mail"), exports);
+__exportStar(require("./module"), exports);
+//# sourceMappingURL=index.js.map

package/dist/interfaces/mail.d.ts

@@ -0,0 +1,85 @@
+/// <reference types="node" />
+import type { Transport, TransportOptions } from 'nodemailer';
+/**
+ * A5 邮件模块构造选项接口
+ *
+ * 参数保持与 nodemailer.createTransport 一致
+ *
+ * @public
+ */
+export type A5MailConstructorOptions = TransportOptions | Transport;
+/**
+ * A5 邮件传输实例接口
+ *
+ * 基于 nodemailer 的 Transporter 类型
+ *
+ * @public
+ */
+export type A5MailInstance = ReturnType<typeof import('nodemailer').createTransport>;
+/**
+ * A5 邮件发送选项接口
+ *
+ * @public
+ */
+export interface A5MailSendOptions {
+    /**
+     * 发件人邮箱地址
+     */
+    from?: string;
+    /**
+     * 收件人邮箱地址（单个或多个）
+     */
+    to: string | string[];
+    /**
+     * 抄送收件人（可选）
+     */
+    cc?: string | string[];
+    /**
+     * 密送收件人（可选）
+     */
+    bcc?: string | string[];
+    /**
+     * 邮件主题
+     */
+    subject: string;
+    /**
+     * 邮件正文（纯文本）
+     */
+    text?: string;
+    /**
+     * 邮件正文（HTML）
+     */
+    html?: string;
+    /**
+     * 附件数组
+     */
+    attachments?: Array<{
+        filename: string;
+        content?: string | Buffer;
+        path?: string;
+        [key: string]: any;
+    }>;
+    /**
+     * 其他邮件选项
+     */
+    [key: string]: any;
+}
+/**
+ * A5 邮件发送响应接口
+ *
+ * @public
+ */
+export interface A5MailSendResponse {
+    /**
+     * 响应消息 ID
+     */
+    messageId?: string;
+    /**
+     * 响应状态
+     */
+    response?: string;
+    /**
+     * 响应信息
+     */
+    [key: string]: any;
+}

package/dist/interfaces/mail.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=mail.js.map

package/dist/interfaces/module.d.ts

@@ -0,0 +1,26 @@
+import type { A5MailConstructorOptions } from './mail';
+/**
+ * A5 缓存模块配置选项
+ *
+ * @public
+ */
+export type A5MailModuleOptions = A5MailConstructorOptions;
+/**
+ * A5 缓存模块异步配置选项接口
+ *
+ * @public
+ */
+export interface A5MailModuleAsyncOptions {
+    /**
+     * 工厂函数，返回 A5MailModuleOptions 配置对象
+     */
+    useFactory?: (...args: unknown[]) => Promise<A5MailModuleOptions> | A5MailModuleOptions;
+    /**
+     * 需要注入到 useFactory 函数中的依赖项
+     */
+    inject?: unknown[];
+    /**
+     * 需要导入的模块列表
+     */
+    imports?: unknown[];
+}

package/dist/interfaces/module.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=module.js.map

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@hz-9/a5-mail",
+  "version": "0.2.0-alpha.26",
+  "description": "Mail module for the @hz-9/a5-* series of repositories, based on nodemailer.",
+  "keywords": [
+    "nest",
+    "a5",
+    "a5-mail",
+    "mail",
+    "nodemailer"
+  ],
+  "homepage": "https://hz-9.github.io/a5/guide/a5-mail",
+  "bugs": {
+    "url": "https://github.com/hz-9/a5/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hz-9/a5.git",
+    "directory": "library/mail"
+  },
+  "license": "MIT",
+  "author": "Chen Zhen <heavenzhen999@163.com>",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./*": {
+      "require": "./dist/*.js",
+      "types": "./dist/*.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.{d.ts,js}"
+  ],
+  "dependencies": {
+    "nodemailer": "^7.0.0"
+  },
+  "devDependencies": {
+    "@hz-9/eslint-config-airbnb-ts": "~0.6.0",
+    "@nestjs/cli": "^10.0.0",
+    "@nestjs/common": "^10.0.0",
+    "@nestjs/core": "^10.0.0",
+    "@nestjs/testing": "^10.0.0",
+    "@rushstack/heft": "0.66.1",
+    "@types/heft-jest": "~1.0.3",
+    "@types/node": "~20.3.1",
+    "@types/nodemailer": "^6.4.15",
+    "eslint": "^8.2.0",
+    "reflect-metadata": "^0.1.13",
+    "rxjs": "^7.8.1",
+    "ts-node": "^10.9.1",
+    "typescript": ">=5.0.0 <5.4.0",
+    "@hz-9/heft-nest-rig": "0.1.2",
+    "@hz-9/a5-core": "0.2.0-alpha.26"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0",
+    "@nestjs/core": "^10.0.0",
+    "reflect-metadata": "^0.1.13",
+    "rxjs": "^7.8.1",
+    "@hz-9/a5-core": "0.2.0-alpha.26"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "heft test-all --clean",
+    "lint": "heft lint",
+    "test": "heft test --clean",
+    "test:watch": "heft test-watch --clean"
+  }
+}