# @faiber/faiber-messenger 中文文档

规范地址：https://npmcn.com/package/%40faiber/faiber-messenger/

版本：2\.7\.0
npm 元数据更新时间：2026-11-04T16:42:50.216Z
中文译文更新时间：2026-11-14T08:55:49.121Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：195 kB，28 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-07-18T14:29:44.290Z
- 最新版本发布：2026-11-04T16:42:49.965Z
- 近 30 天下载量：3898（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：65（近 12 个月 65 个）

## 中文简介

已键入通知管理,接收收件箱,频道组,模板,提供商,移动/网络推码注册,集成元数据.

## 安装

```sh
npm install @faiber/faiber-messenger
```

也可以使用：`pnpm add @faiber/faiber-messenger`、`yarn add @faiber/faiber-messenger`、`bun add @faiber/faiber-messenger`

## README

# @faiber/faiber-送信员

已键入通知管理,接收收件箱,频道组,模板,提供商,移动/网络推码注册,集成元数据.

```bash
npm install @faiber/faiber-messenger
```

```ts
import { FaiberClient, MemoryTokenProvider } from "@faiber/sdk-core";
import { MessengerApi } from "@faiber/faiber-messenger";

const tokens = new MemoryTokenProvider();
const api = new MessengerApi(new FaiberClient("messenger", {
  domains: { messenger: process.env.FAIBER_MESSENGER_URL! },
  tokenProvider: tokens,
  axios: { timeout: 15_000, withCredentials: true },
}));

const inbox = await api.myInboxPage({ "page[number]": 1, "page[size]": 20 });
const first = inbox.data.data.data[0];
if (first) await api.markMyNotificationRead(first.id);
```

使用配置 `TokenProvider` 用于熊鼠认证,或 `withCredentials` 有安全的 Http 唯一的饼干会话。 在可能的情况下,在记忆中保留符号. 呼叫份额 `FaiberClient`包括拦截器和信号刷新器 需要自动收件箱操作 `notification:self:read` 在国内流离失所者中 `message` 命名空间(后端也接受所记录的别名)和一个非无名演员UUID. 行政赠款不能取代明确的收件箱许可检查.

## 完整 API

`api.operations` 曝光所有47个挂载的HTTP操作;输出输入,查询,响应,路径,方法和权限类型. 经审查的后端来源是 `c65ae75c6cbed3f07b13a58887e3bf4842f22d22`来源审查没有确定一个部署的个案是否采纳或当地基础设施是否接受.

| 能力 | 业务 |
| --- | --: |
| 频道组和订阅 | 6个 |
| 库存盘点 | 1个 |
| 整合元数据 | 3个 |
| 通知管理、接收信箱和实时 | 10个 |
| 持久受援者流/数 | 2个 |
| 移动推进注册 | 2个 |
| 供应商服务和准备状态 | 第7条 |
| 模板和频道特定内容 | 第8条 |
| 网络推 | 页:1 |
| 健康和原始开放API | 3个 |

已挂载的 OpenAPI 处理器注释列表不完整 。 使用命名为 SDK 的操作进行全程盘点.

## 管理和排队

频道组使用数字ID和 `{name}`模板 `{name, fa_name, params?, channel_id?}`; 内容使用 `{channel, text, options?}`。内容渠道是 `sms`, (中文(简体) ), `sms-otp`, (中文(简体) ), `email`,或 `push_notification`。模板、频道组和提供者列表返回内部未绘制的数组 `status/message/data`。 。 。 .

```ts
const template = await api.templates.create({
  name: "welcome", fa_name: "Welcome", params: ["name"],
});
await api.createTemplateContent(template.data.data.id, {
  channel: "email", text: "Welcome {{name}}",
});
const queued = await api.send({
  template_id: template.data.data.id,
  channel: "email",
  recipients: ["learner@example.test"],
  params: { name: "Learner" },
});
console.log(queued.data.data.notification_ids);
```

这个例子要求适当的模板管理赠款和调度服务授权。 无空 `recipients` 数组优先于单数 `recipient`发送和发送 `api.notifications.create` 返回 HTTP 200 键 `{notification_ids}`,而不是行政通知记录. `scheduled_at` 调度; `options.correlation_id` 允许本地更新/重新使用行为 。 排队接受不能证明提供者交货.

模板补丁 `channel_id: null` 清除群;遗漏保留了群。 努尔模板名称/fa name/params和内容文本/选项保存被存储的值. 频道重命名需要非空的修饰名 。 Template/channel删除软去除后返回404;提供者删除为一元硬去除. 所有三个返回 HTTP 200 与 `data: {}`。 。 。 .

提供方服务投入的使用 `{name, provider, channel, options, priority?}` 小写提供者名称 `smtp`, (中文(简体) ), `ghasedak`, (中文(简体) ), `armaghan`, (中文(简体) ), `pusher`,或 `firebase`选项是后端加密的针对提供者的动态 JSON;每个提供者读取/创建/更新响应返回 `options: null`。输入/零补丁选项保存证书。 优先级是被签名的16位整数. 设置报告序列化提供者的 enum 标签为 `Smtp`, (中文(简体) ), `Ghasedak`, (中文(简体) ), `Armaghan`, (中文(简体) ), `Pusher`,或 `Firebase`。 。 。 .

行政通知的内容包括提供者诊断和路径领域。 他们的列表使用 `{ "page[number]": 2, "page[size]": 30, recipient?: "user-id" }` 元数据嵌入 `response.data.data.meta`。默认为第1页大小为20;大小为1.100;分页为1。 记录按更新时间排序,然后ID下降. `markAllNotificationsRead({recipient})` 需要非空收件人;其结果是 `{updated}`。 。 。 .

## 个人收件箱状态

使用 `myInboxPage({important:true})` 用于单独的被钉住的部分 `important:false` 剩下的钱. `setMyNotificationState(id,{important:true})` 只改变收件人的重要性. `{read:false}` 恢复未读状态; `{read:true}` 标记它读取。 任意一个字段都可以独立更新,也可以一起更新. 现有 `markMyNotificationRead(id)` 保持兼容。 丢失或被删除的属于另一个收件人的记录和记录返回404.

## 收货人交付

`myInboxPage` 和兼容 `myInbox({params})` 返回减少的收件人记录。 可忽略标题、描述、路径、目的地、工作 项目 id和事件字段始终存在. `description` 是收件人信件副本。 提供者诊断、原始接收者路径、参数和提供者选项除外。 目的地是本地动态JSON:在导航前验证一个被识别的形状.

初始化光标为 `api.delivery.events()` **在此之前** 装入收件箱快照,然后用 `events({cursor})`每页最多包含100个事件、光标和 `has_more`开放 `wait_seconds` 等了25秒后再回来 方便和犬事都称默认为35秒的运输超时;明确的选项将它覆盖. 已过期/ 未来光标返回 410 , 需要新快照; 负光标返回 400 。 持久活动包括: `cursor` 财务报告和审定财务报表 `event_id`;历史错误的通知ID/时间戳可能无效. 遗留的套接字基载荷没有可持久的光标.

`api.delivery.unreadCount()` 返回权威收件人通知数,与聊天未读信件分开. `registerDevice({application_id, installation_id, platform, token, locale})` 登记Android/iOS的安装。 当令牌旋转并注销后, 重新使用它的非零安装 UUID 。 Tokens必须是20.4096个字符和地址,最多32个;每个应用程序允许每个用户使用10个设备. 未知的注册字段拒绝 。 账户切换可以将一个安装/切换到当前角色.

Web Push Canonical 操作暴露出可用性,注册/移除,实际测试排队以及交付状态. 从用户动作中请求浏览器权限;通过浏览器端点和URL-安全无加码的base64键. 端点必须在端口443上使用经批准的FCM,Mozilla或Apple HTTPS主机. 一个测试只能为当前演员的订阅而排队,最多每分钟排一次(否则排队429个). `provider_status` 无效,不证明显示或读取。 取消订阅和移动吊销返回成功去除的旗帜,即使缺席或其他用户的ID. 背景传送需要配置的提供者和OS/浏览器权限. 恢复、重新连接或账户更改后调和收件箱状态.

实时配置用途 `notificationRealtimeConfig`· ; `notificationRealtimeAuth` 返回原始内容 `{auth}` 用于当前接收者精确的私人频道。 使用 `subscribeRealtime` 从 `@faiber/sdk-core`;在重新连接时重新装入持续收件箱记录,在登录时关闭订阅. 保留 Sockudo 服务器端的秘密 。 见 [核心订阅实例](https://github.com/faiber-code/faiber-ts-sdk/tree/main/packages/core#sockudo-realtime-subscriptions)。 。 。 .

## 权力、准备状态和错误

行政路线补助出现在JSDoc的运作中. 调度、明确的用户/频道订阅和流程集成元数据没有处理器权限宏;其实际访问取决于网关/部署政策。 SDK转发器也为这些通话配置了证书. 接受者操作产生自己的角色,不接受任意接受者. 土著行政资料库不通过租户查询场确定租户隔离.

`serviceSetupCheckPost()` 需求 `admin:service:read`它不发出通知,但可以与SMTP/Ghasedak证书和API模板联系。 内容 `{configured, providerVerified, channels, providers, checkedAt}` 报告描述准备状态与HTTP成功分开。 仅限服务器 `serviceReadinessPost({headers:{"x-website-otp-token": token}})` 使用部署密钥并返回原始 `{ready}`; 缺少的令牌配置为503个,错误的令牌为401个. 永远不要把这个秘密放入浏览器代码中.

所有方法都返回 Axios 的完整响应,保存状态,信头和请求ID. 通过普通 Axios 选项,包括 `signal`, (中文(简体) ), `timeout`,标题和适配器,作为最后论据. Axios 错误保留后端状态/ 机构 。 本地应用程序错误 `{error: string}`;提取器出错可能具有不同的正体. 错误的查询/路径输入被拒绝,受保护的呼叫可以返回401/403,没有范围行返回404,注册冲突409,没有可用的交付存储/配置503.

```ts
const controller = new AbortController();
const pending = api.myInboxPage(undefined, { signal: controller.signal, timeout: 5_000 });
controller.abort();
try { await pending; } catch (error) {
  // Handle Axios cancellation or inspect response.status for service failures.
}
```

使用 [`@faiber/faiber-ts-sdk`](https://www.npmjs.com/package/@faiber/faiber-ts-sdk) 用于一个配置下的多个 Faiber 服务.

## 常见问题

### @faiber/faiber-messenger 是什么？

已键入通知管理,接收收件箱,频道组,模板,提供商,移动/网络推码注册,集成元数据\.

### 如何安装 @faiber/faiber-messenger？

在项目目录运行 npm install @faiber/faiber-messenger，或使用 pnpm add / yarn add / bun add。

### @faiber/faiber-messenger 支持 TypeScript 吗？

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

### @faiber/faiber-messenger 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @faiber/faiber-messenger 可以商用吗？

@faiber/faiber-messenger 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @faiber/faiber-messenger 的下载量有多少？

根据 npm 官方下载统计，@faiber/faiber-messenger 在 2026/10/14 – 2026/11/12 这 30 天内被下载 3,898 次，日均约 130 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @faiber/faiber-messenger 还在维护吗？

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