@zhin.js/adapter-discord 8.0.0 → 8.0.1

package/lib/endpoint.js

@@ -1,9 +1,9 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
  * DiscordEndpoint — lifecycle, outbound, admit, gateway / interactions modes, agent tool surface.
  */
 import { ChannelType } from 'discord.js';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
-import { registerDiscordAgentEndpoint } from './discord-agent-deps.js';
 import { connectDiscordGatewayClient, defaultCreateClient, DEFAULT_INTENTS, resolveSenderRole, toMessageCreateOptions, } from './gateway.js';
 import { discordInboundConversation, formatButtonContent, formatButtonSegments, formatInboundContent, formatInboundSegments, formatOutboundBody, senderDisplayName, } from './protocol.js';
 import { registerDiscordInteractionRoutes } from './webhook.js';
@@ -11,7 +11,7 @@ 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 {
+export class DiscordGatewayEndpoint extends Endpoint {
     #logger;
     #options;
     #createClient;
@@ -19,18 +19,14 @@ export class DiscordGatewayEndpoint {
     #client = null;
     #open = false;
     #started = false;
-    #unregisterAgent;
-    management = createDiscordEndpointManagement({
-        getClient: () => this.#requireClient(),
-        getMembers: (guildId) => this.getMembers(guildId),
-    });
+    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);
+            await this.#addReaction(channelId, message.id, emoji);
             return emoji;
         },
     });
@@ -38,29 +34,36 @@ export class DiscordGatewayEndpoint {
         resolve: (reference, context) => resolveDiscordContent(this.#fetch, this.#options.config.token, reference, context),
     });
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('discord', options.config.id);
         this.#options = options;
         this.#createClient = options.createClient ?? defaultCreateClient;
         this.#fetch = options.fetch ?? globalThis.fetch;
     }
+    /** The actual discord.js-compatible client used by this connection. */
+    get client() {
+        return this.#requireClient();
+    }
     async start() {
         if (this.#started)
             return;
         this.#started = true;
         try {
-            this.#unregisterAgent = registerDiscordAgentEndpoint(this.#options.config.id, 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, {
+                onPlatformEvent: (name, event) => {
+                    void this.#emitPlatformEvent(name, event);
+                },
                 onMessage: (msg) => this.admit(msg),
                 onButton: (interaction) => this.admitButton(interaction),
                 onGuildMemberAdd: (member) => {
-                    receiveDiscordGuildMemberSideEvent(this.#options.sideEvents, this.#options.config.id, 'member_increase', member, this.#logger);
+                    receiveDiscordGuildMemberSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, 'member_increase', member, this.#logger);
                 },
                 onGuildMemberRemove: (member) => {
-                    receiveDiscordGuildMemberSideEvent(this.#options.sideEvents, this.#options.config.id, 'member_decrease', member, this.#logger);
+                    receiveDiscordGuildMemberSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, 'member_decrease', member, this.#logger);
                 },
             });
             this.#logger.info(formatCompact({
@@ -84,8 +87,6 @@ export class DiscordGatewayEndpoint {
     }
     async stop() {
         this.#open = false;
-        this.#unregisterAgent?.();
-        this.#unregisterAgent = undefined;
         if (this.#client) {
             try {
                 this.#client.removeAllListeners();
@@ -126,7 +127,7 @@ export class DiscordGatewayEndpoint {
         if (msg.authorBot)
             return;
         const conversation = discordInboundConversation(String(this.#options.id), msg);
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: msg.id },
             content: formatInboundContent(msg),
@@ -158,7 +159,7 @@ export class DiscordGatewayEndpoint {
         if (!this.#open)
             return;
         const conversation = discordInboundConversation(String(this.#options.id), interaction);
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: interaction.id },
             content: formatButtonContent(interaction),
@@ -178,43 +179,7 @@ export class DiscordGatewayEndpoint {
             }));
         });
     }
-    // ── 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) {
+    async #addReaction(channelId, messageId, emoji) {
         const channel = await this.#requireClient().channels.fetch(channelId);
         if (!channel?.isTextBased() || !channel.messages) {
             throw new Error(`Channel ${channelId} 不是文本频道`);
@@ -222,75 +187,14 @@ export class DiscordGatewayEndpoint {
         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 #emitPlatformEvent(name, event) {
+        await this.emitPlatform(name, event).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'discord_platform_event_failed',
+                event: name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
     }
     async #sendBody(channelId, body) {
         const channel = await this.#requireClient().channels.fetch(channelId);
@@ -301,17 +205,45 @@ export class DiscordGatewayEndpoint {
         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 {
+/** Minimal Discord REST client used when Gateway is intentionally disabled. */
+export class DiscordRestClient {
+    token;
+    fetch;
+    constructor(token, fetch = globalThis.fetch) {
+        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}`);
+    }
+}
+export class DiscordInteractionsEndpoint extends Endpoint {
+    client;
     #logger;
     #options;
     #fetch;
@@ -325,9 +257,11 @@ export class DiscordInteractionsEndpoint {
         resolve: (reference, context) => resolveDiscordContent(this.#fetch, this.#options.config.token, reference, context),
     });
     constructor(options) {
+        super();
         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);
     }
     get isOpen() {
         return this.#open;
@@ -362,42 +296,19 @@ export class DiscordInteractionsEndpoint {
     }
     async send({ conversation, payload }) {
         const body = formatOutboundBody(payload);
-        const channelId = conversation.id;
-        const response = await this.#fetch(`${DISCORD_API}/channels/${channelId}/messages`, {
-            method: 'POST',
-            headers: {
-                Authorization: `Bot ${this.#options.config.token}`,
-                'Content-Type': 'application/json',
-            },
-            body: JSON.stringify(body),
-            signal: AbortSignal.timeout(OUTBOUND_TIMEOUT_MS),
-        });
-        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);
-        const snowflake = data.id ?? '';
-        return snowflake;
+        const data = await this.client.createMessage(conversation.id, body);
+        return data.id ?? '';
     }
     async recallMessage(message) {
         if (!message.id)
             return;
-        const response = await this.#fetch(`${DISCORD_API}/channels/${message.conversation.id}/messages/${message.id}`, {
-            method: 'DELETE',
-            headers: { Authorization: `Bot ${this.#options.config.token}` },
-            signal: AbortSignal.timeout(OUTBOUND_TIMEOUT_MS),
-        });
-        if (!response.ok && response.status !== 404) {
-            const text = await response.text();
-            throw new Error(`Discord recall failed (${response.status}): ${text.slice(0, 200)}`);
-        }
+        await this.client.deleteMessage(message.conversation.id, message.id);
     }
     admit(msg) {
         if (!this.#open)
             return;
         const conversation = discordInboundConversation(String(this.#options.id), msg);
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: msg.id },
             content: formatInboundContent(msg),
@@ -422,6 +333,18 @@ export class DiscordInteractionsEndpoint {
             }));
         });
     }
+    admitPlatform(event) {
+        if (!this.#open)
+            return;
+        const type = typeof event.type === 'number' ? `interaction.${event.type}` : 'interaction';
+        void this.emitPlatform(type, event).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'discord_platform_event_failed',
+                event: type,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+    }
 }
 async function resolveDiscordContent(fetch, token, reference, context) {
     if (reference.kind === 'forward') {
@@ -485,11 +408,11 @@ function toGroupId(id) {
  * DiscordGatewayEndpoint 的 EndpointManagement 语义端口（参照 qq 的工厂模式）。
  * 数据源为 discord.js SDK 缓存：guilds.cache / guild.channels.cache / guild.members。
  */
-export function createDiscordEndpointManagement(endpoint) {
+export function createDiscordEndpointManagement(requireClient) {
     return Object.freeze({
         async listGroups() {
             const groups = [];
-            for (const guild of endpoint.getClient().guilds.cache.values()) {
+            for (const guild of requireClient().guilds.cache.values()) {
                 if (!guild?.id)
                     continue;
                 groups.push({
@@ -501,7 +424,7 @@ export function createDiscordEndpointManagement(endpoint) {
         },
         async listChannels() {
             const channels = [];
-            for (const guild of endpoint.getClient().guilds.cache.values()) {
+            for (const guild of requireClient().guilds.cache.values()) {
                 if (!guild?.id)
                     continue;
                 const guildId = String(guild.id);
@@ -521,7 +444,15 @@ export function createDiscordEndpointManagement(endpoint) {
             return channels;
         },
         async listGroupMembers(groupId) {
-            return endpoint.getMembers(groupId);
+            const guild = await requireClient().guilds.fetch(groupId);
+            const members = await guild.members.fetch({ limit: 100 });
+            return [...members.values()].map((member) => ({
+                id: member.id,
+                username: member.user.username,
+                nickname: member.nickname,
+                roles: member.roles.cache.map((role) => role.id),
+                joined_at: member.joinedAt?.toISOString(),
+            }));
         },
     });
 }

package/lib/gateway.d.ts

@@ -127,6 +127,7 @@ export declare function resolveSenderRole(msg: DiscordInboundMessage): string |
 export declare function normalizeDiscordMessage(raw: unknown): DiscordInboundMessage | null;
 export declare function toMessageCreateOptions(body: DiscordOutboundBody): Promise<MessageCreateOptions>;
 export interface DiscordGatewayConnectHandlers {
+    onPlatformEvent(name: string, event: unknown): void;
     onMessage(msg: DiscordInboundMessage): void;
     onButton(interaction: DiscordButtonInbound): void;
     onGuildMemberAdd?(member: {

package/lib/gateway.js

@@ -198,6 +198,7 @@ export async function connectDiscordGatewayClient(client, config, handlers) {
     return new Promise((resolve, reject) => {
         let settled = false;
         client.on('messageCreate', (raw) => {
+            handlers.onPlatformEvent('messageCreate', raw);
             const msg = normalizeDiscordMessage(raw);
             if (!msg)
                 return;
@@ -208,6 +209,7 @@ export async function connectDiscordGatewayClient(client, config, handlers) {
             handlers.onMessage(mentionedBot ? { ...msg, mentionedBot: true } : msg);
         });
         client.on('interactionCreate', (raw) => {
+            handlers.onPlatformEvent('interactionCreate', raw);
             const interaction = raw;
             if (!interaction.isButton?.())
                 return;
@@ -225,6 +227,7 @@ export async function connectDiscordGatewayClient(client, config, handlers) {
             });
         });
         client.on('guildMemberAdd', (raw) => {
+            handlers.onPlatformEvent('guildMemberAdd', raw);
             const member = raw;
             const guildId = member.guild?.id;
             const userId = member.user?.id;
@@ -237,6 +240,7 @@ export async function connectDiscordGatewayClient(client, config, handlers) {
             });
         });
         client.on('guildMemberRemove', (raw) => {
+            handlers.onPlatformEvent('guildMemberRemove', raw);
             const member = raw;
             const guildId = member.guild?.id;
             const userId = member.user?.id;
@@ -249,6 +253,7 @@ export async function connectDiscordGatewayClient(client, config, handlers) {
             });
         });
         client.once('clientReady', () => {
+            handlers.onPlatformEvent('clientReady', client.user);
             void (async () => {
                 try {
                     if (config.defaultActivity && client.user?.setActivity) {

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 export { activityTypeCode, formatButtonContent, formatInboundContent, formatOutboundBody, resolveChannelKind, resolveDiscordConfig, senderDisplayName, type DiscordAdapterConfig, type DiscordButtonInbound, type DiscordInboundAttachment, type DiscordInboundMessage, type DiscordOutboundBody, type DiscordWireSegment, type ResolvedDiscordConfig, type ResolvedDiscordGatewayConfig, type ResolvedDiscordInteractionsConfig, } from './protocol.js';
-export { getDiscordAgentDeps, registerDiscordAgentEndpoint, setDiscordAgentDeps, type DiscordAgentDeps, type DiscordAgentEndpoint, } from './discord-agent-deps.js';
+export { discordClient, type DiscordClient, type DiscordClientEventMap, } from './client.js';
 export { checkDiscordPlatformPermit, discordGroupPermitResolver, normalizeDiscordSenderForPermit, platformPermit, } from './platform-permit.js';
 export { DiscordGatewayEndpoint, DiscordInteractionsEndpoint, type CreateDiscordClient, type DiscordClientTransport, type DiscordEndpointOptions, type DiscordInteractionsEndpointOptions, } from './endpoint.js';
 export { connectDiscordGatewayClient, defaultCreateClient, normalizeDiscordMessage, resolveSenderRole, toMessageCreateOptions, type DiscordGatewayConnectHandlers, } from './gateway.js';

package/lib/index.js

@@ -1,5 +1,5 @@
 export { activityTypeCode, formatButtonContent, formatInboundContent, formatOutboundBody, resolveChannelKind, resolveDiscordConfig, senderDisplayName, } from './protocol.js';
-export { getDiscordAgentDeps, registerDiscordAgentEndpoint, setDiscordAgentDeps, } from './discord-agent-deps.js';
+export { discordClient, } from './client.js';
 export { checkDiscordPlatformPermit, discordGroupPermitResolver, normalizeDiscordSenderForPermit, platformPermit, } from './platform-permit.js';
 export { DiscordGatewayEndpoint, DiscordInteractionsEndpoint, } from './endpoint.js';
 export { connectDiscordGatewayClient, defaultCreateClient, normalizeDiscordMessage, resolveSenderRole, toMessageCreateOptions, } from './gateway.js';

package/lib/protocol.d.ts

@@ -134,7 +134,7 @@ export declare function discordInboundConversation(endpointKey: string, msg: {
     readonly guildId?: string;
 }): ConversationRef;
 export declare function senderDisplayName(msg: DiscordInboundMessage): string;
-/** Build inbound text for MessageGateway.receive (gateway owns reply routing). */
+/** Build inbound text for OutboundMessageService.receive (gateway owns reply routing). */
 export declare function formatInboundContent(msg: DiscordInboundMessage): string;
 export declare function formatButtonContent(interaction: DiscordButtonInbound): string;
 /**

package/lib/protocol.js

@@ -77,7 +77,7 @@ export function discordInboundConversation(endpointKey, msg) {
 export function senderDisplayName(msg) {
     return msg.authorName || msg.authorId;
 }
-/** Build inbound text for MessageGateway.receive (gateway owns reply routing). */
+/** Build inbound text for OutboundMessageService.receive (gateway owns reply routing). */
 export function formatInboundContent(msg) {
     const parts = [];
     if (msg.content?.trim())

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

@@ -1,8 +1,8 @@
-import type { SideEventGateway } from '@zhin.js/core/runtime';
+import type { EndpointEventEmitter } from 'zhin.js/adapter';
 import { type getAdapterLogger } from '@zhin.js/logger';
 export interface DiscordGuildMemberSideEvent {
     readonly guildId: string;
     readonly userId: string;
     readonly userName?: string;
 }
-export declare function receiveDiscordGuildMemberSideEvent(sideEvents: SideEventGateway | undefined, configId: string, kind: 'member_increase' | 'member_decrease', event: DiscordGuildMemberSideEvent, logger: ReturnType<typeof getAdapterLogger>): void;
+export declare function receiveDiscordGuildMemberSideEvent(emit: EndpointEventEmitter, configId: string, kind: 'member_increase' | 'member_decrease', event: DiscordGuildMemberSideEvent, logger: ReturnType<typeof getAdapterLogger>): void;

package/lib/side-event-dispatch.js

@@ -1,9 +1,9 @@
 import { buildNotice, senderFromId } from '@zhin.js/core';
 import { formatCompact } from '@zhin.js/logger';
-export function receiveDiscordGuildMemberSideEvent(sideEvents, configId, kind, event, logger) {
-    if (!sideEvents)
+export function receiveDiscordGuildMemberSideEvent(emit, configId, kind, event, logger) {
+    if (!emit)
         return;
-    void sideEvents.receiveNotice(buildNotice(event, {
+    void emit('notice.receive', buildNotice(event, {
         $id: `discord:guild_member:${kind}:${event.guildId}:${event.userId}:${Date.now()}`,
         $adapter: 'discord',
         $endpoint: configId,

package/lib/webhook.d.ts

@@ -8,6 +8,7 @@ export interface DiscordInteractionsHandler {
     readonly config: ResolvedDiscordInteractionsConfig;
     readonly isOpen: boolean;
     admit(msg: DiscordInboundMessage): void;
+    admitPlatform(event: Record<string, unknown>): void;
 }
 export declare function registerDiscordInteractionRoutes(http: HttpHost, handler: DiscordInteractionsHandler): HttpRouteRegistration[];
 export declare function handleDiscordInteractionRequest(request: IncomingMessage, response: ServerResponse, handler: DiscordInteractionsHandler): Promise<void>;

package/lib/webhook.js

@@ -31,6 +31,8 @@ export async function handleDiscordInteractionRequest(request, response, handler
             return;
         }
         const interaction = JSON.parse(rawBody);
+        if (handler.isOpen)
+            handler.admitPlatform(interaction);
         if (interaction.type === INTERACTION_TYPE_PING) {
             writeJson(response, 200, { type: INTERACTION_RESPONSE_PONG });
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-discord",
-  "version": "8.0.0",
+  "version": "8.0.1",
   "description": "Zhin.js Discord adapter for Plugin Runtime (Gateway WebSocket)",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,20 +33,21 @@
   },
   "dependencies": {
     "discord.js": "^14.27.0",
-    "@zhin.js/adapter": "1.2.0",
-    "@zhin.js/core": "1.5.13",
-    "@zhin.js/host-http": "1.0.12",
+    "@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.2.0",
-    "@zhin.js/agent": "1.1.15",
-    "@zhin.js/command": "1.0.15",
-    "@zhin.js/core": "1.5.13",
-    "zhin.js": "6.0.13"
+    "@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": "6.0.14"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {
@@ -67,9 +68,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.15",
-    "@zhin.js/host-http": "1.0.12",
-    "zhin.js": "6.0.13"
+    "@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,24 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+import type { DiscordRestClient } from './endpoint.js';
+import type { DiscordClientTransport } from './gateway.js';
+
+/** Exact Client variants produced by the Gateway and Interactions Endpoints. */
+export type DiscordClient = DiscordClientTransport | DiscordRestClient;
+export type DiscordClientEventMap = Record<string, unknown>;
+
+/** Narrow an adapter Client for Gateway-only SDK operations. */
+export function requireDiscordGatewayClient(client: DiscordClient): DiscordClientTransport {
+  if ('guilds' in client && 'channels' in client) return client;
+  throw new Error('This Discord tool requires a Gateway Endpoint Client');
+}
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly discord: {
+      readonly client: DiscordClient;
+      readonly events: DiscordClientEventMap;
+    };
+  }
+}
+
+export const discordClient = defineEndpointClient<DiscordClient, DiscordClientEventMap>('discord');