@zhin.js/adapter-discord 1.1.17 → 1.1.19

package/src/gateway.ts

@@ -1,5 +1,6 @@
+import type { EndpointEventSink } from 'zhin.js/adapter';
 import { DiscordFaultProxyStrategy } from './gateway-fault-proxy.js';
-import { createReadStream, promises as fs } from 'node:fs';
+import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import {
   Client,
@@ -12,6 +13,7 @@ import {
   ButtonStyle,
   REST,
   type RESTOptions,
+  type ClientOptions,
   Routes,
   PermissionFlagsBits,
   type MessageCreateOptions,
@@ -38,85 +40,10 @@ export const DEFAULT_INTENTS = [
   GatewayIntentBits.GuildMessageReactions,
 ];
 
-/** Minimal client surface used by the endpoint (real discord.js or test mock). */
-export interface DiscordClientTransport {
-  isReady?(): boolean;
-  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<{
-          delete(): Promise<unknown>;
-          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;
-      name: string;
-      channels: {
-        cache: { values(): IterableIterator<{ id: string; name?: string; type: number }> };
-      };
-    }> };
-  };
-}
-
-export type CreateDiscordClient = (intents: readonly number[], gatewayFaultProxyUrl?: string, restOptions?: Partial<RESTOptions>) => DiscordClientTransport;
-
-export function defaultCreateClient(intents: readonly number[], gatewayFaultProxyUrl?: string, restOptions: Partial<RESTOptions> = {}): DiscordClientTransport {
-  return new Client({ rest: { ...restOptions, retries: 0, rejectOnRateLimit: () => true }, intents: [...intents], partials: [Partials.Channel], ...(gatewayFaultProxyUrl ? { ws: { buildStrategy: manager => new DiscordFaultProxyStrategy(manager, gatewayFaultProxyUrl) } } : {}) }) as unknown as DiscordClientTransport;
+/** Native SDK surface; tests inject transport below the Client rather than replacing its identity. */
+export type DiscordClientTransport = Client;
+export function discordClientOptions(intents: readonly number[], gatewayFaultProxyUrl?: string, restOptions: Partial<RESTOptions> = {}): ClientOptions {
+  return { rest: { ...restOptions, retries: 0, rejectOnRateLimit: () => true }, intents: [...intents], partials: [Partials.Channel], ...(gatewayFaultProxyUrl ? { ws: { buildStrategy: manager => new DiscordFaultProxyStrategy(manager, gatewayFaultProxyUrl) } } : {}) };
 }
 
 export function resolveSenderRole(msg: DiscordInboundMessage): string | undefined {
@@ -155,6 +82,8 @@ export function normalizeDiscordMessage(raw: unknown): DiscordInboundMessage | n
 
   return {
     id: msg.id,
+    event: raw,
+    platformSentAt: msg.createdTimestamp,
     content: msg.content ?? '',
     channelId: msg.channel.id,
     channelKind: resolveChannelKind(msg.channel.type),
@@ -208,7 +137,7 @@ export async function toMessageCreateOptions(body: DiscordOutboundBody): Promise
           name: file.name || 'attachment',
         }));
       } else if (file.file && await fileExists(file.file)) {
-        files.push(new AttachmentBuilder(createReadStream(file.file), {
+        files.push(new AttachmentBuilder(file.file, {
           name: file.name || path.basename(file.file),
         }));
       } else if (file.url) {
@@ -290,6 +219,7 @@ function decodeBase64(value: string): Buffer {
 }
 
 export interface DiscordGatewayConnectHandlers {
+  readonly receive: EndpointEventSink['run'];
   onPlatformEvent(name: string, event: unknown): void;
   onMessage(msg: DiscordInboundMessage): void;
   onButton(interaction: DiscordButtonInbound): void;
@@ -311,85 +241,96 @@ export async function connectDiscordGatewayClient(
     const releaseAbort = () => signal?.removeEventListener('abort', onAbort);
 
     client.on('messageCreate', (raw) => {
-      handlers.onPlatformEvent('messageCreate', raw);
-      const msg = normalizeDiscordMessage(raw);
-      if (!msg) return;
-      // clientReady 之后 client.user 一定可用；消息事件只会在此之后到达
-      const botId = client.user?.id;
-      const mentions = (raw as DiscordMessage).mentions;
-      const mentionedBot = !!botId && mentions?.users?.has?.(botId) === true;
-      handlers.onMessage(mentionedBot ? { ...msg, mentionedBot: true } : msg);
+      void handlers.receive(() => {
+        handlers.onPlatformEvent('messageCreate', raw);
+        const msg = normalizeDiscordMessage(raw);
+        if (!msg) return;
+        // clientReady 之后 client.user 一定可用；消息事件只会在此之后到达
+        const botId = client.user?.id;
+        const mentions = (raw as DiscordMessage).mentions;
+        const mentionedBot = !!botId && mentions?.users?.has?.(botId) === true;
+        handlers.onMessage(mentionedBot ? { ...msg, mentionedBot: true } : msg);
+      }).catch(() => logger.debug('Native callback was not admitted'));
     });
 
     client.on('interactionCreate', (raw) => {
-      handlers.onPlatformEvent('interactionCreate', raw);
-      const interaction = raw as {
-        isButton?(): boolean;
-        deferUpdate?(): Promise<unknown>;
-        id: string;
-        customId: string;
-        channel?: { id: string; type: number } | null;
-        channelId?: string;
-        guildId?: string | null;
-        user: { id: string; username?: string; displayName?: string };
-        message?: { id: string };
-      };
-      const isButton = interaction.isButton?.() === true;
-      logger.info(formatCompact({ op: 'discord_gateway_interaction_received', button: isButton, cachedChannel: !!interaction.channel, hasChannelId: !!interaction.channelId }));
-      if (!isButton) return;
-      void interaction.deferUpdate?.().then(() => {
-        logger.info(formatCompact({ op: 'discord_gateway_button_ack', status: 'confirmed' }));
-      }).catch(() => {
-        // SDK errors may contain token-bearing callback URLs; log no raw error.
-        logger.warn(formatCompact({ op: 'discord_gateway_button_ack', status: 'failed' }));
-      });
-      const channelId = interaction.channelId ?? interaction.channel?.id;
-      if (!channelId) {
-        logger.warn(formatCompact({ op: 'discord_gateway_button_dropped', reason: 'missing_channel_id' }));
-        return;
-      }
-      handlers.onButton({
-        id: interaction.id,
-        customId: interaction.customId,
-        channelId,
-        channelKind: interaction.channel ? resolveChannelKind(interaction.channel.type) : interaction.guildId ? 'channel' : 'private',
-        ...(interaction.guildId ? { guildId: interaction.guildId } : {}),
-        userId: interaction.user.id,
-        userName: interaction.user.username || interaction.user.displayName || interaction.user.id,
-        sourceMessageId: interaction.message?.id,
-      });
+      void handlers.receive(() => {
+        handlers.onPlatformEvent('interactionCreate', raw);
+        const interaction = raw as {
+          isButton?(): boolean;
+          deferUpdate?(): Promise<unknown>;
+          id: string;
+          customId: string;
+          channel?: { id: string; type: number } | null;
+          channelId?: string;
+          guildId?: string | null;
+          user: { id: string; username?: string; displayName?: string };
+          message?: { id: string };
+        };
+        const isButton = interaction.isButton?.() === true;
+        logger.info(formatCompact({ op: 'discord_gateway_interaction_received', button: isButton, cachedChannel: !!interaction.channel, hasChannelId: !!interaction.channelId }));
+        if (!isButton) return;
+        const ack = interaction.deferUpdate?.().then(() => {
+          logger.info(formatCompact({ op: 'discord_gateway_button_ack', status: 'confirmed' }));
+        }).catch(() => {
+          // SDK errors may contain token-bearing callback URLs; log no raw error.
+          logger.warn(formatCompact({ op: 'discord_gateway_button_ack', status: 'failed' }));
+        });
+        const channelId = interaction.channelId ?? interaction.channel?.id;
+        if (!channelId) {
+          logger.warn(formatCompact({ op: 'discord_gateway_button_dropped', reason: 'missing_channel_id' }));
+          return ack ? awaitOwnedAck(ack, signal) : undefined;
+        }
+        handlers.onButton({
+          event: raw,
+          platformSentAt: raw.createdTimestamp,
+          id: interaction.id,
+          customId: interaction.customId,
+          channelId,
+          channelKind: interaction.channel ? resolveChannelKind(interaction.channel.type) : interaction.guildId ? 'channel' : 'private',
+          ...(interaction.guildId ? { guildId: interaction.guildId } : {}),
+          userId: interaction.user.id,
+          userName: interaction.user.username || interaction.user.displayName || interaction.user.id,
+          sourceMessageId: interaction.message?.id,
+        });
+        return ack ? awaitOwnedAck(ack, signal) : undefined;
+      }).catch(() => logger.debug('Native callback was not admitted'));
     });
 
     client.on('guildMemberAdd', (raw) => {
-      handlers.onPlatformEvent('guildMemberAdd', raw);
-      const member = raw as {
-        guild?: { id?: string };
-        user?: { id?: string; username?: string; displayName?: string };
-      };
-      const guildId = member.guild?.id;
-      const userId = member.user?.id;
-      if (!guildId || !userId) return;
-      handlers.onGuildMemberAdd?.({
-        guildId,
-        userId,
-        userName: member.user?.username || member.user?.displayName,
-      });
+      void handlers.receive(() => {
+        handlers.onPlatformEvent('guildMemberAdd', raw);
+        const member = raw as {
+          guild?: { id?: string };
+          user?: { id?: string; username?: string; displayName?: string };
+        };
+        const guildId = member.guild?.id;
+        const userId = member.user?.id;
+        if (!guildId || !userId) return;
+        handlers.onGuildMemberAdd?.({
+          guildId,
+          userId,
+          userName: member.user?.username || member.user?.displayName,
+        });
+      }).catch(() => logger.debug('Native callback was not admitted'));
     });
 
     client.on('guildMemberRemove', (raw) => {
-      handlers.onPlatformEvent('guildMemberRemove', raw);
-      const member = raw as {
-        guild?: { id?: string };
-        user?: { id?: string; username?: string; displayName?: string };
-      };
-      const guildId = member.guild?.id;
-      const userId = member.user?.id;
-      if (!guildId || !userId) return;
-      handlers.onGuildMemberRemove?.({
-        guildId,
-        userId,
-        userName: member.user?.username || member.user?.displayName,
-      });
+      void handlers.receive(() => {
+        handlers.onPlatformEvent('guildMemberRemove', raw);
+        const member = raw as {
+          guild?: { id?: string };
+          user?: { id?: string; username?: string; displayName?: string };
+        };
+        const guildId = member.guild?.id;
+        const userId = member.user?.id;
+        if (!guildId || !userId) return;
+        handlers.onGuildMemberRemove?.({
+          guildId,
+          userId,
+          userName: member.user?.username || member.user?.displayName,
+        });
+      }).catch(() => logger.debug('Native callback was not admitted'));
     });
 
     client.once('clientReady', () => {
@@ -455,3 +396,14 @@ export async function connectDiscordGatewayClient(
     });
   });
 }
+
+/** Logical cancellation only; the native SDK still owns its already-started ACK. */
+function awaitOwnedAck<T>(operation: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return operation;
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener('abort', abort, { once: true });
+    void operation.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+    if (signal.aborted) abort();
+  });
+}

package/src/index.ts

@@ -19,7 +19,6 @@ export {
 } from './protocol.js';
 
 export {
-  discordClient,
   requireDiscordGatewayClient,
   type DiscordClient,
   type DiscordClientEventMap,
@@ -35,7 +34,6 @@ export {
 export {
   DiscordGatewayEndpoint,
   DiscordInteractionsEndpoint,
-  type CreateDiscordClient,
   type DiscordClientTransport,
   type DiscordEndpointOptions,
   type DiscordInteractionsEndpointOptions,
@@ -43,7 +41,7 @@ export {
 
 export {
   connectDiscordGatewayClient,
-  defaultCreateClient,
+  discordClientOptions,
   normalizeDiscordMessage,
   resolveSenderRole,
   toMessageCreateOptions,
@@ -55,3 +53,4 @@ export {
   registerDiscordInteractionRoutes,
   type DiscordInteractionsHandler,
 } from './webhook.js';
+export { DiscordAdapter } from './adapter.js';

package/src/protocol.ts

@@ -72,6 +72,8 @@ export interface DiscordInboundAttachment {
 }
 
 export interface DiscordInboundMessage {
+  readonly event?: unknown;
+  readonly platformSentAt?: number;
   readonly id: string;
   readonly content: string;
   readonly channelId: string;
@@ -92,6 +94,8 @@ export interface DiscordInboundMessage {
 }
 
 export interface DiscordButtonInbound {
+  readonly event?: unknown;
+  readonly platformSentAt?: number;
   readonly guildId?: string;
   readonly id: string;
   readonly customId: string;
@@ -491,6 +495,7 @@ export function interactionToInboundMessage(interaction: Record<string, unknown>
   const user = (interaction.member as { user?: Record<string, unknown> } | undefined)?.user
     ?? (interaction.user as Record<string, unknown> | undefined);
   return {
+    event: interaction,
     id: String(interaction.id),
     content: formatSlashCommandContent(interaction),
     channelId: String(interaction.channel_id ?? ''),

package/src/webhook.ts

@@ -1,8 +1,9 @@
+import { endpointSpec, type Endpoint } from 'zhin.js/adapter';
 /**
  * Discord interactions HTTP: signature → parse → admit.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import { createMessages, type Locale } from 'zhin.js/i18n';
+import { createMessages } from 'zhin.js/i18n';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import {
@@ -25,11 +26,10 @@ const INTERACTION_RESPONSE_CHANNEL_MESSAGE_WITH_SOURCE = 4;
 /** EPHEHEMERAL — 仅发起者可见（对齐旧 endpoint-interactions 默认响应）。 */
 const INTERACTION_FLAG_EPHEMERAL = 64;
 
-export interface DiscordInteractionsHandler {
+export interface DiscordInteractionsHandler extends Endpoint {
   readonly config: ResolvedDiscordInteractionsConfig;
   readonly isOpen: boolean;
   admit(msg: DiscordInboundMessage): void;
-  resolveLocale?(senderId: string): Promise<Locale | undefined>;
   admitButton(interaction: DiscordButtonInbound): void;
   admitPlatform(event: Record<string, unknown>): void;
 }
@@ -71,42 +71,52 @@ export async function handleDiscordInteractionRequest(
       return;
     }
     const interaction = JSON.parse(rawBody) as Record<string, unknown>;
-    if (handler.isOpen) handler.admitPlatform(interaction);
+    if (!interaction || interaction.application_id !== handler.config.applicationId) {
+      response.writeHead(401, { 'Content-Type': 'text/plain' });
+      response.end('Unauthorized');
+      return;
+    }
+    // A verified protocol challenge is not a business message and keeps its immediate ACK.
     if (interaction.type === INTERACTION_TYPE_PING) {
+      if (handler.isOpen) void handler[endpointSpec].events.run(() => handler.admitPlatform(interaction))
+        .catch(() => logger.debug('Protocol event dispatch did not complete'));
       writeJson(response, 200, { type: INTERACTION_RESPONSE_PONG });
       return;
     }
-    if (interaction.type === 3) {
-      const data = interaction.data as { component_type?: number; custom_id?: string } | undefined;
-      if (data?.component_type === 2 && typeof data.custom_id === 'string') {
-        if (!handler.isOpen) { response.writeHead(503); response.end('Unavailable'); return; }
+    await handler[endpointSpec].events.run(async () => {
+      if (handler.isOpen) handler.admitPlatform(interaction);
+      if (interaction.type === 3) {
+        const data = interaction.data as { component_type?: number; custom_id?: string } | undefined;
+        if (data?.component_type === 2 && typeof data.custom_id === 'string') {
+          if (!handler.isOpen) { response.writeHead(503); response.end('Unavailable'); return; }
+          const message = interactionToInboundMessage(interaction);
+          handler.admitButton({ event: interaction, id: message.id, customId: data.custom_id, channelId: message.channelId, channelKind: message.channelKind, userId: message.authorId, userName: message.authorName, ...(message.guildId ? { guildId: message.guildId } : {}), sourceMessageId: (interaction.message as { id?: string } | undefined)?.id });
+          writeJson(response, 200, { type: 6 });
+          return;
+        }
+      }
+      if (interaction.type === INTERACTION_TYPE_APPLICATION_COMMAND) {
         const message = interactionToInboundMessage(interaction);
-        handler.admitButton({ id: message.id, customId: data.custom_id, channelId: message.channelId, channelKind: message.channelKind, userId: message.authorId, userName: message.authorName, ...(message.guildId ? { guildId: message.guildId } : {}), sourceMessageId: (interaction.message as { id?: string } | undefined)?.id });
-        writeJson(response, 200, { type: 6 });
+        if (handler.isOpen) {
+          handler.admit(message);
+        }
+        const locale = await handler[endpointSpec].resolveLocale(message.authorId);
+        // 即时响应（type 4）：defer(type 5) 需要 followup PATCH，未实现会让用户端一直转圈
+        const commandName = String(
+          (interaction.data as { name?: unknown } | undefined)?.name ?? '',
+        );
+        writeJson(response, 200, {
+          type: INTERACTION_RESPONSE_CHANNEL_MESSAGE_WITH_SOURCE,
+          data: {
+            content: messages(locale, 'processing', { command: commandName }),
+            flags: INTERACTION_FLAG_EPHEMERAL,
+          },
+        });
         return;
       }
-    }
-    if (interaction.type === INTERACTION_TYPE_APPLICATION_COMMAND) {
-      const message = interactionToInboundMessage(interaction);
-      if (handler.isOpen) {
-        handler.admit(message);
-      }
-      const locale = await handler.resolveLocale?.(message.authorId);
-      // 即时响应（type 4）：defer(type 5) 需要 followup PATCH，未实现会让用户端一直转圈
-      const commandName = String(
-        (interaction.data as { name?: unknown } | undefined)?.name ?? '',
-      );
-      writeJson(response, 200, {
-        type: INTERACTION_RESPONSE_CHANNEL_MESSAGE_WITH_SOURCE,
-        data: {
-          content: messages(locale, 'processing', { command: commandName }),
-          flags: INTERACTION_FLAG_EPHEMERAL,
-        },
-      });
-      return;
-    }
-    response.writeHead(400, { 'Content-Type': 'text/plain' });
-    response.end('Unsupported interaction type');
+      response.writeHead(400, { 'Content-Type': 'text/plain' });
+      response.end('Unsupported interaction type');
+    });
   } catch (error) {
     logger.error('Discord interactions error:', error);
     if (!response.headersSent) {

package/lib/discord-runtime-state.d.ts

@@ -1 +0,0 @@
-export declare const discordRuntimeStateToken: import("zhin.js").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/discord-runtime-state.js

@@ -1,6 +0,0 @@
-/**
- * Discord 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `discord endpoint` 命令共享（同一 owner generation）。
- */
-import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
-export const discordRuntimeStateToken = defineEndpointRuntimeStateToken('discord');

package/src/discord-runtime-state.ts

@@ -1,7 +0,0 @@
-/**
- * Discord 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `discord endpoint` 命令共享（同一 owner generation）。
- */
-import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
-
-export const discordRuntimeStateToken = defineEndpointRuntimeStateToken('discord');