@zhin.js/adapter-telegram 1.1.10 → 1.1.13

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 (9) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/README.md +24 -16
  3. package/lib/platform-permit.d.ts +3 -0
  4. package/lib/platform-permit.js +7 -7
  5. package/lib/protocol.d.ts +3 -1
  6. package/lib/protocol.js +8 -4
  7. package/package.json +16 -16
  8. package/src/platform-permit.ts +10 -7
  9. package/src/protocol.ts +8 -4
package/CHANGELOG.md CHANGED
@@ -1,5 +1,62 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.1.13
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies [db06de8]
8
+ - @zhin.js/core@1.1.48
9
+
10
+ ## 1.1.12
11
+
12
+ ### Patch Changes
13
+
14
+ - e40899f: Adapters now project group owners and admins onto the canonical `sender.roles` names `owner` / `admin` (Telegram creator/administrator, KOOK guild owner and admin-permission roles, Lark chat owner/managers, QQ official guild owner/admin identities). KOOK numeric role ids moved from `roles` to `permissions` (`role:<id>`). `@zhin.js/command` exports `canManageConversation` ("private chat or owner/admin/master"), now shared by the Bilibili and earthquake subscription commands; Roulette lets owners and admins toggle the mute penalty and cancel a game.
15
+ - fbfefb7: Share segments accept `data.platform` (the song's music service: qq, netease, kugou, kuwo, migu). icqq maps it to the matching music app id when `config.appid` is absent and offers it to the Agent; adapters that cannot render share app metadata reject it like `audio` and `config`.
16
+ - Updated dependencies [1a11207]
17
+ - Updated dependencies [9943df6]
18
+ - Updated dependencies [5be09ae]
19
+ - Updated dependencies [a3ab153]
20
+ - Updated dependencies [e8f7309]
21
+ - Updated dependencies [5afc18f]
22
+ - Updated dependencies [d3563d9]
23
+ - Updated dependencies [c618eb7]
24
+ - Updated dependencies [fbfefb7]
25
+ - @zhin.js/tool@1.1.8
26
+ - @zhin.js/core@1.1.47
27
+ - @zhin.js/adapter@1.1.21
28
+ - @zhin.js/feature-kit@1.1.7
29
+ - @zhin.js/im-contract@1.1.5
30
+ - @zhin.js/agent-feature@1.1.8
31
+ - @zhin.js/skill@1.1.8
32
+ - @zhin.js/host-http@1.1.8
33
+
34
+ ## 1.1.11
35
+
36
+ ### Patch Changes
37
+
38
+ - c407bd2: 安装 HTML 渲染能力时，内置指令菜单通过统一发送链生成菜单图；渲染失败或平台无法投递图片时保留原有文本菜单。菜单采用可自定义标题、配色与背景的三列主题，每页最多 30 项，支持根菜单与插件菜单翻页。平台同时支持原生 Markdown 与按钮时自动附加上一页、下一页控件，在边界禁用；其他平台保留文本导航。Telegram 禁用按钮映射为 Bot API 10.3 DisabledButton。补充中英文文档。
39
+ - 9816c18: 将应用插件装配改为 configVersion: 2：主配置 plugins 映射实例名到包，disable_plugins 控制启停，业务配置使用顶层同名块。package.json 继续保留 features、entry、engine 等包契约，并支持静态 displayName/icon。
40
+
41
+ 这是配置格式的破坏性更新：旧配置不能继续运行，请先停止 Bot，运行 `zhin migrate instances` 预览，再使用 `--apply` 转换；提供备份与中断继续/回滚，无法无损转换的嵌套、optional 和别名碰撞需人工迁移。Runtime、Console、CLI 与创建向导统一使用新声明。
42
+
43
+ 保留框架顶层 `menuKeyword` / `menuStyle`，通过当前 generation 的 Root 配置视图供 Command Feature 消费；严格校验和配置修改不会丢失菜单设置，子实例配置保持隔离。
44
+
45
+ - Updated dependencies [c407bd2]
46
+ - Updated dependencies [064b06d]
47
+ - Updated dependencies [2b4d6dc]
48
+ - Updated dependencies [b58548a]
49
+ - Updated dependencies [e914a93]
50
+ - Updated dependencies [e914a93]
51
+ - Updated dependencies [064b06d]
52
+ - @zhin.js/core@1.1.46
53
+ - @zhin.js/feature-kit@1.1.6
54
+ - @zhin.js/host-http@1.1.7
55
+ - @zhin.js/adapter@1.1.20
56
+ - @zhin.js/agent-feature@1.1.7
57
+ - @zhin.js/skill@1.1.7
58
+ - @zhin.js/tool@1.1.7
59
+
3
60
  ## 1.1.10
4
61
 
5
62
  ### Patch Changes
package/README.md CHANGED
@@ -34,7 +34,7 @@ pnpm add @zhin.js/adapter-telegram
34
34
  - `@zhin.js/adapter` — 约定式 `adapters/telegram/index.ts`（`defineAdapter`）
35
35
  - `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
36
36
  - `zhin.js` — `plugin.ts`（`definePlugin`）
37
- - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
37
+ - 配置经插件 `schema.json` 落到顶层 `<instanceKey>`
38
38
  - **无需** `@zhin.js/host-http`（polling 路径）
39
39
 
40
40
  入站：`gateway.receive({ conversation, message, content, sender, metadata })`（`conversation` 为 ConversationRef，由 `telegramInboundConversation` 归一化）
@@ -59,16 +59,18 @@ pnpm add @zhin.js/adapter-telegram
59
59
  ## 最小配置
60
60
 
61
61
  ```yaml
62
+ configVersion: 2
62
63
  # zhin.config.yml（Plugin Runtime）
63
64
  plugins:
64
- telegram:
65
- # polling: true # 默认
66
- endpoints:
67
- - id: my-telegram-bot
68
- token: ${TELEGRAM_TOKEN}
65
+ telegram: "@zhin.js/adapter-telegram"
66
+ telegram:
67
+ # polling: true # 默认
68
+ endpoints:
69
+ - id: my-telegram-bot
70
+ token: ${TELEGRAM_TOKEN}
69
71
  ```
70
72
 
71
- 根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-telegram`（`instanceKey: telegram`）。
73
+ 主配置 `plugins` 映射需引用 `@zhin.js/adapter-telegram`（`instanceKey: telegram`）。
72
74
 
73
75
  ## 环境变量
74
76
 
@@ -83,19 +85,21 @@ plugins:
83
85
  `webhook.path` 必须与反向代理转发路径一致，多账号使用不同路径。
84
86
 
85
87
  ```yaml
88
+ configVersion: 2
86
89
  http:
87
90
  host: 127.0.0.1
88
91
  port: 8086
89
92
  plugins:
90
- telegram:
91
- polling: false
92
- endpoints:
93
- - id: my-telegram-bot
94
- token: ${TELEGRAM_TOKEN}
95
- webhook:
96
- domain: https://bot.example.com
97
- path: /telegram/webhook
98
- secretToken: ${TELEGRAM_WEBHOOK_SECRET}
93
+ telegram: "@zhin.js/adapter-telegram"
94
+ telegram:
95
+ polling: false
96
+ endpoints:
97
+ - id: my-telegram-bot
98
+ token: ${TELEGRAM_TOKEN}
99
+ webhook:
100
+ domain: https://bot.example.com
101
+ path: /telegram/webhook
102
+ secretToken: ${TELEGRAM_WEBHOOK_SECRET}
99
103
  ```
100
104
 
101
105
  启动时注册 Host 路由并调用 `setWebhook`；停止时释放路由。
@@ -147,3 +151,7 @@ Webhook 接收确认不等于业务处理完成；需要幂等性的业务应自
147
151
  ## License
148
152
 
149
153
  MIT
154
+
155
+ ### 禁用按钮
156
+
157
+ canonical keyboard 的 `disabled: true` 按钮映射为 Telegram Bot API 10.3 的 `disabled: {}`，不携带 `callback_data`；启用按钮仍使用原回调数据，并保留 1–64 UTF-8 字节校验。自建 Bot API Server 需支持该版本，见 [DisabledButton](https://core.telegram.org/bots/api#disabledbutton)。
package/lib/platform-permit.d.ts CHANGED
@@ -1,5 +1,8 @@
1
1
  /**
2
2
  * Telegram platform permit — ChatMember 状态 + 细粒度权限
3
+ *
4
+ * `role` 使用跨平台规范名 owner / admin（原生 creator / administrator 仅作兼容输入）；
5
+ * 细粒度能力放在 `permissions`。
3
6
  */
4
7
  import type { PermissionSubject } from '@zhin.js/permission';
5
8
  export declare function platformPermit(perm: string): string;
package/lib/platform-permit.js CHANGED
@@ -14,7 +14,7 @@ export function normalizeTelegramChatMember(member) {
14
14
  const status = member.status;
15
15
  if (status === 'creator') {
16
16
  permissions.push('chat_creator', 'chat_administrator', 'restrict_members', 'pin_messages');
17
- return { role: 'creator', permissions };
17
+ return { role: 'owner', permissions };
18
18
  }
19
19
  if (status === 'administrator') {
20
20
  permissions.push('chat_administrator');
@@ -26,7 +26,7 @@ export function normalizeTelegramChatMember(member) {
26
26
  permissions.push('delete_messages');
27
27
  if (member.can_manage_chat)
28
28
  permissions.push('manage_chat');
29
- return { role: 'administrator', permissions };
29
+ return { role: 'admin', permissions };
30
30
  }
31
31
  return { role: 'member', permissions };
32
32
  }
@@ -36,15 +36,15 @@ export function checkTelegramPlatformPermit(perm, subject) {
36
36
  const has = (t) => permissions.includes(t);
37
37
  switch (perm) {
38
38
  case 'chat_creator':
39
- return role === 'creator' || has('chat_creator');
39
+ return role === 'owner' || role === 'creator' || has('chat_creator');
40
40
  case 'chat_administrator':
41
- return role === 'creator' || role === 'administrator' || has('chat_administrator');
41
+ return role === 'owner' || role === 'admin' || role === 'creator' || role === 'administrator' || has('chat_administrator');
42
42
  case 'restrict_members':
43
- return has('restrict_members') || role === 'creator';
43
+ return has('restrict_members') || role === 'owner' || role === 'creator';
44
44
  case 'pin_messages':
45
- return has('pin_messages') || role === 'creator';
45
+ return has('pin_messages') || role === 'owner' || role === 'creator';
46
46
  case 'manage_chat':
47
- return has('manage_chat') || role === 'creator';
47
+ return has('manage_chat') || role === 'owner' || role === 'creator';
48
48
  default:
49
49
  return false;
50
50
  }
package/lib/protocol.d.ts CHANGED
@@ -138,7 +138,9 @@ export interface TelegramWireSegment {
138
138
  }
139
139
  export interface TelegramInlineButton {
140
140
  readonly text: string;
141
- readonly callback_data: string;
141
+ readonly callback_data?: string;
142
+ /** Bot API 10.3+: mutually exclusive with callback_data. */
143
+ readonly disabled?: Record<string, never>;
142
144
  }
143
145
  export type TelegramOutboundAction = {
144
146
  readonly method: 'sendMessage';
package/lib/protocol.js CHANGED
@@ -305,7 +305,7 @@ function buildOutboundActions(target, payload, uploads) {
305
305
  }
306
306
  if (!['http:', 'https:'].includes(url.protocol) || typeof data.title !== 'string' || !data.title.trim())
307
307
  throw new EndpointDeliveryError('invalid_payload', 'Telegram share requires an HTTP(S) URL and title', 'not_sent');
308
- if (['image', 'audio', 'artist', 'duration', 'config'].some(key => data[key] !== undefined))
308
+ if (['image', 'audio', 'artist', 'duration', 'platform', 'config'].some(key => data[key] !== undefined))
309
309
  throw new EndpointDeliveryError('unsupported_operation', 'Telegram share media and app metadata are not implemented', 'not_sent');
310
310
  textContent += `<a href="${escapeTelegramHtml(url.href)}">${escapeTelegramHtml(data.title)}</a>`;
311
311
  for (const value of [data.description, data.content])
@@ -335,9 +335,13 @@ function buildOutboundActions(target, payload, uploads) {
335
335
  : {};
336
336
  const text = String(record.label ?? record.text ?? '');
337
337
  const callback = String(record.payload ?? record.callback_data ?? '');
338
- if (record.disabled || record.mode === 'command')
339
- throw new EndpointDeliveryError('unsupported_operation', 'Telegram disabled/command buttons are not implemented', 'not_sent');
340
- if (!text.trim() || Buffer.byteLength(callback, 'utf8') < 1 || Buffer.byteLength(callback, 'utf8') > 64)
338
+ if (record.mode === 'command')
339
+ throw new EndpointDeliveryError('unsupported_operation', 'Telegram command buttons are not implemented', 'not_sent');
340
+ if (!text.trim())
341
+ throw new EndpointDeliveryError('invalid_payload', 'Telegram button label must be nonempty', 'not_sent');
342
+ if (record.disabled)
343
+ return { text, disabled: {} };
344
+ if (Buffer.byteLength(callback, 'utf8') < 1 || Buffer.byteLength(callback, 'utf8') > 64)
341
345
  throw new EndpointDeliveryError('invalid_payload', 'Telegram callback payload must be 1-64 UTF-8 bytes and label nonempty', 'not_sent');
342
346
  return {
343
347
  text,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zhin.js/adapter-telegram",
3
- "version": "1.1.10",
3
+ "version": "1.1.13",
4
4
  "description": "Zhin.js Telegram Bot API adapter for Plugin Runtime (long-poll getUpdates)",
5
5
  "type": "module",
6
6
  "main": "./lib/index.js",
@@ -31,23 +31,23 @@
31
31
  "directory": "plugins/adapters/telegram"
32
32
  },
33
33
  "dependencies": {
34
- "@zhin.js/adapter": "1.1.19",
35
- "@zhin.js/agent-feature": "1.1.6",
36
- "@zhin.js/core": "1.1.45",
37
- "@zhin.js/feature-kit": "1.1.5",
38
- "@zhin.js/host-http": "1.1.6",
39
- "@zhin.js/im-contract": "1.1.4",
34
+ "@zhin.js/adapter": "1.1.21",
35
+ "@zhin.js/agent-feature": "1.1.8",
36
+ "@zhin.js/core": "1.1.48",
37
+ "@zhin.js/feature-kit": "1.1.7",
38
+ "@zhin.js/host-http": "1.1.8",
39
+ "@zhin.js/im-contract": "1.1.5",
40
40
  "@zhin.js/logger": "1.1.2",
41
- "@zhin.js/skill": "1.1.6",
42
- "@zhin.js/tool": "1.1.6"
41
+ "@zhin.js/skill": "1.1.8",
42
+ "@zhin.js/tool": "1.1.8"
43
43
  },
44
44
  "peerDependencies": {
45
45
  "zod": "^4.0.0",
46
- "@zhin.js/adapter": "^1.1.19",
47
- "@zhin.js/command": "^1.1.7",
48
- "@zhin.js/core": "^1.1.45",
49
- "@zhin.js/permission": "^1.1.6",
50
- "zhin.js": "^1.1.10"
46
+ "@zhin.js/adapter": "^1.1.21",
47
+ "@zhin.js/command": "^1.1.9",
48
+ "@zhin.js/core": "^1.1.48",
49
+ "@zhin.js/permission": "^1.1.7",
50
+ "zhin.js": "^1.1.13"
51
51
  },
52
52
  "peerDependenciesMeta": {
53
53
  "@zhin.js/command": {
@@ -65,8 +65,8 @@
65
65
  "typescript": "^6.0.3",
66
66
  "vitest": "^4.1.10",
67
67
  "zod": "^4.4.3",
68
- "@zhin.js/host-http": "1.1.6",
69
- "zhin.js": "1.1.10"
68
+ "@zhin.js/host-http": "1.1.8",
69
+ "zhin.js": "1.1.13"
70
70
  },
71
71
  "files": [
72
72
  "adapters",
package/src/platform-permit.ts CHANGED
@@ -1,5 +1,8 @@
1
1
  /**
2
2
  * Telegram platform permit — ChatMember 状态 + 细粒度权限
3
+ *
4
+ * `role` 使用跨平台规范名 owner / admin（原生 creator / administrator 仅作兼容输入）；
5
+ * 细粒度能力放在 `permissions`。
3
6
  */
4
7
  import type { PermissionSubject } from '@zhin.js/permission';
5
8
 
@@ -29,7 +32,7 @@ export function normalizeTelegramChatMember(member: {
29
32
  const status = member.status;
30
33
  if (status === 'creator') {
31
34
  permissions.push('chat_creator', 'chat_administrator', 'restrict_members', 'pin_messages');
32
- return { role: 'creator', permissions };
35
+ return { role: 'owner', permissions };
33
36
  }
34
37
  if (status === 'administrator') {
35
38
  permissions.push('chat_administrator');
@@ -37,7 +40,7 @@ export function normalizeTelegramChatMember(member: {
37
40
  if (member.can_pin_messages) permissions.push('pin_messages');
38
41
  if (member.can_delete_messages) permissions.push('delete_messages');
39
42
  if (member.can_manage_chat) permissions.push('manage_chat');
40
- return { role: 'administrator', permissions };
43
+ return { role: 'admin', permissions };
41
44
  }
42
45
  return { role: 'member', permissions };
43
46
  }
@@ -49,15 +52,15 @@ export function checkTelegramPlatformPermit(perm: string, subject: PermissionSub
49
52
 
50
53
  switch (perm) {
51
54
  case 'chat_creator':
52
- return role === 'creator' || has('chat_creator');
55
+ return role === 'owner' || role === 'creator' || has('chat_creator');
53
56
  case 'chat_administrator':
54
- return role === 'creator' || role === 'administrator' || has('chat_administrator');
57
+ return role === 'owner' || role === 'admin' || role === 'creator' || role === 'administrator' || has('chat_administrator');
55
58
  case 'restrict_members':
56
- return has('restrict_members') || role === 'creator';
59
+ return has('restrict_members') || role === 'owner' || role === 'creator';
57
60
  case 'pin_messages':
58
- return has('pin_messages') || role === 'creator';
61
+ return has('pin_messages') || role === 'owner' || role === 'creator';
59
62
  case 'manage_chat':
60
- return has('manage_chat') || role === 'creator';
63
+ return has('manage_chat') || role === 'owner' || role === 'creator';
61
64
  default:
62
65
  return false;
63
66
  }
package/src/protocol.ts CHANGED
@@ -155,7 +155,9 @@ export interface TelegramWireSegment {
155
155
 
156
156
  export interface TelegramInlineButton {
157
157
  readonly text: string;
158
- readonly callback_data: string;
158
+ readonly callback_data?: string;
159
+ /** Bot API 10.3+: mutually exclusive with callback_data. */
160
+ readonly disabled?: Record<string, never>;
159
161
  }
160
162
 
161
163
  export type TelegramOutboundAction =
@@ -580,7 +582,7 @@ function buildOutboundActions(
580
582
  let url: URL;
581
583
  try { url = new URL(String(data.url ?? '')); } catch { throw new EndpointDeliveryError('invalid_payload', 'Telegram share requires an HTTP(S) URL', 'not_sent'); }
582
584
  if (!['http:', 'https:'].includes(url.protocol) || typeof data.title !== 'string' || !data.title.trim()) throw new EndpointDeliveryError('invalid_payload', 'Telegram share requires an HTTP(S) URL and title', 'not_sent');
583
- if (['image', 'audio', 'artist', 'duration', 'config'].some(key => data[key] !== undefined)) throw new EndpointDeliveryError('unsupported_operation', 'Telegram share media and app metadata are not implemented', 'not_sent');
585
+ if (['image', 'audio', 'artist', 'duration', 'platform', 'config'].some(key => data[key] !== undefined)) throw new EndpointDeliveryError('unsupported_operation', 'Telegram share media and app metadata are not implemented', 'not_sent');
584
586
  textContent += `<a href="${escapeTelegramHtml(url.href)}">${escapeTelegramHtml(data.title)}</a>`;
585
587
  for (const value of [data.description, data.content]) if (typeof value === 'string' && value) textContent += `\n${escapeTelegramHtml(value)}`;
586
588
  break;
@@ -604,8 +606,10 @@ function buildOutboundActions(
604
606
  : {};
605
607
  const text = String(record.label ?? record.text ?? '');
606
608
  const callback = String(record.payload ?? record.callback_data ?? '');
607
- if (record.disabled || record.mode === 'command') throw new EndpointDeliveryError('unsupported_operation', 'Telegram disabled/command buttons are not implemented', 'not_sent');
608
- if (!text.trim() || Buffer.byteLength(callback, 'utf8') < 1 || Buffer.byteLength(callback, 'utf8') > 64) throw new EndpointDeliveryError('invalid_payload', 'Telegram callback payload must be 1-64 UTF-8 bytes and label nonempty', 'not_sent');
609
+ if (record.mode === 'command') throw new EndpointDeliveryError('unsupported_operation', 'Telegram command buttons are not implemented', 'not_sent');
610
+ if (!text.trim()) throw new EndpointDeliveryError('invalid_payload', 'Telegram button label must be nonempty', 'not_sent');
611
+ if (record.disabled) return { text, disabled: {} };
612
+ if (Buffer.byteLength(callback, 'utf8') < 1 || Buffer.byteLength(callback, 'utf8') > 64) throw new EndpointDeliveryError('invalid_payload', 'Telegram callback payload must be 1-64 UTF-8 bytes and label nonempty', 'not_sent');
609
613
  return {
610
614
  text,
611
615
  callback_data: callback,