@zhin.js/adapter-wechat-mp 5.0.1 → 5.0.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @zhin.js/adapter-wechat-mp
 
+## 5.0.2
+
+### Patch Changes
+
+- Updated dependencies [afc0e66]
+- Updated dependencies [2e41ad5]
+- Updated dependencies [9f57124]
+  - @zhin.js/core@1.5.2
+  - @zhin.js/adapter@1.1.5
+  - @zhin.js/im-contract@1.0.1
+  - @zhin.js/plugin-runtime@1.1.3
+  - @zhin.js/command@1.0.7
+  - @zhin.js/host-http@1.0.6
+  - zhin.js@6.0.2
+
 ## 5.0.1
 
 ### Patch Changes

package/README.md

@@ -24,8 +24,8 @@ pnpm add @zhin.js/adapter-wechat-mp
 - `@zhin.js/plugin-runtime` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 
-入站：`gateway.receive({ adapter, target: openid, content: text, sender, metadata })`  
-出站：`send({ target, payload })` → 被动回复 XML（默认）或客服消息 API（`replyMode: customer_service`）
+入站：`gateway.receive({ conversation: { endpoint, kind: 'private', id: openid }, message: { conversation, id }, content: text, sender, metadata })`  
+出站：`send({ conversation, payload })` → 被动回复 XML（默认）或客服消息 API（`replyMode: customer_service`）
 
 ## 前置条件
 

package/lib/endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointFriend, EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type { EndpointFriend, EndpointInstance, EndpointManagement, EndpointSendRequest } 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';
@@ -33,10 +33,7 @@ export declare class WeChatMpEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     /** Test / internal: admit a parsed message when open (non-webhook path). */
     admit(msg: WeChatMessage): void;
     /**

package/lib/endpoint.js

@@ -3,7 +3,7 @@
  */
 import axios from 'axios';
 import { formatCompact, getLogger } from '@zhin.js/logger';
-import { extractOutboundText, formatCustomerServiceBody, formatInboundContent, formatInboundId, } from './protocol.js';
+import { extractOutboundText, formatCustomerServiceBody, formatInboundContent, formatInboundId, wechatMpInboundConversation, } from './protocol.js';
 import { buildMediaUploadForm, readOutboundMedia, resolveMediaBinary, } from './media-upload.js';
 import { getPassiveReplyCapture, recordPassiveReplyText, } from './passive-reply.js';
 import { registerWeChatMpWebhookRoutes } from './webhook.js';
@@ -110,20 +110,20 @@ export class WeChatMpEndpoint {
         this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         if (getPassiveReplyCapture()) {
             const text = extractOutboundText(payload);
             recordPassiveReplyText(text);
             return `passive_${Date.now()}`;
         }
         if (this.#options.config.replyMode === 'customer_service') {
-            return this.#sendCustomerService(target, payload);
+            return this.#sendCustomerService(conversation.id, payload);
         }
         logger.warn(formatCompact({
             op: 'send',
             skip: 'passive_outside_webhook',
             endpoint: this.#options.config.name,
-            target,
+            target: `${conversation.kind}:${conversation.id}`,
         }));
         return `passive_skipped_${Date.now()}`;
     }
@@ -131,12 +131,12 @@ export class WeChatMpEndpoint {
     admit(msg) {
         if (!this.#open)
             return;
+        const conversation = wechatMpInboundConversation(String(this.#options.id), msg);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target: msg.FromUserName,
+            conversation,
+            message: { conversation, id: formatInboundId(msg) },
             content: formatInboundContent(msg),
             sender: msg.FromUserName,
-            id: formatInboundId(msg),
             metadata: Object.freeze({
                 msgType: msg.MsgType,
                 event: msg.Event,
@@ -146,7 +146,7 @@ export class WeChatMpEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'wechat_mp_gateway_receive_failed',
-                target: msg.FromUserName,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });

package/lib/protocol.d.ts

@@ -3,6 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import type { IncomingMessage } from 'node:http';
+import type { ConversationRef } from '@zhin.js/im-contract';
 export interface WeChatMpAdapterConfig {
     readonly name?: string;
     readonly appId?: string;
@@ -101,6 +102,11 @@ export declare function parseXMLMessage(xmlString: string): Promise<WeChatMessag
 export declare function decryptMessage(encryptedXml: string, msgSignature: string, timestamp: string, nonce: string, token: string, encodingAESKey: string, appId: string): Promise<string>;
 export declare function encryptMessage(replyXml: string, token: string, encodingAESKey: string, appId: string, requestTimestamp?: string): string;
 export declare function buildTextReply(wechatMsg: Pick<WeChatMessage, 'FromUserName' | 'ToUserName'>, content: string): string;
+/**
+ * 入站归一化：公众号只有粉丝单聊场景，一律 kind='private'，id=openid（FromUserName），
+ * 无群/频道容器（parent 恒缺省）。
+ */
+export declare function wechatMpInboundConversation(endpointId: string, msg: WeChatMessage): ConversationRef;
 /**
  * 入站消息 id：普通消息用 MsgId；无 MsgId 的事件消息拼 Event/EventKey，
  * 避免只用秒级 CreateTime 时同秒多事件 id 碰撞。

package/lib/protocol.js

@@ -170,6 +170,17 @@ export function buildTextReply(wechatMsg, content) {
         '</xml>',
     ].join('');
 }
+/**
+ * 入站归一化：公众号只有粉丝单聊场景，一律 kind='private'，id=openid（FromUserName），
+ * 无群/频道容器（parent 恒缺省）。
+ */
+export function wechatMpInboundConversation(endpointId, msg) {
+    return {
+        endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+        kind: 'private',
+        id: msg.FromUserName,
+    };
+}
 /**
  * 入站消息 id：普通消息用 MsgId；无 MsgId 的事件消息拼 Event/EventKey，
  * 避免只用秒级 CreateTime 时同秒多事件 id 碰撞。

package/lib/webhook.js

@@ -1,6 +1,6 @@
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { getPassiveReplyCapture, runWithPassiveReplyCapture, } from './passive-reply.js';
-import { buildTextReply, computeSignatureHash, decryptEchostr, decryptMessage, encryptMessage, formatInboundContent, formatInboundId, isEncryptedEchostr, normalizeEchostrParam, parseXMLMessage, queryParam, readTextBody, resolveEventPassiveReply, verifySignature, } from './protocol.js';
+import { buildTextReply, computeSignatureHash, decryptEchostr, decryptMessage, encryptMessage, formatInboundContent, formatInboundId, isEncryptedEchostr, normalizeEchostrParam, parseXMLMessage, queryParam, readTextBody, resolveEventPassiveReply, verifySignature, wechatMpInboundConversation, } from './protocol.js';
 const logger = getLogger('wechat-mp');
 export function registerWeChatMpWebhookRoutes(http, handler) {
     const path = handler.config.path;
@@ -132,13 +132,13 @@ export async function handleWeChatMpMessage(request, response, url, handler) {
 export async function collectPassiveReply(handler, wechatMsg) {
     const timeoutMs = handler.config.passiveReplyTimeoutMs;
     const text = await runWithPassiveReplyCapture(async () => {
+        const conversation = wechatMpInboundConversation(String(handler.id), wechatMsg);
         await Promise.race([
             handler.gateway.receive({
-                adapter: handler.id,
-                target: wechatMsg.FromUserName,
+                conversation,
+                message: { conversation, id: formatInboundId(wechatMsg) },
                 content: formatInboundContent(wechatMsg),
                 sender: wechatMsg.FromUserName,
-                id: formatInboundId(wechatMsg),
                 metadata: Object.freeze({
                     msgType: wechatMsg.MsgType,
                     event: wechatMsg.Event,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-wechat-mp",
-  "version": "5.0.1",
+  "version": "5.0.2",
   "type": "module",
   "description": "Zhin.js WeChat Official Account adapter for Plugin Runtime (HTTP webhook)",
   "main": "./lib/index.js",
@@ -8,19 +8,20 @@
   "dependencies": {
     "axios": "^1.19.0",
     "xml2js": "^0.6.2",
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/command": "1.0.6",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/host-http": "1.0.5",
+    "@zhin.js/adapter": "1.1.5",
+    "@zhin.js/command": "1.0.7",
+    "@zhin.js/core": "1.5.2",
+    "@zhin.js/host-http": "1.0.6",
+    "@zhin.js/im-contract": "1.0.1",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.2"
+    "@zhin.js/plugin-runtime": "1.1.3"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/host-http": "1.0.5",
-    "@zhin.js/plugin-runtime": "1.1.2",
-    "zhin.js": "6.0.1"
+    "@zhin.js/adapter": "1.1.5",
+    "@zhin.js/core": "1.5.2",
+    "@zhin.js/host-http": "1.0.6",
+    "@zhin.js/plugin-runtime": "1.1.3",
+    "zhin.js": "6.0.2"
   },
   "peerDependenciesMeta": {
     "zhin.js": {

package/src/endpoint.ts

@@ -2,7 +2,7 @@
  * WeChatMpEndpoint — lifecycle, outbound, admit, access token refresh.
  */
 import axios from 'axios';
-import type { EndpointFriend, EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type { EndpointFriend, EndpointInstance, EndpointManagement, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -12,6 +12,7 @@ import {
   formatCustomerServiceBody,
   formatInboundContent,
   formatInboundId,
+  wechatMpInboundConversation,
   type ResolvedWeChatMpConfig,
   type TokenResponse,
   type WeChatAPIResponse,
@@ -159,7 +160,7 @@ export class WeChatMpEndpoint implements EndpointInstance {
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     if (getPassiveReplyCapture()) {
       const text = extractOutboundText(payload);
       recordPassiveReplyText(text);
@@ -167,14 +168,14 @@ export class WeChatMpEndpoint implements EndpointInstance {
     }
 
     if (this.#options.config.replyMode === 'customer_service') {
-      return this.#sendCustomerService(target, payload);
+      return this.#sendCustomerService(conversation.id, payload);
     }
 
     logger.warn(formatCompact({
       op: 'send',
       skip: 'passive_outside_webhook',
       endpoint: this.#options.config.name,
-      target,
+      target: `${conversation.kind}:${conversation.id}`,
     }));
     return `passive_skipped_${Date.now()}`;
   }
@@ -182,12 +183,12 @@ export class WeChatMpEndpoint implements EndpointInstance {
   /** Test / internal: admit a parsed message when open (non-webhook path). */
   admit(msg: WeChatMessage): void {
     if (!this.#open) return;
+    const conversation = wechatMpInboundConversation(String(this.#options.id), msg);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target: msg.FromUserName,
+      conversation,
+      message: { conversation, id: formatInboundId(msg) },
       content: formatInboundContent(msg),
       sender: msg.FromUserName,
-      id: formatInboundId(msg),
       metadata: Object.freeze({
         msgType: msg.MsgType,
         event: msg.Event,
@@ -197,7 +198,7 @@ export class WeChatMpEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'wechat_mp_gateway_receive_failed',
-        target: msg.FromUserName,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });

package/src/protocol.ts

@@ -6,6 +6,7 @@
 import { createHash, createDecipheriv, createCipheriv, randomBytes } from 'node:crypto';
 import type { IncomingMessage } from 'node:http';
 import * as xml2js from 'xml2js';
+import type { ConversationRef } from '@zhin.js/im-contract';
 
 export interface WeChatMpAdapterConfig {
   readonly name?: string;
@@ -310,6 +311,21 @@ export function buildTextReply(
   ].join('');
 }
 
+/**
+ * 入站归一化：公众号只有粉丝单聊场景，一律 kind='private'，id=openid（FromUserName），
+ * 无群/频道容器（parent 恒缺省）。
+ */
+export function wechatMpInboundConversation(
+  endpointId: string,
+  msg: WeChatMessage,
+): ConversationRef {
+  return {
+    endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+    kind: 'private',
+    id: msg.FromUserName,
+  };
+}
+
 /**
  * 入站消息 id：普通消息用 MsgId；无 MsgId 的事件消息拼 Event/EventKey，
  * 避免只用秒级 CreateTime 时同秒多事件 id 碰撞。

package/src/webhook.ts

@@ -25,6 +25,7 @@ import {
   readTextBody,
   resolveEventPassiveReply,
   verifySignature,
+  wechatMpInboundConversation,
   type ResolvedWeChatMpConfig,
   type WeChatMessage,
 } from './protocol.js';
@@ -218,13 +219,13 @@ export async function collectPassiveReply(
 ): Promise<string> {
   const timeoutMs = handler.config.passiveReplyTimeoutMs;
   const text = await runWithPassiveReplyCapture(async () => {
+    const conversation = wechatMpInboundConversation(String(handler.id), wechatMsg);
     await Promise.race([
       handler.gateway.receive({
-        adapter: handler.id,
-        target: wechatMsg.FromUserName,
+        conversation,
+        message: { conversation, id: formatInboundId(wechatMsg) },
         content: formatInboundContent(wechatMsg),
         sender: wechatMsg.FromUserName,
-        id: formatInboundId(wechatMsg),
         metadata: Object.freeze({
           msgType: wechatMsg.MsgType,
           event: wechatMsg.Event,