@zhin.js/adapter-qq 1.0.84 → 1.1.2

package/lib/endpoint.js

@@ -0,0 +1,456 @@
+/**
+ * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
+ */
+import { Endpoint, createEndpointLifecycle, createRecallEndpointControl, } from 'zhin.js/adapter';
+import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
+import { formatOutbound } from './outbound.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 extends Endpoint {
+    #logger;
+    #options;
+    #createBot;
+    #bot = null;
+    #open = false;
+    #lifecycle;
+    #cleanup;
+    management = createQqEndpointManagement(() => this.#requireBot());
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    constructor(options) {
+        super();
+        this.#logger = getAdapterLogger('qq', options.config.id);
+        this.#lifecycle = createEndpointLifecycle({ name: options.config.id, reconnect: false });
+        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;
+    }
+    async start() {
+        await this.#lifecycle.start(async (handle) => {
+            const bot = this.#createBot(this.#options.config);
+            this.#bot = bot;
+            let cancelled = false;
+            let stopping;
+            const stopBot = async () => {
+                try {
+                    bot.removeAllListeners();
+                }
+                catch { /* continue SDK cleanup */ }
+                try {
+                    await bot.stop();
+                }
+                catch { /* best-effort SDK cleanup */ }
+            };
+            const cleanup = () => {
+                cancelled = true;
+                if (this.#bot === bot)
+                    this.#bot = null;
+                return stopping ??= stopBot();
+            };
+            this.#cleanup = cleanup;
+            handle.onForceClose(() => { void cleanup(); });
+            try {
+                this.#bindBot(bot);
+                await bot.start();
+                if (cancelled) {
+                    // SDK startup may create resources after stop; close this exact old client again.
+                    await stopping;
+                    await stopBot();
+                    return;
+                }
+                this.#logger.info(`connected (websocket) | appid: ${this.#options.config.appid}`);
+            }
+            catch (error) {
+                const wasCancelled = cancelled;
+                await cleanup();
+                if (wasCancelled) {
+                    await stopBot();
+                    return;
+                }
+                const raw = error instanceof Error ? error.message : String(error);
+                throw new Error(`QQ WebSocket 连接失败：请检查 appid/secret 是否配对、网关地址（gatewayUrl/accessTokenUrl）是否可达（原始错误：${raw}）`, { cause: error });
+            }
+        });
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        const cleanup = this.#cleanup;
+        this.#cleanup = undefined;
+        await this.#lifecycle.stop();
+        await cleanup?.();
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
+    }
+    async send({ conversation, payload }) {
+        const body = formatOutbound(payload);
+        const kind = qqOutboundKind(conversation);
+        const bot = this.#requireBot();
+        let result;
+        switch (kind) {
+            case 'private':
+                result = await bot.sendPrivateMessage(conversation.id, body);
+                break;
+            case 'group':
+                result = await bot.sendGroupMessage(conversation.id, body);
+                break;
+            case 'channel':
+                result = await bot.sendGuildMessage(conversation.id, body);
+                break;
+            case 'direct':
+                if (!bot.sendDirectMessage)
+                    throw new Error('QQ direct message not supported by transport');
+                result = await bot.sendDirectMessage(conversation.id, body);
+                break;
+        }
+        const messageId = `${kind}-${conversation.id}:${resolveOutboundMessageId(result)}`;
+        this.#logger.info(`send ${kind}:${conversation.id}`
+            + ` | id: ${messageId}`
+            + ` | ${truncatePreview(typeof body === 'string' ? body : String(body), 80)}`);
+        return messageId;
+    }
+    async recallMessage(messageId) {
+        const { kind, channelId, qqMsgId } = parseCompoundMessageId(messageId);
+        const bot = this.#requireBot();
+        switch (kind) {
+            case 'private':
+                await bot.recallPrivateMessage?.(channelId, qqMsgId);
+                break;
+            case 'group':
+                await bot.recallGroupMessage?.(channelId, qqMsgId);
+                break;
+            case 'channel':
+                await bot.recallGuildMessage?.(channelId, qqMsgId);
+                break;
+            case 'direct':
+                await bot.recallDirectMessage?.(channelId, qqMsgId);
+                break;
+        }
+        this.#logger.debug(formatCompact({
+            op: 'qq_recall',
+            endpoint: this.#options.config.id,
+            kind,
+            messageId,
+        }));
+    }
+    /** Test / internal: admit a message when open. */
+    admit(msg) {
+        if (!this.#open)
+            return;
+        const conversation = qqInboundConversation(String(this.#options.id), msg);
+        const content = formatInboundContent(msg);
+        this.#logger.info(`recv ${conversation.kind}:${conversation.id}`
+            + (msg.authorId ? ` from ${msg.authorId}` : '')
+            + (msg.mentioned ? ' (mentioned)' : '')
+            + ` | ${truncatePreview(content, 80)}`);
+        void this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: msg.id },
+            content,
+            ...(msg.segments?.length ? { segments: msg.segments } : {}),
+            sender: {
+                id: msg.authorId,
+                name: senderDisplayName(msg) || undefined,
+                ...(msg.authorRoles?.length ? { roles: msg.authorRoles } : {}),
+            },
+            endpointId: this.#options.config.id,
+            ...(msg.mentioned ? { mentioned: true } : {}),
+            metadata: Object.freeze({
+                channelKind: msg.channelKind,
+                userId: msg.authorId,
+                guildId: msg.guildId,
+                roles: msg.authorRoles,
+            }),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'qq_gateway_receive_failed',
+                target: `${conversation.kind}:${conversation.id}`,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    #bindBot(bot) {
+        bindQqBotInboundEvents(bot, (raw) => {
+            if (this.#bot !== bot)
+                return;
+            this.#emitPlatformEvent('message', raw);
+            const msg = normalizeQqMessage(raw);
+            if (msg)
+                this.admit(msg);
+        });
+        bindQqBotSideEvents(bot, (eventName, raw) => {
+            if (this.#bot !== bot)
+                return;
+            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() {
+        if (!this.#bot)
+            throw new Error('QQ bot not connected');
+        return this.#bot;
+    }
+}
+/** Webhook / middleware inbound via httpHostToken POST (qq-official-bot Middleware receiver). */
+export class QqHttpEndpoint extends Endpoint {
+    #logger;
+    #options;
+    #createBot;
+    #bot = null;
+    #open = false;
+    #lifecycle;
+    #cleanup;
+    management = createQqEndpointManagement(() => this.#requireBot());
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    constructor(options) {
+        super();
+        this.#logger = getAdapterLogger('qq', options.config.id);
+        this.#lifecycle = createEndpointLifecycle({ name: options.config.id, reconnect: false });
+        this.#options = options;
+        this.#createBot = options.createBot ?? defaultCreateHttpBot;
+    }
+    get client() {
+        return this.#requireBot();
+    }
+    /** Live endpoint 名（Console/AdapterIndex 展示用）。 */
+    get name() {
+        return this.#options.config.id;
+    }
+    async start() {
+        await this.#lifecycle.start(async (handle) => {
+            const bot = this.#createBot(this.#options.config);
+            this.#bot = bot;
+            let cancelled = false;
+            let stopping;
+            const routes = [];
+            const stopBot = async () => {
+                try {
+                    bot.removeAllListeners();
+                }
+                catch { /* continue SDK cleanup */ }
+                try {
+                    await bot.stop();
+                }
+                catch { /* best-effort SDK cleanup */ }
+            };
+            const cleanup = () => {
+                cancelled = true;
+                if (this.#bot === bot)
+                    this.#bot = null;
+                for (const release of routes.splice(0))
+                    release();
+                return stopping ??= stopBot();
+            };
+            this.#cleanup = cleanup;
+            handle.onForceClose(() => { void cleanup(); });
+            try {
+                this.#bindBot(bot);
+                routes.push(...registerQqWebhookRoutes(this.#options.http, {
+                    config: this.#options.config,
+                    getBot: () => cancelled ? null : bot,
+                }));
+                await bot.start();
+                if (cancelled) {
+                    // SDK startup may create resources after stop; close this exact old client again.
+                    await stopping;
+                    await stopBot();
+                    return;
+                }
+                this.#logger.info(`connected (${this.#options.config.mode}) | path: ${this.#options.config.webhookPath}`);
+            }
+            catch (error) {
+                const wasCancelled = cancelled;
+                await cleanup();
+                if (wasCancelled) {
+                    await stopBot();
+                    return;
+                }
+                throw error;
+            }
+        });
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        const cleanup = this.#cleanup;
+        this.#cleanup = undefined;
+        await this.#lifecycle.stop();
+        await cleanup?.();
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
+    }
+    async send({ conversation, payload }) {
+        const body = formatOutbound(payload);
+        const kind = qqOutboundKind(conversation);
+        const bot = this.#requireBot();
+        let result;
+        switch (kind) {
+            case 'private':
+                result = await bot.sendPrivateMessage(conversation.id, body);
+                break;
+            case 'group':
+                result = await bot.sendGroupMessage(conversation.id, body);
+                break;
+            case 'channel':
+                result = await bot.sendGuildMessage(conversation.id, body);
+                break;
+            case 'direct':
+                if (!bot.sendDirectMessage)
+                    throw new Error('QQ direct message not supported by transport');
+                result = await bot.sendDirectMessage(conversation.id, body);
+                break;
+        }
+        const messageId = `${kind}-${conversation.id}:${resolveOutboundMessageId(result)}`;
+        this.#logger.info(`send ${kind}:${conversation.id}`
+            + ` | id: ${messageId}`
+            + ` | ${truncatePreview(typeof body === 'string' ? body : String(body), 80)}`);
+        return messageId;
+    }
+    async recallMessage(messageId) {
+        const { kind, channelId, qqMsgId } = parseCompoundMessageId(messageId);
+        const bot = this.#requireBot();
+        switch (kind) {
+            case 'private':
+                await bot.recallPrivateMessage?.(channelId, qqMsgId);
+                break;
+            case 'group':
+                await bot.recallGroupMessage?.(channelId, qqMsgId);
+                break;
+            case 'channel':
+                await bot.recallGuildMessage?.(channelId, qqMsgId);
+                break;
+            case 'direct':
+                await bot.recallDirectMessage?.(channelId, qqMsgId);
+                break;
+        }
+        this.#logger.debug(formatCompact({
+            op: 'qq_recall',
+            endpoint: this.#options.config.id,
+            kind,
+            messageId,
+        }));
+    }
+    admit(msg) {
+        if (!this.#open)
+            return;
+        const conversation = qqInboundConversation(String(this.#options.id), msg);
+        const content = formatInboundContent(msg);
+        this.#logger.info(`recv ${conversation.kind}:${conversation.id}`
+            + (msg.authorId ? ` from ${msg.authorId}` : '')
+            + (msg.mentioned ? ' (mentioned)' : '')
+            + ` | ${truncatePreview(content, 80)}`);
+        void this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: msg.id },
+            content,
+            ...(msg.segments?.length ? { segments: msg.segments } : {}),
+            sender: {
+                id: msg.authorId,
+                name: senderDisplayName(msg) || undefined,
+                ...(msg.authorRoles?.length ? { roles: msg.authorRoles } : {}),
+            },
+            endpointId: this.#options.config.id,
+            ...(msg.mentioned ? { mentioned: true } : {}),
+            metadata: Object.freeze({
+                channelKind: msg.channelKind,
+                userId: msg.authorId,
+                guildId: msg.guildId,
+                roles: msg.authorRoles,
+            }),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'qq_gateway_receive_failed',
+                target: `${conversation.kind}:${conversation.id}`,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    #bindBot(bot) {
+        bindQqBotInboundEvents(bot, (raw) => {
+            if (this.#bot !== bot)
+                return;
+            this.#emitPlatformEvent('message', raw);
+            const msg = normalizeQqMessage(raw);
+            if (msg)
+                this.admit(msg);
+        });
+        bindQqBotSideEvents(bot, (eventName, raw) => {
+            if (this.#bot !== bot)
+                return;
+            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() {
+        if (!this.#bot)
+            throw new Error('QQ bot not connected');
+        return this.#bot;
+    }
+}
+function createQqEndpointManagement(requireClient) {
+    return Object.freeze({
+        async listChannels() {
+            const channels = [];
+            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 client.getChannels(guildId);
+                for (const channelValue of Array.isArray(rows) ? rows : []) {
+                    const channel = asRecord(channelValue);
+                    const id = String(channel.id ?? channel.channel_id ?? channelValue ?? '');
+                    if (!id)
+                        continue;
+                    channels.push({
+                        id,
+                        name: String(channel.name ?? channel.channel_name ?? id),
+                        parent: { type: 'guild', id: guildId, name: guildName },
+                    });
+                }
+            }
+            return channels;
+        },
+    });
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : {};
+}

package/lib/index.d.ts

@@ -1,18 +1,8 @@
-import { QQAdapter } from "./adapter.js";
-import { PageManager } from "@zhin.js/console";
-declare module "zhin.js" {
-    namespace Plugin {
-        interface Contexts {
-            web: PageManager;
-        }
-    }
-}
-declare module "zhin.js" {
-    interface Adapters {
-        qq: QQAdapter;
-    }
-}
-export * from "./types.js";
-export { QQBot } from "./bot.js";
-export { QQAdapter } from "./adapter.js";
-//# sourceMappingURL=index.d.ts.map
+export { formatInboundContent, formatOutboundText, resolveOutboundMessageId, resolveQqConfig, senderDisplayName, type QqEndpointConfig, type QqChannelKind, type QqInboundMessage, type QqWireSegment, type ResolvedQqConfig, type ResolvedQqHttpConfig, type ResolvedQqWebsocketConfig, } from './protocol.js';
+export { DEFAULT_QQ_BOT_KIND, QQ_INTENTS_BY_KIND, defaultQqEndpointIntentFields, parseQqBotKind, resolveQqIntents, type QqBotKind, type QqIntent, } from './qq-intents.js';
+export { formatOutbound, resolveMediaFile, type QqOutboundElem, type QqOutboundMessage, } from './outbound.js';
+export { QqHttpEndpoint, QqWebsocketEndpoint, type CreateQqBot, type CreateQqHttpBot, type QqBotTransport, type QqOfficialApi, 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 { qqClient, type QqClientEventMap } from './client.js';
+export { checkQqPlatformPermit, normalizeQqGuildSenderForPermit, platformPermit, qqGuildPermitResolver, } from './platform-permit.js';