@zhin.js/adapter-discord 1.1.18 → 1.1.20

package/lib/endpoint.js

@@ -1,124 +1,103 @@
-import { createDiscordRestApiAgent } from './rest-api-proxy.js';
 /**
  * DiscordEndpoint — lifecycle, outbound, admit, gateway / interactions modes, agent tool surface.
  */
-import { ChannelType } from 'discord.js';
-import { Endpoint, createEndpointLifecycle, } from 'zhin.js/adapter';
+import { Client, ChannelType } from 'discord.js';
+import { createEndpointSpecification, endpointSpec, createEndpointLifecycle, createEndpointOperation, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
-import { connectDiscordGatewayClient, defaultCreateClient, DEFAULT_INTENTS, resolveSenderRole, toMessageCreateOptions, } from './gateway.js';
+import { connectDiscordGatewayClient, discordClientOptions, DEFAULT_INTENTS, resolveSenderRole, toMessageCreateOptions, } from './gateway.js';
 import { discordInboundConversation, formatButtonContent, formatButtonSegments, formatInboundContent, formatInboundSegments, formatOutboundBody, senderDisplayName, } from './protocol.js';
 import { registerDiscordInteractionRoutes } from './webhook.js';
 import { receiveDiscordGuildMemberSideEvent } from './side-event-dispatch.js';
 const DISCORD_API = 'https://discord.com/api/v10';
 /** 出站 HTTP 调用统一 30s 超时。 */
 const OUTBOUND_TIMEOUT_MS = 30_000;
-export class DiscordGatewayEndpoint extends Endpoint {
+export class DiscordGatewayEndpoint extends Client {
+    [endpointSpec];
     #logger;
     #options;
-    #createClient;
     #fetch;
-    #client = null;
+    #connection;
+    #sdkDisposal;
     #open = false;
     #lifecycle = createEndpointLifecycle({ name: 'discord', reconnect: false });
     #cleanup;
     #retiring;
-    management = createDiscordEndpointManagement(() => this.#requireClient());
-    control = Object.freeze({
-        recall: (message) => this.recallMessage(message),
-        addReaction: async (message, emoji, hint) => {
-            const channelId = hint?.channelId ?? message.conversation.id;
-            if (!channelId || !message.id)
-                return null;
-            await this.#addReaction(channelId, message.id, emoji);
-            return emoji;
-        },
+    #management = createDiscordEndpointManagement(() => this.#requireClient());
+    #control = Object.freeze({
+        recall: request => this.#recallMessage(request),
+        addReaction: request => this.#addReaction(request),
     });
-    content = Object.freeze({
+    #content = Object.freeze({
         resolve: (reference, context) => resolveDiscordContent(this.#fetch, this.#options.config.token, reference, context),
     });
     constructor(options) {
-        super();
+        super(discordClientOptions(options.config.intents?.length ? options.config.intents : DEFAULT_INTENTS, options.config.gatewayFaultProxyUrl, options.restApiAgent ? { agent: options.restApiAgent } : {}));
         this.#logger = getAdapterLogger('discord', options.config.id);
         this.#options = options;
-        this.#createClient = options.createClient ?? defaultCreateClient;
         this.#fetch = options.fetch ?? globalThis.fetch;
+        const endpoint = this;
+        this[endpointSpec] = createEndpointSpecification(this, {
+            start: signal => this.#startFramework(signal), open: () => this.#openFramework(), close: () => this.#closeFramework(),
+            stop: () => this.#stopFramework(), send: request => this.#sendFramework(request),
+            get name() { return options.config.id; }, get transportState() { return endpoint.#transportState; },
+            management: this.#management, control: this.#control, content: this.#content,
+        });
     }
-    /** The actual discord.js-compatible client used by this connection. */
-    get client() {
-        return this.#requireClient();
-    }
-    get transportState() {
+    get #transportState() {
         if (this.#lifecycle.state !== 'open')
             return this.#lifecycle.state;
-        if (!this.#client)
+        if (!this.#connection)
             return 'closed';
-        if (!this.#client.isReady)
-            return this.#lifecycle.state;
-        return this.#client.isReady() ? 'open' : 'reconnecting';
+        return this.isReady() ? 'open' : 'reconnecting';
     }
-    async start() {
+    async #startFramework(executionSignal) {
         await this.#retiring;
         await this.#lifecycle.start(async (handle) => {
             let cleanup;
             let cancelled = false;
             try {
-                const intents = this.#options.config.intents?.length
-                    ? [...this.#options.config.intents]
-                    : DEFAULT_INTENTS;
-                const restAgent = this.#options.config.restApiProxy ? createDiscordRestApiAgent(this.#options.config.restApiProxy) : undefined;
-                let client;
-                try {
-                    client = this.#createClient(intents, this.#options.config.gatewayFaultProxyUrl, restAgent ? { agent: restAgent } : undefined);
-                }
-                catch (error) {
-                    await restAgent?.destroyProxy();
-                    throw error;
-                }
-                this.#client = client;
+                const client = this;
                 const abort = new AbortController();
                 let stopping;
+                this.#connection = abort;
                 cleanup = () => {
                     cancelled = true;
                     abort.abort();
-                    if (this.#client === client)
-                        this.#client = null;
-                    return stopping ??= (async () => { client.removeAllListeners(); try {
-                        await client.destroy();
-                    }
-                    finally {
-                        await restAgent?.destroyProxy();
-                    } })();
+                    if (this.#connection === abort)
+                        this.#connection = undefined;
+                    return stopping ??= this.#disposeSdk();
                 };
                 this.#cleanup = cleanup;
                 handle.onForceClose(() => { void cleanup?.().catch(() => { }); });
                 await connectDiscordGatewayClient(client, this.#options.config, {
+                    receive: action => this[endpointSpec].events.run(action),
                     onPlatformEvent: (name, event) => {
-                        if (this.#client !== client)
+                        if (this.#connection !== abort)
                             return;
                         void this.#emitPlatformEvent(name, event);
                     },
-                    onMessage: (msg) => { if (this.#client === client)
+                    onMessage: (msg) => { if (this.#connection === abort)
                         return this.admit(msg); },
-                    onButton: (interaction) => { if (this.#client === client)
+                    onButton: (interaction) => { if (this.#connection === abort)
                         return this.admitButton(interaction); },
                     onGuildMemberAdd: (member) => {
-                        if (this.#client !== client)
+                        if (this.#connection !== abort)
                             return;
-                        receiveDiscordGuildMemberSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, 'member_increase', member, this.#logger);
+                        receiveDiscordGuildMemberSideEvent((name, payload) => this[endpointSpec].events.emit(name, payload), this.#options.config.id, 'member_increase', member, this.#logger);
                     },
                     onGuildMemberRemove: (member) => {
-                        if (this.#client !== client)
+                        if (this.#connection !== abort)
                             return;
-                        receiveDiscordGuildMemberSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, 'member_decrease', member, this.#logger);
+                        receiveDiscordGuildMemberSideEvent((name, payload) => this[endpointSpec].events.emit(name, payload), this.#options.config.id, 'member_decrease', member, this.#logger);
                     },
-                }, abort.signal);
-                if (abort.signal.aborted || this.#client !== client)
+                }, AbortSignal.any([abort.signal, executionSignal]));
+                if (abort.signal.aborted || this.#connection !== abort)
                     return;
                 this.#logger.info(formatCompact({
                     op: 'connect',
                     endpoint: this.#options.config.id,
                     mode: 'gateway',
-                    user: this.#client.user?.tag,
+                    user: this.user?.tag,
                 }));
             }
             catch (error) {
@@ -134,30 +113,27 @@ export class DiscordGatewayEndpoint extends Endpoint {
             }
         });
     }
-    open() {
+    #openFramework() {
         this.#open = true;
     }
-    close() {
+    #closeFramework() {
         this.#open = false;
     }
-    async stop() {
+    async #stopFramework() {
         this.#open = false;
         const cleanup = this.#cleanup;
         this.#cleanup = undefined;
         this.#lifecycle.stop();
-        const retiring = this.#retiring ?? Promise.resolve().then(async () => { try {
-            await cleanup?.();
-        }
-        catch { /* best-effort SDK shutdown */ } });
+        const retiring = this.#retiring ?? Promise.resolve().then(() => cleanup ? cleanup() : this.#disposeSdk());
         this.#retiring = retiring;
         await retiring;
         if (this.#retiring === retiring)
             this.#retiring = undefined;
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
-    async send({ conversation, payload }) {
+    async #sendFramework({ conversation, payload, signal }) {
         const body = formatOutboundBody(payload);
-        const snowflake = await this.#sendBody(conversation.id, body);
+        const snowflake = await this.#sendBody({ channelId: conversation.id, body, signal });
         this.#logger.debug(formatCompact({
             op: 'discord_send',
             endpoint: this.#options.config.id,
@@ -166,14 +142,15 @@ export class DiscordGatewayEndpoint extends Endpoint {
         }));
         return snowflake;
     }
-    async recallMessage(message) {
+    async #recallMessage({ message, signal }) {
         if (!message.id)
             return;
-        const channel = await this.#requireClient().channels.fetch(message.conversation.id);
+        const operation = createEndpointOperation({ signal });
+        const channel = await operation.prepare(() => this.#requireClient().channels.fetch(message.conversation.id));
         if (!channel?.isTextBased() || !channel.messages)
             return;
-        const msg = await channel.messages.fetch(message.id);
-        await msg.delete();
+        const msg = await operation.prepare(() => channel.messages.fetch(message.id));
+        await operation.run(() => msg.delete());
     }
     /** Test / internal: admit a message when open. */
     admit(msg) {
@@ -182,8 +159,10 @@ export class DiscordGatewayEndpoint extends Endpoint {
         if (msg.authorBot)
             return;
         const conversation = discordInboundConversation(String(this.#options.id), msg);
-        void this.emit('message.receive', {
+        void this[endpointSpec].events.emit('message.receive', {
             conversation,
+            event: msg.event,
+            platformSentAt: msg.platformSentAt,
             message: { conversation, id: msg.id },
             content: formatInboundContent(msg),
             segments: formatInboundSegments(msg),
@@ -214,7 +193,9 @@ export class DiscordGatewayEndpoint extends Endpoint {
         if (!this.#open)
             return;
         const conversation = discordInboundConversation(String(this.#options.id), interaction);
-        void this.emit('message.receive', {
+        void this[endpointSpec].events.emit('message.receive', {
+            event: interaction.event,
+            platformSentAt: interaction.platformSentAt,
             conversation,
             message: { conversation, id: interaction.id },
             content: formatButtonContent(interaction),
@@ -234,16 +215,20 @@ export class DiscordGatewayEndpoint extends Endpoint {
             }));
         });
     }
-    async #addReaction(channelId, messageId, emoji) {
-        const channel = await this.#requireClient().channels.fetch(channelId);
-        if (!channel?.isTextBased() || !channel.messages) {
+    async #addReaction({ message, emoji, hint, signal }) {
+        const channelId = hint?.channelId ?? message.conversation.id;
+        if (!channelId || !message.id)
+            return null;
+        const operation = createEndpointOperation({ signal });
+        const channel = await operation.prepare(() => this.#requireClient().channels.fetch(channelId));
+        if (!channel?.isTextBased() || !channel.messages)
             throw new Error(`Channel ${channelId} 不是文本频道`);
-        }
-        const message = await channel.messages.fetch(messageId);
-        await message.react(emoji);
+        const native = await operation.prepare(() => channel.messages.fetch(message.id));
+        await operation.run(() => native.react(emoji));
+        return emoji;
     }
     async #emitPlatformEvent(name, event) {
-        await this.emitPlatform(name, event).catch((error) => {
+        await this[endpointSpec].events.platform(name, event).catch((error) => {
             this.#logger.warn(formatCompact({
                 op: 'discord_platform_event_failed',
                 event: name,
@@ -251,17 +236,18 @@ export class DiscordGatewayEndpoint extends Endpoint {
             }));
         });
     }
-    async #sendBody(channelId, body) {
+    async #sendBody({ channelId, body, signal }) {
+        const operation = createEndpointOperation({ signal });
         let stage = 'fetch_channel';
         try {
-            const channel = await this.#requireClient().channels.fetch(channelId);
-            if (!channel || !channel.isTextBased() || !channel.send) {
+            const channel = await operation.prepare(() => this.#requireClient().channels.fetch(channelId));
+            if (!channel || !channel.isSendable()) {
                 throw new Error(`Channel ${channelId} is not a text channel`);
             }
             stage = 'render';
-            const options = await toMessageCreateOptions(body);
+            const options = await operation.prepare(() => toMessageCreateOptions(body));
             stage = 'send';
-            const result = await channel.send(options);
+            const result = await operation.run(async () => channel.send(options));
             return result.id;
         }
         catch (error) {
@@ -273,10 +259,22 @@ export class DiscordGatewayEndpoint extends Endpoint {
             throw error;
         }
     }
+    #disposeSdk() {
+        this.#sdkDisposal ??= Promise.resolve().then(async () => {
+            this.removeAllListeners();
+            try {
+                await super.destroy();
+            }
+            finally {
+                await this.#options.restApiAgent?.destroyProxy();
+            }
+        });
+        return this.#sdkDisposal;
+    }
     #requireClient() {
-        if (!this.#client)
+        if (!this.#connection)
             throw new Error('Discord client not connected');
-        return this.#client;
+        return this;
     }
 }
 /** Minimal Discord REST client used when Gateway is intentionally disabled. */
@@ -287,49 +285,55 @@ export class DiscordRestClient {
         this.token = token;
         this.fetch = fetch;
     }
-    async request(method, path, body) {
-        const response = await this.fetch(`${DISCORD_API}${path}`, {
-            method,
-            headers: {
-                Authorization: `Bot ${this.token}`,
-                ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
-            },
-            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-            signal: AbortSignal.timeout(OUTBOUND_TIMEOUT_MS),
-        });
-        const text = await response.text();
-        if (!response.ok) {
-            throw new Error(`Discord API ${method} ${path} failed (${response.status}): ${text.slice(0, 200)}`);
-        }
-        return (text ? JSON.parse(text) : undefined);
-    }
-    createMessage(channelId, body) {
-        return this.request('POST', `/channels/${channelId}/messages`, body);
-    }
-    deleteMessage(channelId, messageId) {
-        return this.request('DELETE', `/channels/${channelId}/messages/${messageId}`);
+    async request({ method, path, body, signal }) {
+        const deadline = AbortSignal.timeout(OUTBOUND_TIMEOUT_MS);
+        const operationSignal = signal ? AbortSignal.any([signal, deadline]) : deadline;
+        const operation = createEndpointOperation({ signal: operationSignal });
+        const execute = async () => {
+            const response = await this.fetch(`${DISCORD_API}${path}`, {
+                method,
+                headers: { Authorization: `Bot ${this.token}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                signal: operationSignal,
+            });
+            const text = await response.text();
+            if (!response.ok)
+                throw new Error(`Discord API ${method} ${path} failed (${response.status}): ${text.slice(0, 200)}`);
+            return (text ? JSON.parse(text) : undefined);
+        };
+        return operation.run(execute);
+    }
+    createMessage({ channelId, body, signal }) {
+        return this.request({ method: 'POST', path: `/channels/${channelId}/messages`, body, signal });
+    }
+    deleteMessage({ channelId, messageId, signal }) {
+        return this.request({ method: 'DELETE', path: `/channels/${channelId}/messages/${messageId}`, signal });
     }
 }
-export class DiscordInteractionsEndpoint extends Endpoint {
-    client;
+export class DiscordInteractionsEndpoint extends DiscordRestClient {
+    [endpointSpec];
     #logger;
     #options;
     #fetch;
     #routeReleases = [];
     #open = false;
     #started = false;
-    control = Object.freeze({
-        recall: (message) => this.recallMessage(message),
+    #control = Object.freeze({
+        recall: request => this.#recallMessage(request),
     });
-    content = Object.freeze({
+    #content = Object.freeze({
         resolve: (reference, context) => resolveDiscordContent(this.#fetch, this.#options.config.token, reference, context),
     });
     constructor(options) {
-        super();
+        super(options.config.token, options.fetch ?? globalThis.fetch);
         this.#logger = getAdapterLogger('discord', options.config.id);
         this.#options = options;
         this.#fetch = options.fetch ?? globalThis.fetch;
-        this.client = new DiscordRestClient(options.config.token, this.#fetch);
+        this[endpointSpec] = createEndpointSpecification(this, {
+            start: () => this.#startFramework(), open: () => this.#openFramework(), close: () => this.#closeFramework(),
+            stop: () => this.#stopFramework(), send: request => this.#sendFramework(request), name: options.config.id,
+            control: this.#control, content: this.#content,
+        });
     }
     get isOpen() {
         return this.#open;
@@ -337,7 +341,7 @@ export class DiscordInteractionsEndpoint extends Endpoint {
     get config() {
         return this.#options.config;
     }
-    async start() {
+    async #startFramework() {
         if (this.#started)
             return;
         this.#started = true;
@@ -349,35 +353,37 @@ export class DiscordInteractionsEndpoint extends Endpoint {
             path: this.#options.config.interactionsPath,
         }));
     }
-    open() {
+    #openFramework() {
         this.#open = true;
     }
-    close() {
+    #closeFramework() {
         this.#open = false;
     }
-    async stop() {
+    async #stopFramework() {
         this.#open = false;
         for (const release of this.#routeReleases.splice(0))
             release();
         this.#started = false;
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
-    async send({ conversation, payload }) {
+    async #sendFramework({ conversation, payload, signal }) {
         const body = formatOutboundBody(payload);
-        const data = await this.client.createMessage(conversation.id, body);
+        const data = await this.createMessage({ channelId: conversation.id, body, signal });
         return data.id ?? '';
     }
-    async recallMessage(message) {
+    async #recallMessage({ message, signal }) {
         if (!message.id)
             return;
-        await this.client.deleteMessage(message.conversation.id, message.id);
+        await this.deleteMessage({ channelId: message.conversation.id, messageId: message.id, signal });
     }
     admit(msg) {
         if (!this.#open)
             return;
         const conversation = discordInboundConversation(String(this.#options.id), msg);
-        void this.emit('message.receive', {
+        void this[endpointSpec].events.emit('message.receive', {
             conversation,
+            event: msg.event,
+            platformSentAt: msg.platformSentAt,
             message: { conversation, id: msg.id },
             content: formatInboundContent(msg),
             segments: formatInboundSegments(msg),
@@ -406,7 +412,9 @@ export class DiscordInteractionsEndpoint extends Endpoint {
         if (!this.#open)
             return;
         const conversation = discordInboundConversation(String(this.#options.id), interaction);
-        void this.emit('message.receive', {
+        void this[endpointSpec].events.emit('message.receive', {
+            event: interaction.event,
+            platformSentAt: interaction.platformSentAt,
             conversation,
             message: { conversation, id: interaction.id },
             content: formatButtonContent(interaction),
@@ -430,7 +438,7 @@ export class DiscordInteractionsEndpoint extends Endpoint {
         if (!this.#open)
             return;
         const type = typeof event.type === 'number' ? `interaction.${event.type}` : 'interaction';
-        void this.emitPlatform(type, event).catch((error) => {
+        void this[endpointSpec].events.platform(type, event).catch((error) => {
             this.#logger.warn(formatCompact({
                 op: 'discord_platform_event_failed',
                 event: type,
@@ -488,57 +496,53 @@ async function resolveDiscordContent(fetch, token, reference, context) {
         return Object.freeze({ status: 'failed', code: 'discord_content_resolution_failed', message: error instanceof Error ? error.message : String(error) });
     }
 }
-/**
- * Discord snowflake 是 64 位整数的字符串形式，超出 Number.MAX_SAFE_INTEGER，
- * Number() 转换会丢精度。Console 社交面只把 group_id 当 JSON 值透传、
- * 并以字符串回传给 listGroupMembers，因此这里保留原始字符串（仅按契约
- * 类型声明强转），是全链路最不丢信息的方案。
- */
-function toGroupId(id) {
-    return id;
-}
 /**
  * DiscordGatewayEndpoint 的 EndpointManagement 语义端口（参照 qq 的工厂模式）。
  * 数据源为 discord.js SDK 缓存：guilds.cache / guild.channels.cache / guild.members。
  */
 export function createDiscordEndpointManagement(requireClient) {
     return Object.freeze({
-        async listGroups() {
-            const groups = [];
-            for (const guild of requireClient().guilds.cache.values()) {
-                if (!guild?.id)
-                    continue;
-                groups.push({
-                    group_id: toGroupId(String(guild.id)),
-                    name: String(guild.name ?? guild.id),
-                });
-            }
-            return groups;
-        },
-        async listChannels() {
-            const channels = [];
-            for (const guild of requireClient().guilds.cache.values()) {
-                if (!guild?.id)
-                    continue;
-                const guildId = String(guild.id);
-                const guildName = String(guild.name ?? guildId);
-                for (const channel of guild.channels?.cache?.values() ?? []) {
-                    if (!channel?.id)
+        async listGroups(request = {}) {
+            return createEndpointOperation(request).run(() => {
+                const groups = [];
+                for (const guild of requireClient().guilds.cache.values()) {
+                    if (!guild?.id)
                         continue;
-                    if (channel.type !== ChannelType.GuildText)
-                        continue;
-                    channels.push({
-                        id: String(channel.id),
-                        name: channel.name ? String(channel.name) : undefined,
-                        parent: { type: 'guild', id: guildId, name: guildName },
+                    groups.push({
+                        group_id: String(guild.id),
+                        name: String(guild.name ?? guild.id),
                     });
                 }
-            }
-            return channels;
+                return groups;
+            });
+        },
+        async listChannels(request = {}) {
+            return createEndpointOperation(request).run(() => {
+                const channels = [];
+                for (const guild of requireClient().guilds.cache.values()) {
+                    if (!guild?.id)
+                        continue;
+                    const guildId = String(guild.id);
+                    const guildName = String(guild.name ?? guildId);
+                    for (const channel of guild.channels?.cache?.values() ?? []) {
+                        if (!channel?.id)
+                            continue;
+                        if (channel.type !== ChannelType.GuildText)
+                            continue;
+                        channels.push({
+                            id: String(channel.id),
+                            name: channel.name ? String(channel.name) : undefined,
+                            parent: { type: 'guild', id: guildId, name: guildName },
+                        });
+                    }
+                }
+                return channels;
+            });
         },
-        async listGroupMembers(groupId) {
-            const guild = await requireClient().guilds.fetch(groupId);
-            const members = await guild.members.fetch({ limit: 100 });
+        async listGroupMembers({ groupId, signal }) {
+            const operation = createEndpointOperation({ signal });
+            const guild = await operation.run(() => requireClient().guilds.fetch(groupId));
+            const members = await operation.run(() => guild.members.fetch({ limit: 100 }));
             return [...members.values()].map((member) => ({
                 id: member.id,
                 username: member.user.username,