@zhin.js/adapter-wechat-mp 1.1.18 → 1.1.20

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @zhin.js/adapter-wechat-mp
 
+## 1.1.20
+
+### Patch Changes
+
+- Updated dependencies [5e878ba]
+  - @zhin.js/page@1.1.12
+
+## 1.1.19
+
+### Patch Changes
+
+- 2c3610a: Move account lifecycle ownership into the generic Adapter base and let native Endpoints retain their SDK Client inheritance. Infer platform-specific operation Sessions from a single adapter registry while preserving command parameter, option, configuration and factory inference.
+
+  Bind message replies, management ports, login challenges and Agent cancellation to the captured account incarnation. Persist runtime account intent with encrypted, revision-checked Host storage; keep account management independent of Root process restarts. Require explicit operator confirmation before importing existing accounts, and give replacement accounts a new identity without inheriting previous Sessions.
+
+  Expose account save, start, stop, update and replacement through the existing adapter Console, with exact account ownership, truthful pending/unknown outcomes and no startup configuration or environment-file rewrites.
+
+  Complete the target migration across every adapter, the public authoring API, generators, examples and Console. This intentionally removes the old create factory, inheritable Endpoint/ClientEndpoint classes, Client descriptors and file-rewrite account management; plugin authors must use createAdapter, native Client inheritance and the single AdapterRegistry. Satori and OneBot12 require explicit platform/userId selection, and WeCom requires a separate agentId.
+
+  Verify opaque credential changes before the same configuration snapshot is committed. Drain admitted native callbacks across close/rollback, cancel target work on stop, and keep raw transport parsing, platform ACK timing and SDK native methods under their existing owners. Account metadata conceals credentials carried in URLs.
+
+- a9f4e48: PATCH COMPATIBILITY CUTOVER: this batch intentionally changes plugin APIs. The maintainer explicitly chose patch releases with declared version boundaries. Upgrade the complete tested dependency set; patch numbering does not promise compatibility with the removed interfaces.
+
+  The first planned floors are zhin.js 1.1.19, Core 1.1.54, Adapter 1.1.26, FeatureKit 1.1.10, Plugin Runtime 1.1.18, Runtime/Isolate 1.1.16 and Agent 1.1.45. Keep old-interface plugins with the earlier locked stack until they are migrated. Adapter's independent Feature API changes from 1.0.0 to 2.0.0; official consumers declare ^2.0.0. Existing Feature API admission rejects explicitly incompatible ranges; omitted API metadata keeps its existing behavior and does not certify compatibility. Runtime engine and patch-only release gates remain unchanged.
+
+  Use the native-Client Adapter target contract, canonical FeatureKit AdapterRegistry augmentation and named Endpoint control/management requests. Route message controls from canonical message/conversation refs; retain exact source authority and propagate caller/account/explicit-Root-stop cancellation. Replace removed Agent activity feedback exports with source-bound feedback. HMR pause/resume belongs to concrete plugin instances; plugins choose accepted-work policy without changing Controller commit/rollback authority. Cooperative worker/process control cancellation does not kill an isolate or reopen retired business admission.
+
+  Provide authenticated historical-data preview, exact selected binding, transactional application, authoritative inspection and explicit resumption, including active games. Preserve before-images and journals; never replay an unconfirmed effect, infer an account from an alias, or reuse historical permission grants. Owner V2 approvals remain inactive legacy data, while new writes use V3. Rollback requires matching software, lockfile and verified data; installing old code alone cannot read a new V3 approval file. Conflicting after-images are never overwritten.
+
+  See docs/plans/adapter-operation-version-boundaries.md and the Chinese/English upgrade guide for the complete version inventory, custom-plugin changes, acceptance and recovery sequence. These code and metadata changes do not authorize merging, publication, deployment, login, production migration or removal of installed workspace patches.
+
+- Updated dependencies [2c3610a]
+- Updated dependencies [a9f4e48]
+- Updated dependencies [f8505b0]
+- Updated dependencies [2c3610a]
+  - @zhin.js/adapter@1.1.26
+  - @zhin.js/feature-kit@1.1.10
+  - @zhin.js/core@1.1.54
+  - @zhin.js/host-http@1.1.12
+  - @zhin.js/client@1.1.22
+  - @zhin.js/page@1.1.11
+  - @zhin.js/skill@1.1.11
+
 ## 1.1.18
 
 ### Patch Changes

package/README.md

@@ -18,13 +18,16 @@ pnpm add @zhin.js/adapter-wechat-mp
 
 ## Plugin Runtime
 
+`WeChatMpEndpoint` 的 Client 实际拥有 axios API、Token 与签名/加密 Webhook；原始 XML 保留。框架生命周期只经 `endpointSpec` 接入。所属 `Adapter` 是账号期望状态与运行实例的唯一管理者，目录按实际内部身份路由。
+
 - `@zhin.js/adapter` — 约定式 `adapters/wechat-mp/index.ts`（`defineAdapter`）
-- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `@zhin.js/core` — `endpointSpec.events` 入站、`outboundMessageToken` 出站
 - `@zhin.js/host-http` — `httpHostToken` 注册 Webhook 路由（**非** legacy host-router/Koa）
 - `zhin.js` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到顶层 `<instanceKey>`
 
-入站：`gateway.receive({ conversation: { endpoint, kind: 'private', id: openid }, message: { conversation, id }, content: text, sender, metadata })`  
+入站：`endpoint[endpointSpec].events.emit('message.receive', { conversation: { endpoint, kind: 'private', id: openid }, message: { conversation, id }, content: text, sender, metadata })`
+
 出站：`send({ conversation, payload })` → 被动回复 XML（默认）或客服消息 API（`replyMode: customer_service`）
 
 ## 前置条件
@@ -77,13 +80,11 @@ Runtime Host（`http`）须已 listen，Webhook 才可达。
 
 ## Console 页面
 
-启动后打开 Console 的「微信公众号」页（地址 `/wechat-mp`），可以：
+在所属插件的 Console 页面管理账号：查看配置与运行状态，添加、编辑、启动、停止、替换或删除账号。首次修改启动账号前，管理员需确认迁移清单；保留原身份与历史。此后保存到 Host 运行时存储，不改启动配置或 `.env`，无需重启进程。
 
-- 查看运行中的连接、点「测试连接」做连通性诊断；
-- 增删 `plugins.wechat-mp.endpoints`（凭据写入 `.env`，配置里只保留 `${ENV}` 引用）；
-- 如果适配器要求登录，页面会显示 LoginAssist 的扫码 / 滑块 / 设备确认待办；
+新增仅保存，需手动启动；运行账号的普通配置更新只重连该账号。身份变化走明确替换，新账号不会继承旧 Session 或登录状态。账号凭据变化先按平台实际只读接口核验；平台无法核验时需明确替换。空白或遮蔽的密码不会覆盖既有密码。
 
-读取需要 `wechat-mp:read`，写操作需要 `wechat-mp:write`；管理员 full token 不受限。页面里的「添加 endpoint」等价于原来的 `wechat-mp endpoint add`。
+读取需要 `wechat-mp:read`，写入需要 `wechat-mp:write`；首次迁移还需管理员身份。无持久化存储时管理操作不可用，提交结果未知时先刷新核实，不重复提交。
 
 ## 故障排查
 

package/adapters/wechat-mp/index.js

@@ -1,12 +1,10 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { WeChatMpAdapter } from "../../lib/adapter.js";
 /**
  * Convention entry: discover `adapters/wechat-mp/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { httpHostToken } from '@zhin.js/host-http';
-import { WeChatMpEndpoint } from "../../lib/endpoint.js";
-import { resolveWeChatMpConfig, } from "../../lib/protocol.js";
-import { wechatMpRuntimeStateToken } from "../../lib/wechat-mp-runtime-state.js";
+import {} from "../../lib/protocol.js";
 export { WeChatMpEndpoint } from "../../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
@@ -16,17 +14,5 @@ export default defineAdapter({
         outboundMedia: ['upload'],
         interactive: 'text',
     },
-    create(context) {
-        const config = resolveWeChatMpConfig(context.config);
-        // 注册到插件运行时状态（wechat-mp endpoint list 的"运行中"数据源）
-        context.use(wechatMpRuntimeStateToken).endpoints.set(config.id, {
-            id: config.id,
-            mode: 'webhook',
-        });
-        return new WeChatMpEndpoint({
-            id: context.id,
-            http: context.use(httpHostToken),
-            config,
-        });
-    },
+    createAdapter: context => new WeChatMpAdapter(context),
 });

package/adapters/wechat-mp/index.ts

@@ -1,14 +1,11 @@
+import { WeChatMpAdapter } from '../../src/adapter.js';
 /**
  * Convention entry: discover `adapters/wechat-mp/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { httpHostToken } from '@zhin.js/host-http';
-import { WeChatMpEndpoint } from '../../src/endpoint.js';
 import {
-  resolveWeChatMpConfig,
   type WeChatMpEndpointConfig,
 } from '../../src/protocol.js';
-import { wechatMpRuntimeStateToken } from '../../src/wechat-mp-runtime-state.js';
 
 export { WeChatMpEndpoint } from '../../src/endpoint.js';
 export type { WeChatMpEndpointOptions } from '../../src/endpoint.js';
@@ -22,17 +19,5 @@ export default defineAdapter<WeChatMpEndpointConfig>({
     outboundMedia: ['upload'],
     interactive: 'text',
   },
-  create(context) {
-    const config = resolveWeChatMpConfig(context.config);
-    // 注册到插件运行时状态（wechat-mp endpoint list 的"运行中"数据源）
-    context.use(wechatMpRuntimeStateToken).endpoints.set(config.id, {
-      id: config.id,
-      mode: 'webhook',
-    });
-    return new WeChatMpEndpoint({
-      id: context.id,
-      http: context.use(httpHostToken),
-      config,
-    });
-  },
+  createAdapter: context => new WeChatMpAdapter(context),
 });

package/commands/wechat-mp/endpoint/definition.js

@@ -5,7 +5,6 @@
  */
 import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { wechatMpRuntimeStateToken } from "../../../lib/wechat-mp-runtime-state.js";
 export const wechatMpEndpointCommands = createEndpointCommands({
     adapterKey: 'wechat-mp',
     adapterDisplayName: 'WeChat MP',
@@ -15,6 +14,5 @@ export const wechatMpEndpointCommands = createEndpointCommands({
         { key: 'token', required: true, env: true, description: '服务器配置 token', descriptionI18n: { en: "Server configuration token" } },
         { key: 'encodingAESKey', env: true, description: '消息加解密 key', descriptionI18n: { en: "Message encryption key" } },
     ],
-    running: (use) => use(wechatMpRuntimeStateToken).endpoints.values(),
     describeEntry: (entry) => `appId: ${String(entry.appId)}`,
 }, defineCommand);

package/commands/wechat-mp/endpoint/definition.ts

@@ -4,7 +4,6 @@
  */
 import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { wechatMpRuntimeStateToken } from '../../../src/wechat-mp-runtime-state.js';
 
 export const wechatMpEndpointCommands = createEndpointCommands({
   adapterKey: 'wechat-mp',
@@ -15,6 +14,5 @@ export const wechatMpEndpointCommands = createEndpointCommands({
     { key: 'token', required: true, env: true, description: '服务器配置 token', descriptionI18n: { en: "Server configuration token" } },
     { key: 'encodingAESKey', env: true, description: '消息加解密 key', descriptionI18n: { en: "Message encryption key" } },
   ],
-  running: (use) => use(wechatMpRuntimeStateToken).endpoints.values(),
   describeEntry: (entry) => `appId: ${String(entry.appId)}`,
 }, defineCommand);

package/lib/adapter.d.ts

@@ -0,0 +1,18 @@
+import { Adapter, type AdapterContext, type EndpointCreationContext } from 'zhin.js/adapter';
+import { WeChatMpEndpoint } from './endpoint.js';
+import { type WeChatMpEndpointConfig } from './protocol.js';
+import type { WeChatMpClientEventMap } from './client.js';
+export declare class WeChatMpAdapter extends Adapter<WeChatMpEndpoint, WeChatMpEndpointConfig, WeChatMpClientEventMap> {
+    #private;
+    constructor(context: AdapterContext<WeChatMpEndpointConfig>);
+    get configurationIdentityFields(): readonly string[];
+    get configurationUpdateFields(): readonly string[];
+    get configurationIdentityProbeFields(): readonly string[];
+    protected validateConfiguration(config: WeChatMpEndpointConfig): void;
+    protected createEndpoint(input: WeChatMpEndpointConfig, execution: EndpointCreationContext): WeChatMpEndpoint;
+}
+declare module '@zhin.js/feature-kit' {
+    interface AdapterRegistry {
+        readonly 'wechat-mp': WeChatMpAdapter;
+    }
+}

package/lib/adapter.js

@@ -0,0 +1,16 @@
+import { Adapter } from 'zhin.js/adapter';
+import { WeChatMpEndpoint } from './endpoint.js';
+import { resolveWeChatMpConfig } from './protocol.js';
+import { httpHostToken } from '@zhin.js/host-http';
+export class WeChatMpAdapter extends Adapter {
+    #context;
+    constructor(context) { super(); this.#context = context; }
+    get configurationIdentityFields() { return ['id', 'appId']; }
+    get configurationUpdateFields() { return ['appSecret', 'token', 'encodingAESKey', 'path', 'encrypt', 'encryptMode', 'replyMode', 'passiveReplyTimeoutMs']; }
+    get configurationIdentityProbeFields() { return ['appSecret']; }
+    validateConfiguration(config) { resolveWeChatMpConfig(config); }
+    createEndpoint(input, execution) {
+        const config = resolveWeChatMpConfig(input);
+        return new WeChatMpEndpoint({ id: execution.canonicalId, config, http: this.#context.use(httpHostToken) });
+    }
+}

package/lib/api-client.d.ts

@@ -0,0 +1,34 @@
+import { type EndpointManagementRequest, type EndpointOperationOptions } from 'zhin.js/adapter';
+import { EventEmitter } from 'node:events';
+import type { ResolvedWeChatMpConfig, WeChatAPIResponse } from './protocol.js';
+export type WeChatMpFetch = (url: string, init?: {
+    readonly method?: string;
+    readonly body?: unknown;
+    readonly headers?: Record<string, string>;
+    readonly signal?: AbortSignal;
+}) => Promise<{
+    readonly data: unknown;
+}>;
+/** Direct WeChat Official Account API client exposed to plugins. */
+export declare class WeChatMpApiClient extends EventEmitter {
+    #private;
+    readonly apiConfig: ResolvedWeChatMpConfig;
+    constructor(apiConfig: ResolvedWeChatMpConfig, fetch: WeChatMpFetch);
+    readonly fetch: WeChatMpFetch;
+    protected transportSignal?: AbortSignal;
+    get accessToken(): string | null;
+    get tokenExpired(): boolean;
+    /**
+     * 刷新 access_token。并发调用共享同一次请求：微信每次换取新 token 都会使旧 token
+     * 进入失效倒计时，且有每日调用次数上限，重复刷新会互相顶掉并消耗配额。
+     */
+    refreshAccessToken(): Promise<string>;
+    request<T = unknown>(path: string, init?: Parameters<WeChatMpFetch>[1]): Promise<T>;
+    sendCustomerService(messageData: unknown, request?: EndpointOperationOptions): Promise<WeChatAPIResponse>;
+    uploadMedia({ type, body, signal }: WeChatMpUploadRequest): Promise<string>;
+    getFollowerIds(request?: EndpointManagementRequest): Promise<readonly string[]>;
+}
+export interface WeChatMpUploadRequest extends EndpointOperationOptions {
+    readonly type: 'image' | 'voice' | 'video';
+    readonly body: unknown;
+}

package/lib/api-client.js

@@ -0,0 +1,113 @@
+import { createEndpointOperation } from 'zhin.js/adapter';
+import { EventEmitter } from 'node:events';
+const TOKEN_INVALID_ERRCODES = new Set([40001, 40014, 42001]);
+/** 换取 token 请求的超时，防止挂起的请求让 single-flight 永久卡住。 */
+const TOKEN_FETCH_TIMEOUT_MS = 15_000;
+/** 官方 access_token 有效期为 7200s；对异常大的 expires_in 设上限。 */
+const MAX_TOKEN_LIFETIME_SEC = 7200;
+/** Direct WeChat Official Account API client exposed to plugins. */
+export class WeChatMpApiClient extends EventEmitter {
+    apiConfig;
+    #accessToken = null;
+    #tokenExpireTime = 0;
+    #refreshing = null;
+    constructor(apiConfig, fetch) {
+        super();
+        this.apiConfig = apiConfig;
+        this.fetch = (url, init) => {
+            this.transportSignal?.throwIfAborted();
+            return fetch(url, { ...init, ...(this.transportSignal ? { signal: init?.signal ? AbortSignal.any([this.transportSignal, init.signal]) : this.transportSignal } : {}) });
+        };
+    }
+    fetch;
+    transportSignal;
+    get accessToken() {
+        return this.#accessToken;
+    }
+    get tokenExpired() {
+        return !this.#accessToken || Date.now() >= this.#tokenExpireTime;
+    }
+    /**
+     * 刷新 access_token。并发调用共享同一次请求：微信每次换取新 token 都会使旧 token
+     * 进入失效倒计时，且有每日调用次数上限，重复刷新会互相顶掉并消耗配额。
+     */
+    refreshAccessToken() {
+        if (!this.#refreshing) {
+            this.#refreshing = this.#fetchAccessToken().finally(() => {
+                this.#refreshing = null;
+            });
+        }
+        return this.#refreshing;
+    }
+    async #fetchAccessToken() {
+        const { appId, appSecret } = this.apiConfig;
+        const url = `https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=${encodeURIComponent(appId)}&secret=${encodeURIComponent(appSecret)}`;
+        let timeout;
+        const response = await Promise.race([
+            this.fetch(url),
+            new Promise((_, reject) => {
+                timeout = setTimeout(() => reject(new Error('Failed to get access token: request timed out')), TOKEN_FETCH_TIMEOUT_MS);
+            }),
+        ]).finally(() => clearTimeout(timeout));
+        const data = response.data;
+        if (!data.access_token) {
+            throw new Error(data.errmsg
+                ? `Failed to get access token: ${data.errcode} ${data.errmsg}`
+                : 'Failed to get access token');
+        }
+        this.#accessToken = data.access_token;
+        // expires_in 缺失/非法时 NaN 会让 tokenExpired 永远为 false；按官方默认 7200s 兜底。
+        const expiresIn = Number(data.expires_in);
+        const lifetimeSec = Number.isFinite(expiresIn) && expiresIn > 0
+            ? Math.min(expiresIn, MAX_TOKEN_LIFETIME_SEC)
+            : MAX_TOKEN_LIFETIME_SEC;
+        this.#tokenExpireTime = Date.now() + (lifetimeSec - 300) * 1000;
+        return data.access_token;
+    }
+    async request(path, init) {
+        return (await this.#requestWithToken(path, init)).data;
+    }
+    async #requestWithToken(path, init) {
+        if (this.tokenExpired)
+            await createEndpointOperation({ signal: init?.signal }).prepare(() => this.refreshAccessToken());
+        init?.signal?.throwIfAborted();
+        const token = this.#accessToken;
+        const separator = path.includes('?') ? '&' : '?';
+        const response = await this.fetch(`https://api.weixin.qq.com${path}${separator}access_token=${token}`, init);
+        return { data: response.data, token };
+    }
+    async sendCustomerService(messageData, request = {}) {
+        const first = await this.#requestWithToken('/cgi-bin/message/custom/send', { method: 'POST', body: messageData, signal: request.signal });
+        let result = first.data;
+        if (result.errcode && TOKEN_INVALID_ERRCODES.has(Number(result.errcode))) {
+            request.signal?.throwIfAborted();
+            // 失败请求使用的 token 若已被其他请求换掉，直接用新 token 重试，不再重复刷新。
+            if (this.#accessToken === first.token)
+                await createEndpointOperation(request).prepare(() => this.refreshAccessToken());
+            request.signal?.throwIfAborted();
+            result = await this.request('/cgi-bin/message/custom/send', { method: 'POST', body: messageData, signal: request.signal });
+        }
+        return result;
+    }
+    async uploadMedia({ type, body, signal }) {
+        const data = await this.request(`/cgi-bin/media/upload?type=${type}`, { method: 'POST', body, signal });
+        if (data.media_id)
+            return data.media_id;
+        throw new Error(`WeChat media upload failed: ${data.errcode ?? 'unknown'} ${data.errmsg ?? ''}`.trim());
+    }
+    async getFollowerIds(request = {}) {
+        const followers = [];
+        let nextOpenid = '';
+        do {
+            const data = await this.request(`/cgi-bin/user/get?next_openid=${encodeURIComponent(nextOpenid)}`, { signal: request.signal });
+            if (data.errcode && data.errcode !== 0) {
+                throw new Error(`WeChat API error: ${data.errcode} - ${data.errmsg}`);
+            }
+            followers.push(...(data.data?.openid ?? []).filter(Boolean));
+            if (Number(data.count ?? 0) < 10_000)
+                break;
+            nextOpenid = data.next_openid ?? '';
+        } while (nextOpenid);
+        return Object.freeze(followers);
+    }
+}

package/lib/client.d.ts

@@ -1,36 +1,42 @@
-import type { ResolvedWeChatMpConfig, WeChatAPIResponse } from './protocol.js';
-export type WeChatMpFetch = (url: string, init?: {
-    readonly method?: string;
-    readonly body?: unknown;
-    readonly headers?: Record<string, string>;
-}) => Promise<{
-    readonly data: unknown;
-}>;
-/** Direct WeChat Official Account API client exposed to plugins. */
-export declare class WeChatMpClient {
-    #private;
+import { WeChatMpApiClient, type WeChatMpFetch } from './api-client.js';
+import { type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from 'zhin.js';
+import { type ResolvedWeChatMpConfig, type WeChatMessage } from './protocol.js';
+export interface WeChatMpEndpointOptions {
+    readonly id: CapabilityId;
+    readonly http: HttpHost;
     readonly config: ResolvedWeChatMpConfig;
-    readonly fetch: WeChatMpFetch;
-    constructor(config: ResolvedWeChatMpConfig, fetch: WeChatMpFetch);
-    get accessToken(): string | null;
-    get tokenExpired(): boolean;
-    /**
-     * 刷新 access_token。并发调用共享同一次请求：微信每次换取新 token 都会使旧 token
-     * 进入失效倒计时，且有每日调用次数上限，重复刷新会互相顶掉并消耗配额。
-     */
-    refreshAccessToken(): Promise<string>;
-    request<T = unknown>(path: string, init?: Parameters<WeChatMpFetch>[1]): Promise<T>;
-    sendCustomerService(messageData: unknown): Promise<WeChatAPIResponse>;
-    uploadMedia(type: 'image' | 'voice' | 'video', body: unknown): Promise<string>;
-    getFollowerIds(): Promise<readonly string[]>;
+    readonly fetch?: WeChatMpFetch;
 }
-export type WeChatMpClientEventMap = Record<string, unknown>;
-declare module '@zhin.js/feature-kit' {
-    interface AdapterClientRegistry {
-        readonly 'wechat-mp': {
-            readonly client: WeChatMpClient;
-            readonly events: WeChatMpClientEventMap;
-        };
-    }
+export declare class WeChatMpClient extends WeChatMpApiClient {
+    #private;
+    protected readonly endpointManagement: EndpointManagement;
+    protected configName(): string;
+    protected resolvePresentationLocale(_senderId: string): Promise<import('zhin.js').Locale | undefined>;
+    get transportState(): import('zhin.js/adapter').EndpointTransportState | undefined;
+    protected executionSignal?: AbortSignal;
+    protected setExecutionSignal(signal: AbortSignal): void;
+    /** Native protocol work runs here; Endpoint attaches the framework receipt without replacing SDK APIs. */
+    protected receiveInboundCallback<T>(receive: () => T | Promise<T>): Promise<T>;
+    protected publishEvent(name: string, payload: unknown): Promise<unknown>;
+    protected publishAccepted(name: string, payload: unknown): Promise<void>;
+    protected publishPlatform(name: string, event: unknown): Promise<unknown>;
+    constructor(options: WeChatMpEndpointOptions);
+    /** Used by webhook handler. */
+    get isOpen(): boolean;
+    get config(): ResolvedWeChatMpConfig;
+    get id(): CapabilityId;
+    /** 微信 5s 重推去重：见过该 MsgId 时返回首次回复 XML（含空串=success）。 */
+    getCachedReply(msgId: string): string | undefined;
+    cacheReply(msgId: string, replyXML: string): void;
+    protected connectTransport(signal?: AbortSignal): Promise<void>;
+    protected openInput(): void;
+    protected closeInput(): void;
+    protected disconnectTransport(): Promise<void>;
+    protected sendPayload({ conversation, payload, signal }: EndpointSendRequest): Promise<string>;
+    /** Test / internal: admit a parsed message when open (non-webhook path). */
+    admit(msg: WeChatMessage, nativeEvent?: unknown): void | Promise<unknown>;
 }
-export declare const wechatMpClient: import("@zhin.js/adapter").EndpointClientToken<WeChatMpClient, WeChatMpClientEventMap>;
+export type WeChatMpClientEventMap = Record<string, unknown>;
+export type { WeChatMpFetch } from './api-client.js';