@zhin.js/adapter-telegram 5.0.2 → 6.0.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## 6.0.0
+
+### Patch Changes
+
+- 7db69c1: 命令前缀改为适配器配置项：`MessageDispatcher` 不再硬编码 `/`，默认按消息所属适配器实例 config 的 `commandPrefix` 解析（默认 `''` 无前缀，任意文本按命令匹配），`endpoints[i].commandPrefix` 逐项覆盖；`ImRuntime({ commandPrefix })` 仍可设全局静态前缀。全部 20 个平台适配器 schema 新增 `commandPrefix` 属性。
+
+  BREAKING（行为变化）：未配置时命令不再需要 `/` 前缀——原 `/zt` 写法不再命中，直接发 `zt` 即可；需要斜杠风格的适配器请在配置里显式设 `commandPrefix: '/'`。
+
+- 713445c: 适配器配置格式定稿（不兼容旧格式）：`plugins.<adapter>` 顶层仅共享字段 + `commandPrefix`，`endpoints[i]` 携带 endpoint 级字段（`name` + 凭据，各 schema 已类型化），`endpoints` 为必填（icqq 另需顶层 `master`）；icqq 新增 `trusted` 列表（顶层/逐项均可）。scaffold-wizard 全部字段式与自定义 configure() 产出改为新格式，examples（full-bot / qq-games-bot）与 20 个适配器 README 同步迁移。
+- Updated dependencies [7db69c1]
+- Updated dependencies [e5c84ed]
+- Updated dependencies [3ea84a0]
+- Updated dependencies [1ddcd70]
+- Updated dependencies [ac9da66]
+  - @zhin.js/core@1.4.0
+  - @zhin.js/adapter@1.1.0
+  - @zhin.js/plugin-runtime@1.1.0
+  - @zhin.js/agent@1.0.5
+  - @zhin.js/host-http@1.0.2
+  - zhin.js@5.0.0
+
+## 5.0.3
+
+### Patch Changes
+
+- cc5c94d: 约定式插件运行时迁移（breaking）：插件与适配器由 `usePlugin()` / `extends Adapter` 迁移为 `definePlugin` / `defineAdapter` + `plugin.ts` + 约定目录（`adapters/`、`commands/`、`components/`、`tools/` 等）。
+
+  - 新增约定式运行时包：`@zhin.js/plugin-runtime`、`@zhin.js/adapter`、`@zhin.js/runtime`、`@zhin.js/host-http`（首版 1.0.0 走 init-publish，不在本 changeset 内 bump）。
+  - 全部 20 个平台适配器改为约定式 `defineAdapter`，旧 `usePlugin` / `extends Adapter` / `segment-mapper` 生产入口已删除；onebot11 反向 WSS、onebot12 webhook/wss、milky sse/webhook/wss、satori webhook、kook webhook、qq webhook/middleware 等 slice 1 推迟的连接模式已补齐。
+  - 游戏 / 工具 / 服务插件同步迁移到约定目录结构。
+  - CLI 增加 plugin-runtime host installer（http/database/outbound/schedule/console 等）。
+
+  后续加固（同批）：
+
+  - CLI：`zhin runtime start --daemon`（pidfile/崩溃拉起/风暴保护），orphan watchdog 防僵尸进程；legacy `zhin dev` / `zhin start` 已移除（含 `zhin restart`），`zhin stop` 兼容新 daemon。
+  - 安全：builtin 工具统一走 `security/policy-facade.ts` 的 `runToolPolicies`（声明式策略表，deny 优先）；审计日志 close flush + 背压队列；`splitCompoundCommand` 引号感知、`extractCommandName` 去引号堵绕过。
+  - 日志：Logger 双堆栈修复、本地时区、`getLogger` 挂树（`setLevel` 递归生效）、第三方库（log4js/discord）桥接、启动人读总结。
+  - 结构：`plugins/games/shared` 迁为 `packages/game-kit`（`@zhin.js/game-kit`）；死目录 `plugins/adapters/common` 删除。
+  - 脚手架：`create-zhin-app` / `zhin new` / scaffold-wizard 生成物改为 Plugin Runtime 形态（minimal-bot 同构，新配置格式）。
+  - Console：endpoint.list 真实名称与 phase、schema:get-all 按 instanceKey 映射、db:\* 接 DatabaseHost。
+
+  注：按仓库发布惯例（见 1bb345dd2），本次 breaking 迁移统一使用 patch，避免 zhin.js 5.0 级联。
+
+- 447f3e2: 迁移缺口修复（legacy 功能对齐）：
+
+  - html 段出站规范化：经 `@zhin.js/html-renderer` 渲染为 image 段（sandbox 豁免、无渲染器时降级文本），修复真实平台 `[object Object]`。
+  - 群聊 @ 触发 AI：适配器入站标注 `metadata.mentioned`（icqq/qq/slack/onebot11/onebot12/napcat/milky/discord/telegram/kook/dingtalk/satori），`matchAiTrigger` 补齐 ignorePrefixes/respondToAt/respondToPrivate/keywords（默认值与 legacy 对齐）。
+  - im_transcripts 全量流水恢复写入（chat_history 工具可用）；群聊旁听上下文回迁。
+  - `ai.trigger.timeout/thinkingMessage/errorTemplate` 生效；masters/trusted 角色解析对齐 legacy。
+  - `Message.sender` 统一为用户 ID（onebot11/12、napcat、milky 原误传显示名）；quote_id 经 metadata 接入 AI 引用上下文。
+
+- Updated dependencies [16ec4e8]
+- Updated dependencies [cc5c94d]
+- Updated dependencies [447f3e2]
+  - @zhin.js/core@1.3.5
+  - @zhin.js/agent@1.0.4
+  - @zhin.js/host-http@1.0.1
+  - zhin.js@4.1.3
+  - @zhin.js/logger@1.0.75
+  - @zhin.js/plugin-runtime@1.0.1
+  - @zhin.js/adapter@1.0.1
+
 ## 5.0.2
 
 ### Patch Changes

package/README.md

@@ -1,188 +1,106 @@
 # @zhin.js/adapter-telegram
 
-Telegram adapter for zhin.js framework.
+Zhin.js Telegram Bot API 适配器（Plugin Runtime），默认通过 **长轮询 `getUpdates`** 收发消息（无需 host）。
 
-## Installation
+## 功能
+
+- 长轮询 `getUpdates` 入站（默认；无需公网 IP / host-http）
+- 解析 text / image / video / audio / voice / document / sticker / location / callback_query
+- 支持私聊与群组
+- 出站 `send({ target, payload })` → Bot API（text / media / keyboard）
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
+- Webhook 模式延期（需 `httpHostToken`）；配置 `polling: false` 会明确报错
+
+## 安装
 
 ```bash
 pnpm add @zhin.js/adapter-telegram
 ```
 
-## Prerequisites
+## Plugin Runtime
 
-| 要求 | 说明 |
-|------|------|
-| **Bot Token** | 通过 [@BotFather](https://t.me/botfather) 创建 Endpoint 并获取 Token |
-| **Polling（默认）** | 本地开发无需公网 IP；`polling: true`（默认） |
-| **Webhook（可选）** | 生产环境：`polling: false` + 公网 **HTTPS** 域名与有效 TLS；Telegraf 在 `webhook.port` 监听 |
-| **host-router** | 不需要；本适配器自行处理 polling / webhook |
+- `@zhin.js/adapter` — 约定式 `adapters/telegram.ts`（`defineAdapter`）
+- `@zhin.js/core` — `messageGatewayToken` 入站/出站
+- `@zhin.js/plugin-runtime` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
+- **无需** `@zhin.js/host-http`（polling 路径）
 
-必填字段见 `TelegramEndpointConfig`：`context`、`name`、`token`；`polling` 默认为 `true`。
+入站：`gateway.receive({ adapter, target: chatId, content: text, sender, metadata })`  
+出站：`send({ target, payload })` → Telegram Bot API
 
-## Minimal configuration
+### 平台权限（platform permit）
 
-```yaml
-plugins:
-  - "@zhin.js/adapter-telegram"
+- sender role 已恢复：群消息入站时经 `getChatMember`（60s 缓存）解析，写入 `metadata.senderRole` / `metadata.senderPermissions`。
+- `plugin.ts` 在 generation setup 注册 checker，并在 dispose 注销；Plugin Runtime CapabilityIngress 与 ToolSystem 统一经 Core `canAccessTool()` 消费 `permissions`。
 
-endpoints:
-  - context: telegram
-    name: my-telegram-bot
-    token: "${TELEGRAM_TOKEN}"
-    polling: true
-```
+## 前置条件
 
-## Configuration
+| 要求 | 说明 |
+|------|------|
+| **Bot Token** | 通过 [@BotFather](https://t.me/botfather) 创建并获取 Token |
+| **Polling（默认）** | 本地/生产均可；主动拉取更新，无需公网 HTTPS |
+| **网络** | 出站可访问 `api.telegram.org` |
+| **host-http** | Polling **不需要**；Webhook 延期至下一棒 |
 
-### 长轮询 Polling（默认，本地开发）
+必填字段（`endpoints[i]`）：`name`、`token`。
 
-无需公网 IP 或 HTTPS，Bot 主动向 Telegram 拉取更新：
+## 最小配置
 
 ```yaml
+# zhin.config.yml（Plugin Runtime）
 plugins:
-  - "@zhin.js/adapter-telegram"
-
-endpoints:
-  - context: telegram
-    name: my-telegram-bot
-    token: "${TELEGRAM_TOKEN}"
-    polling: true
+  telegram:
+    # polling: true   # 默认
+    endpoints:
+      - name: my-telegram-bot
+        token: ${TELEGRAM_TOKEN}
 ```
 
-### Webhook（生产环境）
-
-设置 `polling: false` 并配置 `webhook` 对象；Telegraf 在 `webhook.port` 上启动 HTTPS 服务：
-
-```yaml
-endpoints:
-  - context: telegram
-    name: my-telegram-bot
-    token: "${TELEGRAM_TOKEN}"
-    polling: false
-    webhook:
-      domain: https://bot.example.com
-      path: /telegram-webhook
-      port: 8443
-```
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-telegram`（`instanceKey: telegram`）。
 
-#### Webhook 前置条件
+## 环境变量
 
-| 要求 | 说明 |
+| 变量 | 说明 |
 |------|------|
-| **HTTPS 公网域名** | `webhook.domain` 须为 Telegram 可访问的 `https://` 地址（有效 TLS 证书） |
-| **端口可达** | `webhook.port`（如 8443）须从公网可连，或通过反向代理转发 |
-| **Bot Token** | 通过 [@BotFather](https://t.me/botfather) 获取 |
-| **无需 host-router** | 本适配器由 Telegraf 自行监听 webhook，不依赖 `@zhin.js/host-router` |
-
-> 本地开发建议先用 **polling**；上线后再切 webhook 并在 BotFather 或 launch 时注册 webhook URL。
-
-TypeScript 等价配置：
-
-```typescript
-import { defineConfig } from 'zhin.js'
-
-export default defineConfig({
-  endpoints: [
-    {
-      name: 'my-telegram-bot',
-      context: 'telegram',
-      token: 'YOUR_BOT_TOKEN',
-      polling: true,
-      // polling: false,
-      // webhook: { domain: 'https://yourdomain.com', path: '/telegram-webhook', port: 8443 },
-    }
-  ]
-})
-```
+| `TELEGRAM_TOKEN` / `TELEGRAM_BOT_TOKEN` | Bot Token |
+| `TELEGRAM_BOT_NAME` | 可选，默认 endpoint 名 |
 
-## Features
+## Webhook（延期）
 
-- ✅ Send and receive text messages
-- ✅ Support for rich media (images, videos, audio, documents)
-- ✅ Message formatting (bold, italic, code, links)
-- ✅ Reply to messages
-- ✅ Mentions (@username)
-- ✅ Stickers and locations
-- ✅ Callback queries (inline buttons)
-- ✅ Long polling and webhook modes
-- ✅ Private and group chats
+`polling: false` + `webhook` 目前会抛出明确错误：
 
-## Getting Your Endpoint Token
+> Telegram webhook mode is deferred until httpHostToken wiring; use polling: true (default) for now
 
-1. Talk to [@BotFather](https://t.me/botfather) on Telegram
-2. Send `/newbot` and follow the instructions
-3. Copy the bot token provided
-4. Add the token to your configuration
+下一棒将用 `httpHostToken` 注册 POST 路由，不再使用 Telegraf 自建监听或 legacy host-router。
 
-## Usage Examples
+## 消息类型映射
 
-### Basic Message Handling
-
-```typescript
-import { usePlugin, MessageCommand } from 'zhin.js'
-
-const { addCommand } = usePlugin()
-
-addCommand(new MessageCommand('hello')
-  .action(async (message) => {
-    return 'Hello from Telegram!'
-  })
-)
-```
-
-### Send Rich Media
-
-```typescript
-addCommand(new MessageCommand('photo')
-  .action(async (message) => {
-    return [
-      { type: 'image', data: { url: 'https://example.com/photo.jpg' } },
-      { type: 'text', data: { text: 'Check out this photo!' } }
-    ]
-  })
-)
-```
-
-### Reply to Messages
-
-```typescript
-addCommand(new MessageCommand('quote <text:text>')
-  .action(async (message, result) => {
-    await message.$reply(`You said: ${result.params.text}`, true) // true = quote original message
-  })
-)
-```
-
-## Telegram-Specific Features
-
-### Callback Queries
-
-The adapter automatically handles callback queries (from inline keyboards) as special messages.
-
-### File Handling
-
-You can send files using:
-- `file_id` (from received messages)
-- URL
-- Local file path
+| Telegram | 入站 content（文本摘要） | 出站 wire |
+|----------|--------------------------|-----------|
+| text | 原文 | sendMessage |
+| photo | `[image]` / caption | sendPhoto（`file_id` / `url`） |
+| video | `[video]` | sendVideo |
+| audio / voice | `[audio]` / `[voice]` | sendAudio / sendVoice |
+| document | `[file: name]` | sendDocument |
+| sticker | `[sticker: …]` | sendSticker |
+| location | `[location: lat,lon]` | sendLocation |
+| callback_query | `[action: data]` | — |
 
 ## AI tools
 
 | Kind | Path |
 |------|------|
-| Platform tools (10) | `agent/tools/` (`telegram_*`: invites, pins, admins, stickers, etc.) |
+| Platform tools (10) | `agent/tools/`（invite / pin / admins / sticker / poll 等） |
 | Skill doc | `agent/skills/telegram.md` |
-| Scene management | `createSceneManagementTools()` |
-
 
-## Troubleshooting
+## 故障排查
 
 | 现象 | 排查 |
 |------|------|
-| Endpoint 无响应 / 收不到消息 | 确认 Token 正确；进程已启动；私聊 Endpoint 或将其加入群组 |
-| Polling 报错 | 检查网络能否访问 `api.telegram.org`；同一 Token 勿多进程同时 polling |
-| Webhook 不工作 | `webhook.domain` 须为 Telegram 可访问的 `https://`；放行 `webhook.port`；BotFather 或 launch 时注册 URL |
-| 发送失败 | Token  revoked 或 Endpoint 被限制；查看日志中的 Telegraf 错误 |
+| 收不到消息 | Token 是否正确；进程已 `open()`；同一 Token 勿多进程同时 polling |
+| Polling 报错 | 检查能否访问 `api.telegram.org`；查看日志 `op: poll` |
+| Webhook 配置报错 | 当前仅支持 polling；去掉 `polling: false` |
+| 发送失败 | Token 是否被撤销；查看 Bot API 错误描述 |
 
 ## Documentation
 

package/adapters/telegram.ts

@@ -0,0 +1,27 @@
+/**
+ * Convention entry: discover `adapters/telegram.ts` → defineAdapter.
+ */
+import { defineAdapter } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { httpHostToken } from '@zhin.js/host-http';
+import { TelegramEndpoint } from '../src/endpoint.js';
+import {
+  resolveTelegramConfig,
+  type TelegramAdapterConfig,
+} from '../src/protocol.js';
+
+export { TelegramEndpoint } from '../src/endpoint.js';
+export type { TelegramEndpointOptions, TelegramFetch } from '../src/endpoint.js';
+
+export default defineAdapter<TelegramAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  create(context) {
+    const config = resolveTelegramConfig(context.config);
+    return new TelegramEndpoint({
+      id: context.id,
+      gateway: context.use(messageGatewayToken),
+      config,
+      http: config.mode === 'webhook' ? context.use(httpHostToken) : undefined,
+    });
+  },
+});

package/agent/tools/create_invite.ts

@@ -1,9 +1,9 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
 import { getTelegramAgentDeps } from '../../src/telegram-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; chat_id: string }>({
+export default defineAgentTool<{ endpoint_id: string; chat_id: string }>({
   description: '创建 Telegram 群组邀请链接',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/list_admins.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getTelegramAgentDeps } from '../../src/telegram-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; chat_id: string }>({
+export default defineAgentTool<{ endpoint_id: string; chat_id: string }>({
   description: '获取 Telegram 群组管理员列表',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/member_count.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getTelegramAgentDeps } from '../../src/telegram-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; chat_id: string }>({
+export default defineAgentTool<{ endpoint_id: string; chat_id: string }>({
   description: '获取 Telegram 群组成员数量',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/pin_message.ts

@@ -1,9 +1,9 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
 import { getTelegramAgentDeps } from '../../src/telegram-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; chat_id: string; message_id: string }>({
+export default defineAgentTool<{ endpoint_id: string; chat_id: string; message_id: string }>({
   description: '置顶 Telegram 群组消息',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/react.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getTelegramAgentDeps } from '../../src/telegram-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; chat_id: string; message_id: string; reaction: string }>({
+export default defineAgentTool<{ endpoint_id: string; chat_id: string; message_id: string; reaction: string }>({
   description: '对 Telegram 消息添加表情反应',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/send_poll.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getTelegramAgentDeps } from '../../src/telegram-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; chat_id: string; question: string; options: string; is_anonymous?: boolean; allows_multiple?: boolean }>({
+export default defineAgentTool<{ endpoint_id: string; chat_id: string; question: string; options: string; is_anonymous?: boolean; allows_multiple?: boolean }>({
   description: '在 Telegram 群组中发起投票',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/send_sticker.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getTelegramAgentDeps } from '../../src/telegram-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; chat_id: string; sticker: string }>({
+export default defineAgentTool<{ endpoint_id: string; chat_id: string; sticker: string }>({
   description: '发送 Telegram 贴纸',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/set_description.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getTelegramAgentDeps } from '../../src/telegram-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; chat_id: string; description: string }>({
+export default defineAgentTool<{ endpoint_id: string; chat_id: string; description: string }>({
   description: '设置 Telegram 群组描述',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/set_permissions.ts

@@ -1,9 +1,9 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
 import { getTelegramAgentDeps } from '../../src/telegram-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; chat_id: string; can_send_messages?: boolean; can_send_photos?: boolean; can_send_videos?: boolean; can_send_polls?: boolean; can_send_other_messages?: boolean; can_add_web_page_previews?: boolean; can_change_info?: boolean; can_invite_users?: boolean; can_pin_messages?: boolean }>({
+export default defineAgentTool<{ endpoint_id: string; chat_id: string; can_send_messages?: boolean; can_send_photos?: boolean; can_send_videos?: boolean; can_send_polls?: boolean; can_send_other_messages?: boolean; can_add_web_page_previews?: boolean; can_change_info?: boolean; can_invite_users?: boolean; can_pin_messages?: boolean }>({
   description: '设置 Telegram 群组的默认成员权限',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/unpin_message.ts

@@ -1,9 +1,9 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
 import { getTelegramAgentDeps } from '../../src/telegram-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; chat_id: string; message_id?: string }>({
+export default defineAgentTool<{ endpoint_id: string; chat_id: string; message_id?: string }>({
   description: '取消置顶 Telegram 群组消息',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/lib/endpoint.d.ts

@@ -0,0 +1,65 @@
+/**
+ * TelegramEndpoint — lifecycle, outbound, admit, Bot API helpers for agent tools.
+ */
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { type ResolvedTelegramConfig, type TelegramCallbackQuery, type TelegramChatMember, type TelegramMessage, type TelegramUpdate } from './protocol.js';
+export type TelegramFetch = (url: string, init?: {
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly body?: string;
+    readonly signal?: AbortSignal;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+}>;
+export interface TelegramEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly config: ResolvedTelegramConfig;
+    readonly http?: HttpHost;
+    readonly fetch?: TelegramFetch;
+}
+export declare class TelegramEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: TelegramEndpointOptions);
+    /** Used by webhook handler. */
+    get isOpen(): boolean;
+    get config(): ResolvedTelegramConfig;
+    get allowedUpdates(): readonly string[];
+    getUpdateOffset(): number;
+    setUpdateOffset(offset: number): void;
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): Promise<string>;
+    /** Test / internal: admit a message when open. */
+    admit(msg: TelegramMessage): void;
+    /** Test / internal: admit a callback query when open. */
+    admitCallback(query: TelegramCallbackQuery): void;
+    /** Used by webhook / polling handlers. */
+    handleUpdate(update: TelegramUpdate): void;
+    callApi<T = unknown>(method: string, params?: Record<string, unknown>, signal?: AbortSignal): Promise<T>;
+    pinMessage(chatId: number, messageId: number): Promise<boolean>;
+    unpinMessage(chatId: number, messageId?: number): Promise<boolean>;
+    setChatDescription(chatId: number, description: string): Promise<boolean>;
+    setMessageReaction(chatId: number, messageId: number, reaction: string): Promise<boolean>;
+    getChatMemberCount(chatId: number): Promise<number>;
+    getChatAdmins(chatId: number): Promise<TelegramChatMember[]>;
+    sendStickerMessage(chatId: number, sticker: string): Promise<{
+        message_id: number;
+    }>;
+    setChatPermissionsAll(chatId: number, permissions: Record<string, boolean | undefined>): Promise<boolean>;
+    createInviteLink(chatId: number): Promise<string>;
+    sendPoll(chatId: number, question: string, options: string[], isAnonymous?: boolean, allowsMultipleAnswers?: boolean): Promise<{
+        message_id: number;
+    }>;
+}