@zhin.js/adapter-telegram 2.0.7 → 2.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/README.md +85 -8
  3. package/package.json +11 -11
package/CHANGELOG.md CHANGED
@@ -1,5 +1,29 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.0.9
4
+
5
+ ### Patch Changes
6
+
7
+ - c8f8207: fix: 修复内存泄露问题
8
+ - Updated dependencies [c8f8207]
9
+ - @zhin.js/logger@0.1.70
10
+ - @zhin.js/client@2.0.2
11
+ - @zhin.js/contract@1.0.1
12
+ - @zhin.js/host-api@0.0.3
13
+ - @zhin.js/host-router@0.0.3
14
+ - zhin.js@1.0.90
15
+
16
+ ## 2.0.8
17
+
18
+ ### Patch Changes
19
+
20
+ - c78d2cd: fix: cli 更新,文档更新
21
+ - Updated dependencies [c78d2cd]
22
+ - @zhin.js/client@2.0.1
23
+ - @zhin.js/host-router@0.0.2
24
+ - zhin.js@1.0.89
25
+ - @zhin.js/host-api@0.0.2
26
+
3
27
  ## 2.0.7
4
28
 
5
29
  ### Patch Changes
package/README.md CHANGED
@@ -8,8 +8,76 @@ Telegram adapter for zhin.js framework.
8
8
  pnpm add @zhin.js/adapter-telegram
9
9
  ```
10
10
 
11
+ ## Prerequisites
12
+
13
+ | 要求 | 说明 |
14
+ |------|------|
15
+ | **Bot Token** | 通过 [@BotFather](https://t.me/botfather) 创建 Bot 并获取 Token |
16
+ | **Polling（默认）** | 本地开发无需公网 IP；`polling: true`（默认） |
17
+ | **Webhook（可选）** | 生产环境：`polling: false` + 公网 **HTTPS** 域名与有效 TLS；Telegraf 在 `webhook.port` 监听 |
18
+ | **host-router** | 不需要；本适配器自行处理 polling / webhook |
19
+
20
+ 必填字段见 `TelegramBotConfig`：`context`、`name`、`token`；`polling` 默认为 `true`。
21
+
22
+ ## Minimal configuration
23
+
24
+ ```yaml
25
+ plugins:
26
+ - "@zhin.js/adapter-telegram"
27
+
28
+ bots:
29
+ - context: telegram
30
+ name: my-telegram-bot
31
+ token: "${TELEGRAM_TOKEN}"
32
+ polling: true
33
+ ```
34
+
11
35
  ## Configuration
12
36
 
37
+ ### 长轮询 Polling（默认，本地开发）
38
+
39
+ 无需公网 IP 或 HTTPS，Bot 主动向 Telegram 拉取更新：
40
+
41
+ ```yaml
42
+ plugins:
43
+ - "@zhin.js/adapter-telegram"
44
+
45
+ bots:
46
+ - context: telegram
47
+ name: my-telegram-bot
48
+ token: "${TELEGRAM_TOKEN}"
49
+ polling: true
50
+ ```
51
+
52
+ ### Webhook（生产环境）
53
+
54
+ 设置 `polling: false` 并配置 `webhook` 对象；Telegraf 在 `webhook.port` 上启动 HTTPS 服务：
55
+
56
+ ```yaml
57
+ bots:
58
+ - context: telegram
59
+ name: my-telegram-bot
60
+ token: "${TELEGRAM_TOKEN}"
61
+ polling: false
62
+ webhook:
63
+ domain: https://bot.example.com
64
+ path: /telegram-webhook
65
+ port: 8443
66
+ ```
67
+
68
+ #### Webhook 前置条件
69
+
70
+ | 要求 | 说明 |
71
+ |------|------|
72
+ | **HTTPS 公网域名** | `webhook.domain` 须为 Telegram 可访问的 `https://` 地址（有效 TLS 证书） |
73
+ | **端口可达** | `webhook.port`（如 8443）须从公网可连，或通过反向代理转发 |
74
+ | **Bot Token** | 通过 [@BotFather](https://t.me/botfather) 获取 |
75
+ | **无需 host-router** | 本适配器由 Telegraf 自行监听 webhook，不依赖 `@zhin.js/host-router` |
76
+
77
+ > 本地开发建议先用 **polling**；上线后再切 webhook 并在 BotFather 或 launch 时注册 webhook URL。
78
+
79
+ TypeScript 等价配置：
80
+
13
81
  ```typescript
14
82
  import { defineConfig } from 'zhin.js'
15
83
 
@@ -18,15 +86,10 @@ export default defineConfig({
18
86
  {
19
87
  name: 'my-telegram-bot',
20
88
  context: 'telegram',
21
- token: 'YOUR_BOT_TOKEN', // Get from @BotFather
22
- polling: true, // Use long polling (default)
23
- // OR use webhooks:
89
+ token: 'YOUR_BOT_TOKEN',
90
+ polling: true,
24
91
  // polling: false,
25
- // webhook: {
26
- // domain: 'https://yourdomain.com',
27
- // path: '/telegram-webhook',
28
- // port: 8443
29
- // }
92
+ // webhook: { domain: 'https://yourdomain.com', path: '/telegram-webhook', port: 8443 },
30
93
  }
31
94
  ]
32
95
  })
@@ -103,6 +166,20 @@ You can send files using:
103
166
  - URL
104
167
  - Local file path
105
168
 
169
+ ## Troubleshooting
170
+
171
+ | 现象 | 排查 |
172
+ |------|------|
173
+ | Bot 无响应 / 收不到消息 | 确认 Token 正确；进程已启动；私聊 Bot 或将其加入群组 |
174
+ | Polling 报错 | 检查网络能否访问 `api.telegram.org`；同一 Token 勿多进程同时 polling |
175
+ | Webhook 不工作 | `webhook.domain` 须为 Telegram 可访问的 `https://`；放行 `webhook.port`；BotFather 或 launch 时注册 URL |
176
+ | 发送失败 | Token revoked 或 Bot 被限制；查看日志中的 Telegraf 错误 |
177
+
178
+ ## Documentation
179
+
180
+ - [Telegram adapter on zhin.js.org](https://zhin.js.org/adapters/telegram)
181
+ - [Adapters overview](https://zhin.js.org/essentials/adapters)
182
+
106
183
  ## License
107
184
 
108
185
  MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zhin.js/adapter-telegram",
3
- "version": "2.0.7",
3
+ "version": "2.0.9",
4
4
  "description": "Zhin.js adapter for Telegram",
5
5
  "type": "module",
6
6
  "main": "./lib/index.js",
@@ -40,18 +40,18 @@
40
40
  "@types/react-dom": "^19.2.3",
41
41
  "lucide-react": "^1.17.0",
42
42
  "typescript": "^6.0.3",
43
- "@zhin.js/cli": "1.0.84",
44
- "@zhin.js/host-api": "0.0.1",
45
- "@zhin.js/contract": "1.0.0",
46
- "zhin.js": "1.0.88"
43
+ "@zhin.js/cli": "1.0.86",
44
+ "@zhin.js/host-api": "0.0.3",
45
+ "@zhin.js/contract": "1.0.1",
46
+ "zhin.js": "1.0.90"
47
47
  },
48
48
  "peerDependencies": {
49
- "@zhin.js/client": "2.0.0",
50
- "@zhin.js/host-api": "0.0.1",
51
- "@zhin.js/contract": "1.0.0",
52
- "@zhin.js/host-router": "0.0.1",
53
- "@zhin.js/logger": "0.1.69",
54
- "zhin.js": "1.0.88"
49
+ "@zhin.js/client": "2.0.2",
50
+ "@zhin.js/host-api": "0.0.3",
51
+ "@zhin.js/contract": "1.0.1",
52
+ "@zhin.js/host-router": "0.0.3",
53
+ "@zhin.js/logger": "0.1.70",
54
+ "zhin.js": "1.0.90"
55
55
  },
56
56
  "peerDependenciesMeta": {
57
57
  "@zhin.js/client": {