@quecue/notify-core 0.1.0 → 0.2.0

package/CHANGELOG.en.md

@@ -2,6 +2,14 @@
 
 English | [简体中文](CHANGELOG.md)
 
+## 0.2.0
+
+- Add a separate Feishu self-built app `createFeishuClient`: explicitly start WebSocket reception of `im.message.receive_v1`, with HTTP sending/replies and no card-action callbacks. Existing Webhook `makePlan`/`deliver` and `NotifyConfig` remain unchanged.
+- Synchronous creation is offline and the SDK is lazy-loaded. Startup waits for actual readiness, defaults to a 10000 ms timeout and is idempotent. Support connection states, stopping with pending-start cancellation/reconnection disabled, and restart. Stop does not wait for or cancel callbacks/HTTP requests in progress; sending does not require startup.
+- Add safe `FeishuError` errors and offline/custom `adapterFactory` injection. Message handlers are awaited; failure is safely reported before returning a failure ACK. Isolate `onError` failures and disable SDK logs by default. Handlers must finish within 3 seconds; hosts own deduplication, authorization, self-reply prevention and durable queues, with no exactly-once guarantee across disconnects/redelivery.
+- Add the official MIT-licensed runtime dependency `@larksuiteoapi/node-sdk`, pinned to `1.76.0`, for app tokens, the binary protocol, framing, heartbeats and reconnection. SDK HTTP separately enforces 10 seconds/1 MiB/no redirects; WebSocket frames are outside `createTransport`'s JSON-response guarantee.
+- Synchronize Chinese/English receive/reply examples, security boundaries, contribution and release guidance, including npm registry access when installing the SDK.
+
 ## 0.1.0
 
 First standalone release; the npm registry is authoritative for actual publication status and available versions.

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 简体中文 | [English](CHANGELOG.en.md)
 
+## 0.2.0
+
+- 新增独立的飞书自建应用 `createFeishuClient`：显式启动 WebSocket 接收 `im.message.receive_v1`，通过 HTTP 发送／回复，不支持卡片动作回调；现有 Webhook `makePlan`／`deliver` 和 `NotifyConfig` 不变。
+- 同步创建不联网，SDK 懒加载；启动等待实际 ready，默认超时 10000 毫秒，重复启动幂等。支持连接状态、停止取消待启动／禁用重连和重启；停止不等待或取消已执行的回调／HTTP 请求，发送无需先启动。
+- 新增 `FeishuError` 安全错误和离线／自定义 `adapterFactory`；消息回调被 await，失败安全报告后返回失败 ACK，`onError` 失败被隔离，默认不输出 SDK 日志。回调须在 3 秒内结束；宿主负责去重、授权、防自回复和持久队列，不保证断线／重推恰好一次。
+- 新增官方 MIT 许可运行时依赖 `@larksuiteoapi/node-sdk`，固定为 `1.76.0`，负责应用 token、二进制协议、分帧心跳和重连；SDK HTTP 独立限制 10 秒／1 MiB／禁止重定向，WebSocket 帧不适用 `createTransport` 的 JSON 响应保证。
+- 同步中英文接收／回复用法、安全边界、贡献与发布说明，明确安装 SDK 会访问 npm registry。
+
 ## 0.1.0
 
 首次独立发行；实际发布状态和可用版本以 npm registry 为准。

package/CONTRIBUTING.md

@@ -6,16 +6,20 @@
 
 - Node.js 22 或更高版本、npm。
 - 在本仓库执行 `npm ci --ignore-scripts`、`npm test`。
-- 测试默认禁止真实网络，使用虚假凭据和注入的 HTTP／等待函数；不应要求贡献者提供个人 Bot Token 或 Webhook。
+- 测试默认禁止真实网络，使用虚假凭据和注入的 HTTP／等待函数；飞书客户端通过 `adapterFactory` 注入离线 SDK 适配器，不应要求贡献者提供真实 Bot Token、Webhook、App ID 或 App Secret。依赖安装会访问 npm registry，与运行时测试离线是不同边界。
 - 修改 API 时同步 `.d.ts` 构建、中文／英文 README、错误边界和变更记录。不要手工编辑 `dist`。
 
-建议为限流、超时、格式回退、Unicode 分段、部分投递、自定义回调失败和错误脱敏补测试。保持默认导入无网络或配置副作用。传输与授权的边界应写清楚，不要使用测试通过来替代真实平台兼容承诺。
+建议为限流、超时、格式回退、Unicode 分段、部分投递、自定义回调失败和错误脱敏补测试。保持默认导入及客户端创建无网络或配置副作用，SDK 懒加载。传输与授权的边界应写清楚，不要使用测试通过来替代真实平台兼容承诺。
+
+飞书客户端修改还应覆盖：实际 WS ready 才完成启动、默认 10000 毫秒启动超时／致命失败、重复启动幂等、同步停止取消待启动并禁用重连、停止后重启，以及 `idle`／`connecting`／`connected`／`reconnecting`／`failed`／`stopped` 状态。验证 SDK 原格式事件与 JSON 字符串 `content`、无需启动的 HTTP 发送／回复、`FeishuError` 的 operation／数值 code 和错误脱敏。消息回调须被 await，失败返回失败 ACK；`onError` 抛错／拒绝须隔离且不输出原日志。`stop()` 不等待或取消已执行的回调／HTTP 请求。
+
+回调需在 3 秒内结束；去重、授权、防机器人自回复和耗时任务持久队列属于宿主，不承诺断线／重推恰好一次。现有 Webhook `makePlan`／`deliver` 与 `NotifyConfig` 保持不变，不扩展为卡片动作回调接收器。SDK HTTP 的 10 秒／1 MiB／禁重定向限制应单独验证，不要把 `createTransport` 的 JSON 响应保证套用到 WebSocket 帧。
 
 ## 提交范围
 
 不要提交 `.env`、Token、Webhook、真实接收人、消息原文、日志、node_modules 或包含这些内容的安装包。使用明显的假值，例如 `123:TEST_ONLY`；issue 和截图也需脱敏。
 
-MIT 许可证及从 [dev-notify](https://github.com/QueCue/dev-notify) 提取的既有版权声明应保留。新增依赖、复制外部代码或改变发布方式前，请说明来源、许可证、目的及测试范围。
+MIT 许可证及从 [dev-notify](https://github.com/QueCue/dev-notify) 提取的既有版权声明应保留。飞书客户端使用固定版本 `1.76.0` 的官方 MIT 许可运行时依赖 `@larksuiteoapi/node-sdk`，由其负责应用 token、二进制协议、分帧心跳和重连，默认关闭 SDK 日志；不要再将本库描述为无运行时依赖。新增／更新依赖、复制外部代码或改变发布方式前，请说明来源、许可证、目的及测试范围。
 
 ## 版本包
 

package/PUBLISHING.md

@@ -5,7 +5,7 @@
 ## 包和发布边界
 
 - 包名 `@quecue/notify-core`，MIT 许可证，公开 npm 包。保留从 [dev-notify](https://github.com/QueCue/dev-notify) 提取代码的版权声明。
-- 没有第三方运行时依赖；开发工具由 package-lock 固定。npm 包仅含 dist 运行时／类型、公开说明、package.json 和许可证，不含测试、CI 脚本或应用凭据。
+- 飞书客户端新增官方 MIT 许可运行时依赖 `@larksuiteoapi/node-sdk`，固定为 `1.76.0`；本库不再是无运行时依赖。直接版本由 package.json 固定，开发工具及依赖树由 package-lock 固定；发行前核对 SDK 和传递依赖的来源、许可证及锁文件。npm 包仅含 dist 运行时／类型、公开说明、package.json 和许可证，不含测试、CI 脚本或应用凭据。
 - GitHub Actions 使用托管 Ubuntu runner、Node.js 24 和 npm 11.21.0；只有正式发布任务拥有 `id-token: write`。不需要 `NPM_TOKEN`、`NODE_AUTH_TOKEN` secret 或本机 npm 登录。
 - GitHub 仓库公开、工作流存在和测试通过，都不能证明 npm 账户侧信任已配置，也不等于包已经发布。
 
@@ -35,6 +35,8 @@
 5. 保持 `verify_only=true` 先运行验证：安装锁定依赖、编译、测试、生成 tarball、校验精确文件白名单／元数据／SHA512，再隔离安装同一个 tarball，核对 ESM 导出及 TypeScript 类型。下载 `npm-package` artifact 检查。
 6. 确认 npm 信任已建立且版本可发行后，对**同一提交**再次运行，设置 `verify_only=false`。正式运行会重新验证，并只上传本次验证任务保存的同一 tarball；不是直接上传之前某次运行或本机目录中的包。
 
+隔离安装本地 tarball **仍会联网 npm registry 下载 SDK 及其传递依赖**，不是完全离线检查；`npm ci --ignore-scripts` 也需要可用的 registry／缓存。安装忽略脚本不等于禁止网络，隔离目录不等于网络沙箱。库导入／客户端创建不联网、SDK 懒加载的承诺仅指运行时，不覆盖 npm 安装；冒烟验证应保持使用虚假凭据和离线适配器，不执行真实 `start()` 或发送。检查新客户端的 ESM 导出和类型、启动／停止／错误边界，以及 Webhook／`NotifyConfig` 未变；SDK HTTP 的 10 秒／1 MiB／禁止重定向保护不代表 WebSocket 帧也有 `createTransport` 的 JSON 响应保证。
+
 工作流仅通过 `workflow_dispatch` 触发。正式版本映射 `latest`；`alpha.N`、`beta.N`、`rc.N` 映射对应预发布标签。不会让预发布额外覆盖 `latest`。手动表单通过环境变量传给脚本，不直接拼接到 shell。
 
 ## 发布与失败核验
@@ -47,11 +49,11 @@
 - 测试或仅验证任务成功不表示发布成功。以正式发布任务结果和 registry 状态为准：
 
 ```sh
-npm view @quecue/notify-core@0.1.0 version dist.integrity --json --registry=https://registry.npmjs.org/
+npm view @quecue/notify-core@0.2.0 version dist.integrity --json --registry=https://registry.npmjs.org/
 npm view @quecue/notify-core dist-tags --json --registry=https://registry.npmjs.org/
 ```
 
-应用应声明正常的 npm 运行时依赖，如 `"@quecue/notify-core": "0.1.0"`，在版本可用后更新锁文件并回归；无需保存 vendor tarball、复制通讯运行时或检出兄弟仓库。
+应用应声明正常的 npm 运行时依赖，如 `"@quecue/notify-core": "0.2.0"`，在版本可用后更新锁文件并回归；无需保存 vendor tarball、复制通讯运行时或检出兄弟仓库。
 
 ## 官方参考
 

package/README.en.md

@@ -7,17 +7,17 @@ A small Node.js library for Telegram and Feishu: message planning, a Markdown re
 Originally extracted from [dev-notify](https://github.com/QueCue/dev-notify) and maintained independently at [QueCue/notify-core](https://github.com/QueCue/notify-core).
 
 - ESM with TypeScript declarations; Node.js 22 or later.
-- No third-party runtime dependencies; uses built-in `fetch` and `crypto`.
-- Telegram message sending and selected query/button APIs; Feishu custom-bot Webhook sending, **not Feishu inbound events or card callbacks**.
-- Importing does not read credentials, application configuration or keyrings, start polling, or perform network requests.
+- Webhook/Telegram transport uses built-in `fetch` and `crypto`; the Feishu client adds the official MIT-licensed `@larksuiteoapi/node-sdk`, pinned to `1.76.0` as a runtime dependency.
+- Telegram sending and selected query/button APIs; Feishu custom-bot Webhook sending plus self-built app WebSocket message reception and HTTP sending/replies; **no card-action callbacks**.
+- No credential discovery from environment variables, application configuration or keyrings, and no automatic polling or long connections. Importing and creating a Feishu client are offline; the SDK is lazy-loaded, and reception requires an explicit `start()`.
 
 ## Status and installation
 
-MIT-licensed source; npm package name: `@quecue/notify-core`. The registry is authoritative for available versions:
+MIT-licensed source; npm package name: `@quecue/notify-core`. The Feishu self-built app client below is available starting with `0.2.0`; see the [changelog](CHANGELOG.en.md). The registry is authoritative for available versions:
 
 ```sh
 npm view @quecue/notify-core version --registry=https://registry.npmjs.org/
-npm install @quecue/notify-core@0.1.0
+npm install @quecue/notify-core@0.2.0
 ```
 
 Applications can declare it as a normal runtime dependency. npm installs it automatically, without a source checkout, vendor archive or embedded copy. Import the ESM API and declarations through `@quecue/notify-core`.
@@ -34,7 +34,7 @@ npm pack --pack-destination releases
 Install the generated file in your own Node.js application, replacing the path:
 
 ```sh
-npm install /path/to/quecue-notify-core-0.1.0.tgz
+npm install /path/to/quecue-notify-core-0.2.0.tgz
 ```
 
 No other project needs to be checked out. Use the declared ESM entry; CommonJS `require()` and browser compatibility are not guaranteed.
@@ -99,6 +99,7 @@ console.log(result.ok); // true; the injected transport performs no real request
 | `splitPlainText(text, limit = 4000)` | UTF-16-unit budget without splitting surrogate pairs; not grapheme-cluster or atomic-delivery protection |
 | `createTransport(options?)` | Defaults to a 10-second timeout, 1 MiB response limit, no redirects, strict UTF-8 and JSON-object checks; supports an injected fetcher |
 | `createTelegramApi(token, options?)` | Selected API methods, without a polling loop, offset persistence or authorization |
+| `createFeishuClient({appId,appSecret}, options)` | Synchronously creates a self-built app client; explicit `start()` receives messages, while `sendMessage`/`replyMessage` use HTTP |
 
 Markdown supports readable headings, quotations, lists, emphasis, code and tables. Link addresses remain visible. Telegram parse rejection can fall back to plain text; Feishu can retry using compatible card components. Metadata that cannot fit safely is rejected instead of silently truncated.
 
@@ -122,10 +123,82 @@ const api = createTelegramApi(process.env.TELEGRAM_BOT_TOKEN ?? '', {
 
 Allowed methods: `sendMessage`, `editMessageReplyMarkup`, `answerCallbackQuery`, `getMe`, `getUpdates`, `getWebhookInfo`. The library never deletes a Webhook. `getUpdates` and Webhooks are mutually exclusive; only one consumer may receive a Bot's updates. The application owns offsets, deduplication, backlogs and process coordination.
 
+### Feishu self-built apps: WebSocket reception and HTTP replies
+
+This client is separate from existing Webhook `makePlan`/`deliver`; `NotifyConfig` is unchanged. **Only self-built apps support long connections; custom-bot Webhook URLs and secrets cannot receive events.** WebSocket receives only `im.message.receive_v1` message events; sends/replies use HTTP APIs. Card-action callbacks are unsupported, and the host does not need a public callback endpoint.
+
+Configure the app in the Feishu developer console first:
+
+1. Create a self-built app and enable its bot capability.
+2. Select long-connection mode under events and callbacks, and subscribe to `im.message.receive_v1`.
+3. Request `im:message:send_as_bot` for sending, and as needed `im:message.p2p_msg:readonly` for private messages and `im:message.group_at_msg:readonly` for group mentions. The platform is authoritative for permissions, approvals and visibility.
+4. Publish an app version and ensure the user account is within its availability scope. The runtime needs outbound access to Feishu services.
+
+Minimal receive-and-reply example (host-selected user only; production also needs deduplication and full authorization):
+
+```js
+import { createFeishuClient } from '@quecue/notify-core';
+
+// The host still reads credentials and the allowlist; never hard-code real values.
+const allowedOpenId = process.env.FEISHU_ALLOWED_OPEN_ID ?? '';
+const client = createFeishuClient({
+  appId: process.env.FEISHU_APP_ID ?? '',
+  appSecret: process.env.FEISHU_APP_SECRET ?? '',
+}, {
+  onMessage: async (event) => {
+    // Avoid bot self-replies and check the sender before executing any business action.
+    if (event.sender.sender_type !== 'user' || !allowedOpenId ||
+        event.sender.sender_id?.open_id !== allowedOpenId) return;
+    if (event.message.message_type !== 'text') return;
+    const content = JSON.parse(event.message.content);
+    if (typeof content.text !== 'string') return;
+    await client.replyMessage(event.message.message_id, {
+      msgType: 'text',
+      content: JSON.stringify({ text: 'Received your text message' }),
+    });
+  },
+  onError: (error) => console.error('Feishu operation failed', error.operation),
+  startTimeoutMs: 10_000,
+}); // Synchronous, offline creation.
+
+process.once('SIGINT', () => client.stop());
+await client.start(); // Explicit network access; resolves only when WebSocket is ready.
+```
+
+`onMessage` receives the SDK-shaped `FeishuMessageEvent`, not a wrapper with an extra `event` layer: `event.event_id?`, `event.sender.sender_id.open_id?`, `event.sender.sender_type`, and `event.message` fields `message_id`, `chat_id`, `chat_type`, `message_type`, `content`. `content` is a JSON string suitable for `JSON.parse`; do not assume non-text messages have a `text` field.
+
+Client contract:
+
+- `createFeishuClient({appId,appSecret}, {onMessage, onError?, startTimeoutMs?, adapterFactory?})` returns synchronously. `adapterFactory` supports offline tests or a custom SDK adapter; custom implementations own their network and redaction boundaries.
+- `await client.start()` waits for actual WS readiness, with a default `10000` ms timeout. Timeout or fatal errors reject the Promise; repeated `start()` is idempotent. `client.state` is `idle`, `connecting`, `connected`, `reconnecting`, `failed` or `stopped`.
+- `client.stop()` synchronously closes the connection and disables reconnection, canceling a pending `start()` by rejecting its Promise; the client can be started again. It **does not wait for or cancel** callbacks or HTTP requests already in progress.
+- `onMessage` is awaited and must finish within **3 seconds**. Failure is safely reported to `onError`, then a safe error is thrown so the SDK returns a failure ACK. Throws/rejections from `onError` are isolated without logging the original error. The 10-second HTTP timeout is not the callback time budget.
+- The host owns `event_id`/`message_id` deduplication, sender/chat authorization, bot self-reply prevention and a durable queue for slow work. Disconnects/redelivery provide no exactly-once guarantee; callback retries can repeat business effects. The example does not implement durable deduplication. Multiple long-connected clients for one app receive in cluster mode, not broadcast mode.
+
+Sending does not require `start()` and makes an HTTP request directly:
+
+```js
+const sent = await client.sendMessage({
+  receiveId: 'oc_EXAMPLE', // Replace with a host-validated recipient.
+  receiveIdType: 'chat_id', // Optional; defaults to chat_id.
+  msgType: 'text',
+  content: JSON.stringify({ text: 'Proactive message' }),
+  // uuid: 'host-provided-request-id',
+});
+// sent: { messageId, chatId? }
+```
+
+`client.replyMessage(messageId, {msgType, content, replyInThread?, uuid?})` also returns `{messageId,chatId?}`; `content` is a JSON string for the selected message type. Neither method uses message planning or automatic splitting.
+
+The official MIT-licensed `@larksuiteoapi/node-sdk@1.76.0` handles app tokens, the binary protocol, framing, heartbeats and reconnection; SDK logging is disabled by default. SDK HTTP is independently configured with a 10-second timeout, 1 MiB limit and no redirects. **WebSocket frames are not covered by `createTransport`'s 1 MiB JSON-response guarantee**, nor do they use its `request`/`fetcher` injection.
+
+Reference: [official SDK WebSocket event reception](https://github.com/larksuite/node-sdk#receive-events-by-websocket-connection).
+
 ## Errors and delivery semantics
 
-- Built-in transport-generated safe errors omit original URLs, response bodies and underlying network exception text. `NotifyError` is the base class for `TransportError`, `HttpError` and `TelegramApiError`. Custom translators, transports and callbacks are outside this guarantee and must sanitize their own errors.
+- Built-in transport-generated safe errors omit original URLs, response bodies and underlying network exception text. `NotifyError` is the base class for `TransportError`, `HttpError`, `TelegramApiError` and `FeishuError`. Custom translators, transports and callback-owned output are outside this guarantee and must be sanitized by the caller.
 - `HttpError.status` describes an already-parsed HTTP failure. Invalid JSON or UTF-8 may first produce `TransportError`; not every HTTP 401 is guaranteed to become the same error type.
+- `FeishuError extends NotifyError`: `operation` is `configuration`, `connection`, `stopped`, `send`, `reply` or `handler`; optional `code` is numeric. Generated errors omit SDK text. Handler failures are wrapped as safe errors rather than forwarding the original callback exception to the SDK or `onError`.
 - `TelegramApiError` has `code`, `retryAfterSeconds` and `fatal`. `fatal` is true only for 401/404/409 and does not terminate the host process.
 - `createTelegramApi` retries a 429 at most once within its default 60-second wait threshold. Set `maxRateLimitWaitSeconds: 0` to disable this internal wait. Other network failures are not automatically resent.
 - `deliver` has separate handling for valid Telegram 429 waits up to 60 seconds, format fallback for the current part, and 250 ms spacing between successful Feishu parts. Combined fallback paths do not imply a two-request maximum for the whole operation.

package/README.md

@@ -7,17 +7,17 @@
 代码最初提取自 [dev-notify](https://github.com/QueCue/dev-notify)，在 [QueCue/notify-core](https://github.com/QueCue/notify-core) 独立维护。
 
 - ESM，提供 TypeScript 类型，要求 Node.js 22 或更新版本。
-- 无第三方运行时依赖；使用 Node 内置 `fetch` 和 `crypto`。
-- Telegram：发送消息，以及有限的查询／按钮 API；飞书：自定义机器人 Webhook 发送，**不包含飞书消息或卡片回调接收服务**。
-- 不读取环境变量或配置文件来取得凭据，不访问系统凭据库，不启动轮询或后台服务；单纯导入不会联网。
+- Webhook／Telegram 传输使用 Node 内置 `fetch` 和 `crypto`；飞书客户端新增官方 MIT 许可 SDK `@larksuiteoapi/node-sdk`，运行时依赖固定为 `1.76.0`。
+- Telegram：发送消息，以及有限的查询／按钮 API；飞书：自定义机器人 Webhook 发送，以及自建应用 WebSocket 收消息、HTTP API 发送／回复；**不支持卡片动作回调**。
+- 不读取环境变量或配置文件来取得凭据，不访问系统凭据库，不自动启动轮询或长连接。导入和创建飞书客户端均不联网，SDK 懒加载；显式 `start()` 才启动接收。
 
 ## 当前状态与安装
 
-源码使用 MIT 许可证，npm 包名为 `@quecue/notify-core`。实际可用版本以 registry 为准：
+源码使用 MIT 许可证，npm 包名为 `@quecue/notify-core`。从 `0.2.0` 起提供下述飞书自建应用客户端，版本变化见[变更记录](CHANGELOG.md)。实际可用版本以 registry 为准：
 
 ```sh
 npm view @quecue/notify-core version --registry=https://registry.npmjs.org/
-npm install @quecue/notify-core@0.1.0
+npm install @quecue/notify-core@0.2.0
 ```
 
 应用可将它声明为普通运行时依赖，npm 会自动安装，不需要用户检出本仓库、复制 vendor 包或手工嵌入通讯源码。ESM／类型入口均通过 `@quecue/notify-core` 导入。
@@ -34,7 +34,7 @@ npm pack --pack-destination releases
 在你的 Node.js 项目中安装生成的文件（将路径换为实际位置）：
 
 ```sh
-npm install /path/to/quecue-notify-core-0.1.0.tgz
+npm install /path/to/quecue-notify-core-0.2.0.tgz
 ```
 
 `npm ci` 需要完整源码检出，包括锁文件；不需要同时检出其他项目。运行时只支持本包声明的 ESM 入口，不保证 `require()` 或浏览器环境兼容性。
@@ -99,6 +99,7 @@ console.log(result.ok); // true；使用注入传输，没有真实发送。
 | `splitPlainText(text, limit = 4000)` | 按 UTF-16 单元预算分段，不切断代理对；保持正文，不保证不拆开组合字形或整条消息原子投递 |
 | `createTransport(options?)` | 10 秒超时、1 MiB 响应上限、禁止重定向、严格 UTF-8／JSON 对象检查；返回可注入 `fetcher` 的请求函数 |
 | `createTelegramApi(token, options?)` | 固定 Telegram 方法集合，不启动轮询、不持久化 offset、不提供身份授权 |
+| `createFeishuClient({appId,appSecret}, options)` | 同步创建自建应用客户端；显式 `start()` 接收消息，`sendMessage`／`replyMessage` 通过 HTTP 发送 |
 
 Markdown 支持标题、引用、列表、内联强调、代码和表格的可读渲染，链接地址保留在可见文字中。Telegram 解析失败可回退纯文本；飞书卡片组件被拒绝时可尝试兼容组件。过长标题／footer 等不能安全分段时明确失败，不悄悄截断。
 
@@ -122,10 +123,82 @@ const api = createTelegramApi(process.env.TELEGRAM_BOT_TOKEN ?? '', {
 
 允许的方法仅为 `sendMessage`、`editMessageReplyMarkup`、`answerCallbackQuery`、`getMe`、`getUpdates` 和 `getWebhookInfo`。不会删除现有 Webhook。`getUpdates` 与 Webhook 互斥，同一个 Bot 只能有一个更新消费者；offset、去重、积压消息、业务授权和进程互斥由应用管理。
 
+### 飞书自建应用：长连接接收与 HTTP 回复
+
+此入口独立于现有 Webhook `makePlan`／`deliver`，`NotifyConfig` 不变。**只有自建应用支持长连接；自定义机器人 Webhook 地址和 `secret` 不能用于接收。** WebSocket 仅接收 `im.message.receive_v1` 消息事件，发送／回复走 HTTP API，不支持卡片动作回调，也不需要宿主提供公网回调地址。
+
+先在飞书开放平台完成配置：
+
+1. 创建自建应用并启用机器人能力。
+2. 在“事件与回调”选择长连接模式，订阅 `im.message.receive_v1`。
+3. 申请发送权限 `im:message:send_as_bot`，按需申请私聊接收权限 `im:message.p2p_msg:readonly`、群聊 @机器人接收权限 `im:message.group_at_msg:readonly`；具体权限、审批及可见范围以平台为准。
+4. 发布应用版本，并确保使用账号在应用可用范围内；运行环境需能访问飞书公网服务。
+
+最小接收并回复示例（只允许宿主指定的用户，生产环境还需去重和完整授权）：
+
+```js
+import { createFeishuClient } from '@quecue/notify-core';
+
+// 凭据及授权名单仍由宿主读取；不要把真实值写进源码。
+const allowedOpenId = process.env.FEISHU_ALLOWED_OPEN_ID ?? '';
+const client = createFeishuClient({
+  appId: process.env.FEISHU_APP_ID ?? '',
+  appSecret: process.env.FEISHU_APP_SECRET ?? '',
+}, {
+  onMessage: async (event) => {
+    // 防止机器人自回复，并验证发送者；不要对所有入站消息自动执行业务。
+    if (event.sender.sender_type !== 'user' || !allowedOpenId ||
+        event.sender.sender_id?.open_id !== allowedOpenId) return;
+    if (event.message.message_type !== 'text') return;
+    const content = JSON.parse(event.message.content);
+    if (typeof content.text !== 'string') return;
+    await client.replyMessage(event.message.message_id, {
+      msgType: 'text',
+      content: JSON.stringify({ text: '收到你的文本消息' }),
+    });
+  },
+  onError: (error) => console.error('飞书操作失败', error.operation),
+  startTimeoutMs: 10_000,
+}); // 同步返回，不联网。
+
+process.once('SIGINT', () => client.stop());
+await client.start(); // 主动联网；实际 WebSocket ready 后才完成。
+```
+
+`onMessage` 收到 SDK 原格式 `FeishuMessageEvent`，不是包含额外 `event` 层的包装：`event.event_id?`、`event.sender.sender_id.open_id?`、`event.sender.sender_type`，以及 `event.message` 的 `message_id`、`chat_id`、`chat_type`、`message_type`、`content`。`content` 是 JSON 字符串，可用 `JSON.parse`；非文本消息不要假设存在 `text` 字段。
+
+客户端约定：
+
+- `createFeishuClient({appId,appSecret}, {onMessage, onError?, startTimeoutMs?, adapterFactory?})` 同步返回客户端。`adapterFactory` 用于离线测试或自定义 SDK 适配器；自定义实现须自行维护网络和脱敏边界。
+- `await client.start()` 等待实际 WS ready，默认超时 `10000` 毫秒；超时或致命错误使 Promise 拒绝，重复 `start()` 幂等。`client.state` 为 `idle`／`connecting`／`connected`／`reconnecting`／`failed`／`stopped`。
+- `client.stop()` 同步关闭长连接并禁用重连，取消正在等待的 `start()`（其 Promise 拒绝）；之后可再次 `start()`。它**不等待或取消**已执行中的消息回调或 HTTP 请求。
+- `onMessage` 会被 await，必须在 **3 秒内结束**。失败会先安全报告给 `onError`，再抛安全错误，让 SDK 返回失败 ACK。`onError` 自身抛错或拒绝会被库隔离，不输出原日志。HTTP 请求的 10 秒超时不是消息回调的时间预算。
+- 宿主负责按 `event_id`／`message_id` 去重、发送者／会话授权、防机器人自回复，并将耗时任务放入持久队列。断线与重推不保证恰好一次，重试回调可能重复业务副作用；上例未实现持久去重。相同应用的多个长连客户端按集群模式接收，不是广播。
+
+主动发送不要求先 `start()`，会直接通过 HTTP 联网：
+
+```js
+const sent = await client.sendMessage({
+  receiveId: 'oc_EXAMPLE', // 换成宿主验证过的接收人。
+  receiveIdType: 'chat_id', // 可省略，默认 chat_id。
+  msgType: 'text',
+  content: JSON.stringify({ text: '主动发送' }),
+  // uuid: '由宿主提供的请求标识',
+});
+// sent: { messageId, chatId? }
+```
+
+`client.replyMessage(messageId, {msgType, content, replyInThread?, uuid?})` 同样返回 `{messageId,chatId?}`，`content` 使用相应消息类型的 JSON 字符串；这两个方法不经过消息规划或自动分段。
+
+官方 MIT 许可 SDK `@larksuiteoapi/node-sdk@1.76.0` 负责应用 token、二进制协议、分帧、心跳和重连；默认不输出 SDK 日志。SDK HTTP 独立配置为 10 秒超时、1 MiB 上限、禁止重定向；**WebSocket 帧不适用 `createTransport` 的 1 MiB JSON 响应保证**，也不通过该传输的 `request`／`fetcher` 注入。
+
+参考：[官方 SDK 长连接接收事件](https://github.com/larksuite/node-sdk#receive-events-by-websocket-connection)。
+
 ## 错误、重试与投递语义
 
-- 内置传输不把底层 URL、响应原文或网络异常原文放进它生成的安全错误。`NotifyError` 是公共基类，`TransportError`、`HttpError` 和 `TelegramApiError` 可按类型处理。自定义翻译／传输／回调不在此保证内，调用方须自行脱敏。
+- 内置传输不把底层 URL、响应原文或网络异常原文放进它生成的安全错误。`NotifyError` 是公共基类，`TransportError`、`HttpError`、`TelegramApiError` 和 `FeishuError` 可按类型处理。自定义翻译／传输及业务回调自身的输出不在此保证内，调用方须自行脱敏。
 - `HttpError.status` 是已解析响应的 HTTP 状态；无效 JSON／UTF-8 等可能先表现为 `TransportError`。不要假设所有 HTTP 401 都必然映射为某一种错误。
+- `FeishuError extends NotifyError`：`operation` 区分 `configuration`／`connection`／`stopped`／`send`／`reply`／`handler`，`code?` 为数值；生成的错误不包含 SDK 原文。消息处理失败会被包装为安全错误，不会把业务回调原异常交给 SDK 或 `onError`。
 - `TelegramApiError` 提供 `code`、`retryAfterSeconds`、`fatal`；`fatal` 只对 401／404／409 为真，是供宿主参考的标记，不会自动退出进程。
 - `createTelegramApi` 默认对一次 429 进行至多一次等待重试，等待阈值为 60 秒；`maxRateLimitWaitSeconds: 0` 关闭内层等待。其余网络失败不自动重发。
 - `deliver` 有自己的策略：Telegram 明确 429 且有效 `retry_after` 在 60 秒内时有限重试；格式兼容回退只处理当前分段；飞书成功分段间等待 250 毫秒。上述回退叠加时不能理解为整个调用只会发生两次 HTTP 请求。

package/SECURITY.en.md

@@ -6,17 +6,20 @@ This is a communication library, not an authorization system or security agent.
 
 ## Data and network
 
-- Importing does not access the network, environment credentials, application configuration or system keyrings. Explicit sends/API calls transmit selected content to the configured service, whose retention is outside this library's control.
+- Importing and creating a Feishu client are offline and do not read environment credentials, application configuration or system keyrings. Explicit sends/API calls transmit content; Feishu `start()` initiates network reception, while `sendMessage`/`replyMessage` use HTTP without requiring startup. Service-side retention is outside this library's control.
 - The Telegram factory fixes its official HTTPS base and limits methods. Generic JSON transport and Feishu Webhook configuration are **not URL access controls**. Hosts must validate schemes, destination domains, recipients and links; never pass untrusted external URLs directly.
 - Default transport preserves runtime TLS verification, rejects redirects, defaults to 10 seconds and 1 MiB, and checks UTF-8 and JSON objects. Limits are configurable; weakened settings or substituted transports require their own review.
+- The Feishu client adds the official MIT-licensed runtime dependency `@larksuiteoapi/node-sdk`, pinned to `1.76.0` and lazy-loaded. It manages app tokens, the binary protocol, framing, heartbeats and reconnection. SDK HTTP is independently configured with a 10-second timeout, 1 MiB limit and no redirects. **SDK WebSocket frames are outside `createTransport`'s 1 MiB JSON-response guarantee**; do not extend that guarantee to all SDK traffic.
 - Proxy configuration belongs to the host. Default fetch behavior depends on Node startup and network settings; unconditional proxy bypass is not promised.
 - Built-in safe error summaries omit original URLs, response bodies and underlying network exception text. This is not general content redaction: titles, bodies, footers, buttons, custom translators, injected transports and callbacks can contain sensitive data.
 - `NotifyConfig` is a type contract, not account validation or exhaustive runtime schema validation. Hosts and services must handle missing, invalid or revoked credentials.
 
 ## Receiving and authorization
 
-- `getUpdates` is a request API, not a background receiver, Webhook server, offset store, deduplicator or sender authorization system. Feishu supports custom-bot Webhook sending only, not inbound events.
-- A Bot must have one update consumer. The library does not delete Webhooks, take over other consumers or automatically execute backlogged actions.
+- Telegram `getUpdates` is a request API, not a background receiver, Webhook server, offset store, deduplicator or sender authorization system.
+- A Telegram Bot must have one update consumer. The library does not delete Webhooks, take over other consumers or automatically execute backlogged actions.
+- Only Feishu self-built apps can explicitly `start()` a long connection for `im.message.receive_v1`. Webhook URLs/secrets cannot receive events; card-action callbacks are unsupported. Hosts must enable the bot, configure long-connection event subscriptions, request send/receive permissions, publish a version and restrict app availability (see the [README setup](README.en.md#feishu-self-built-apps-websocket-reception-and-http-replies)).
+- Incoming messages remain untrusted business input. Hosts own `event_id`/`message_id` deduplication, user/chat authorization, bot self-reply prevention and a durable queue for slow work. Reception is not permission to execute commands. Disconnects/redelivery provide no exactly-once guarantee; multiple clients for one app receive in cluster mode, not broadcast mode.
 - `reply.users` selects recipients shown buttons; it grants no permission to submit callbacks. Hosts must verify user/chat/request identities, lengths, expiry and routing.
 
 ## Retries and state
@@ -24,6 +27,8 @@ This is a communication library, not an authorization system or security agent.
 - A timeout may follow server acceptance; delivery may be unknown. Exactly-once or atomic multipart delivery is not promised.
 - Explicit rate-limit or format rejection can trigger bounded retries/fallbacks, not repeated application-side effects.
 - `onSent` runs after reported delivery; a callback failure cannot undo the message. Do not blindly resend a whole plan because `ok` is false.
+- Feishu `onMessage` is awaited and must finish within 3 seconds. Failure is safely reported to `onError`, then a safe error is thrown so the SDK returns a failure ACK, potentially causing redelivery. `FeishuError extends NotifyError`; `operation` is `configuration`, `connection`, `stopped`, `send`, `reply` or `handler`, and optional `code` is numeric, without SDK text. Throws/rejections from `onError` are isolated; SDK logs and original callback exceptions are not output by default. Hosts must still sanitize their own logs.
+- Feishu startup waits up to 10000 ms by default for actual WS readiness; timeout/fatal errors reject, and repeated startup is idempotent. Synchronous `stop()` closes the connection, disables reconnection and rejects pending startup; restarting is supported. It does not wait for or cancel callbacks/HTTP requests in progress and cannot undo business actions.
 - The library does not persist queues, tokens, content, offsets or logs. Application storage, logs, backups, permissions and updates require separate assessment.
 
 ## Reporting vulnerabilities

package/SECURITY.md

@@ -6,17 +6,20 @@
 
 ## 数据与网络
 
-- 导入库不会联网、读取应用配置、环境凭据或系统凭据库。应用显式调用投递／API 后，请求正文才发送到所选平台；外部平台的数据保留规则不由本库控制。
+- 导入库及创建飞书客户端不会联网，也不会读取应用配置、环境凭据或系统凭据库。显式投递／API 调用才发送内容；飞书 `start()` 主动联网接收，`sendMessage`／`replyMessage` 无需先启动即可通过 HTTP 发送。外部平台的数据保留规则不由本库控制。
 - Telegram API 工厂固定官方 HTTPS 基址并限制方法；通用 JSON 传输和飞书 Webhook 配置并不构成 URL 访问控制。宿主必须验证协议、目的地域名、接收人以及跳转链接，不能将外部不可信 URL 直接交给传输。
 - 默认传输保留运行时 TLS 验证，禁止重定向，默认超时 10 秒、响应最多 1 MiB，严格检查 UTF-8 和 JSON 对象。限制可配置；降低保护或替换传输后的安全性由宿主承担。
+- 飞书客户端新增固定版本 `1.76.0` 的官方 MIT 许可运行时依赖 `@larksuiteoapi/node-sdk`，懒加载并由其管理应用 token、二进制协议、分帧、心跳和重连。SDK HTTP 独立配置 10 秒超时、1 MiB 上限及禁止重定向；**SDK WebSocket 帧不受 `createTransport` 的 1 MiB JSON 响应保证约束**，不能将该保证推广到所有 SDK 流量。
 - 代理由宿主提供。默认 fetch 的行为受 Node 启动和网络配置影响；库不保证完全不使用代理，也不提供自动代理发现或凭据隔离。
 - 内置错误对 URL、响应原文、底层异常采用安全摘要。不要把这理解为对任何用户输入的通用脱敏：标题、正文、footer、按钮内容、自定义翻译、注入传输和业务回调仍可能包含敏感信息。
 - `NotifyConfig` 是类型约定，不会查询凭据是否有效，也不实现全面运行时 schema 验证。缺少、错误或已撤销的凭据由应用和服务端处理。
 
 ## 接收与授权
 
-- `getUpdates` 只是请求接口，没有内置后台循环、Webhook 接收器、offset 保存、重复更新过滤或发送者授权。飞书当前只有自定义机器人 Webhook 发送，不提供事件接收服务。
-- 只能由一个消费者读取同一 Bot 的更新；本库不会删除现有 Webhook、抢占其他消费者或自动恢复积压命令。
+- Telegram `getUpdates` 只是请求接口，没有内置后台循环、Webhook 接收器、offset 保存、重复更新过滤或发送者授权。
+- 只能由一个消费者读取同一 Telegram Bot 的更新；本库不会删除现有 Webhook、抢占其他消费者或自动恢复积压命令。
+- 飞书仅自建应用可通过显式 `start()` 长连接接收 `im.message.receive_v1`；Webhook 地址／secret 不可用于接收，不支持卡片动作回调。宿主需启用机器人、配置长连接事件订阅、申请发送／接收权限、发布版本并限制可用范围（配置步骤见 [README](README.md#飞书自建应用长连接接收与-http-回复)）。
+- 入站消息仍是不可信业务输入。宿主负责 `event_id`／`message_id` 去重、用户和会话授权、防机器人自回复及耗时任务的持久队列；不要假设收到消息就有权执行命令。断线与重推不保证恰好一次，同一应用的多个长连客户端是集群分发而非广播。
 - `reply.users` 只控制展示给哪些接收人按钮，不授予回调提交权。应用必须自行核验用户、聊天、请求身份、长度、时效和路由。
 
 ## 重试与状态
@@ -24,7 +27,9 @@
 - 网络超时可能发生在服务端已接受消息之后；投递可能未知，不保证恰好一次或长消息原子发送。
 - 明确的限流和格式兼容拒绝可能触发有界重试／回退；它们不允许宿主重复执行有副作用的业务操作。
 - `onSent` 在成功发送后调用，其失败不能撤销已投递消息。不要因为 `ok:false` 就不加区分地重发整个计划。
-- 库不保存持久队列、Token、消息正文、offset 或日志。应用自己的存储、日志、备份、权限和更新机制需单独评估。
+- 飞书 `onMessage` 被 await，须在 3 秒内结束；失败先安全报告 `onError`，再抛安全错误使 SDK 返回失败 ACK，可能触发重推。`FeishuError extends NotifyError`，`operation` 区分 `configuration`／`connection`／`stopped`／`send`／`reply`／`handler`，`code?` 为数值，不携带 SDK 原文。`onError` 自身抛错／拒绝会被隔离，默认不输出 SDK 日志或回调原异常；宿主日志仍须自行脱敏。
+- 飞书启动默认等待实际 WS ready 最多 10000 毫秒；超时／致命错误拒绝，重复启动幂等。同步 `stop()` 关闭长连、禁用重连并拒绝正在等待的启动，之后可重启；不等待或取消已执行中的回调／HTTP 请求，不能作为撤销业务操作的保证。
+- 库不持久保存队列、Token、消息正文、offset 或日志。应用自己的存储、日志、备份、权限和更新机制需单独评估。
 
 ## 报告安全问题
 

package/dist/feishu-sdk.d.ts

@@ -0,0 +1,5 @@
+import type { FeishuAdapter, FeishuCredentials } from './feishu.js';
+type Sdk = typeof import('@larksuiteoapi/node-sdk');
+/** 内部适配层；SDK 懒加载，导入 notify-core 或创建客户端都不会建立连接。 */
+export declare function createFeishuSdkAdapter(credentials: FeishuCredentials, loadSdk?: () => Promise<Sdk>): Promise<FeishuAdapter>;
+export {};

package/dist/feishu-sdk.js

@@ -0,0 +1,44 @@
+/** 内部适配层；SDK 懒加载，导入 notify-core 或创建客户端都不会建立连接。 */
+export async function createFeishuSdkAdapter(credentials, loadSdk = () => import('@larksuiteoapi/node-sdk')) {
+    const sdk = await loadSdk();
+    // 不使用 SDK 默认日志，避免连接 URL、凭据、事件正文或底层异常进入控制台。
+    const quiet = () => { };
+    const logger = { error: quiet, warn: quiet, info: quiet, debug: quiet, trace: quiet };
+    const httpInstance = sdk.defaultHttpInstance.create({ timeout: 10000, maxRedirects: 0,
+        maxContentLength: 1024 * 1024, maxBodyLength: 1024 * 1024, responseType: 'json',
+        transitional: { silentJSONParsing: false } });
+    // SDK 的长连接发现请求自带 timeout，仍统一收紧到本库的 HTTP 边界。
+    httpInstance.interceptors.request.use(request => { request.timeout = 10000; return request; });
+    httpInstance.interceptors.response.use(response => response.data);
+    const config = { ...credentials, appType: sdk.AppType.SelfBuild, domain: sdk.Domain.Feishu,
+        logger, httpInstance: httpInstance };
+    const client = new sdk.Client(config);
+    let connection;
+    return {
+        start(handlers) {
+            connection = new sdk.WSClient({ ...config, autoReconnect: true, handshakeTimeoutMs: 10000,
+                onReady: handlers.onReady, onError: handlers.onError,
+                onReconnecting: handlers.onReconnecting, onReconnected: handlers.onReconnected });
+            const eventDispatcher = new sdk.EventDispatcher({ logger }).register({
+                'im.message.receive_v1': handlers.onMessage,
+            });
+            return connection.start({ eventDispatcher });
+        },
+        close() {
+            const active = connection;
+            connection = undefined;
+            active?.close({ force: true });
+        },
+        sendMessage(message) {
+            return client.im.v1.message.create({ params: { receive_id_type: message.receiveIdType ?? 'chat_id' },
+                data: { receive_id: message.receiveId, msg_type: message.msgType, content: message.content,
+                    ...(message.uuid === undefined ? {} : { uuid: message.uuid }) } });
+        },
+        replyMessage(messageId, message) {
+            return client.im.v1.message.reply({ path: { message_id: messageId },
+                data: { msg_type: message.msgType, content: message.content,
+                    ...(message.replyInThread === undefined ? {} : { reply_in_thread: message.replyInThread }),
+                    ...(message.uuid === undefined ? {} : { uuid: message.uuid }) } });
+        },
+    };
+}

package/dist/feishu.d.ts

@@ -0,0 +1,100 @@
+import { NotifyError } from './messages.js';
+export interface FeishuCredentials {
+    appId: string;
+    appSecret: string;
+}
+export interface FeishuUserId {
+    open_id?: string;
+    user_id?: string;
+    union_id?: string;
+}
+/** 飞书 SDK 分发的消息事件；content 保持平台原始 JSON 字符串。 */
+export interface FeishuMessageEvent {
+    event_id?: string;
+    event_type?: string;
+    create_time?: string;
+    tenant_key?: string;
+    sender: {
+        sender_id?: FeishuUserId;
+        sender_type: string;
+        tenant_key?: string;
+    };
+    message: {
+        message_id: string;
+        chat_id: string;
+        chat_type: string;
+        message_type: string;
+        content: string;
+        create_time: string;
+        update_time?: string;
+        root_id?: string;
+        parent_id?: string;
+        thread_id?: string;
+        mentions?: {
+            key: string;
+            id: FeishuUserId;
+            name: string;
+            tenant_key?: string;
+        }[];
+    };
+}
+export type FeishuReceiveIdType = 'chat_id' | 'open_id' | 'user_id' | 'union_id' | 'email';
+export interface FeishuOutgoingMessage {
+    msgType: string;
+    content: string;
+    uuid?: string;
+}
+export interface FeishuSendMessage extends FeishuOutgoingMessage {
+    receiveId: string;
+    receiveIdType?: FeishuReceiveIdType;
+}
+export interface FeishuReplyMessage extends FeishuOutgoingMessage {
+    replyInThread?: boolean;
+}
+export interface FeishuMessageResult {
+    messageId: string;
+    chatId?: string;
+}
+export type FeishuState = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'failed' | 'stopped';
+export type FeishuOperation = 'configuration' | 'connection' | 'stopped' | 'send' | 'reply' | 'handler';
+export declare class FeishuError extends NotifyError {
+    readonly operation: FeishuOperation;
+    readonly code?: number | undefined;
+    constructor(operation: FeishuOperation, code?: number | undefined);
+}
+export interface FeishuConnectionHandlers {
+    onReady(): void;
+    onError(): void;
+    onReconnecting(): void;
+    onReconnected(): void;
+    onMessage(event: FeishuMessageEvent): Promise<void>;
+}
+export interface FeishuApiResponse {
+    code?: number;
+    data?: {
+        message_id?: string;
+        chat_id?: string;
+    };
+}
+/** 工厂及 start 之前的适配器必须无网络副作用；close 必须终止重连。 */
+export interface FeishuAdapter {
+    start(handlers: FeishuConnectionHandlers): void | Promise<void>;
+    close(): void;
+    sendMessage(message: FeishuSendMessage): Promise<FeishuApiResponse>;
+    replyMessage(messageId: string, message: FeishuReplyMessage): Promise<FeishuApiResponse>;
+}
+export interface FeishuClientOptions {
+    onMessage?: (event: FeishuMessageEvent) => void | Promise<void>;
+    onError?: (error: FeishuError) => void | Promise<void>;
+    startTimeoutMs?: number;
+    adapterFactory?: (credentials: FeishuCredentials) => FeishuAdapter | Promise<FeishuAdapter>;
+}
+export interface FeishuClient {
+    readonly state: FeishuState;
+    start(): Promise<void>;
+    /** 关闭长连接，但不取消已经执行的业务回调或 HTTP 发送。 */
+    stop(): void;
+    sendMessage(message: FeishuSendMessage): Promise<FeishuMessageResult>;
+    replyMessage(messageId: string, message: FeishuReplyMessage): Promise<FeishuMessageResult>;
+}
+export declare function createFeishuClient(credentials: FeishuCredentials, options?: FeishuClientOptions): FeishuClient;

package/dist/feishu.js

@@ -0,0 +1,145 @@
+import { NotifyError } from './messages.js';
+import { createFeishuSdkAdapter } from './feishu-sdk.js';
+const errors = {
+    configuration: '飞书应用客户端配置无效。',
+    connection: '飞书长连接建立失败、超时或已终止。',
+    stopped: '飞书长连接启动已取消。',
+    send: '飞书消息发送失败，结果可能未知；不会自动重发。',
+    reply: '飞书消息回复失败，结果可能未知；不会自动重发。',
+    handler: '飞书消息处理失败。',
+};
+export class FeishuError extends NotifyError {
+    operation;
+    code;
+    constructor(operation, code) {
+        super(errors[operation]);
+        this.operation = operation;
+        this.code = code;
+        this.name = 'FeishuError';
+    }
+}
+const receiveIdTypes = new Set(['chat_id', 'open_id', 'user_id', 'union_id', 'email']);
+const nonempty = (value) => typeof value === 'string' && value.trim().length > 0;
+export function createFeishuClient(credentials, options = {}) {
+    const startTimeoutMs = options.startTimeoutMs ?? 10000;
+    if (!credentials || typeof credentials.appId !== 'string' || !/^cli_[0-9a-fA-F]{16}$/.test(credentials.appId) ||
+        !nonempty(credentials.appSecret) || !Number.isSafeInteger(startTimeoutMs) || startTimeoutMs < 1 || startTimeoutMs > 2147483647 ||
+        (options.onMessage !== undefined && typeof options.onMessage !== 'function') ||
+        (options.onError !== undefined && typeof options.onError !== 'function') ||
+        (options.adapterFactory !== undefined && typeof options.adapterFactory !== 'function'))
+        throw new FeishuError('configuration');
+    const config = { appId: credentials.appId, appSecret: credentials.appSecret };
+    const { onMessage, onError, adapterFactory = createFeishuSdkAdapter } = options;
+    let state = 'idle', session;
+    let adapter, initializing;
+    function report(error) {
+        // 错误观察回调不能破坏连接状态机或产生未处理的 Promise 拒绝。
+        void Promise.resolve().then(() => onError?.(error)).catch(() => { });
+    }
+    function getAdapter() {
+        if (!initializing)
+            initializing = Promise.resolve().then(() => adapterFactory({ ...config }))
+                .then(value => { adapter = value; return value; })
+                .catch(() => { initializing = undefined; throw new FeishuError('configuration'); });
+        return initializing;
+    }
+    function closeAdapter() {
+        try {
+            adapter?.close();
+        }
+        catch {
+            report(new FeishuError('connection'));
+        }
+    }
+    function fail(active, error) {
+        if (session !== active)
+            return;
+        session = undefined;
+        clearTimeout(active.timer);
+        state = 'failed';
+        closeAdapter();
+        active.reject(error);
+        report(error);
+    }
+    function start() {
+        if (session)
+            return session.promise;
+        if (!onMessage)
+            return Promise.reject(new FeishuError('configuration'));
+        let resolve, reject;
+        const active = { promise: new Promise((ok, no) => { resolve = ok; reject = no; }),
+            resolve: () => resolve(), reject: error => reject(error) };
+        session = active;
+        state = 'connecting';
+        active.timer = setTimeout(() => fail(active, new FeishuError('connection')), startTimeoutMs);
+        const ready = () => {
+            if (session !== active)
+                return;
+            clearTimeout(active.timer);
+            state = 'connected';
+            active.resolve();
+        };
+        void getAdapter().then(value => {
+            if (session !== active)
+                return;
+            return value.start({
+                onReady: ready,
+                onError: () => fail(active, new FeishuError('connection')),
+                onReconnecting: () => { if (session === active)
+                    state = 'reconnecting'; },
+                onReconnected: ready,
+                onMessage: async (event) => {
+                    if (session !== active)
+                        return;
+                    try {
+                        await onMessage(event);
+                    }
+                    catch {
+                        const error = new FeishuError('handler');
+                        report(error);
+                        // 交给 SDK 发送失败 ACK，而不是把失败处理伪装为已成功消费。
+                        throw error;
+                    }
+                },
+            });
+        }).catch(() => fail(active, new FeishuError('connection')));
+        return active.promise;
+    }
+    function stop() {
+        const active = session;
+        session = undefined;
+        state = 'stopped';
+        if (active) {
+            clearTimeout(active.timer);
+            active.reject(new FeishuError('stopped'));
+        }
+        closeAdapter();
+    }
+    async function send(operation, message, messageId) {
+        if (!message || !nonempty(message.msgType) || !nonempty(message.content) ||
+            (message.uuid !== undefined && !nonempty(message.uuid)))
+            throw new FeishuError('configuration');
+        if (operation === 'send') {
+            const target = message;
+            if (!nonempty(target.receiveId) || !receiveIdTypes.has(target.receiveIdType ?? 'chat_id'))
+                throw new FeishuError('configuration');
+        }
+        else if (!nonempty(messageId) ||
+            (message.replyInThread !== undefined && typeof message.replyInThread !== 'boolean'))
+            throw new FeishuError('configuration');
+        let response;
+        try {
+            const value = await getAdapter();
+            response = operation === 'send' ? await value.sendMessage({ ...message }) :
+                await value.replyMessage(messageId, { ...message });
+        }
+        catch {
+            throw new FeishuError(operation);
+        }
+        if (response?.code !== 0 || !nonempty(response.data?.message_id))
+            throw new FeishuError(operation, Number.isSafeInteger(response?.code) ? response.code : undefined);
+        return { messageId: response.data.message_id, ...(nonempty(response.data.chat_id) ? { chatId: response.data.chat_id } : {}) };
+    }
+    return { get state() { return state; }, start, stop,
+        sendMessage: message => send('send', message), replyMessage: (messageId, message) => send('reply', message, messageId) };
+}

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export * from './messages.js';
 export * from './formatting.js';
 export * from './transport.js';
 export * from './channels.js';
+export * from './feishu.js';

package/dist/index.js

@@ -2,3 +2,4 @@ export * from './messages.js';
 export * from './formatting.js';
 export * from './transport.js';
 export * from './channels.js';
+export * from './feishu.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quecue/notify-core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "独立的 Telegram 与飞书通讯、格式化和传输边界库",
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/QueCue/notify-core.git" },
@@ -21,5 +21,8 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "typescript": "^5.9.0"
+  },
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "1.76.0"
   }
 }