@zhin.js/adapter-wecom 0.0.1 → 1.1.0

package/README.md

@@ -1,6 +1,13 @@
 # @zhin.js/adapter-wecom
 
-Zhin.js 企业微信（WeCom）适配器，支持企业内部应用机器人开发。
+Zhin.js 企业微信（WeCom）适配器（Plugin Runtime），通过 Runtime Host HTTP Webhook 收发消息。
+
+## 功能
+
+- Webhook 事件接收（`httpHostToken` GET 验签解密 + POST 消息）
+- AES-256-CBC 消息加解密与 SHA1 签名验证
+- Access Token 自动刷新
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 
 ## 安装
 
@@ -8,255 +15,112 @@ Zhin.js 企业微信（WeCom）适配器，支持企业内部应用机器人开
 pnpm add @zhin.js/adapter-wecom
 ```
 
-## 前置条件
+## Plugin Runtime
 
-### 企业微信管理后台配置
+- `@zhin.js/adapter` — 约定式 `adapters/wecom.ts`（`defineAdapter`）
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `@zhin.js/host-http` — `httpHostToken` 注册 Webhook 路由（**非** legacy host-router/Koa）
+- `zhin.js` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 
-1. **登录企业微信管理后台**
-   - 访问 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame)
-   - 使用管理员账号登录
+入站：`gateway.receive({ conversation, message: { conversation, id: MsgId }, content: text, sender, metadata })`（`conversation` 为 `ConversationRef`，`@chatroom` → kind `group`，其余 → kind `private`）  
+出站：`send({ conversation, payload })` → 企业微信 `message/send` API
 
-2. **创建应用**
-   - 进入「应用管理」→「自建」
-   - 点击「创建应用」
-   - 填写应用名称、上传 Logo、选择可见范围
+入站 `metadata.mentioned`：**未接线**。企业微信应用消息回调的 XML 事件不含 mentions/@ 字段，回调里的 `ToUserName` 是 CorpID（企业 ID）而非可比较的 bot 用户 id，配置中也没有 bot id/name 可作可靠判据，故无法可靠识别 @ 机器人。
 
-3. **获取应用凭证**
-   - 在应用详情页面获取：
-     - **CorpId**（企业 ID）：在「我的企业」→「企业信息」中查看
-     - **AgentId**（应用 AgentId）：在应用详情页面
-     - **Secret**（应用 Secret）：在应用详情页面
+## 前置条件
 
-4. **配置接收消息**
-   - 在应用详情页面，进入「接收消息」设置
-   - 设置 **URL**：`https://yourdomain.com/wecom/callback`
-   - 设置 **Token**：自定义字符串（用于签名验证）
-   - 设置 **EncodingAESKey**：点击「随机获取」（用于消息加解密）
-   - 点击「保存」，企业微信会发送验证请求
+### 企业微信管理后台配置
 
-5. **配置权限**
-   - 在「API 权限」中申请所需权限：
-     - `通讯录只读权限` - 读取组织架构和用户信息
-     - `应用消息发送权限` - 向用户发送消息
-     - 其他业务需要的权限
+1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame)
+2. 「应用管理」→「自建」→ 创建应用，获取 **CorpId**、**AgentId**、**Secret**
+3. 「接收消息」设置：
+   - **URL**：`https://yourdomain.com/wecom/callback`
+   - **Token** / **EncodingAESKey** 与配置一致
+4. Runtime Host（`http`）须已 listen，Webhook 才可达
 
-## 配置
+必填字段（`endpoints[i]`）：`name`、`corpId`、`agentSecret`、`token`、`encodingAESKey`。
 
-### 基础配置（zhin.config.yml）
+## 最小配置
 
 ```yaml
-endpoints:
-  - name: wecom-bot
-    context: wecom
-    corpId: "ww1234567890abcdef"
-    agentSecret: "your-agent-secret"
-    token: "your-verify-token"
-    encodingAESKey: "your-43-char-encoding-aes-key"
-    webhookPath: "/wecom/callback"
-
+# zhin.config.yml（Plugin Runtime）
 plugins:
-  - "@zhin.js/host-router"
-  - "@zhin.js/adapter-wecom"
-```
-
-### 完整配置
-
-```yaml
-endpoints:
-  - name: wecom-bot
-    context: wecom
-    corpId: "ww1234567890abcdef"
-    agentSecret: "your-agent-secret"
-    token: "your-verify-token"
-    encodingAESKey: "your-43-char-encoding-aes-key"
-    webhookPath: "/wecom/callback"
-    apiBaseUrl: "https://qyapi.weixin.qq.com"  # 可选，默认值
+  wecom:
+    webhookPath: /wecom/callback       # 可选，默认 /wecom/callback
+    apiBaseUrl: https://qyapi.weixin.qq.com  # 可选
+    endpoints:
+      - name: wecom-bot
+        corpId: ${WECOM_CORP_ID}
+        agentSecret: ${WECOM_AGENT_SECRET}
+        token: ${WECOM_TOKEN}
+        encodingAESKey: ${WECOM_AES_KEY}
 ```
 
-### 配置参数说明
-
-| 参数 | 必需 | 说明 |
-|------|------|------|
-| `corpId` | 是 | 企业 ID，在管理后台「我的企业」查看 |
-| `agentSecret` | 是 | 应用 Secret，在应用详情页获取 |
-| `token` | 是 | 用于签名验证，需与管理后台「接收消息」设置中的 Token 一致 |
-| `encodingAESKey` | 是 | 用于消息加解密，需与管理后台一致（43 字符） |
-| `webhookPath` | 否 | Webhook 回调路径，默认 `/wecom/callback` |
-| `apiBaseUrl` | 否 | 企业微信 API 地址，默认 `https://qyapi.weixin.qq.com` |
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-wecom`（`instanceKey: wecom`）。
 
-### 环境变量推荐
-
-```yaml
-endpoints:
-  - name: wecom-bot
-    context: wecom
-    corpId: "${WECOM_CORP_ID}"
-    agentSecret: "${WECOM_AGENT_SECRET}"
-    token: "${WECOM_TOKEN}"
-    encodingAESKey: "${WECOM_AES_KEY}"
-```
-
-## 使用示例
-
-### 接收和发送消息
-
-```typescript
-import { usePlugin, MessageCommand } from 'zhin.js'
-
-const { addCommand, logger } = usePlugin()
-
-// 定义命令
-addCommand(new MessageCommand('hello <name:text>')
-  .action(async (message, result) => {
-    logger.info(`收到问候: ${result.params.name}`)
-    return `你好，${result.params.name}！欢迎使用企业微信机器人。`
-  })
-)
-
-// 监听所有消息
-import { onMessage } from 'zhin.js'
-
-onMessage(async (message) => {
-  logger.info(`收到消息：${JSON.stringify(message.$content)}`)
-  logger.info(`发送者：${message.$sender.name}`)
-  logger.info(`会话类型：${message.$channel.type}`)
-})
-```
+## 环境变量
 
-### 发送富文本消息
-
-```typescript
-addCommand(new MessageCommand('info')
-  .action(async (message) => {
-    return [
-      {
-        type: 'markdown',
-        data: {
-          content: `# 系统信息\n\n- 服务器: 运行正常\n- 版本: v1.0.0\n- 状态: 在线`
-        }
-      }
-    ]
-  })
-)
-```
+| 变量 | 说明 |
+|------|------|
+| `WECOM_CORP_ID` | 企业 ID |
+| `WECOM_AGENT_SECRET` | 应用 Secret |
+| `WECOM_TOKEN` | 回调签名 Token |
+| `WECOM_AES_KEY` | EncodingAESKey（43 字符） |
 
 ## 消息类型支持
 
-### 接收消息类型
-
-| 类型 | 状态 | 说明 |
-|------|------|------|
-| 文本消息 (`text`) | 支持 | 普通文本 |
-| 图片消息 (`image`) | 支持 | 图片文件 |
-| 语音消息 (`voice`) | 支持 | 含语音识别结果 |
-| 视频消息 (`video`) | 支持 | 视频文件 |
-| 位置消息 (`location`) | 支持 | 地理位置 |
-| 链接消息 (`link`) | 支持 | 链接卡片 |
-| 事件消息 (`event`) | 支持 | 关注/取消关注等 |
-
-### 发送消息类型
-
-| 类型 | 状态 | 说明 |
-|------|------|------|
-| 文本消息 | 支持 | 支持 @ 提醒 |
-| 图片消息 | 支持 | 需要 media_id |
-| Markdown 消息 | 支持 | 企业微信原生 Markdown |
-| 图文消息 | 支持 | news 类型 |
-| 撤回消息 | 不支持 | 企业微信机器人不支持撤回 |
+| 入站类型 | content 摘要 |
+|----------|--------------|
+| text | 原文 |
+| image | `[image: url]` |
+| voice | 识别结果或 `[voice]` |
+| video / shortvideo | `[video]` |
+| location | `[位置] …` |
+| link | `[link: …]` |
+| event | `[事件] …` |
+
+| 出站 wire | 说明 |
+|-----------|------|
+| text | 支持 `<@userid>` |
+| image | 需 `media_id` |
+| markdown | 企业微信原生 Markdown |
+| news | link 段映射 |
 
 ## 安全说明
 
-### 消息加解密
-
-企业微信使用 AES-256-CBC 加密算法对回调消息进行加密：
-
-- **签名验证**：SHA1 排序拼接 `[token, timestamp, nonce, encrypt]`
-- **解密流程**：
-  1. Base64 解码加密消息
-  2. AES-256-CBC 解密（Key: `encodingAESKey` + `=` 的 Base64 解码，IV: Key 的前 16 字节）
-  3. PKCS7 去填充
-  4. 提取：16 字节随机数 + 4 字节消息长度 + 消息体 + CorpId
+企业微信回调始终加密：
 
-适配器自动处理所有加解密，无需手动处理。
-
-### Token 管理
-
-适配器会自动管理 access_token：
-- 首次连接时获取 token
-- Token 过期前 5 分钟自动刷新
-- 所有 API 请求自动携带有效 token
-
-## API 方法
-
-### 获取用户信息
-
-```typescript
-const endpoint = app.adapters.get('wecom')?.endpoints.get('wecom-bot')
-if (endpoint) {
-  const userInfo = await endpoint.getUserInfo('user-id')
-  console.log(userInfo)
-}
-```
+- **签名**：SHA1 排序拼接 `[token, timestamp, nonce, encrypt]`
+- **解密**：AES-256-CBC（Key = `encodingAESKey` + `=` 的 Base64，IV = Key 前 16 字节）
 
-### 获取部门用户列表
-
-```typescript
-const users = await endpoint.getDepartmentUsers(1) // 部门 ID
-console.log(users)
-```
-
-### 获取部门列表
-
-```typescript
-const departments = await endpoint.getDepartmentList(1) // 父部门 ID
-console.log(departments)
-```
-
-### 发送文本消息
-
-```typescript
-const success = await endpoint.sendTextMessage('user-id', '这是一条测试消息')
-```
+Access Token 在过期前 5 分钟自动刷新。
 
 ## 故障排查
 
-### Q: Webhook 验证失败？
-
-A: 检查以下几点：
-1. `token` 是否与企业微信管理后台设置的 Token 一致
-2. `encodingAESKey` 是否与管理后台一致（43 字符）
-3. 服务器是否可从公网访问
-4. 服务器是否返回了正确的验证响应（解密后的 echostr）
-
-### Q: 收不到消息回调？
-
-A: 可能的原因：
-1. 应用未启用「接收消息」功能
-2. Webhook URL 配置错误或不可达
-3. 应用可见范围未包含发送消息的用户
-4. 服务器日志中是否有签名验证失败的警告
+| 现象 | 排查 |
+|------|------|
+| URL 验证失败 | `token` / `encodingAESKey` / `corpId` 与管理后台一致；Host 已 listen 且公网可达 |
+| 收不到消息 | 应用已启用接收消息；可见范围包含发送者；endpoint 已 `open()` |
+| 发送失败 | `corpId` + `agentSecret` 可换取 token；接收者在可见范围 |
 
-### Q: 发送消息失败？
+## AI 工具
 
-A: 可能的原因：
-1. `agentSecret`（应用 Secret）配置错误
-2. access_token 获取失败（检查 CorpId 和 Secret）
-3. 接收者不在应用可见范围内
-4. 应用未开通消息发送权限
+| 类别 | 路径 |
+|------|------|
+| Permit 词汇 | `agent/PERMITS.md` |
+| 平台工具（4 个） | `agent/tools/` |
+| 技能说明 | `agent/skills/wecom.md` |
 
-### Q: Token 刷新失败？
+## 平台权限（platform permit）
 
-A: 检查：
-1. CorpId 是否正确
-2. agentSecret 是否是应用 Secret（不是应用的 AgentId 数字）
-3. 企业微信 API 是否可访问
+`plugin.ts` 在 generation setup 注册 `src/platform-permit.ts` checker，并在 dispose 注销；CapabilityIngress 与 ToolSystem 统一经 Core `canAccessTool()` 消费工具权限。
 
 ## 相关链接
 
 - [企业微信开发文档](https://developer.work.weixin.qq.com/document/)
-- [企业微信接收消息](https://developer.work.weixin.qq.com/document/path/90930)
-- [企业微信发送应用消息](https://developer.work.weixin.qq.com/document/path/90236)
-- [Zhin.js 官方文档](https://github.com/zhinjs/zhin)
+- [接收消息](https://developer.work.weixin.qq.com/document/path/90930)
+- [发送应用消息](https://developer.work.weixin.qq.com/document/path/90236)
 
 ## 许可证
 

package/adapters/wecom.js

@@ -0,0 +1,34 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/wecom.ts` → defineAdapter.
+ * Implementation lives under `src/` (endpoint / webhook / protocol).
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { WecomEndpoint } from "../lib/endpoint.js";
+import { resolveWecomConfig, } from "../lib/protocol.js";
+import { wecomRuntimeStateToken } from "../lib/wecom-runtime-state.js";
+export { WecomEndpoint } from "../lib/endpoint.js";
+export default defineAdapter({
+    capabilities: ['inbound', 'outbound'],
+    operations: ['recall'],
+    // image 段全部经 /cgi-bin/media/upload 物化为 media_id（url 下载后上传、
+    // base64/path 直接上传、file 引用直用 media_id）；无卡片交互面，交互段降级纯文本。
+    segments: {
+        outboundMedia: ['upload'],
+        interactive: 'text',
+    },
+    create(context) {
+        const config = resolveWecomConfig(context.config);
+        // 注册到插件运行时状态（wecom.endpoint list 的"运行中"数据源）
+        context.use(wecomRuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
+            mode: 'webhook',
+        });
+        return new WecomEndpoint({
+            id: context.id,
+            http: context.use(httpHostToken),
+            config,
+        });
+    },
+});

package/adapters/wecom.ts

@@ -0,0 +1,39 @@
+/**
+ * Convention entry: discover `adapters/wecom.ts` → defineAdapter.
+ * Implementation lives under `src/` (endpoint / webhook / protocol).
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { WecomEndpoint } from '../src/endpoint.js';
+import {
+  resolveWecomConfig,
+  type WecomAdapterConfig,
+} from '../src/protocol.js';
+import { wecomRuntimeStateToken } from '../src/wecom-runtime-state.js';
+
+export { WecomEndpoint } from '../src/endpoint.js';
+export type { WecomEndpointOptions, WecomFetch } from '../src/endpoint.js';
+
+export default defineAdapter<WecomAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  operations: ['recall'],
+  // image 段全部经 /cgi-bin/media/upload 物化为 media_id（url 下载后上传、
+  // base64/path 直接上传、file 引用直用 media_id）；无卡片交互面，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['upload'],
+    interactive: 'text',
+  },
+  create(context) {
+    const config = resolveWecomConfig(context.config);
+    // 注册到插件运行时状态（wecom.endpoint list 的"运行中"数据源）
+    context.use(wecomRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
+      mode: 'webhook',
+    });
+    return new WecomEndpoint({
+      id: context.id,
+      http: context.use(httpHostToken),
+      config,
+    });
+  },
+});

package/{skills/wecom → agent}/PERMITS.md

@@ -16,4 +16,4 @@
 
 ## 工厂映射
 
-`group_admin` → `chat_admin` · `group_owner` → `chat_owner`
+`scene_admin` → `chat_admin` · `scene_owner` → `chat_owner`

package/agent/tools/get_dept_users.ts

@@ -0,0 +1,16 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+export default defineAgentTool<{ dept_id: string }>({
+  description: '获取企业微信部门用户列表',
+  inputSchema: z.object({
+    dept_id: z.string().describe('部门 ID'),
+  }),
+  adapter: 'wecom',
+  tags: ['wecom'],
+  async execute({ dept_id    }: { dept_id: string }, context) {
+    const endpoint = context.$client;
+    const users = await endpoint.getDepartmentUsers(Number(dept_id));
+    return { users, count: users.length };
+  },
+});
+

package/agent/tools/get_user.ts

@@ -0,0 +1,15 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+export default defineAgentTool<{ user_id: string }>({
+  description: '获取企业微信用户信息',
+  inputSchema: z.object({
+    user_id: z.string().describe('用户 ID'),
+  }),
+  adapter: 'wecom',
+  tags: ['wecom'],
+  async execute({ user_id    }: { user_id: string }, context) {
+    const endpoint = context.$client;
+    return await endpoint.getUserInfo(user_id);
+  },
+});
+

package/agent/tools/list_departments.ts

@@ -0,0 +1,16 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+export default defineAgentTool<{ dept_id?: string }>({
+  description: '获取企业微信部门列表',
+  inputSchema: z.object({
+    dept_id: z.string().optional().describe('父部门 ID，默认 1（根部门）'),
+  }),
+  adapter: 'wecom',
+  tags: ['wecom'],
+  async execute({ dept_id    }: { dept_id?: string }, context) {
+    const endpoint = context.$client;
+    const departments = await endpoint.getDepartmentList(Number(dept_id) || 1);
+    return { departments, count: departments.length };
+  },
+});
+

package/agent/tools/send_text.ts

@@ -0,0 +1,17 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+export default defineAgentTool<{ user_id: string; content: string }>({
+  description: '向指定企业微信用户发送文本消息',
+  inputSchema: z.object({
+    user_id: z.string().describe('用户 ID'),
+    content: z.string().describe('消息内容'),
+  }),
+  adapter: 'wecom',
+  tags: ['wecom'],
+  async execute({ user_id, content    }: { user_id: string; content: string }, context) {
+    const endpoint = context.$client;
+    const success = await endpoint.sendTextMessage(user_id, content);
+    return { success, message: success ? '消息已发送' : '发送失败' };
+  },
+});
+

package/commands/endpoint/add/[id].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { wecomEndpointCommands } from "../../../lib/wecom-endpoint-commands.js";
+export default wecomEndpointCommands.add;

package/commands/endpoint/add/[id].ts

@@ -0,0 +1,3 @@
+import { wecomEndpointCommands } from '../../../src/wecom-endpoint-commands.js';
+
+export default wecomEndpointCommands.add;

package/commands/endpoint/list.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { wecomEndpointCommands } from "../../lib/wecom-endpoint-commands.js";
+export default wecomEndpointCommands.list;

package/commands/endpoint/list.ts

@@ -0,0 +1,3 @@
+import { wecomEndpointCommands } from '../../src/wecom-endpoint-commands.js';
+
+export default wecomEndpointCommands.list;

package/commands/endpoint/remove/[id].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { wecomEndpointCommands } from "../../../lib/wecom-endpoint-commands.js";
+export default wecomEndpointCommands.remove;

package/commands/endpoint/remove/[id].ts

@@ -0,0 +1,3 @@
+import { wecomEndpointCommands } from '../../../src/wecom-endpoint-commands.js';
+
+export default wecomEndpointCommands.remove;

package/lib/client.d.ts

@@ -0,0 +1,12 @@
+import type { WecomClient } from './endpoint.js';
+import type { WecomMessage } from './protocol.js';
+export type WecomClientEventMap = Record<string, WecomMessage>;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly wecom: {
+            readonly client: WecomClient;
+            readonly events: WecomClientEventMap;
+        };
+    }
+}
+export declare const wecomClient: import("@zhin.js/adapter").EndpointClientToken<WecomClient, WecomClientEventMap>;

package/lib/client.js

@@ -0,0 +1,2 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+export const wecomClient = defineEndpointClient('wecom');

package/lib/endpoint.d.ts

@@ -1,43 +1,61 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
- * 企业微信 Endpoint 实现
+ * WecomEndpoint — lifecycle, outbound send, inbound admit, OpenAPI helpers for agent tools.
  */
-import { Endpoint, Message, type SendOptions } from 'zhin.js';
-import { type Router } from '@zhin.js/host-router/router';
-import type { WecomEndpointConfig, WecomMessage, WecomApiResponse } from './types.js';
-import type { WecomAdapter } from './adapter.js';
-export declare class WecomEndpoint implements Endpoint<WecomEndpointConfig, WecomMessage> {
-    #private;
-    adapter: WecomAdapter;
-    $config: WecomEndpointConfig;
-    $connected: boolean;
-    private router;
-    private accessToken;
-    private baseURL;
-    private aesKey;
-    private corpId;
-    get $id(): string;
-    get logger(): import("zhin.js").Logger;
-    constructor(adapter: WecomAdapter, router: Router, $config: WecomEndpointConfig);
-    private request;
-    private setupWebhookRoute;
-    private handleVerification;
-    private handleWebhook;
-    private verifySignature;
-    private decryptMessage;
-    private parseXmlMessage;
-    private handleMessage;
-    private ensureAccessToken;
-    private refreshAccessToken;
-    $formatMessage(msg: WecomMessage): Message<WecomMessage>;
-    private parseMessageContent;
-    $sendMessage(options: SendOptions): Promise<string>;
-    $recallMessage(_id: string): Promise<void>;
-    private formatSendContent;
-    $connect(): Promise<void>;
-    $disconnect(): Promise<void>;
-    getUserInfo(userId: string): Promise<WecomApiResponse | null>;
+import { type EndpointControl, type EndpointSendRequest } from 'zhin.js/adapter';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from 'zhin.js';
+import { type ResolvedWecomConfig, type WecomMessage } from './protocol.js';
+export type WecomFetch = (url: string, init?: {
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly body?: string | FormData;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+}>;
+export interface WecomEndpointOptions {
+    readonly id: CapabilityId;
+    readonly http: HttpHost;
+    readonly config: ResolvedWecomConfig;
+    readonly fetch?: WecomFetch;
+}
+export interface WecomClientApi {
+    getUserInfo(userId: string): Promise<unknown>;
     getDepartmentUsers(deptId: number): Promise<unknown[]>;
     getDepartmentList(deptId?: number): Promise<unknown[]>;
     sendTextMessage(userId: string, content: string): Promise<boolean>;
 }
-//# sourceMappingURL=endpoint.d.ts.map
+/** WeCom API surface exposed to plugin events without Endpoint lifecycle methods. */
+export declare class WecomClient implements WecomClientApi {
+    readonly api: WecomClientApi;
+    constructor(api: WecomClientApi);
+    getUserInfo: (userId: string) => Promise<unknown>;
+    getDepartmentUsers: (deptId: number) => Promise<unknown[]>;
+    getDepartmentList: (deptId?: number) => Promise<unknown[]>;
+    sendTextMessage: (userId: string, content: string) => Promise<boolean>;
+}
+/**
+ * 企业微信服务端 API 无 bot 群列表/群成员列表接口（客户群接口属「客户联系」
+ * 独立授权域，非 bot 社交面），好友/频道概念亦不存在；
+ * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
+ */
+export declare class WecomEndpoint extends Endpoint<WecomClient> {
+    #private;
+    readonly client: WecomClient;
+    readonly control: EndpointControl;
+    constructor(options: WecomEndpointOptions);
+    /** Used by webhook handler. */
+    get isOpen(): boolean;
+    get config(): ResolvedWecomConfig;
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    recallMessage(messageId: string): Promise<void>;
+    /** Test / internal: admit a parsed message when open (non-webhook path). */
+    admit(msg: WecomMessage): void;
+}