@zhin.js/adapter-qq 7.0.14 → 8.0.1

package/lib/endpoint.js

@@ -1,24 +1,32 @@
+import { Endpoint } from 'zhin.js/adapter';
+/**
+ * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
+ */
+import { createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import { formatOutbound } from './outbound.js';
-import { registerQqAgentEndpoint } from './qq-agent-deps.js';
 import { formatInboundContent, parseCompoundMessageId, qqInboundConversation, qqOutboundKind, resolveOutboundMessageId, senderDisplayName, } from './protocol.js';
 import { defaultCreateHttpBot, registerQqWebhookRoutes, } from './webhook.js';
 import { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';
 import { bindQqBotSideEvents, receiveQqSideEvent, } from './side-event-dispatch.js';
-export class QqWebsocketEndpoint {
+export class QqWebsocketEndpoint extends Endpoint {
     #logger;
     #options;
     #createBot;
     #bot = null;
     #open = false;
     #started = false;
-    #unregisterAgent;
-    management = createQqEndpointManagement(this);
+    management = createQqEndpointManagement(() => this.#requireBot());
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('qq', options.config.id);
         this.#options = options;
         this.#createBot = options.createBot ?? defaultCreateBot;
     }
+    get client() {
+        return this.#requireBot();
+    }
     /** Live endpoint 名（Console/AdapterIndex 展示用，如 bot appid 别名）。 */
     get name() {
         return this.#options.config.id;
@@ -28,7 +36,6 @@ export class QqWebsocketEndpoint {
             return;
         this.#started = true;
         try {
-            this.#unregisterAgent = registerQqAgentEndpoint(this.#options.config.id, this);
             this.#bot = this.#createBot(this.#options.config);
             this.#bindBot(this.#bot);
             await this.#bot.start();
@@ -49,8 +56,6 @@ export class QqWebsocketEndpoint {
     }
     async stop() {
         this.#open = false;
-        this.#unregisterAgent?.();
-        this.#unregisterAgent = undefined;
         if (this.#bot) {
             try {
                 this.#bot.removeAllListeners();
@@ -125,7 +130,7 @@ export class QqWebsocketEndpoint {
             + (msg.authorId ? ` from ${msg.authorId}` : '')
             + (msg.mentioned ? ' (mentioned)' : '')
             + ` | ${truncatePreview(content, 80)}`);
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: msg.id },
             content,
@@ -151,38 +156,25 @@ export class QqWebsocketEndpoint {
             }));
         });
     }
-    getGuilds() {
-        return this.#requireBot().getGuilds();
-    }
-    getChannels(guildId) {
-        return this.#requireBot().getChannels(guildId);
-    }
-    getChannelInfo(channelId) {
-        return this.#requireBot().getChannelInfo(channelId);
-    }
-    getGuildMember(guildId, userId) {
-        return this.#requireBot().getGuildMember(guildId, userId);
-    }
-    getGuildRoles(guildId) {
-        return this.#requireBot().getGuildRoles(guildId);
-    }
-    createGuildRole(guildId, name, color) {
-        return this.#requireBot().createGuildRole(guildId, name, color);
-    }
-    addMemberRole(guildId, channelId, userId, roleId) {
-        return this.#requireBot().addMemberRole(guildId, channelId, userId, roleId);
-    }
-    removeMemberRole(guildId, channelId, userId, roleId) {
-        return this.#requireBot().removeMemberRole(guildId, channelId, userId, roleId);
-    }
     #bindBot(bot) {
         bindQqBotInboundEvents(bot, (raw) => {
+            this.#emitPlatformEvent('message', raw);
             const msg = normalizeQqMessage(raw);
             if (msg)
                 this.admit(msg);
         });
         bindQqBotSideEvents(bot, (eventName, raw) => {
-            receiveQqSideEvent(this.#options.sideEvents, this.#options.config.id, bot, eventName, raw, this.#logger);
+            this.#emitPlatformEvent(eventName, raw);
+            receiveQqSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, bot, eventName, raw, this.#logger);
+        });
+    }
+    #emitPlatformEvent(name, event) {
+        void this.emitPlatform(name, event).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'qq_platform_event_failed',
+                event: name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
         });
     }
     #requireBot() {
@@ -192,7 +184,7 @@ export class QqWebsocketEndpoint {
     }
 }
 /** Webhook / middleware inbound via httpHostToken POST (qq-official-bot Middleware receiver). */
-export class QqHttpEndpoint {
+export class QqHttpEndpoint extends Endpoint {
     #logger;
     #options;
     #createBot;
@@ -200,13 +192,17 @@ export class QqHttpEndpoint {
     #routeReleases = [];
     #open = false;
     #started = false;
-    #unregisterAgent;
-    management = createQqEndpointManagement(this);
+    management = createQqEndpointManagement(() => this.#requireBot());
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('qq', options.config.id);
         this.#options = options;
         this.#createBot = options.createBot ?? defaultCreateHttpBot;
     }
+    get client() {
+        return this.#requireBot();
+    }
     /** Live endpoint 名（Console/AdapterIndex 展示用）。 */
     get name() {
         return this.#options.config.id;
@@ -216,7 +212,6 @@ export class QqHttpEndpoint {
             return;
         this.#started = true;
         try {
-            this.#unregisterAgent = registerQqAgentEndpoint(this.#options.config.id, this);
             this.#setupRoutes();
             this.#bot = this.#createBot(this.#options.config);
             this.#bindBot(this.#bot);
@@ -239,8 +234,6 @@ export class QqHttpEndpoint {
         this.#open = false;
         for (const release of this.#routeReleases.splice(0))
             release();
-        this.#unregisterAgent?.();
-        this.#unregisterAgent = undefined;
         if (this.#bot) {
             try {
                 this.#bot.removeAllListeners();
@@ -314,7 +307,7 @@ export class QqHttpEndpoint {
             + (msg.authorId ? ` from ${msg.authorId}` : '')
             + (msg.mentioned ? ' (mentioned)' : '')
             + ` | ${truncatePreview(content, 80)}`);
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: msg.id },
             content,
@@ -340,30 +333,6 @@ export class QqHttpEndpoint {
             }));
         });
     }
-    getGuilds() {
-        return this.#requireBot().getGuilds();
-    }
-    getChannels(guildId) {
-        return this.#requireBot().getChannels(guildId);
-    }
-    getChannelInfo(channelId) {
-        return this.#requireBot().getChannelInfo(channelId);
-    }
-    getGuildMember(guildId, userId) {
-        return this.#requireBot().getGuildMember(guildId, userId);
-    }
-    getGuildRoles(guildId) {
-        return this.#requireBot().getGuildRoles(guildId);
-    }
-    createGuildRole(guildId, name, color) {
-        return this.#requireBot().createGuildRole(guildId, name, color);
-    }
-    addMemberRole(guildId, channelId, userId, roleId) {
-        return this.#requireBot().addMemberRole(guildId, channelId, userId, roleId);
-    }
-    removeMemberRole(guildId, channelId, userId, roleId) {
-        return this.#requireBot().removeMemberRole(guildId, channelId, userId, roleId);
-    }
     #setupRoutes() {
         this.#routeReleases.push(...registerQqWebhookRoutes(this.#options.http, {
             config: this.#options.config,
@@ -372,12 +341,23 @@ export class QqHttpEndpoint {
     }
     #bindBot(bot) {
         bindQqBotInboundEvents(bot, (raw) => {
+            this.#emitPlatformEvent('message', raw);
             const msg = normalizeQqMessage(raw);
             if (msg)
                 this.admit(msg);
         });
         bindQqBotSideEvents(bot, (eventName, raw) => {
-            receiveQqSideEvent(this.#options.sideEvents, this.#options.config.id, bot, eventName, raw, this.#logger);
+            this.#emitPlatformEvent(eventName, raw);
+            receiveQqSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, bot, eventName, raw, this.#logger);
+        });
+    }
+    #emitPlatformEvent(name, event) {
+        void this.emitPlatform(name, event).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'qq_platform_event_failed',
+                event: name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
         });
     }
     #requireBot() {
@@ -386,18 +366,19 @@ export class QqHttpEndpoint {
         return this.#bot;
     }
 }
-function createQqEndpointManagement(endpoint) {
+function createQqEndpointManagement(requireClient) {
     return Object.freeze({
         async listChannels() {
             const channels = [];
-            const guilds = await endpoint.getGuilds();
+            const client = requireClient();
+            const guilds = await client.getGuilds();
             for (const guildValue of Array.isArray(guilds) ? guilds : []) {
                 const guild = asRecord(guildValue);
                 const guildId = String(guild.id ?? guild.guild_id ?? guildValue ?? '');
                 if (!guildId)
                     continue;
                 const guildName = String(guild.name ?? guild.guild_name ?? guildId);
-                const rows = await endpoint.getChannels(guildId);
+                const rows = await client.getChannels(guildId);
                 for (const channelValue of Array.isArray(rows) ? rows : []) {
                     const channel = asRecord(channelValue);
                     const id = String(channel.id ?? channel.channel_id ?? channelValue ?? '');

package/lib/index.d.ts

@@ -4,5 +4,5 @@ export { formatOutbound, resolveMediaFile, type QqOutboundElem, type QqOutboundM
 export { QqHttpEndpoint, QqWebsocketEndpoint, type CreateQqBot, type CreateQqHttpBot, type QqBotTransport, type QqEndpointOptions, type QqHttpBotTransport, type QqHttpEndpointOptions, } from './endpoint.js';
 export { registerQqWebhookRoutes, handleQqWebhookRequest, readRequestBodyText, defaultCreateHttpBot, type QqWebhookHandler, } from './webhook.js';
 export { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';
-export { getQqAgentDeps, registerQqAgentEndpoint, setQqAgentDeps, type QqAgentDeps, type QqAgentEndpoint, } from './qq-agent-deps.js';
+export { qqClient, type QqClientEventMap } from './client.js';
 export { checkQqPlatformPermit, normalizeQqGuildSenderForPermit, platformPermit, qqGuildPermitResolver, } from './platform-permit.js';

package/lib/index.js

@@ -4,5 +4,5 @@ export { formatOutbound, resolveMediaFile, } from './outbound.js';
 export { QqHttpEndpoint, QqWebsocketEndpoint, } from './endpoint.js';
 export { registerQqWebhookRoutes, handleQqWebhookRequest, readRequestBodyText, defaultCreateHttpBot, } from './webhook.js';
 export { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';
-export { getQqAgentDeps, registerQqAgentEndpoint, setQqAgentDeps, } from './qq-agent-deps.js';
+export { qqClient } from './client.js';
 export { checkQqPlatformPermit, normalizeQqGuildSenderForPermit, platformPermit, qqGuildPermitResolver, } from './platform-permit.js';

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

@@ -42,4 +42,4 @@ export declare function runQqEndpointRemove(_state: QqRuntimeState, id: string,
  * 通用套件生成的 QQ endpoint 命令（add 经 bindFlow 钩子走扫码绑定）。
  * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项；cancel 为 QQ 特化，单独定义。
  */
-export declare const qqEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;
+export declare const qqEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage, string | undefined>>>;

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

@@ -1,4 +1,4 @@
-import type { SideEventGateway } from '@zhin.js/core/runtime';
+import type { EndpointEventEmitter } from 'zhin.js/adapter';
 import { type getAdapterLogger } from '@zhin.js/logger';
 export interface QqSideEventCaller {
     approveGroupJoinRequest?(groupId: string, userId: string, options: {
@@ -10,4 +10,4 @@ export interface QqSideEventCaller {
 export declare function bindQqBotSideEvents(bot: {
     on(event: string, listener: (...args: unknown[]) => void): void;
 }, dispatch: (eventName: string, raw: unknown) => void): void;
-export declare function receiveQqSideEvent(sideEvents: SideEventGateway | undefined, endpointKey: string, caller: QqSideEventCaller, eventName: string, raw: unknown, logger: ReturnType<typeof getAdapterLogger>): void;
+export declare function receiveQqSideEvent(emit: EndpointEventEmitter, endpointKey: string, caller: QqSideEventCaller, eventName: string, raw: unknown, logger: ReturnType<typeof getAdapterLogger>): void;

package/lib/side-event-dispatch.js

@@ -51,8 +51,8 @@ function toOneBotLikeRaw(eventName, raw) {
     }
     return null;
 }
-export function receiveQqSideEvent(sideEvents, endpointKey, caller, eventName, raw, logger) {
-    if (!sideEvents)
+export function receiveQqSideEvent(emit, endpointKey, caller, eventName, raw, logger) {
+    if (!emit)
         return;
     const mapped = toOneBotLikeRaw(eventName, raw);
     if (!mapped)
@@ -61,7 +61,7 @@ export function receiveQqSideEvent(sideEvents, endpointKey, caller, eventName, r
     const joinRaw = isJoinRequest && raw && typeof raw === 'object'
         ? raw
         : undefined;
-    void receiveOneBotLikeSideEvent(sideEvents, {
+    void receiveOneBotLikeSideEvent(emit, {
         adapter: 'qq',
         endpointKey,
         platform: 'qq',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "7.0.14",
+  "version": "8.0.1",
   "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
@@ -35,21 +35,22 @@
   },
   "dependencies": {
     "qq-official-bot": "^1.2.3",
-    "@zhin.js/adapter": "1.1.11",
-    "@zhin.js/core": "1.5.12",
-    "@zhin.js/host-http": "1.0.11",
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/core": "1.5.14",
+    "@zhin.js/feature-kit": "1.0.13",
+    "@zhin.js/host-http": "1.0.13",
     "@zhin.js/im-contract": "1.0.4",
-    "@zhin.js/logger": "1.0.76",
-    "@zhin.js/permission": "1.0.3"
+    "@zhin.js/logger": "1.0.77",
+    "@zhin.js/permission": "1.0.4"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.11",
-    "@zhin.js/agent": "1.1.14",
-    "@zhin.js/command": "1.0.15",
-    "@zhin.js/core": "1.5.12",
-    "@zhin.js/middleware": "1.0.12",
-    "zhin.js": "6.0.12"
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/agent": "1.1.16",
+    "@zhin.js/command": "1.0.16",
+    "@zhin.js/core": "1.5.14",
+    "@zhin.js/middleware": "1.0.13",
+    "zhin.js": "6.0.14"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {
@@ -73,9 +74,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.14",
-    "@zhin.js/host-http": "1.0.11",
-    "zhin.js": "6.0.12"
+    "@zhin.js/agent": "1.1.16",
+    "@zhin.js/host-http": "1.0.13",
+    "zhin.js": "6.0.14"
   },
   "files": [
     "adapters",

package/src/client.ts

@@ -0,0 +1,16 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+import type { QqInboundMessage } from './protocol.js';
+import type { QqBotTransport } from './ws.js';
+
+export type QqClientEventMap = Record<string, QqInboundMessage | unknown>;
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly qq: {
+      readonly client: QqBotTransport;
+      readonly events: QqClientEventMap;
+    };
+  }
+}
+
+export const qqClient = defineEndpointClient<QqBotTransport, QqClientEventMap>('qq');