hookbot 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+> HookBot 仍在开发中，我们会在开发完毕后发布 Release.
+
+# HookBot
+
+<!-- [![npm version](https://badge.fury.io/js/hookbot.svg)](https://badge.fury.io/js/hookbot) -->
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**HookBot** 是一个可扩展的、为 Webhook 而做的 TypeScript 机器人流程框架，旨在轻松实现不同聊天平台、服务或 API 之间的消息同步。
+
+不仅如此，您可以轻松编写插件系统，来编写自己的信息处理逻辑。
+
+我们在初期准备支持 Telegram（收/发），Discord（发），您也可以自己编写自己的适配器，一次编写就可以支持本机器人。
+
+同时我们支持 Node.js 服务器和 Serverless 环境，具体请看「快速开始」部分。
+
+## ✨ 特性
+
+- **🔌 统一的适配器接口**: 只需编写适配器，轻松集成任何消息源或目标。
+- **🚀 插件化架构**: 使用插件方法，可以轻松地为您的机器人添加新功能或集成第三方服务。
+- **⚙️ 中间件支持**: 通过添加处理方法，可以在消息处理流程的任何阶段添加处理器，以实现日志记录、权限控制、消息修改等功能。
+- **🔒 类型安全**: 完全使用 TypeScript 编写，提供强大的类型推断和编译时检查。
+- **🌐 灵活部署**: 同时支持在传统的 Node.js 服务器 (`listen()`) 和 Serverless 环境 (`fire()`) 中运行。
+- **💬 提供 utils**: 内置便捷方法，轻松处理 Markdown、HTML 的转换，并且提供了不支持富文本的后备处理。
+
+## 📦 安装
+
+```bash
+bun add hookbot
+```
+
+## 🚀 快速开始
+
+下面是一个简单的例子，演示了如何创建一个在同步消息的机器人。
+
+```typescript
+import HookBot from 'hookbot';
+
+// 1. 创建 Bot
+// 2. 订阅/发布一个消息源
+
+// 3. 采用 Node.js Server 或 Serverless
+```
+
+## 核心概念
+
+Webhook 是一种事件驱动的、基于 HTTP 的回调机制，它允许一个应用程序在特定事件发生时，自动将数据推送给另一个应用程序。
+
+我们在传入 Webhook 请求时，会通过适配器的 `id` 来识别需要哪一种适配器处理，然后解析请求为一个消息数组，接下来我们对于消息，拦截器->同步消息给其他适配器->处理器。
+
+```mermaid
+flowchart TB
+  Start([HookBot])
+  A0[注册路由]
+
+  subgraph "Listen (Server Mode)"
+    direction TB
+    A1[启动服务]
+    A3[持续接收请求]
+    A1 --> A3
+  end
+
+  subgraph "Fire (Serverless Mode)"
+    direction TB
+    B2[接收 webhook 请求]
+  end
+
+  C1[路由交给对应的 Subscriber]
+  C2[解析为消息数组]
+
+  subgraph "处理消息数组"
+    direction TB
+
+    C3[全局拦截器 Interceptor]
+
+    subgraph "与其他 Publishers 同步"
+        direction TB
+        D1[拦截器 Interceptor]
+        D2[同步消息 sendMessage]
+        D3[处理器 Handler]
+        D1 --> D2 --> D3
+    end
+  C4[全局处理器 Handler]
+
+  end
+  Start --> A0
+  A0 --> A1
+  A0 --> B2
+
+  A3 --> C1
+  B2 --> C1
+
+  C1 --> C2 --> C3 --> D1
+  D3 --> C4
+
+```
+
+### 适配器
+
+适配器是 HookBot 与第三方消息源沟通的桥梁，他们通过 `id` 建立的来建立路由。
+
+如果你要编写自己的适配器，请继承以下接口。
+
+- **`SubscribableAdaptor`**: 只接收消息。它必须实现一个 `id` 和一个 `receive` 方法。HookBot 会为每个订阅者创建一个 webhook 端点 (`POST /<adaptor_id>`)。
+- **`PublishableAdaptor`**: 只发送消息。它必须实现一个 `id` 和至少一个 `sendText` 方法。
+- **`SyncableAdaptor`**: 既能接收也能发送消息，是 `Subscribable` 和 `Publishable` 的结合。
+
+```typescript
+
+```
+
+### 消息
+
+所有通过 HookBot 流转的数据都被封装成 `Message` 对象。它有一个 `type` 字段（如 `'text'`, `'media', 'location'`）来区分不同类型的消息。
+
+```json
+{
+  "type": "text"
+}
+```
+
+某些适配器可能无法处理复杂类型的媒体，你需要在编写适配器时添加 `alt: string` 参数作为 fallback，我们会转换为文字消息处理。
+
+```json
+{
+    type: 'location',
+    //...
+
+    alt: '${content.longitude}, ${content.latitude}',
+    //...
+}
+```
+
+### 处理器
+
+处理器是可以在消息生命周期的特定节点执行的函数，类似于中间件。
+
+HookBot 有自己的全局处理器，分配到每个适配器时也有自己的处理器。
+
+#### 拦截器
+
+**`Interceptor`**: 在消息被同步给其他发布者 **之前** 执行。可以用于消息验证、修改或过滤。
+
+#### 处理器
+
+**`Handler`**: 在消息被同步给所有发布者 **之后** 执行。可以用于日志记录、分析或收尾工作。
+
+您可以通过 `.intercept()` 和 `.handle()` 方法注册，他根据 `priority` 属性（数字越小，优先级越高）的顺序执行。
+
+```typescript
+bot.intercept({
+  name: 'process before syncing',
+  priority: 1,
+  process: processor1,
+});
+
+bot.handle({
+  name: 'process after syncing',
+  priority: 1,
+  process: processor2,
+});
+```
+
+### 插件
+
+您可以通过 `.use()` 方法来添加插件。
+
+## 🤝 贡献
+
+欢迎提交 Pull Requests 和 Issues！
+
+## TODO
+1. 便捷添加命令/便捷筛选
+2. 状态管理/持久化存储插件
+3. i18n
+
+## 📄 许可证
+
+[MIT](./LICENSE)

package/index.js

@@ -0,0 +1,11 @@
+export class HookBotPlaceholderError extends Error {
+  constructor() {
+    super("hookbot is a placeholder package. The public SDK has not been released yet.");
+    this.name = "HookBotPlaceholderError";
+  }
+}
+
+export default function HookBot() {
+  // Keep the reserved npm package intentionally non-functional until the SDK is ready.
+  throw new HookBotPlaceholderError();
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "hookbot",
+  "version": "0.0.0",
+  "description": "Placeholder package for HookBot.",
+  "main": "index.js",
+  "exports": "./index.js",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "build": "tsc",
+    "build:clean": "rm -rf dist && bun run build",
+    "test": "bun test",
+    "test:run": "bun test",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint --write .",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "check": "biome check .",
+    "check:fix": "biome check --write .",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist build node_modules/.cache"
+  },
+  "keywords": [
+    "webhook",
+    "bot",
+    "hookbot",
+    "typescript"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.2.4",
+    "@types/bun": "^1.2.0",
+    "@types/marked": "^5.0.2",
+    "@types/turndown": "^5.0.5",
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.17.1",
+    "hono": "^4.8.5",
+    "marked": "^16.1.1",
+    "node-html-parser": "^7.0.1",
+    "ofetch": "^1.4.1",
+    "turndown": "^7.2.0"
+  }
+}