@quecue/notify-core 0.0.0-bootstrap.0 → 0.1.0

package/CHANGELOG.en.md

@@ -0,0 +1,13 @@
+# Changelog
+
+English | [简体中文](CHANGELOG.md)
+
+## 0.1.0
+
+First standalone release; the npm registry is authoritative for actual publication status and available versions.
+
+- Extract independent Telegram/Feishu planning, formatting, splitting and delivery from [dev-notify](https://github.com/QueCue/dev-notify).
+- Provide injectable bounded JSON transport, selected Telegram APIs, safe error types and plain-text splitting.
+- Exclude application configuration, keyrings, polling loops, authorization and business state; hosts can inject translation and transport.
+- Add Chinese/English usage and security documentation plus a publication checklist. There are 13 public API tests using simulated network responses and 8 release-validation tests, not exhaustive platform or real-service acceptance.
+- Add a manually dispatched GitHub Actions npm release workflow: verification-only by default, separate OIDC identity and provenance for publishing, delivery of the same verified artifact, and remote integrity checks. The account owner must first initialize the npm package and configure trust.

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# 更新记录
+
+简体中文 | [English](CHANGELOG.en.md)
+
+## 0.1.0
+
+首次独立发行；实际发布状态和可用版本以 npm registry 为准。
+
+- 从 [dev-notify](https://github.com/QueCue/dev-notify) 提取独立的双渠道消息规划、格式化、分段和投递能力。
+- 提供可注入的有界 JSON 传输、有限 Telegram API、安全错误类型及纯文本分段。
+- 不包含应用配置、凭据库、更新接收循环、授权或业务状态；允许宿主注入翻译和传输。
+- 补充中文／英文使用说明、安全边界和公开发布检查表；13 项公共 API 测试使用模拟网络，另有 8 项发行校验测试，不代表全平台或真实服务验收。
+- 新增手动触发的 GitHub Actions npm 发行：默认仅验证，正式模式使用独立 OIDC 身份及 provenance，上传同次验证的候选包并核对远端完整性；npm 包初始化和信任配置须先由账户所有者完成。

package/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# 贡献与本地验证
+
+本库仅维护 Telegram／飞书通用通讯，不接收应用专属命令、会话业务或授权策略。源码与贡献入口为 [QueCue/notify-core](https://github.com/QueCue/notify-core)。
+
+## 开发环境
+
+- Node.js 22 或更高版本、npm。
+- 在本仓库执行 `npm ci --ignore-scripts`、`npm test`。
+- 测试默认禁止真实网络，使用虚假凭据和注入的 HTTP／等待函数；不应要求贡献者提供个人 Bot Token 或 Webhook。
+- 修改 API 时同步 `.d.ts` 构建、中文／英文 README、错误边界和变更记录。不要手工编辑 `dist`。
+
+建议为限流、超时、格式回退、Unicode 分段、部分投递、自定义回调失败和错误脱敏补测试。保持默认导入无网络或配置副作用。传输与授权的边界应写清楚，不要使用测试通过来替代真实平台兼容承诺。
+
+## 提交范围
+
+不要提交 `.env`、Token、Webhook、真实接收人、消息原文、日志、node_modules 或包含这些内容的安装包。使用明显的假值，例如 `123:TEST_ONLY`；issue 和截图也需脱敏。
+
+MIT 许可证及从 [dev-notify](https://github.com/QueCue/dev-notify) 提取的既有版权声明应保留。新增依赖、复制外部代码或改变发布方式前，请说明来源、许可证、目的及测试范围。
+
+## 版本包
+
+当前为 0.x API，不承诺跨版本不变；破坏性变化必须在变更记录和版本中明确体现。生成包前执行测试及 `npm pack --dry-run`，检查 [PUBLISHING.md](PUBLISHING.md)。相同版本号的正式发布包不可覆盖，不应以手改 tarball 的方式绕开版本更新。
+
+安全问题按 [SECURITY.md](SECURITY.md) 处理，不在公开 issue 中附秘密或完整攻击细节。仓库地址、权限和实际发布状态以维护者公开配置为准。

package/PUBLISHING.md

@@ -0,0 +1,61 @@
+# npm 发布流程
+
+本说明面向 [QueCue/notify-core](https://github.com/QueCue/notify-core) 维护者。正式 npm 发行使用本仓库的 [GitHub Actions 工作流](https://github.com/QueCue/notify-core/actions/workflows/publish-npm.yml)，不共享其他项目的发布身份。普通分支推送或版本标签推送均不会自动发布。
+
+## 包和发布边界
+
+- 包名 `@quecue/notify-core`，MIT 许可证，公开 npm 包。保留从 [dev-notify](https://github.com/QueCue/dev-notify) 提取代码的版权声明。
+- 没有第三方运行时依赖；开发工具由 package-lock 固定。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 账户侧信任已配置，也不等于包已经发布。
+
+## 首次建立 npm 包与信任
+
+**npm 官方要求配置 Trusted Publisher 的包已经存在于 registry。** 尚不存在的包不能仅凭本工作流建立首次信任。账户所有者需先通过 npm 支持的认证流程初始化包，然后在该包的 npm 设置配置以下身份；不要把本机登录凭据或其他包的授权复制到 Actions。
+
+| 字段 | 值 |
+| --- | --- |
+| Provider | GitHub Actions |
+| Organization or user | `QueCue` |
+| Repository | `notify-core` |
+| Workflow filename | `publish-npm.yml`，不含目录 |
+| Environment | 留空，本工作流不使用 environment |
+| Publishing permission | 允许直接 `npm publish` |
+
+阶段发布也是 npm 提供的初始化方式，但会产生公开的 `0.0.0-stage` 占位版本，并需账户认证和后续审核；本工作流不会擅自创建该额外版本。具体初始化操作应由维护者明确选择及执行。若首次已直接发布 `0.1.0`，Actions 不会覆盖它或把不同 tarball 当作同一次发行，应使用下一版本验证后续 OIDC 发行。
+
+新建且尚未成功发布的信任配置会在两天后过期；请在包和工作流准备好后配置。成功发行会验证绑定，不能把它理解为所有已绑定配置每两天失效。本流程不自动改 dist-tag，不要求额外的标签管理权限。
+
+## 日常发行
+
+1. 检查待公开源码、历史、版本、CHANGELOG、中英文 README 和安全说明，避免 Token、Webhook、真实配置、本机路径及无关内容。
+2. 修改 package.json 和 package-lock 的版本。npm 已有且内容不同的版本必须换版本，不覆盖或重打历史版本。
+3. 本地执行 `npm ci --ignore-scripts`、`npm test`。当前回归包含模拟网络的公共 API 测试及发行校验测试，不代表全部平台、代理或真实服务验收。
+4. 将已审核的源码、锁文件和工作流推送到 GitHub。进入 Actions → **Publish npm** → **Run workflow**，选择待发行分支或提交所在分支，填写与 package.json 完全一致的 `version`。
+5. 保持 `verify_only=true` 先运行验证：安装锁定依赖、编译、测试、生成 tarball、校验精确文件白名单／元数据／SHA512，再隔离安装同一个 tarball，核对 ESM 导出及 TypeScript 类型。下载 `npm-package` artifact 检查。
+6. 确认 npm 信任已建立且版本可发行后，对**同一提交**再次运行，设置 `verify_only=false`。正式运行会重新验证，并只上传本次验证任务保存的同一 tarball；不是直接上传之前某次运行或本机目录中的包。
+
+工作流仅通过 `workflow_dispatch` 触发。正式版本映射 `latest`；`alpha.N`、`beta.N`、`rc.N` 映射对应预发布标签。不会让预发布额外覆盖 `latest`。手动表单通过环境变量传给脚本，不直接拼接到 shell。
+
+## 发布与失败核验
+
+- 正式任务核对下载包 SHA512，使用 OIDC 执行带 provenance 的 `npm publish`，再只读核对 registry 版本、integrity 和 dist-tag。
+- 包尚未初始化、查询失败或认证失败：停止，不回退到长期 Token，不借用其他仓库身份。
+- 已有版本仅在 SHA512 与本次包一致时跳过上传；不同内容立即停止，不能覆盖。构建环境或文档变化也可能产生不同 tarball。
+- 上传失败或结果未知不自动重发；先查询 registry。上传成功后版本可见性最多等待约 10 分钟，标签最多约 1 分钟；超时不能当作未发布。
+- 不自动修正既有标签。若版本已存在但标签不匹配，应由维护者核实影响后单独处理。
+- 测试或仅验证任务成功不表示发布成功。以正式发布任务结果和 registry 状态为准：
+
+```sh
+npm view @quecue/notify-core@0.1.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、复制通讯运行时或检出兄弟仓库。
+
+## 官方参考
+
+- [Trusted Publishing](https://docs.npmjs.com/trusted-publishers/)
+- [npm trust：包必须已存在的前置条件](https://docs.npmjs.com/cli/v11/commands/npm-trust/)
+- [阶段发布及首次包占位行为](https://docs.npmjs.com/staged-publishing/)
+- [npm publish](https://docs.npmjs.com/cli/v11/commands/npm-publish)

package/README.en.md

@@ -0,0 +1,143 @@
+# notify-core
+
+English | [简体中文](README.md)
+
+A small Node.js library for Telegram and Feishu: message planning, a Markdown rendering subset, Unicode-safe splitting, bounded JSON transport, and an injectable Telegram API. **It does not implement application-specific workflows.**
+
+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.
+
+## Status and installation
+
+MIT-licensed source; npm package name: `@quecue/notify-core`. 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
+```
+
+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`.
+
+For source development or unpublished changes, build a local candidate package:
+
+```sh
+npm ci --ignore-scripts
+npm test
+node -e "require('node:fs').mkdirSync('releases', {recursive: true})"
+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
+```
+
+No other project needs to be checked out. Use the declared ESM entry; CommonJS `require()` and browser compatibility are not guaranteed.
+
+## Quick start
+
+```js
+import { makePlan, deliver } from '@quecue/notify-core';
+
+// The application reads and validates credentials; the library does not discover them.
+const config = {
+  telegram: {
+    token: process.env.TELEGRAM_BOT_TOKEN ?? '',
+    chatIds: [process.env.TELEGRAM_CHAT_ID ?? ''],
+  },
+  feishu: {
+    webhook: process.env.FEISHU_WEBHOOK ?? '',
+    secret: process.env.FEISHU_SECRET ?? '',
+  },
+};
+const message = {
+  title: 'Build completed',
+  content: '**Result**: passed\n\n' + 'Full output\n'.repeat(1000),
+  footer: 'From CI',
+  level: 'success',
+};
+
+// Planning is offline. Validate credentials and recipients before choosing to send.
+const plan = makePlan('telegram', message, config);
+console.log(`Planned ${plan.items.length} parts`);
+// const result = await deliver(plan, config); // Uncommenting performs a real send.
+// if (!result.ok) console.error(result.error);
+```
+
+For Feishu, use `makePlan('feishu', message, config)`; a non-empty `secret` enables custom-bot signing. Channel enablement, credential precedence and authorization belong to the application, not `NotifyConfig`. A non-empty string does not prove that a credential or destination is valid.
+
+### Offline delivery example
+
+```js
+import { makePlan, deliver } from '@quecue/notify-core';
+const config = {
+  telegram: { token: '123:TEST_ONLY', chatIds: ['111'] },
+  feishu: { webhook: '', secret: '' },
+};
+const plan = makePlan('telegram', {
+  title: 'Offline example', content: 'No network', footer: '', level: 'info',
+}, config);
+const result = await deliver(plan, config, async () => ({
+  ok: true, result: { message_id: 1 },
+}));
+console.log(result.ok); // true; the injected transport performs no real request.
+```
+
+## API and boundaries
+
+| API | Behavior |
+| --- | --- |
+| `createChannels(translate?)` | Per-instance message planner and delivery functions |
+| `makePlan(channel, message, config)` | Offline planning, without credential or account validation |
+| `deliver(plan, config, request?, sleep?)` | Sequential delivery returning `{channel,sent,planned,ok,error?}`; stops remaining parts for a failed recipient while continuing others |
+| `createFormatting(translate?)` | Markdown subset parsing and splitting, not full CommonMark |
+| `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 |
+
+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.
+
+Optional `reply` metadata is `{token,url,users,callbackData?}`: an identifier, a Feishu link, recipients shown Telegram buttons, and optional callback data. The default callback data is `reply:` plus `token`. **This does not grant input permission**; the host must validate identities, callback length, expiry, routing and authorization.
+
+### Transport and proxies
+
+There is no built-in proxy URL setting. Inject an application-owned `request` or `fetcher` when required, preserving timeout, TLS, redirect and response-size protections. Default `fetch` proxy behavior depends on Node and startup configuration; unconditional direct connectivity is not guaranteed.
+
+`createTransport({timeoutMs,maxResponseBytes,translate})` returns `(url,payload,fetcher?)`. This generic transport **does not restrict destination URLs**. Applications must validate schemes, domains and recipients rather than passing untrusted external URLs directly.
+
+### Telegram methods
+
+```js
+import { createTelegramApi, TelegramApiError } from '@quecue/notify-core';
+const api = createTelegramApi(process.env.TELEGRAM_BOT_TOKEN ?? '', {
+  maxRateLimitWaitSeconds: 0, // Let the application schedule retries; errors remain visible.
+});
+// const bot = await api('getMe', {}); // An explicit call performs network I/O.
+```
+
+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.
+
+## 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.
+- `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.
+- `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.
+- A timeout can occur after server acceptance: **no exactly-once delivery, durable offline queue, or multipart atomicity is promised**.
+- `onSent` runs after reported server success. If mapping or the callback fails, `sent` may be positive while `ok` is false. Retrying the entire plan can duplicate messages.
+
+Tests use simulated network responses, not exhaustive real-service, proxy or Node-version acceptance. Sharing this library does not share application credentials or permissions.
+
+## Development
+
+- [Security boundaries and reporting](SECURITY.en.md)
+- [Contribution and local checks](CONTRIBUTING.md)
+- [Release checklist](PUBLISHING.md)
+- [Changes](CHANGELOG.en.md)
+- [MIT license](LICENSE)

package/README.md

@@ -1,9 +1,143 @@
-# notify-core 注册占位包
+# notify-core
 
-此版本仅用于初始化 npm 包名和配置 GitHub Actions Trusted Publishing。
+简体中文 | [English](README.en.md)
 
-**不包含任何运行时实现，请勿安装使用。** 正式版本及可用标签以 npm registry 为准。
+面向 Node.js 的轻量 Telegram／飞书通讯库：消息规划、Markdown 子集渲染、Unicode 安全分段、HTTP 边界和可注入的 Telegram API。**不绑定具体业务或应用。**
 
-源码与后续发行说明：https://github.com/QueCue/notify-core
+代码最初提取自 [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 发送，**不包含飞书消息或卡片回调接收服务**。
+- 不读取环境变量或配置文件来取得凭据，不访问系统凭据库，不启动轮询或后台服务；单纯导入不会联网。
+
+## 当前状态与安装
+
+源码使用 MIT 许可证，npm 包名为 `@quecue/notify-core`。实际可用版本以 registry 为准：
+
+```sh
+npm view @quecue/notify-core version --registry=https://registry.npmjs.org/
+npm install @quecue/notify-core@0.1.0
+```
+
+应用可将它声明为普通运行时依赖，npm 会自动安装，不需要用户检出本仓库、复制 vendor 包或手工嵌入通讯源码。ESM／类型入口均通过 `@quecue/notify-core` 导入。
+
+如需从源码构建或测试尚未发布的修改，也可生成本地候选包：
+
+```sh
+npm ci --ignore-scripts
+npm test
+node -e "require('node:fs').mkdirSync('releases', {recursive: true})"
+npm pack --pack-destination releases
+```
+
+在你的 Node.js 项目中安装生成的文件（将路径换为实际位置）：
+
+```sh
+npm install /path/to/quecue-notify-core-0.1.0.tgz
+```
+
+`npm ci` 需要完整源码检出，包括锁文件；不需要同时检出其他项目。运行时只支持本包声明的 ESM 入口，不保证 `require()` 或浏览器环境兼容性。
+
+## 快速开始：双渠道消息规划
+
+```js
+import { makePlan, deliver } from '@quecue/notify-core';
+
+// 环境变量由应用主动读取；库本身不发现、保存或验证你的凭据来源。
+const config = {
+  telegram: {
+    token: process.env.TELEGRAM_BOT_TOKEN ?? '',
+    chatIds: [process.env.TELEGRAM_CHAT_ID ?? ''],
+  },
+  feishu: {
+    webhook: process.env.FEISHU_WEBHOOK ?? '',
+    secret: process.env.FEISHU_SECRET ?? '',
+  },
+};
+const message = {
+  title: '构建完成',
+  content: '**结果**：通过\n\n' + '完整输出\n'.repeat(1000),
+  footer: '来自 CI',
+  level: 'success',
+};
+
+// makePlan 只规划，不联网。由应用先校验渠道凭据和接收人，再明确发送。
+const plan = makePlan('telegram', message, config);
+console.log(`准备发送 ${plan.items.length} 段`);
+// const result = await deliver(plan, config); // 取消注释会向 Telegram 真实发送。
+// if (!result.ok) console.error(result.error);
+```
+
+飞书改用 `makePlan('feishu', message, config)`；`secret` 非空时按飞书自定义机器人协议签名。`enabled`、默认渠道、环境变量优先级和接收人授权都是应用职责，不是 `NotifyConfig` 的字段。接口使用结构类型；不要把非空字符串误认为已经验证了 Token 或 Webhook。
+
+### 离线模拟投递
+
+```js
+import { makePlan, deliver } from '@quecue/notify-core';
+const config = {
+  telegram: { token: '123:TEST_ONLY', chatIds: ['111'] },
+  feishu: { webhook: '', secret: '' },
+};
+const plan = makePlan('telegram', {
+  title: '离线示例', content: '不会联网', footer: '', level: 'info',
+}, config);
+const result = await deliver(plan, config, async () => ({
+  ok: true, result: { message_id: 1 },
+}));
+console.log(result.ok); // true；使用注入传输，没有真实发送。
+```
+
+## 核心接口
+
+| 接口 | 用途与默认边界 |
+| --- | --- |
+| `createChannels(translate?)` | 创建消息规划／投递实例；翻译只作用于该实例 |
+| `makePlan(channel, message, config)` | 生成发送计划，不联网、不检查账号真实有效性 |
+| `deliver(plan, config, request?, sleep?)` | 顺序投递，返回 `{channel,sent,planned,ok,error?}`；失败后停止该接收人的后续分段，其他接收人继续 |
+| `createFormatting(translate?)` | 创建 Markdown 子集解析与分段函数；不是完整 CommonMark 实现 |
+| `splitPlainText(text, limit = 4000)` | 按 UTF-16 单元预算分段，不切断代理对；保持正文，不保证不拆开组合字形或整条消息原子投递 |
+| `createTransport(options?)` | 10 秒超时、1 MiB 响应上限、禁止重定向、严格 UTF-8／JSON 对象检查；返回可注入 `fetcher` 的请求函数 |
+| `createTelegramApi(token, options?)` | 固定 Telegram 方法集合，不启动轮询、不持久化 offset、不提供身份授权 |
+
+Markdown 支持标题、引用、列表、内联强调、代码和表格的可读渲染，链接地址保留在可见文字中。Telegram 解析失败可回退纯文本；飞书卡片组件被拒绝时可尝试兼容组件。过长标题／footer 等不能安全分段时明确失败，不悄悄截断。
+
+`reply` 是可选展示信息：`{token,url,users,callbackData?}`，分别用于按钮标识、飞书跳转 URL、展示 Telegram 按钮的接收人列表及自定义回调数据。默认回调数据为 `reply:` 加 `token`。**这些字段不授予权限**；宿主仍须校验用户、回调长度、过期时间、会话路由和接收端身份。
+
+### 传输与代理
+
+公共库不内置代理地址配置。需要代理时，应用通过 `request` 或 `fetcher` 注入自己的 HTTP 客户端，并保留超时、TLS 校验、禁止重定向和响应大小限制。默认 `fetch` 的代理行为受 Node 运行时及启动配置影响；库不会承诺无条件直连。
+
+`createTransport({timeoutMs,maxResponseBytes,translate})` 返回的函数签名为 `(url,payload,fetcher?)`。它是通用 JSON 传输，**不限制目标 URL**；应用必须验证目标域名、协议和接收人，不能直接接受外部不可信 URL。
+
+### Telegram 查询与按钮
+
+```js
+import { createTelegramApi, TelegramApiError } from '@quecue/notify-core';
+const api = createTelegramApi(process.env.TELEGRAM_BOT_TOKEN ?? '', {
+  maxRateLimitWaitSeconds: 0, // 交由应用决定何时再请求；不会忽略限流错误。
+});
+// const bot = await api('getMe', {}); // 明确调用才联网。
+```
+
+允许的方法仅为 `sendMessage`、`editMessageReplyMarkup`、`answerCallbackQuery`、`getMe`、`getUpdates` 和 `getWebhookInfo`。不会删除现有 Webhook。`getUpdates` 与 Webhook 互斥，同一个 Bot 只能有一个更新消费者；offset、去重、积压消息、业务授权和进程互斥由应用管理。
+
+## 错误、重试与投递语义
+
+- 内置传输不把底层 URL、响应原文或网络异常原文放进它生成的安全错误。`NotifyError` 是公共基类，`TransportError`、`HttpError` 和 `TelegramApiError` 可按类型处理。自定义翻译／传输／回调不在此保证内，调用方须自行脱敏。
+- `HttpError.status` 是已解析响应的 HTTP 状态；无效 JSON／UTF-8 等可能先表现为 `TransportError`。不要假设所有 HTTP 401 都必然映射为某一种错误。
+- `TelegramApiError` 提供 `code`、`retryAfterSeconds`、`fatal`；`fatal` 只对 401／404／409 为真，是供宿主参考的标记，不会自动退出进程。
+- `createTelegramApi` 默认对一次 429 进行至多一次等待重试，等待阈值为 60 秒；`maxRateLimitWaitSeconds: 0` 关闭内层等待。其余网络失败不自动重发。
+- `deliver` 有自己的策略：Telegram 明确 429 且有效 `retry_after` 在 60 秒内时有限重试；格式兼容回退只处理当前分段；飞书成功分段间等待 250 毫秒。上述回退叠加时不能理解为整个调用只会发生两次 HTTP 请求。
+- 服务端可能已接受消息，但响应丢失，投递结果会未知；**不保证恰好一次、离线补发或整个长消息的原子性**。
+- `onSent` 在服务端报告成功后调用。若映射／回调失败，`sent` 仍可能大于零而 `ok` 为 false；不要因此重发整条计划，否则可能重复通知。
+
+## 开发、版本与安全
+
+当前自动化测试使用模拟网络，不代表已完成全部 Node 版本、代理环境或真实平台验收。复用库源码不代表共享应用的凭据或系统权限。
+
+- [安全边界与报告方式](SECURITY.md)
+- [贡献与本地验证](CONTRIBUTING.md)
+- [发布前检查与版本包更新](PUBLISHING.md)
+- [变更记录](CHANGELOG.md)
+- [MIT 许可证](LICENSE)

package/SECURITY.en.md

@@ -0,0 +1,35 @@
+# Security boundaries
+
+English | [简体中文](SECURITY.md)
+
+This is a communication library, not an authorization system or security agent. MIT licensing does not imply an independent security audit or suitability for every environment; no such audit is claimed.
+
+## 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.
+- 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.
+- 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.
+- `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
+
+- 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.
+- The library does not persist queues, tokens, content, offsets or logs. Application storage, logs, backups, permissions and updates require separate assessment.
+
+## Reporting vulnerabilities
+
+Source repository: [QueCue/notify-core](https://github.com/QueCue/notify-core). GitHub private vulnerability reporting is not claimed to be enabled, and no dedicated public security email is currently specified.
+
+Prefer a private report if the Security page offers one. Otherwise, open a non-sensitive issue requesting a private contact, without publishing exploit details or secrets. Never include tokens, Webhooks or private chat content in a public issue. Revoke/rotate exposed credentials first; deleting text does not undo exposure.
+
+Include the affected version, reproduction conditions, expected/actual behavior and sanitized evidence. For ordinary contributions, see [CONTRIBUTING.md](CONTRIBUTING.md).

package/SECURITY.md

@@ -0,0 +1,35 @@
+# 安全边界
+
+简体中文 | [English](SECURITY.en.md)
+
+本项目是通讯库，不是权限系统或安全代理。代码采用 MIT 许可证，但尚未经过独立安全审计，不应据此声称适用于所有环境。
+
+## 数据与网络
+
+- 导入库不会联网、读取应用配置、环境凭据或系统凭据库。应用显式调用投递／API 后，请求正文才发送到所选平台；外部平台的数据保留规则不由本库控制。
+- Telegram API 工厂固定官方 HTTPS 基址并限制方法；通用 JSON 传输和飞书 Webhook 配置并不构成 URL 访问控制。宿主必须验证协议、目的地域名、接收人以及跳转链接，不能将外部不可信 URL 直接交给传输。
+- 默认传输保留运行时 TLS 验证，禁止重定向，默认超时 10 秒、响应最多 1 MiB，严格检查 UTF-8 和 JSON 对象。限制可配置；降低保护或替换传输后的安全性由宿主承担。
+- 代理由宿主提供。默认 fetch 的行为受 Node 启动和网络配置影响；库不保证完全不使用代理，也不提供自动代理发现或凭据隔离。
+- 内置错误对 URL、响应原文、底层异常采用安全摘要。不要把这理解为对任何用户输入的通用脱敏：标题、正文、footer、按钮内容、自定义翻译、注入传输和业务回调仍可能包含敏感信息。
+- `NotifyConfig` 是类型约定，不会查询凭据是否有效，也不实现全面运行时 schema 验证。缺少、错误或已撤销的凭据由应用和服务端处理。
+
+## 接收与授权
+
+- `getUpdates` 只是请求接口，没有内置后台循环、Webhook 接收器、offset 保存、重复更新过滤或发送者授权。飞书当前只有自定义机器人 Webhook 发送，不提供事件接收服务。
+- 只能由一个消费者读取同一 Bot 的更新；本库不会删除现有 Webhook、抢占其他消费者或自动恢复积压命令。
+- `reply.users` 只控制展示给哪些接收人按钮，不授予回调提交权。应用必须自行核验用户、聊天、请求身份、长度、时效和路由。
+
+## 重试与状态
+
+- 网络超时可能发生在服务端已接受消息之后；投递可能未知，不保证恰好一次或长消息原子发送。
+- 明确的限流和格式兼容拒绝可能触发有界重试／回退；它们不允许宿主重复执行有副作用的业务操作。
+- `onSent` 在成功发送后调用，其失败不能撤销已投递消息。不要因为 `ok:false` 就不加区分地重发整个计划。
+- 库不保存持久队列、Token、消息正文、offset 或日志。应用自己的存储、日志、备份、权限和更新机制需单独评估。
+
+## 报告安全问题
+
+源码仓库为 [QueCue/notify-core](https://github.com/QueCue/notify-core)。目前未声明已启用 GitHub 私密漏洞报告，也没有公开的专用安全邮箱。
+
+如 Security 页面提供私密报告入口，请优先使用；否则可以提交不含漏洞细节或秘密的 issue 请求私密联系方式。不要在公开 issue 中发布 Token、Webhook、个人聊天内容或可直接用于攻击的细节。若凭据已经泄漏，请先在平台撤销／轮换；删除文本不能撤销泄漏。
+
+报告时提供受影响版本、复现条件、预期与实际行为及脱敏证据。普通功能问题与贡献流程见 [CONTRIBUTING.md](CONTRIBUTING.md)。

package/dist/channels.d.ts

@@ -0,0 +1,49 @@
+import { type Translator } from './messages.js';
+import { type Request } from './transport.js';
+export type Channel = 'telegram' | 'feishu';
+export interface NotifyConfig {
+    telegram: {
+        token: string;
+        chatIds: string[];
+    };
+    feishu: {
+        webhook: string;
+        secret: string;
+    };
+}
+export interface Message {
+    title: string;
+    content: string;
+    footer: string;
+    level: 'info' | 'success' | 'warn' | 'error';
+    reply?: {
+        token: string;
+        url: string;
+        users: string[];
+        callbackData?: string;
+    };
+}
+export interface Item {
+    payload: Record<string, any>;
+    plain?: string;
+    recipient: string;
+}
+export interface Plan {
+    channel: Channel;
+    items: Item[];
+    recipients: number;
+    onSent?: (item: Item, response: Record<string, any>) => Promise<void>;
+}
+export interface Result {
+    channel: Channel;
+    sent: number;
+    planned: number;
+    ok: boolean;
+    error?: string;
+}
+export declare function createChannels(t?: Translator): {
+    makePlan: (channel: Channel, message: Message, config: NotifyConfig) => Plan;
+    deliver: (plan: Plan, config: NotifyConfig, request?: Request, sleep?: (ms: number) => Promise<unknown>) => Promise<Result>;
+    requestJson: (url: string, payload: Record<string, any>, fetcher?: typeof fetch) => Promise<Record<string, any>>;
+};
+export declare const makePlan: (channel: Channel, message: Message, config: NotifyConfig) => Plan, deliver: (plan: Plan, config: NotifyConfig, request?: Request, sleep?: (ms: number) => Promise<unknown>) => Promise<Result>;

package/dist/channels.js

@@ -0,0 +1,123 @@
+import { createHmac } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { createFormatting, escapeHtml, partTitle } from './formatting.js';
+import { defaultTranslate } from './messages.js';
+import { createTransport, TransportError } from './transport.js';
+const icons = { info: 'ℹ️', success: '✅', warn: '⚠️', error: '❌' };
+const colors = { info: 'blue', success: 'green', warn: 'yellow', error: 'red' };
+const bytes = (data) => Buffer.byteLength(JSON.stringify(data), 'utf8');
+export function createChannels(t = defaultTranslate) {
+    const { parseMarkdown, telegramParts, feishuParts } = createFormatting(t);
+    const requestJson = createTransport({ translate: t });
+    function text(title, content, footer, icon, html) {
+        const sections = [`${icon} ${html ? `<b>${escapeHtml(title)}</b>` : title}`];
+        if (content)
+            sections.push(content);
+        if (footer)
+            sections.push('────────\n' + (html ? `<i>${escapeHtml(footer)}</i>` : footer));
+        return sections.join('\n\n');
+    }
+    function card(message, title, content) {
+        const elements = [];
+        if (content)
+            elements.push({ tag: 'markdown', content });
+        if (message.footer)
+            elements.push({ tag: 'hr' }, { tag: 'note', elements: [{ tag: 'plain_text', content: message.footer }] });
+        if (message.reply?.url)
+            elements.push({ tag: 'action', actions: [{ tag: 'button', text: { tag: 'plain_text', content: t('channels.feishuReplyButton') }, url: message.reply.url, type: 'primary' }] });
+        return { msg_type: 'interactive', card: { config: { wide_screen_mode: true }, header: { template: colors[message.level], title: { tag: 'plain_text', content: title } }, elements } };
+    }
+    function makePlan(channel, message, config) {
+        if (!message.title.trim())
+            throw new Error(t('channels.emptyTitle'));
+        const blocks = parseMarkdown(message.content);
+        if (channel === 'telegram') {
+            const icon = icons[message.level], reserve = String(Math.max(1, message.content.length)).length * 2 + 16;
+            const budget = 3900 - text(message.title, '', message.footer, icon, false).length - reserve;
+            const chunks = telegramParts(blocks, budget), items = [];
+            for (const chatId of config.telegram.chatIds)
+                chunks.forEach((chunk, index) => {
+                    const title = partTitle(message.title, index, chunks.length), plain = text(title, chunk.plain, message.footer, icon, false);
+                    if (plain.length > 4096)
+                        throw new Error(t('channels.telegramTooLong'));
+                    items.push({ recipient: chatId, plain, payload: { chat_id: chatId,
+                            text: text(title, chunk.html, message.footer, icon, true), parse_mode: 'HTML', disable_web_page_preview: true,
+                            ...(message.reply?.users.includes(chatId) ? { reply_markup: { inline_keyboard: [[{ text: t('channels.telegramReplyButton'), callback_data: message.reply.callbackData ?? 'reply:' + message.reply.token }]] } } : {}) } });
+                });
+            return { channel, items, recipients: config.telegram.chatIds.length };
+        }
+        const budget = Math.min(10000, Math.floor((28000 - bytes(card(message, message.title, '')) - 512) / 6));
+        const chunks = feishuParts(blocks, budget);
+        const items = chunks.map((chunk, index) => {
+            const payload = card(message, partTitle(message.title, index, chunks.length), chunk);
+            if (bytes(payload) + 128 > 28000)
+                throw new Error(t('channels.feishuTooLong'));
+            return { recipient: 'feishu', payload };
+        });
+        return { channel, items, recipients: 1 };
+    }
+    async function deliver(plan, config, request = requestJson, sleep = delay) {
+        let sent = 0, error;
+        const failed = new Set(), telegram = plan.channel === 'telegram';
+        const url = telegram ? `https://api.telegram.org/bot${config.telegram.token}/sendMessage` : config.feishu.webhook;
+        const post = async (payload) => {
+            if (!telegram && config.feishu.secret) {
+                const timestamp = String(Math.floor(Date.now() / 1000));
+                payload.timestamp = timestamp;
+                payload.sign = createHmac('sha256', `${timestamp}\n${config.feishu.secret}`).update('').digest('base64');
+            }
+            let response = await request(url, payload);
+            if (telegram && response.error_code === 429) {
+                const wait = response.parameters?.retry_after;
+                if (typeof wait === 'number' && Number.isFinite(wait) && wait > 0 && wait <= 60) {
+                    await sleep(wait * 1000);
+                    response = await request(url, payload);
+                }
+            }
+            return response;
+        };
+        for (let index = 0; index < plan.items.length; index++) {
+            const item = plan.items[index];
+            if (failed.has(item.recipient))
+                continue;
+            const payload = structuredClone(item.payload);
+            try {
+                let response = await post(payload);
+                if (telegram && response.ok !== true && /parse|entit/i.test(String(response.description ?? ''))) {
+                    delete payload.parse_mode;
+                    payload.text = item.plain;
+                    response = await post(payload);
+                }
+                else if (!telegram && response.code !== 0) {
+                    let changed = false;
+                    payload.card.elements = payload.card.elements.map((element) => {
+                        if (element.tag !== 'markdown')
+                            return element;
+                        changed = true;
+                        return { tag: 'div', text: { tag: 'lark_md', content: element.content } };
+                    });
+                    if (changed)
+                        response = await post(payload);
+                }
+                if (telegram ? response.ok === true : response.code === 0) {
+                    sent++;
+                    if (plan.onSent)
+                        await plan.onSent(item, response);
+                }
+                else {
+                    failed.add(item.recipient);
+                    error = t('channels.rejected');
+                }
+            }
+            catch (cause) {
+                failed.add(item.recipient);
+                error = cause instanceof TransportError ? cause.message : t('channels.sendFailed');
+            }
+            if (!telegram && !failed.has(item.recipient) && index + 1 < plan.items.length)
+                await sleep(250);
+        }
+        return { channel: plan.channel, sent, planned: plan.items.length, ok: sent > 0 && sent === plan.items.length && !error, error };
+    }
+    return { makePlan, deliver, requestJson };
+}
+export const { makePlan, deliver } = createChannels();

package/dist/formatting.d.ts

@@ -0,0 +1,24 @@
+import { type Translator } from './messages.js';
+export interface Span {
+    text: string;
+    tags: string[];
+}
+export interface Block {
+    spans: Span[];
+    code: boolean;
+}
+export declare const escapeHtml: (text: string) => string;
+export declare const partTitle: (title: string, index: number, total: number) => string;
+export declare function createFormatting(t?: Translator): {
+    parseMarkdown: (content: string) => Block[];
+    visibleText: (blocks: Block[]) => string;
+    telegramParts: (blocks: Block[], budget: number) => {
+        html: string;
+        plain: string;
+    }[];
+    feishuParts: (blocks: Block[], budget: number) => string[];
+};
+export declare const parseMarkdown: (content: string) => Block[], visibleText: (blocks: Block[]) => string, telegramParts: (blocks: Block[], budget: number) => {
+    html: string;
+    plain: string;
+}[], feishuParts: (blocks: Block[], budget: number) => string[];

package/dist/formatting.js

@@ -0,0 +1,197 @@
+// 从原 dev-notify 格式化实现提取；无配置、凭据、网络或集成依赖。
+import { defaultTranslate } from './messages.js';
+export const escapeHtml = (text) => text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+export const partTitle = (title, index, total) => total > 1 ? `${title} (${index + 1}/${total})` : title;
+export function createFormatting(t = defaultTranslate) {
+    function inline(text, tags = [], depth = 0) {
+        if (depth > 8)
+            return [{ text, tags }];
+        const expression = /`([^`\n]+)`|\[([^\]\n]+)\]\((https?:\/\/[^\s)]+)\)|\*\*(\S(?:.*?\S)?)\*\*|__(\S(?:.*?\S)?)__|~~(\S(?:.*?\S)?)~~|(?<![\w*])\*([^*\n]+)\*(?![\w*])|(?<![\w_])_([^_\n]+)_(?![\w_])/g;
+        const spans = [];
+        let cursor = 0;
+        for (const match of text.matchAll(expression)) {
+            if (match.index > cursor)
+                spans.push({ text: text.slice(cursor, match.index), tags });
+            if (match[1] !== undefined)
+                spans.push({ text: match[1], tags: [...tags, 'code'] });
+            else if (match[2] !== undefined)
+                spans.push(...inline(match[2], tags, depth + 1), { text: ` (${match[3]})`, tags });
+            else {
+                const content = match[4] ?? match[5] ?? match[6] ?? match[7] ?? match[8];
+                const tag = match[4] !== undefined || match[5] !== undefined ? 'b' : match[6] !== undefined ? 's' : 'i';
+                spans.push(...inline(content, [...tags, tag], depth + 1));
+            }
+            cursor = match.index + match[0].length;
+        }
+        if (cursor < text.length)
+            spans.push({ text: text.slice(cursor), tags });
+        return spans.length ? spans : [{ text: '', tags }];
+    }
+    const cells = (line) => line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map(cell => inline(cell.trim()).map(s => s.text).join(''));
+    const separator = (line) => line.includes('|') && line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').every(cell => /^:?-{3,}:?$/.test(cell.trim()));
+    function width(text) {
+        let size = 0;
+        for (const ch of text) {
+            const code = ch.codePointAt(0);
+            size += code >= 0x1100 && (code <= 0x115f || code >= 0x2e80 && code <= 0xa4cf || code >= 0xac00 && code <= 0xd7af || code >= 0xff01 && code <= 0xff60 || code >= 0x1f300) ? 2 : 1;
+        }
+        return size;
+    }
+    function table(lines) {
+        const rows = lines.filter((_, index) => index !== 1).map(cells);
+        const count = Math.max(...rows.map(row => row.length));
+        const widths = Array.from({ length: count }, (_, col) => Math.max(3, ...rows.map(row => width(row[col] ?? ''))));
+        const output = [];
+        rows.forEach((row, index) => {
+            output.push(widths.map((size, col) => (row[col] ?? '') + ' '.repeat(size - width(row[col] ?? ''))).join(' | '));
+            if (!index)
+                output.push(widths.map(size => '-'.repeat(size)).join('-+-'));
+        });
+        return output.join('\n');
+    }
+    function parseMarkdown(content) {
+        const lines = content.replace(/\r\n?/g, '\n').replace(/\0/g, '').split('\n');
+        const blocks = [];
+        let index = 0;
+        while (index < lines.length) {
+            const line = lines[index], fence = /^\s*(`{3,}|~{3,})(.*)$/.exec(line);
+            if (fence) {
+                const marker = fence[1][0], closing = new RegExp(`^\\s*${marker === '`' ? '`' : '~'}{${fence[1].length},}\\s*$`);
+                const body = [];
+                index++;
+                while (index < lines.length && !closing.test(lines[index]))
+                    body.push(lines[index++]);
+                if (index < lines.length)
+                    index++;
+                blocks.push({ spans: [{ text: body.join('\n'), tags: [] }], code: true });
+                continue;
+            }
+            if (index + 1 < lines.length && line.includes('|') && separator(lines[index + 1])) {
+                const rows = [line, lines[index + 1]];
+                index += 2;
+                while (index < lines.length && lines[index].trim() && lines[index].includes('|'))
+                    rows.push(lines[index++]);
+                blocks.push({ spans: [{ text: table(rows), tags: [] }], code: true });
+                continue;
+            }
+            const heading = /^\s{0,3}#{1,6}\s+(.*)$/.exec(line), quote = /^\s*>\s?(.*)$/.exec(line), list = /^(\s*)[-*+]\s+(.*)$/.exec(line);
+            let spans;
+            if (heading)
+                spans = inline(heading[1], ['b']);
+            else if (/^\s*([-*_])(?:\s*\1){2,}\s*$/.test(line))
+                spans = [{ text: '────────', tags: [] }];
+            else if (quote)
+                spans = inline(quote[1], ['blockquote']);
+            else if (list)
+                spans = inline(`${list[1]}• ${list[2].replace(/^\[ \] /, '☐ ').replace(/^\[x\] /i, '☑ ')}`);
+            else
+                spans = inline(line);
+            blocks.push({ spans, code: false });
+            index++;
+        }
+        return blocks;
+    }
+    const visibleText = (blocks) => blocks.map(block => block.spans.map(span => span.text).join('')).join('\n');
+    function cut(text, budget, measure) {
+        if (budget < 1)
+            throw new Error(t('format.noSpace'));
+        let used = 0, end = 0;
+        for (const ch of text) {
+            const size = measure(ch);
+            if (used + size > budget)
+                break;
+            used += size;
+            end += ch.length;
+        }
+        if (!end && text)
+            throw new Error(t('format.oneChar'));
+        if (end < text.length)
+            for (const boundary of ['\n\n', '\n', ' ']) {
+                const offset = text.slice(0, end).lastIndexOf(boundary);
+                if (offset >= end / 2) {
+                    end = offset + boundary.length;
+                    break;
+                }
+            }
+        return [text.slice(0, end), text.slice(end)];
+    }
+    function telegramParts(blocks, budget) {
+        if (budget < 2)
+            throw new Error(t('format.telegramHeader'));
+        const output = [];
+        let html = '', plain = '';
+        const flush = () => { if (plain)
+            output.push({ html, plain }); html = ''; plain = ''; };
+        blocks.forEach((block, index) => {
+            const spans = index ? [{ text: '\n', tags: [] }, ...block.spans] : block.spans;
+            for (const span of spans) {
+                let rest = span.text;
+                while (rest) {
+                    if (budget - plain.length < [...rest][0].length)
+                        flush();
+                    const [piece, remaining] = cut(rest, budget - plain.length, text => text.length);
+                    const actualTags = block.code && !(index && span === spans[0]) ? ['pre'] : span.tags;
+                    html += actualTags.map(tag => `<${tag}>`).join('') + escapeHtml(piece) + [...actualTags].reverse().map(tag => `</${tag}>`).join('');
+                    plain += piece;
+                    rest = remaining;
+                    if (rest)
+                        flush();
+                }
+            }
+        });
+        flush();
+        return output.length ? output : [{ html: '', plain: '' }];
+    }
+    function feishuParts(blocks, budget) {
+        if (budget < 128)
+            throw new Error(t('format.feishuHeader'));
+        const output = [];
+        let current = '';
+        const size = (text) => Buffer.byteLength(text, 'utf8');
+        const flush = () => { if (current)
+            output.push(current); current = ''; };
+        blocks.forEach((block, index) => {
+            if (index) {
+                if (size(current) + 1 > budget)
+                    flush();
+                current += '\n';
+            }
+            for (const span of block.spans) {
+                let rest = span.text, prefix = '', suffix = '';
+                if (block.code) {
+                    const runs = rest.match(/`+/g) ?? [], marker = '`'.repeat(Math.max(3, ...runs.map(run => run.length + 1)));
+                    prefix = marker + 'text\n';
+                    suffix = '\n' + marker;
+                    if (size(prefix + suffix) > budget / 2) {
+                        prefix = '';
+                        suffix = '';
+                    }
+                }
+                else
+                    for (const tag of span.tags) {
+                        const wrapper = tag === 'b' ? '**' : tag === 'i' ? '*' : tag === 's' ? '~~' : tag === 'code' ? '`' : '';
+                        if (tag === 'blockquote')
+                            prefix += '▎ ';
+                        else {
+                            prefix += wrapper;
+                            suffix = wrapper + suffix;
+                        }
+                    }
+                while (rest) {
+                    const overhead = size(prefix + suffix);
+                    if (size(current) + overhead + size([...rest][0]) > budget)
+                        flush();
+                    const [piece, remaining] = cut(rest, budget - size(current) - overhead, size);
+                    current += prefix + piece + suffix;
+                    rest = remaining;
+                    if (rest)
+                        flush();
+                }
+            }
+        });
+        flush();
+        return output.length ? output : [''];
+    }
+    return { parseMarkdown, visibleText, telegramParts, feishuParts };
+}
+export const { parseMarkdown, visibleText, telegramParts, feishuParts } = createFormatting();

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './messages.js';
+export * from './formatting.js';
+export * from './transport.js';
+export * from './channels.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './messages.js';
+export * from './formatting.js';
+export * from './transport.js';
+export * from './channels.js';

package/dist/messages.d.ts

@@ -0,0 +1,23 @@
+declare const defaults: {
+    readonly 'channels.emptyTitle': "通知标题不能为空。";
+    readonly 'channels.telegramTooLong': "Telegram 分段后仍然超过消息长度限制。";
+    readonly 'channels.feishuTooLong': "飞书分段后仍然超过请求大小限制。";
+    readonly 'channels.noResponse': "服务端没有返回内容。";
+    readonly 'channels.responseTooLarge': "服务端响应过大，已停止读取。";
+    readonly 'channels.notJsonObject': "服务端返回的不是 JSON 对象。";
+    readonly 'channels.network': "网络请求失败或响应无效。为避免重复通知，不会自动重发；这条消息可能没有送达。";
+    readonly 'channels.rejected': "渠道拒绝了这次发送。请检查凭据、接收人授权、签名和频率限制。";
+    readonly 'channels.sendFailed': "发送失败，这条消息可能没有送达。";
+    readonly 'channels.feishuReplyButton': "在 Telegram 回复";
+    readonly 'channels.telegramReplyButton': "回复";
+    readonly 'format.noSpace': "可用空间不足，无法分段。";
+    readonly 'format.oneChar': "可用空间连一个字符都放不下。";
+    readonly 'format.telegramHeader': "Telegram 标题或底部信息太长，没有剩余空间放正文。";
+    readonly 'format.feishuHeader': "飞书标题或底部信息太长，没有剩余空间放正文。";
+};
+export type TranslationKey = keyof typeof defaults;
+export type Translator = (key: TranslationKey) => string;
+export declare const defaultTranslate: Translator;
+export declare class NotifyError extends Error {
+}
+export {};

package/dist/messages.js

@@ -0,0 +1,20 @@
+const defaults = {
+    'channels.emptyTitle': '通知标题不能为空。',
+    'channels.telegramTooLong': 'Telegram 分段后仍然超过消息长度限制。',
+    'channels.feishuTooLong': '飞书分段后仍然超过请求大小限制。',
+    'channels.noResponse': '服务端没有返回内容。',
+    'channels.responseTooLarge': '服务端响应过大，已停止读取。',
+    'channels.notJsonObject': '服务端返回的不是 JSON 对象。',
+    'channels.network': '网络请求失败或响应无效。为避免重复通知，不会自动重发；这条消息可能没有送达。',
+    'channels.rejected': '渠道拒绝了这次发送。请检查凭据、接收人授权、签名和频率限制。',
+    'channels.sendFailed': '发送失败，这条消息可能没有送达。',
+    'channels.feishuReplyButton': '在 Telegram 回复',
+    'channels.telegramReplyButton': '回复',
+    'format.noSpace': '可用空间不足，无法分段。',
+    'format.oneChar': '可用空间连一个字符都放不下。',
+    'format.telegramHeader': 'Telegram 标题或底部信息太长，没有剩余空间放正文。',
+    'format.feishuHeader': '飞书标题或底部信息太长，没有剩余空间放正文。'
+};
+export const defaultTranslate = key => defaults[key];
+export class NotifyError extends Error {
+}

package/dist/transport.d.ts

@@ -0,0 +1,29 @@
+import { NotifyError, type Translator } from './messages.js';
+export type Request = (url: string, payload: Record<string, any>) => Promise<Record<string, any>>;
+export declare class TransportError extends NotifyError {
+}
+export declare class HttpError extends TransportError {
+    readonly status: number;
+    constructor(status: number);
+}
+export interface TransportOptions {
+    translate?: Translator;
+    timeoutMs?: number;
+    maxResponseBytes?: number;
+}
+export declare function createTransport(options?: TransportOptions): (url: string, payload: Record<string, any>, fetcher?: typeof fetch) => Promise<Record<string, any>>;
+export declare const requestJson: (url: string, payload: Record<string, any>, fetcher?: typeof fetch) => Promise<Record<string, any>>;
+export type TelegramMethod = 'sendMessage' | 'editMessageReplyMarkup' | 'answerCallbackQuery' | 'getMe' | 'getUpdates' | 'getWebhookInfo';
+export declare class TelegramApiError extends NotifyError {
+    readonly code: number;
+    readonly retryAfterSeconds: number;
+    readonly fatal: boolean;
+    constructor(code: number, retryAfterSeconds?: number);
+}
+export interface TelegramClientOptions {
+    request?: Request;
+    sleep?: (ms: number) => Promise<unknown>;
+    maxRateLimitWaitSeconds?: number;
+}
+export declare function createTelegramApi(token: string, options?: TelegramClientOptions): (method: string, payload: Record<string, unknown>) => Promise<any>;
+export declare function splitPlainText(text: string, limit?: number): string[];

package/dist/transport.js

@@ -0,0 +1,118 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { defaultTranslate, NotifyError } from './messages.js';
+export class TransportError extends NotifyError {
+}
+export class HttpError extends TransportError {
+    status;
+    constructor(status) {
+        super(`HTTP 请求失败（状态码 ${status}）。`);
+        this.status = status;
+    }
+}
+export function createTransport(options = {}) {
+    const t = options.translate ?? defaultTranslate;
+    const timeoutMs = options.timeoutMs ?? 10000, maximum = options.maxResponseBytes ?? 1024 * 1024;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || !Number.isSafeInteger(maximum) || maximum < 1)
+        throw new NotifyError('传输边界配置无效。');
+    return async function requestJson(url, payload, fetcher = fetch) {
+        try {
+            const response = await fetcher(url, { method: 'POST', body: JSON.stringify(payload),
+                headers: { 'Content-Type': 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(timeoutMs) });
+            if (!response.body)
+                throw new TransportError(t('channels.noResponse'));
+            const reader = response.body.getReader(), chunks = [];
+            let size = 0;
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    size += value.byteLength;
+                    if (size > maximum) {
+                        await reader.cancel();
+                        throw new TransportError(t('channels.responseTooLarge'));
+                    }
+                    chunks.push(value);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+            const result = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+            if (!result || typeof result !== 'object' || Array.isArray(result))
+                throw new TransportError(t('channels.notJsonObject'));
+            // 保留渠道的明确拒绝包供 429 等策略处理；HTTP 失败绝不能因正文声称成功而算投递成功。
+            if (!response.ok && result.ok !== false && !(Number.isInteger(result.code) && result.code !== 0))
+                throw new HttpError(response.status);
+            return result;
+        }
+        catch (error) {
+            if (error instanceof TransportError)
+                throw error;
+            throw new TransportError(t('channels.network'));
+        }
+    };
+}
+export const requestJson = createTransport();
+const methods = new Set(['sendMessage', 'editMessageReplyMarkup', 'answerCallbackQuery', 'getMe', 'getUpdates', 'getWebhookInfo']);
+export class TelegramApiError extends NotifyError {
+    code;
+    retryAfterSeconds;
+    fatal;
+    constructor(code, retryAfterSeconds = 5) {
+        super(`Telegram API 调用失败（错误码 ${code}）。`);
+        this.code = code;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.fatal = [401, 404, 409].includes(code);
+    }
+}
+export function createTelegramApi(token, options = {}) {
+    if (!/^\d+:[A-Za-z0-9_-]+$/.test(token))
+        throw new NotifyError('Telegram Token 格式无效。');
+    const request = options.request ?? requestJson, sleep = options.sleep ?? delay;
+    const maxWait = options.maxRateLimitWaitSeconds ?? 60;
+    return async (method, payload) => {
+        if (!methods.has(method))
+            throw new NotifyError('不允许的 Telegram API 方法。');
+        for (let attempt = 0;; attempt++) {
+            let response;
+            try {
+                response = await request(`https://api.telegram.org/bot${token}/${method}`, payload);
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw new TelegramApiError(error.status);
+                throw error;
+            }
+            if (response.ok === true) {
+                if (!Object.hasOwn(response, 'result'))
+                    throw new NotifyError('Telegram 返回缺少结果。');
+                return response.result;
+            }
+            const code = Number.isSafeInteger(response.error_code) ? response.error_code : 0;
+            const rawWait = response.parameters?.retry_after;
+            const wait = typeof rawWait === 'number' && Number.isFinite(rawWait) && rawWait > 0 ? rawWait : 5;
+            if (code === 429 && attempt === 0 && wait <= maxWait) {
+                await sleep(wait * 1000);
+                continue;
+            }
+            throw new TelegramApiError(code, Math.max(1, Math.min(300, Math.ceil(wait))));
+        }
+    };
+}
+export function splitPlainText(text, limit = 4000) {
+    if (!Number.isSafeInteger(limit) || limit < 2 || limit > 4096)
+        throw new NotifyError('消息分段上限无效。');
+    const parts = [];
+    let part = '';
+    for (const ch of text) {
+        if (part.length + ch.length > limit) {
+            parts.push(part);
+            part = '';
+        }
+        part += ch;
+    }
+    if (part || !parts.length)
+        parts.push(part);
+    return parts;
+}

package/package.json

@@ -1,19 +1,25 @@
 {
   "name": "@quecue/notify-core",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Package registration placeholder. Do not install; no runtime implementation.",
+  "version": "0.1.0",
+  "description": "独立的 Telegram 与飞书通讯、格式化和传输边界库",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/QueCue/notify-core.git"
-  },
+  "repository": { "type": "git", "url": "git+https://github.com/QueCue/notify-core.git" },
   "homepage": "https://github.com/QueCue/notify-core#readme",
-  "files": [
-    "README.md",
-    "LICENSE"
-  ],
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
+  "bugs": { "url": "https://github.com/QueCue/notify-core/issues" },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist", "README.md", "README.en.md", "SECURITY.md", "SECURITY.en.md", "CONTRIBUTING.md", "PUBLISHING.md", "CHANGELOG.md", "CHANGELOG.en.md", "LICENSE"],
+  "engines": { "node": ">=22.0.0" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.0"
   }
 }