@zhin.js/adapter-wecom 4.0.13 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @zhin.js/adapter-wecom
 
+## 5.0.0
+
+### Patch Changes
+
+- f2c532f: Expose exact per-Endpoint message operations through one validated Adapter capability model, route Core control calls through declared active capabilities, and connect existing recall, edit, reaction, and typing implementations across platform adapters.
+- Updated dependencies [b10d058]
+- Updated dependencies [f2c532f]
+- Updated dependencies [3dbf990]
+  - @zhin.js/host-http@1.0.12
+  - @zhin.js/adapter@1.2.0
+  - @zhin.js/core@1.5.13
+  - @zhin.js/agent@1.1.15
+  - zhin.js@6.0.13
+
+## 4.0.14
+
+### Patch Changes
+
+- 5969c5b: Add SideEventGateway so adapters forward notice/request/system into HandlerIndex. HandlerContext now exposes only generation-safe capabilities and prompt ports; live Endpoint escape hatches are removed.
+- Updated dependencies [5969c5b]
+- Updated dependencies [d336a3f]
+- Updated dependencies [0c82a7e]
+- Updated dependencies [b9217e4]
+- Updated dependencies [5969c5b]
+- Updated dependencies [5969c5b]
+- Updated dependencies [974772e]
+- Updated dependencies [5969c5b]
+- Updated dependencies [5969c5b]
+- Updated dependencies [2f786bd]
+- Updated dependencies [63d89f9]
+- Updated dependencies [71c7cdd]
+- Updated dependencies [3cca0ea]
+- Updated dependencies [1312ca0]
+- Updated dependencies [985fa22]
+- Updated dependencies [04b861d]
+- Updated dependencies [a23d544]
+- Updated dependencies [8cddabf]
+- Updated dependencies [dbe5081]
+  - @zhin.js/im-contract@1.0.4
+  - @zhin.js/core@1.5.12
+  - @zhin.js/adapter@1.1.11
+  - @zhin.js/agent@1.1.14
+  - @zhin.js/host-http@1.0.11
+  - @zhin.js/command@1.0.15
+  - zhin.js@6.0.12
+  - @zhin.js/permission@1.0.3
+
 ## 4.0.13
 
 ### Patch Changes

package/adapters/wecom.js

@@ -4,7 +4,7 @@
  * Implementation lives under `src/` (endpoint / webhook / protocol).
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { WecomEndpoint } from "../lib/endpoint.js";
 import { resolveWecomConfig, } from "../lib/protocol.js";
@@ -12,6 +12,7 @@ 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: {
@@ -28,6 +29,7 @@ export default defineAdapter({
         return new WecomEndpoint({
             id: context.id,
             gateway: context.use(messageGatewayToken),
+            sideEvents: context.use(sideEventGatewayToken),
             http: context.use(httpHostToken),
             config,
         });

package/adapters/wecom.ts

@@ -3,7 +3,7 @@
  * Implementation lives under `src/` (endpoint / webhook / protocol).
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { WecomEndpoint } from '../src/endpoint.js';
 import {
@@ -17,6 +17,7 @@ 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: {
@@ -33,6 +34,7 @@ export default defineAdapter<WecomAdapterConfig>({
     return new WecomEndpoint({
       id: context.id,
       gateway: context.use(messageGatewayToken),
+      sideEvents: context.use(sideEventGatewayToken),
       http: context.use(httpHostToken),
       config,
     });

package/lib/endpoint.d.ts

@@ -1,8 +1,8 @@
 /**
  * WecomEndpoint — lifecycle, outbound send, inbound admit, OpenAPI helpers for agent tools.
  */
-import type { EndpointInstance, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import { type EndpointControl, type EndpointInstance, type EndpointSendRequest } from 'zhin.js/adapter';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { type ResolvedWecomConfig, type WecomApiResponse, type WecomMessage } from './protocol.js';
@@ -19,6 +19,7 @@ export type WecomFetch = (url: string, init?: {
 export interface WecomEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
+    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: ResolvedWecomConfig;
     readonly fetch?: WecomFetch;
@@ -30,6 +31,7 @@ export interface WecomEndpointOptions {
  */
 export declare class WecomEndpoint implements EndpointInstance {
     #private;
+    readonly control: EndpointControl;
     constructor(options: WecomEndpointOptions);
     /** Used by webhook handler. */
     get isOpen(): boolean;

package/lib/endpoint.js

@@ -1,8 +1,13 @@
+/**
+ * WecomEndpoint — lifecycle, outbound send, inbound admit, OpenAPI helpers for agent tools.
+ */
+import { createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { registerWecomAgentEndpoint } from './wecom-agent-deps.js';
 import { buildMediaUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
 import { buildSendRequestBody, formatInboundContent, formatOutboundBody, resolveChatType, wecomInboundConversation, } from './protocol.js';
 import { registerWecomWebhookRoutes } from './webhook.js';
+import { receiveWecomSideEvent } from './side-event-dispatch.js';
 /**
  * 企业微信服务端 API 无 bot 群列表/群成员列表接口（客户群接口属「客户联系」
  * 独立授权域，非 bot 社交面），好友/频道概念亦不存在；
@@ -11,6 +16,7 @@ import { registerWecomWebhookRoutes } from './webhook.js';
 export class WecomEndpoint {
     #logger;
     #options;
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
     #fetch;
     #routeReleases = [];
     #accessToken = { access_token: '', expires_in: 0, timestamp: 0 };
@@ -151,6 +157,9 @@ export class WecomEndpoint {
     admit(msg) {
         if (!this.#open)
             return;
+        if (receiveWecomSideEvent(this.#options.sideEvents, String(this.#options.id), this.#options.config.id, msg, this.#logger)) {
+            return;
+        }
         const chatType = resolveChatType(msg.FromUserName);
         const conversation = wecomInboundConversation(String(this.#options.id), msg);
         void this.#options.gateway.receive({

package/lib/side-event-dispatch.d.ts

@@ -0,0 +1,4 @@
+import type { SideEventGateway } from '@zhin.js/core/runtime';
+import { type getAdapterLogger } from '@zhin.js/logger';
+import { type WecomMessage } from './protocol.js';
+export declare function receiveWecomSideEvent(sideEvents: SideEventGateway | undefined, endpointKey: string, configId: string, msg: WecomMessage, logger: ReturnType<typeof getAdapterLogger>): boolean;

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(sideEvents, endpointKey, configId, msg, logger) {
+    if (!sideEvents || msg.MsgType !== 'event')
+        return false;
+    const eventName = msg.Event ?? 'unknown';
+    if (eventName === 'enter_agent') {
+        void sideEvents.receiveSystem(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 sideEvents.receiveNotice(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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-wecom",
-  "version": "4.0.13",
+  "version": "5.0.0",
   "description": "Zhin.js WeCom (企业微信) adapter for Plugin Runtime (HTTP webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,21 +34,21 @@
     "directory": "plugins/adapters/wecom"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/core": "1.5.11",
-    "@zhin.js/host-http": "1.0.10",
-    "@zhin.js/im-contract": "1.0.3",
+    "@zhin.js/adapter": "1.2.0",
+    "@zhin.js/core": "1.5.13",
+    "@zhin.js/host-http": "1.0.12",
+    "@zhin.js/im-contract": "1.0.4",
     "@zhin.js/logger": "1.0.76"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/agent": "1.1.13",
-    "@zhin.js/command": "1.0.14",
-    "@zhin.js/core": "1.5.11",
-    "@zhin.js/host-http": "1.0.10",
-    "@zhin.js/permission": "1.0.2",
-    "zhin.js": "6.0.11"
+    "@zhin.js/adapter": "1.2.0",
+    "@zhin.js/agent": "1.1.15",
+    "@zhin.js/command": "1.0.15",
+    "@zhin.js/core": "1.5.13",
+    "@zhin.js/host-http": "1.0.12",
+    "@zhin.js/permission": "1.0.3",
+    "zhin.js": "6.0.13"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {
@@ -69,8 +69,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.13",
-    "zhin.js": "6.0.11"
+    "@zhin.js/agent": "1.1.15",
+    "zhin.js": "6.0.13"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -1,8 +1,13 @@
 /**
  * WecomEndpoint — lifecycle, outbound send, inbound admit, OpenAPI helpers for agent tools.
  */
-import type { EndpointInstance, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import {
+  createRecallEndpointControl,
+  type EndpointControl,
+  type EndpointInstance,
+  type EndpointSendRequest,
+} from 'zhin.js/adapter';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -25,6 +30,7 @@ import {
   type WecomMessage,
 } from './protocol.js';
 import { registerWecomWebhookRoutes } from './webhook.js';
+import { receiveWecomSideEvent } from './side-event-dispatch.js';
 
 export type WecomFetch = (
   url: string,
@@ -43,6 +49,7 @@ export type WecomFetch = (
 export interface WecomEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
+  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly config: ResolvedWecomConfig;
   readonly fetch?: WecomFetch;
@@ -57,6 +64,7 @@ export class WecomEndpoint implements EndpointInstance {
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: WecomEndpointOptions;
+  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
   readonly #fetch: WecomFetch;
   #routeReleases: HttpRouteRegistration[] = [];
   #accessToken: AccessToken = { access_token: '', expires_in: 0, timestamp: 0 };
@@ -202,6 +210,15 @@ export class WecomEndpoint implements EndpointInstance {
   /** Test / internal: admit a parsed message when open (non-webhook path). */
   admit(msg: WecomMessage): void {
     if (!this.#open) return;
+    if (receiveWecomSideEvent(
+      this.#options.sideEvents,
+      String(this.#options.id),
+      this.#options.config.id,
+      msg,
+      this.#logger,
+    )) {
+      return;
+    }
     const chatType = resolveChatType(msg.FromUserName);
     const conversation = wecomInboundConversation(String(this.#options.id), msg);
     void this.#options.gateway.receive({

package/src/side-event-dispatch.ts

@@ -0,0 +1,70 @@
+import { buildNotice, buildSystem, senderFromId } from '@zhin.js/core';
+import type { SideEventGateway } from '@zhin.js/core/runtime';
+import { formatCompact, type getAdapterLogger } from '@zhin.js/logger';
+import { resolveChatType, type WecomMessage } from './protocol.js';
+
+function mapWecomEventParts(eventName: string): { scene_type: string; sub_type: string } | null {
+  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(
+  sideEvents: SideEventGateway | undefined,
+  endpointKey: string,
+  configId: string,
+  msg: WecomMessage,
+  logger: ReturnType<typeof getAdapterLogger>,
+): boolean {
+  if (!sideEvents || msg.MsgType !== 'event') return false;
+  const eventName = msg.Event ?? 'unknown';
+  if (eventName === 'enter_agent') {
+    void sideEvents.receiveSystem(buildSystem(msg, {
+      $id: `wecom:enter_agent:${msg.FromUserName}:${msg.CreateTime ?? Date.now()}`,
+      $adapter: 'wecom' as never,
+      $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 sideEvents.receiveNotice(buildNotice(msg, {
+    $id: `wecom:${eventName}:${msg.FromUserName}:${msg.CreateTime ?? Date.now()}`,
+    $adapter: 'wecom' as never,
+    $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;
+}