@zhin.js/adapter-wecom 0.0.1 → 1.1.0

package/lib/side-event-dispatch.js

@@ -0,0 +1,63 @@
+import { buildNotice, buildSystem, senderFromId } from '@zhin.js/core';
+import { formatCompact } from '@zhin.js/logger';
+import { resolveChatType } from './protocol.js';
+function mapWecomEventParts(eventName) {
+    switch (eventName) {
+        case 'subscribe':
+            return { scene_type: 'friend', sub_type: 'increase' };
+        case 'unsubscribe':
+            return { scene_type: 'friend', sub_type: 'decrease' };
+        case 'enter_agent':
+            return null;
+        default:
+            return { scene_type: 'wecom', sub_type: eventName || 'unknown' };
+    }
+}
+export function receiveWecomSideEvent(emit, endpointKey, configId, msg, logger) {
+    if (msg.MsgType !== 'event')
+        return false;
+    const eventName = msg.Event ?? 'unknown';
+    if (eventName === 'enter_agent') {
+        void emit('system.receive', buildSystem(msg, {
+            $id: `wecom:enter_agent:${msg.FromUserName}:${msg.CreateTime ?? Date.now()}`,
+            $adapter: 'wecom',
+            $endpoint: configId,
+            $type: 'system',
+            $scene_id: msg.FromUserName,
+            $scene_type: 'wecom',
+            $sub_type: 'enter_agent',
+            $timestamp: msg.CreateTime ?? Date.now(),
+        })).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'wecom_system_side_event_failed',
+                endpoint: configId,
+                event: eventName,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+        return true;
+    }
+    const parts = mapWecomEventParts(eventName);
+    if (!parts)
+        return false;
+    const sceneType = resolveChatType(msg.FromUserName);
+    void emit('notice.receive', buildNotice(msg, {
+        $id: `wecom:${eventName}:${msg.FromUserName}:${msg.CreateTime ?? Date.now()}`,
+        $adapter: 'wecom',
+        $endpoint: configId,
+        $type: 'notice',
+        $scene_id: msg.FromUserName,
+        $scene_type: parts.scene_type === 'friend' ? parts.scene_type : sceneType,
+        $sub_type: parts.sub_type,
+        $actor: senderFromId(msg.FromUserName),
+        $timestamp: msg.CreateTime ?? Date.now(),
+    })).catch((err) => {
+        logger.warn(formatCompact({
+            op: 'wecom_side_event_failed',
+            endpoint: configId,
+            event: eventName,
+            error: err instanceof Error ? err.message : String(err),
+        }));
+    });
+    return true;
+}

package/lib/webhook.d.ts

@@ -0,0 +1,14 @@
+/**
+ * WeCom webhook HTTP: URL verification (GET) + encrypted inbound (POST).
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { type ResolvedWecomConfig, type WecomMessage } from './protocol.js';
+export interface WecomWebhookHandler {
+    readonly config: ResolvedWecomConfig;
+    readonly isOpen: boolean;
+    admit(msg: WecomMessage): void;
+}
+export declare function registerWecomWebhookRoutes(http: HttpHost, handler: WecomWebhookHandler): HttpRouteRegistration[];
+export declare function handleWecomVerificationRequest(_request: IncomingMessage, response: ServerResponse, url: URL, handler: WecomWebhookHandler): void;
+export declare function handleWecomWebhookRequest(request: IncomingMessage, response: ServerResponse, url: URL, handler: WecomWebhookHandler): Promise<void>;

package/lib/webhook.js

@@ -0,0 +1,86 @@
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { decryptMessage, extractEncryptFromXml, normalizeEchostrParam, parseXmlMessage, queryParam, readTextBody, verifySignature, } from './protocol.js';
+const logger = getLogger('wecom');
+export function registerWecomWebhookRoutes(http, handler) {
+    const path = handler.config.webhookPath;
+    return [
+        http.route('GET', path, (request, response, url) => {
+            handleWecomVerificationRequest(request, response, url, handler);
+        }, { summary: 'WeCom URL verification', tags: ['wecom'] }),
+        http.route('POST', path, async (request, response, url) => {
+            await handleWecomWebhookRequest(request, response, url, handler);
+        }, { summary: 'WeCom inbound webhook', tags: ['wecom'] }),
+    ];
+}
+export function handleWecomVerificationRequest(_request, response, url, handler) {
+    try {
+        const msgSignature = queryParam(url.searchParams.get('msg_signature'));
+        const timestamp = queryParam(url.searchParams.get('timestamp'));
+        const nonce = queryParam(url.searchParams.get('nonce'));
+        const echostr = normalizeEchostrParam(queryParam(url.searchParams.get('echostr')));
+        const { token, encodingAESKey, corpId } = handler.config;
+        if (!msgSignature || !timestamp || !nonce || !echostr) {
+            response.writeHead(400, { 'Content-Type': 'text/plain' });
+            response.end('Missing required query parameters');
+            return;
+        }
+        if (!verifySignature(token, timestamp, nonce, echostr, msgSignature)) {
+            logger.warn(formatCompact({ op: 'verify', ok: false, error: 'invalid signature' }));
+            response.writeHead(403, { 'Content-Type': 'text/plain' });
+            response.end('Forbidden');
+            return;
+        }
+        const decrypted = decryptMessage(echostr, encodingAESKey, corpId);
+        if (!decrypted) {
+            response.writeHead(400, { 'Content-Type': 'text/plain' });
+            response.end('Decryption failed');
+            return;
+        }
+        response.writeHead(200, { 'Content-Type': 'text/plain' });
+        response.end(decrypted);
+    }
+    catch (error) {
+        logger.error('URL verification error:', error);
+        response.writeHead(500, { 'Content-Type': 'text/plain' });
+        response.end('Internal Server Error');
+    }
+}
+export async function handleWecomWebhookRequest(request, response, url, handler) {
+    try {
+        const msgSignature = queryParam(url.searchParams.get('msg_signature'));
+        const timestamp = queryParam(url.searchParams.get('timestamp'));
+        const nonce = queryParam(url.searchParams.get('nonce'));
+        const { token, encodingAESKey, corpId } = handler.config;
+        const rawBody = await readTextBody(request);
+        const encrypted = extractEncryptFromXml(rawBody);
+        if (!encrypted) {
+            logger.warn(formatCompact({ op: 'webhook', ok: false, error: 'no Encrypt field' }));
+            response.writeHead(200, { 'Content-Type': 'text/plain' });
+            response.end('success');
+            return;
+        }
+        if (!verifySignature(token, timestamp, nonce, encrypted, msgSignature)) {
+            logger.warn(formatCompact({ op: 'webhook', ok: false, error: 'invalid signature' }));
+            response.writeHead(403, { 'Content-Type': 'text/plain' });
+            response.end('Forbidden');
+            return;
+        }
+        const decryptedXml = decryptMessage(encrypted, encodingAESKey, corpId);
+        if (!decryptedXml) {
+            response.writeHead(200, { 'Content-Type': 'text/plain' });
+            response.end('success');
+            return;
+        }
+        const message = parseXmlMessage(decryptedXml);
+        if (message && handler.isOpen) {
+            handler.admit(message);
+        }
+        response.writeHead(200, { 'Content-Type': 'text/plain' });
+        response.end('success');
+    }
+    catch (error) {
+        logger.error('Webhook error:', error);
+        response.writeHead(200, { 'Content-Type': 'text/plain' });
+        response.end('success');
+    }
+}

package/lib/wecom-endpoint-commands.d.ts

@@ -0,0 +1 @@
+export declare const wecomEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage, string | undefined>>>;

package/lib/wecom-endpoint-commands.js

@@ -0,0 +1,19 @@
+/**
+ * `wecom.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { wecomRuntimeStateToken } from './wecom-runtime-state.js';
+export const wecomEndpointCommands = createEndpointCommands({
+    adapterKey: 'wecom',
+    adapterDisplayName: 'WeCom',
+    fields: [
+        { key: 'corpId', required: true, env: true, description: '企业 corpId' },
+        { key: 'agentSecret', required: true, env: true, description: '应用 secret' },
+        { key: 'token', required: true, env: true, description: '回调 token' },
+        { key: 'encodingAESKey', required: true, env: true, description: '回调加解密 key' },
+    ],
+    running: (use) => use(wecomRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => `corpId: ${String(entry.corpId)}`,
+}, defineCommand);

package/lib/wecom-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const wecomRuntimeStateToken: import("zhin.js").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/wecom-runtime-state.js

@@ -0,0 +1,6 @@
+/**
+ * WeCom 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `wecom.endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
+export const wecomRuntimeStateToken = defineEndpointRuntimeStateToken('wecom');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-wecom",
-  "version": "0.0.1",
-  "description": "Zhin.js adapter for WeCom (企业微信)",
+  "version": "1.1.0",
+  "description": "Zhin.js WeCom (企业微信) adapter for Plugin Runtime (HTTP webhook)",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -33,27 +33,54 @@
     "type": "git",
     "directory": "plugins/adapters/wecom"
   },
-  "devDependencies": {
-    "@types/koa": "^3.0.3",
-    "@types/node": "^25.9.2",
-    "typescript": "^6.0.3",
-    "@zhin.js/host-router": "1.0.1",
-    "zhin.js": "2.0.1"
+  "dependencies": {
+    "@zhin.js/adapter": "1.1.12",
+    "@zhin.js/core": "1.1.35",
+    "@zhin.js/feature-kit": "1.1.0",
+    "@zhin.js/host-http": "1.1.0",
+    "@zhin.js/im-contract": "1.1.0",
+    "@zhin.js/logger": "1.1.0"
   },
   "peerDependencies": {
-    "@zhin.js/host-router": "1.0.1",
-    "zhin.js": "2.0.1"
+    "zod": "^4.0.0",
+    "@zhin.js/adapter": "^1.1.12",
+    "@zhin.js/agent": "^1.1.23",
+    "@zhin.js/command": "^1.1.0",
+    "@zhin.js/core": "^1.1.35",
+    "@zhin.js/host-http": "^1.1.0",
+    "@zhin.js/permission": "^1.1.0",
+    "zhin.js": "^1.1.0"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/host-router": {
-      "optional": false
+    "@zhin.js/agent": {
+      "optional": true
+    },
+    "@zhin.js/command": {
+      "optional": true
+    },
+    "zhin.js": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3",
+    "@zhin.js/agent": "1.1.23",
+    "zhin.js": "1.1.0"
+  },
   "files": [
+    "adapters",
+    "commands",
+    "plugin.js",
+    "schema.json",
     "src",
     "lib",
-    "skills",
-    "plugin.yml",
+    "agent",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -61,9 +88,30 @@
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.js",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
-    "build": "pnpm build:node",
+    "build": "tsc",
     "clean": "rimraf lib",
-    "build:node": "tsc"
+    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/wecom/tests"
   }
 }

package/plugin.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { createEndpointRuntimeState } from 'zhin.js/adapter';
+import { definePlugin } from 'zhin.js';
+import { permissionHostToken } from '@zhin.js/permission';
+import { checkWecomPlatformPermit } from "./lib/platform-permit.js";
+import { wecomRuntimeStateToken } from "./lib/wecom-runtime-state.js";
+export default definePlugin({
+    name: 'wecom',
+    metadata: {
+        displayName: 'WeCom (企业微信) Adapter',
+    },
+    setup(context) {
+        context.resources.provide(wecomRuntimeStateToken, createEndpointRuntimeState());
+        if (context.resources.has(permissionHostToken)) {
+            const host = context.resources.use(permissionHostToken);
+            return host.registerPlatform('wecom', checkWecomPlatformPermit);
+        }
+    },
+});

package/schema.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "webhookPath": {
+      "type": "string",
+      "default": "/wecom/callback"
+    },
+    "apiBaseUrl": {
+      "type": "string",
+      "default": "https://qyapi.weixin.qq.com"
+    },
+    "master": {
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master（WeCom userid；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted WeCom userid"
+      },
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的框架 master（WeCom userid）；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted WeCom userid"
+            },
+            "description": "本 endpoint 的 trusted 列表"
+          },
+          "corpId": {
+            "type": "string",
+            "description": "WeCom corp ID"
+          },
+          "agentSecret": {
+            "type": "string",
+            "description": "WeCom agent secret"
+          },
+          "token": {
+            "type": "string",
+            "description": "WeCom callback token"
+          },
+          "encodingAESKey": {
+            "type": "string",
+            "description": "WeCom encoding AES key"
+          },
+          "id": {
+            "type": "string",
+            "description": "WeCom bot name"
+          }
+        },
+        "required": [
+          "id",
+          "corpId",
+          "agentSecret",
+          "token",
+          "encodingAESKey"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    }
+  },
+  "required": [
+    "endpoints"
+  ]
+}

package/src/client.ts

@@ -0,0 +1,16 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+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 const wecomClient = defineEndpointClient<WecomClient, WecomClientEventMap>('wecom');