Welcome, {{name}}!

# @sadikkhan02/notifykit 中文文档

规范地址：https://npmcn.com/package/%40sadikkhan02/notifykit/

版本：1\.0\.0
npm 元数据更新时间：2026-11-02T08:18:58.531Z
中文译文更新时间：2026-11-02T10:33:09.516Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40sadikkhan02/notifykit
原文对照：https://npmcn.com/package/%40sadikkhan02/notifykit/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：554 kB，30 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：6 个
- 首次发布：2026-11-02T08:17:40.740Z
- 最新版本发布：2026-11-02T08:18:58.296Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

面向Node.js的企业级事务性通知交付引擎

## 安装

```sh
npm install @sadikkhan02/notifykit
```

也可以使用：`pnpm add @sadikkhan02/notifykit`、`yarn add @sadikkhan02/notifykit`、`bun add @sadikkhan02/notifykit`

## README

# `@sadikkhan02/notifykit` (核心)

> 代码优先，用于Node.js和TypeScript的无状态通知编排库。

`@sadikkhan02/notifykit` 提供了一个统一的多通道通知引擎，由BullMQ和Redis提供支持。它允许应用程序快速排队通知，在内存中可靠地预呈现模板，并通过持久的重试逻辑、自动错误分类和死信队列（DLQ）保护跨Email、SMS和Push通知通道传递消息。

* * *

## 功能

-   **统一多通道API**:单 `notifier.notify()` 方法同时针对邮件、短信和推送。
-   **使用BullMQ进行持久队列**： Redis流支持的持久后台作业处理。
-   **快速故障内存预渲染**：模板渲染 _之前_ 队列（ADR-004），防止语法错误或缺少变量进入Redis。
-   **指数后退重试**：自动重试瞬态提供商/网络故障（最多5次尝试与抖动）。
-   **死信队列（DLQ）**：自动隔离不可重试的故障（无效的电话号码、格式错误的电子邮件、身份验证拒绝）。
-   **关联与分布式跟踪**：每个事件生成一个按时间顺序排列的uidv7跟踪ID，它在队列、工作者、日志和适配器调用之间传播。
-   **自动秘密和PII修订**：敏感领域(`auth.pass`， `token`， `phone`， `email`， `authorization`)在结构化日志中剥离。
-   **可插拔适配器架构**：与Nodemailer、Twilio、MSG91和Firebase Cloud Messaging （FCM）的官方适配器兼容。

* * *

## 安装

```bash
npm install @sadikkhan02/notifykit
```

安装所需的适配器：

```bash
# Email (Universal SMTP, SendGrid, Gmail, Mailtrap)
npm install @sadikkhan02/adapter-nodemailer nodemailer

# SMS (Twilio)
npm install @sadikkhan02/adapter-twilio twilio

# SMS (MSG91 - India DLT optimized, native fetch, zero vendor SDK)
npm install @sadikkhan02/adapter-msg91

# Push (Firebase Cloud Messaging)
npm install @sadikkhan02/adapter-fcm firebase-admin
```

* * *

## 快速入门

```typescript
import { createNotifier } from '@sadikkhan02/notifykit';
import { NodemailerEmailProvider } from '@sadikkhan02/adapter-nodemailer';

// 1. Initialize the Notifier
const notifier = createNotifier({
  redis: process.env.REDIS_URL || 'redis://localhost:6379',
  providers: {
    email: {
      type: 'nodemailer',
      adapter: new NodemailerEmailProvider({
        host: process.env.SMTP_HOST || 'smtp.mailtrap.io',
        port: Number(process.env.SMTP_PORT) || 587,
        auth: {
          user: process.env.SMTP_USER || 'mock_user',
          pass: process.env.SMTP_PASSWORD || 'mock_pass',
        },
      }),
      from: 'noreply@example.com',
    },
  },
});

// 2. Register a template
notifier.registerTemplate(
  'welcome-email',
  '<h1>Welcome, {{name}}!</h1><p>Your account is ready.</p>',
);

// 3. Enqueue notification (guarantees durable Redis acceptance)
const { jobId } = await notifier.notify({
  to: { email: 'user@example.com' },
  channels: ['email'],
  template: 'welcome-email',
  data: { name: 'Alice' },
});

console.log(`Notification enqueued with ID: ${jobId}`);

// 4. Start processing background queues
notifier.startWorker({ channels: ['email'], concurrency: 5 });

// 5. Gracefully shutdown on termination signals
process.on('SIGINT', async () => {
  await notifier.stopWorker();
  process.exit(0);
});
```

* * *

## 核心API参考

### `createNotifier(options?: CreateNotifierOptions): Notifier`

工厂功能，用于创建已配置的 `Notifier` 协调器实例。

#### 选项(`CreateNotifierOptions`）

| 选项 | 类型 | 描述 |
| :-- | :-- | :-- |
| `redis` | `string` | Redis连接URL(例如： `redis://localhost:6379`）. 默认为 `process.env.REDIS_URL`. |
| `providers` | `NotifierConfig['providers']` | 通道提供者映射(`email`， `sms`， `push`）。 |
| `templates` | `Record<string, string>` | 初始模板字典 `[id]: source`. |
| `logLevel` | `LogLevel` | Pino日志级别(`fatal`， `error`， `warn`， `info`， `debug`， `trace`， `silent`）。 |
| `logger` | `Logger` | 自定义Pino记录器实例。 |

* * *

### `notifier.notify(event: NotificationEvent): Promise<NotifyResult>`

验证事件，在内存中预呈现模板，解析通道适配器，并自动将作业排队给Redis。

> **重要的区别：排队与交付** `await notifier.notify(...)` 一旦通知被安全地保存在Redis队列中，就会解析。它返回 `{ jobId: string }`． 实际传输到SMTP、Twilio、MSG91或FCM是在后台worker异步进行的。

#### 事件架构(`NotificationEvent`）

```typescript
export interface NotificationEvent {
  to: {
    email?: string; // RFC 5322 formatted email
    phone?: string; // E.164 formatted phone number (+15555550100)
    pushToken?: string; // FCM device registration token
  };
  channels: Array<'email' | 'sms' | 'push'>;
  template: string; // Registered template ID
  data: Record<string, unknown>; // Template variables
}
```

* * *

### `notifier.registerTemplate(id: string, source: string): void`

编译并在内存中缓存Handlebars模板。支持内置帮助器：

-   `{{uppercase text}}`：将文本转换为大写。
-   `{{formatDate timestamp}}`：安全地格式化日期。

* * *

### `notifier.startWorker(options?: StartWorkerOptions): void`

启动BullMQ队列工作者，以使用和分派已排队的通知。

```typescript
notifier.startWorker({
  channels: ['email', 'sms'], // Channels to process (defaults to all configured)
  concurrency: { email: 10, sms: 5 }, // Global number or per-channel overrides
});
```

* * *

### `notifier.stopWorker(): Promise<void>`

清除正在运行的作业并干净地暂停队列工作。在应用程序进程退出之前调用此函数。

* * *

### 全局连接拆解

对于独立脚本和自动化测试，关闭队列实例和共享Redis连接池：

```typescript
import { resetDefaultRegistry, closeRedisConnection } from 'notifykit';

await notifier.stopWorker();
await resetDefaultRegistry();
await closeRedisConnection();
```

* * *

## 重试策略&死信队列（DLQ）

NotifyKit遵循严格的交付弹性策略：

1.  **瞬态误差(`retryable: true`）**：
    -   连接超时、HTTP 429速率限制和5xx网关错误自动重试 **5倍**.
    -   退避策略：随机抖动的指数退避(`1s`， `2s`， `4s`， `8s`， `16s`）。
2.  **终端错误(`retryable: false`）**：
    -   无效的电话号码（例如Twilio） `21211`)， DLT注册拒绝（MSG91），未注册的推送令牌（FCM）或身份验证失败立即绕过重试并直接路由到 `bull:notifykit:dlq:*`.
    -   DLQ作业将无限期保留，以便事后分析。

* * *

## 许可证

麻省理工学院

## 常见问题

### @sadikkhan02/notifykit 是什么？

面向Node\.js的企业级事务性通知交付引擎

### 如何安装 @sadikkhan02/notifykit？

在项目目录运行 npm install @sadikkhan02/notifykit，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 notifykit，可以用 npx notifykit 直接运行。

### @sadikkhan02/notifykit 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @sadikkhan02/notifykit 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @sadikkhan02/notifykit 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @sadikkhan02/notifykit 可以商用吗？

@sadikkhan02/notifykit 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @sadikkhan02/notifykit 还在维护吗？

最新版本 1\.0\.0 发布于 2026/11/02（1 天前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/11/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。