@zhin.js/adapter-discord 5.0.2 → 5.0.3

package/lib/endpoint.js

@@ -0,0 +1,355 @@
+/**
+ * DiscordEndpoint — lifecycle, outbound, admit, gateway / interactions modes, agent tool surface.
+ */
+import { ChannelType } from 'discord.js';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { registerDiscordAgentEndpoint } from './discord-agent-deps.js';
+import { connectDiscordGatewayClient, defaultCreateClient, DEFAULT_INTENTS, resolveSenderRole, toMessageCreateOptions, } from './gateway.js';
+import { formatButtonContent, formatInboundContent, formatOutboundBody, senderDisplayName, } from './protocol.js';
+import { registerDiscordInteractionRoutes } from './webhook.js';
+const DISCORD_API = 'https://discord.com/api/v10';
+const logger = getLogger('discord');
+export class DiscordGatewayEndpoint {
+    #options;
+    #createClient;
+    #client = null;
+    #open = false;
+    #started = false;
+    #unregisterAgent;
+    #messageChannelMap = new Map();
+    constructor(options) {
+        this.#options = options;
+        this.#createClient = options.createClient ?? defaultCreateClient;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        try {
+            this.#unregisterAgent = registerDiscordAgentEndpoint(this.#options.config.name, this);
+            const intents = this.#options.config.intents?.length
+                ? [...this.#options.config.intents]
+                : DEFAULT_INTENTS;
+            this.#client = this.#createClient(intents);
+            await connectDiscordGatewayClient(this.#client, this.#options.config, {
+                onMessage: (msg) => this.admit(msg),
+                onButton: (interaction) => this.admitButton(interaction),
+            });
+            logger.info(formatCompact({
+                op: 'connect',
+                endpoint: this.#options.config.name,
+                mode: 'gateway',
+                user: this.#client.user?.tag,
+            }));
+        }
+        catch (error) {
+            await this.stop();
+            logger.error('Failed to connect Discord gateway:', error);
+            throw error;
+        }
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        this.#unregisterAgent?.();
+        this.#unregisterAgent = undefined;
+        if (this.#client) {
+            try {
+                this.#client.removeAllListeners();
+                await this.#client.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+            this.#client = null;
+        }
+        this.#started = false;
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    }
+    async send({ target, payload }) {
+        const body = formatOutboundBody(payload);
+        const messageId = await this.#sendBody(target, body);
+        this.#messageChannelMap.set(messageId, target);
+        logger.debug(formatCompact({
+            op: 'discord_send',
+            endpoint: this.#options.config.name,
+            target,
+            messageId,
+        }));
+        return messageId;
+    }
+    /** Test / internal: admit a message when open. */
+    admit(msg) {
+        if (!this.#open)
+            return;
+        if (msg.authorBot)
+            return;
+        this.#messageChannelMap.set(msg.id, msg.channelId);
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target: msg.channelId,
+            content: formatInboundContent(msg),
+            sender: senderDisplayName(msg),
+            id: msg.id,
+            metadata: Object.freeze({
+                endpoint: this.#options.config.name,
+                channelKind: msg.channelKind,
+                userId: msg.authorId,
+                guildId: msg.guildId,
+                permissions: msg.permissionTokens,
+                role: resolveSenderRole(msg),
+                ...(msg.mentionedBot ? { mentioned: true } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'discord_gateway_receive_failed',
+                target: msg.channelId,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    /** Test / internal: admit a button interaction when open. */
+    admitButton(interaction) {
+        if (!this.#open)
+            return;
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target: interaction.channelId,
+            content: formatButtonContent(interaction),
+            sender: interaction.userName,
+            id: interaction.id,
+            metadata: Object.freeze({
+                endpoint: this.#options.config.name,
+                eventType: 'button',
+                payload: interaction.customId,
+                sourceMessageId: interaction.sourceMessageId,
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'discord_gateway_receive_failed',
+                target: interaction.channelId,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    // ── Agent tool surface ──────────────────────────────────────────────
+    async addRole(guildId, userId, roleId) {
+        const member = await this.#fetchMember(guildId, userId);
+        await member.roles.add(roleId);
+        return true;
+    }
+    async removeRole(guildId, userId, roleId) {
+        const member = await this.#fetchMember(guildId, userId);
+        await member.roles.remove(roleId);
+        return true;
+    }
+    async getRoles(guildId) {
+        const guild = await this.#requireClient().guilds.fetch(guildId);
+        await guild.roles.fetch();
+        const cache = guild.roles.cache;
+        return [...cache.values()].map((role) => ({
+            id: role.id,
+            name: role.name,
+            color: role.hexColor,
+            position: role.position,
+            permissions: role.permissions.bitfield.toString(),
+        }));
+    }
+    async createThread(channelId, name, messageId, autoArchiveDuration) {
+        const channel = await this.#requireClient().channels.fetch(channelId);
+        if (!channel || !('threads' in channel) || !channel.threads) {
+            throw new Error(`Channel ${channelId} 不支持创建帖子`);
+        }
+        const options = {
+            name,
+            autoArchiveDuration: autoArchiveDuration || 1440,
+        };
+        if (messageId)
+            options.startMessage = messageId;
+        return channel.threads.create(options);
+    }
+    async addReaction(channelId, messageId, emoji) {
+        const channel = await 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);
+    }
+    async sendEmbed(channelId, embedData) {
+        const body = { embeds: [embedData] };
+        const id = await this.#sendBody(channelId, body);
+        return { id };
+    }
+    async createForumPost(channelId, name, content, tags) {
+        const channel = await this.#requireClient().channels.fetch(channelId);
+        if (!channel || channel.type !== ChannelType.GuildForum || !channel.threads) {
+            throw new Error(`Channel ${channelId} 不是论坛频道`);
+        }
+        const options = {
+            name,
+            message: { content },
+        };
+        if (tags?.length && channel.availableTags?.length) {
+            const tagIds = channel.availableTags
+                .filter((t) => tags.includes(t.name))
+                .map((t) => t.id);
+            if (tagIds.length)
+                options.appliedTags = tagIds;
+        }
+        return channel.threads.create(options);
+    }
+    async kickMember(guildId, userId, reason) {
+        const member = await this.#fetchMember(guildId, userId);
+        await member.kick(reason);
+        return true;
+    }
+    async banMember(guildId, userId, reason) {
+        const guild = await this.#requireClient().guilds.fetch(guildId);
+        await guild.members.ban(userId, { reason });
+        return true;
+    }
+    async unbanMember(guildId, userId, reason) {
+        const guild = await this.#requireClient().guilds.fetch(guildId);
+        await guild.members.unban(userId, reason);
+        return true;
+    }
+    async timeoutMember(guildId, userId, duration = 600, reason) {
+        const member = await this.#fetchMember(guildId, userId);
+        await member.timeout(duration === 0 ? null : duration * 1000, reason);
+        return true;
+    }
+    async setNickname(guildId, userId, nickname) {
+        const member = await this.#fetchMember(guildId, userId);
+        await member.setNickname(nickname);
+        return true;
+    }
+    async getMembers(guildId, limit = 100) {
+        const guild = await this.#requireClient().guilds.fetch(guildId);
+        const members = await guild.members.fetch({ limit });
+        return [...members.values()].map((member) => ({
+            id: member.id,
+            username: member.user.username,
+            nickname: member.nickname,
+            roles: member.roles.cache.map((r) => r.id),
+            joined_at: member.joinedAt?.toISOString(),
+        }));
+    }
+    async getGuildInfo(guildId) {
+        const guild = await this.#requireClient().guilds.fetch(guildId);
+        return {
+            id: guild.id,
+            name: guild.name,
+            icon: guild.iconURL?.(),
+            owner_id: guild.ownerId,
+            member_count: guild.memberCount,
+            created_at: guild.createdAt?.toISOString(),
+        };
+    }
+    async #sendBody(channelId, body) {
+        const channel = await this.#requireClient().channels.fetch(channelId);
+        if (!channel || !channel.isTextBased() || !channel.send) {
+            throw new Error(`Channel ${channelId} is not a text channel`);
+        }
+        const options = await toMessageCreateOptions(body);
+        const result = await channel.send(options);
+        return result.id;
+    }
+    async #fetchMember(guildId, userId) {
+        const guild = await this.#requireClient().guilds.fetch(guildId);
+        return guild.members.fetch(userId);
+    }
+    #requireClient() {
+        if (!this.#client)
+            throw new Error('Discord client not connected');
+        return this.#client;
+    }
+}
+export class DiscordInteractionsEndpoint {
+    #options;
+    #fetch;
+    #routeReleases = [];
+    #open = false;
+    #started = false;
+    constructor(options) {
+        this.#options = options;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+    }
+    get isOpen() {
+        return this.#open;
+    }
+    get config() {
+        return this.#options.config;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        this.#routeReleases.push(...registerDiscordInteractionRoutes(this.#options.http, this));
+        logger.info(formatCompact({
+            op: 'connect',
+            endpoint: this.#options.config.name,
+            mode: 'interactions',
+            path: this.#options.config.interactionsPath,
+        }));
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#started = false;
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    }
+    async send({ target, payload }) {
+        const body = formatOutboundBody(payload);
+        const response = await this.#fetch(`${DISCORD_API}/channels/${target}/messages`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bot ${this.#options.config.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+        const text = await response.text();
+        if (!response.ok) {
+            throw new Error(`Discord send failed (${response.status}): ${text.slice(0, 200)}`);
+        }
+        const data = JSON.parse(text);
+        return data.id ?? '';
+    }
+    admit(msg) {
+        if (!this.#open)
+            return;
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target: msg.channelId,
+            content: formatInboundContent(msg),
+            sender: senderDisplayName(msg),
+            id: msg.id,
+            metadata: Object.freeze({
+                endpoint: this.#options.config.name,
+                channelKind: msg.channelKind,
+                userId: msg.authorId,
+                guildId: msg.guildId,
+                eventType: 'application_command',
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'discord_gateway_receive_failed',
+                target: msg.channelId,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+}

package/lib/gateway.d.ts

@@ -0,0 +1,122 @@
+import { GatewayIntentBits, type MessageCreateOptions } from 'discord.js';
+import { type DiscordButtonInbound, type DiscordInboundMessage, type DiscordOutboundBody, type ResolvedDiscordGatewayConfig } from './protocol.js';
+export declare const DEFAULT_INTENTS: GatewayIntentBits[];
+/** Minimal client surface used by the endpoint (real discord.js or test mock). */
+export interface DiscordClientTransport {
+    login(token: string): Promise<string>;
+    destroy(): Promise<void>;
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    once(event: string, listener: (...args: unknown[]) => void): void;
+    removeAllListeners(): void;
+    readonly user?: {
+        readonly id: string;
+        readonly tag?: string;
+        setActivity?(name: string, options?: {
+            type?: number;
+            url?: string;
+        }): void;
+    } | null;
+    channels: {
+        fetch(id: string): Promise<{
+            id: string;
+            type: number;
+            isTextBased(): boolean;
+            send?(options: MessageCreateOptions): Promise<{
+                id: string;
+            }>;
+            messages?: {
+                fetch(id: string): Promise<{
+                    react(emoji: string): Promise<unknown>;
+                    reactions: {
+                        resolve(emoji: unknown): {
+                            users: {
+                                remove(userId: string): Promise<unknown>;
+                            };
+                        } | null;
+                        cache: {
+                            find(fn: (r: {
+                                emoji: {
+                                    toString(): string;
+                                    name?: string | null;
+                                    id?: string | null;
+                                };
+                            }) => boolean): {
+                                users: {
+                                    remove(userId: string): Promise<unknown>;
+                                };
+                            } | undefined;
+                        };
+                    };
+                }>;
+            };
+            threads?: {
+                create(options: Record<string, unknown>): Promise<{
+                    id: string;
+                }>;
+            };
+            availableTags?: Array<{
+                id: string;
+                name: string;
+            }>;
+        } | null>;
+    };
+    guilds: {
+        fetch(id: string): Promise<{
+            id: string;
+            name: string;
+            ownerId: string;
+            memberCount: number;
+            createdAt?: Date | null;
+            iconURL?(options?: {
+                size?: number;
+            }): string | null;
+            roles: {
+                fetch(): Promise<unknown>;
+                cache: Map<string, {
+                    id: string;
+                    name: string;
+                    hexColor: string;
+                    position: number;
+                    permissions: {
+                        bitfield: bigint;
+                    };
+                }> | {
+                    map(fn: (role: {
+                        id: string;
+                        name: string;
+                        hexColor: string;
+                        position: number;
+                        permissions: {
+                            bitfield: bigint;
+                        };
+                    }) => unknown): unknown[];
+                };
+            };
+            members: {
+                fetch(userId: string | {
+                    limit?: number;
+                }): Promise<unknown>;
+                ban(userId: string, options?: {
+                    reason?: string;
+                    deleteMessageSeconds?: number;
+                }): Promise<unknown>;
+                unban(userId: string, reason?: string): Promise<unknown>;
+            };
+        }>;
+        cache: {
+            values(): IterableIterator<{
+                id: string;
+            }>;
+        };
+    };
+}
+export type CreateDiscordClient = (intents: readonly number[]) => DiscordClientTransport;
+export declare function defaultCreateClient(intents: readonly number[]): DiscordClientTransport;
+export declare function resolveSenderRole(msg: DiscordInboundMessage): string | undefined;
+export declare function normalizeDiscordMessage(raw: unknown): DiscordInboundMessage | null;
+export declare function toMessageCreateOptions(body: DiscordOutboundBody): Promise<MessageCreateOptions>;
+export interface DiscordGatewayConnectHandlers {
+    onMessage(msg: DiscordInboundMessage): void;
+    onButton(interaction: DiscordButtonInbound): void;
+}
+export declare function connectDiscordGatewayClient(client: DiscordClientTransport, config: ResolvedDiscordGatewayConfig, handlers: DiscordGatewayConnectHandlers): Promise<void>;