@openclaw/discord 2026.3.13 → 2026.5.2-beta.1

package/src/internal/interactions.ts

@@ -0,0 +1,378 @@
+import {
+  ComponentType,
+  InteractionResponseType,
+  InteractionType,
+  type APIApplicationCommandInteraction,
+  type APIApplicationCommandInteractionDataOption,
+  type APIChannel,
+  type APIInteraction,
+  type APIInteractionDataResolvedChannel,
+  type APIMessage,
+  type APIMessageComponentInteraction,
+  type APIModalSubmitInteraction,
+  type APIUser,
+} from "discord-api-types/v10";
+import {
+  createInteractionCallback,
+  createWebhookMessage,
+  deleteWebhookMessage,
+  editWebhookMessage,
+  getWebhookMessage,
+} from "./api.js";
+import { OptionsHandler } from "./interaction-options.js";
+import {
+  InteractionResponseController,
+  needsComponentsV2Query,
+  type InteractionResponseState,
+} from "./interaction-response.js";
+import { extractModalFields, ModalFields } from "./modal-fields.js";
+import { serializePayload, type MessagePayload } from "./payload.js";
+import { assertDiscordInteractionPayload } from "./schemas.js";
+import {
+  channelFactory,
+  Guild,
+  Message,
+  User,
+  type DiscordChannel,
+  type StructureClient,
+} from "./structures.js";
+
+export { OptionsHandler } from "./interaction-options.js";
+export { ModalFields } from "./modal-fields.js";
+
+type InteractionClient = StructureClient & {
+  options: { clientId: string };
+  componentHandler: {
+    waitForMessageComponent(
+      message: Message,
+      timeoutMs: number,
+    ): Promise<
+      | { success: true; customId: string; message: Message; values?: string[] }
+      | { success: false; message: Message; reason: "timed out" }
+    >;
+  };
+  fetchChannel(id: string): Promise<DiscordChannel>;
+};
+
+type Modal = {
+  serialize: () => unknown;
+};
+
+type ComponentData = Record<string, unknown>;
+
+export type RawInteraction = APIInteraction & {
+  token: string;
+  member?: { user?: APIUser; roles?: string[] };
+  guild_id?: string;
+  channel_id?: string;
+  channel?: unknown;
+  data?: {
+    custom_id?: string;
+    component_type?: number;
+    values?: string[];
+    components?: unknown[];
+    options?: APIApplicationCommandInteractionDataOption[];
+    resolved?: {
+      channels?: Record<string, APIInteractionDataResolvedChannel>;
+      roles?: Record<string, { id: string; name?: string }>;
+      users?: Record<string, { id: string; username?: string; discriminator?: string }>;
+    };
+  };
+  message?: unknown;
+};
+
+type CommandRawInteraction = APIApplicationCommandInteraction & RawInteraction;
+type MessageComponentRawInteraction = APIMessageComponentInteraction & RawInteraction;
+type ModalSubmitRawInteraction = APIModalSubmitInteraction & RawInteraction;
+
+function toCommandRawInteraction(rawData: RawInteraction): CommandRawInteraction {
+  return rawData as CommandRawInteraction;
+}
+
+function toMessageComponentRawInteraction(rawData: RawInteraction): MessageComponentRawInteraction {
+  return rawData as MessageComponentRawInteraction;
+}
+
+function toModalSubmitRawInteraction(rawData: RawInteraction): ModalSubmitRawInteraction {
+  return rawData as ModalSubmitRawInteraction;
+}
+
+function readInteractionUser(rawData: RawInteraction, client: InteractionClient): User | null {
+  const directUser = "user" in rawData ? rawData.user : undefined;
+  if (directUser && typeof directUser === "object" && "id" in directUser) {
+    return new User(client, directUser);
+  }
+  const memberUser = rawData.member?.user;
+  if (memberUser && typeof memberUser === "object" && typeof memberUser.id === "string") {
+    const user = { ...memberUser } as APIUser;
+    if (typeof user.username !== "string") {
+      user.username = "";
+    }
+    return new User(client, user);
+  }
+  return null;
+}
+
+export class BaseInteraction {
+  readonly id: string;
+  readonly token: string;
+  readonly user: User | null;
+  readonly userId: string;
+  readonly guild: Guild | null;
+  readonly channel: DiscordChannel | null;
+  message: Message | null = null;
+  private readonly response = new InteractionResponseController();
+
+  constructor(
+    public client: InteractionClient,
+    public rawData: RawInteraction,
+  ) {
+    this.id = rawData.id;
+    this.token = rawData.token;
+    this.user = readInteractionUser(rawData, client);
+    this.userId = this.user?.id ?? "";
+    this.guild = rawData.guild_id ? new Guild<true>(client, rawData.guild_id) : null;
+    this.channel =
+      "channel" in rawData && rawData.channel
+        ? channelFactory(client, rawData.channel as APIChannel)
+        : null;
+  }
+
+  get acknowledged(): boolean {
+    return this.response.acknowledged;
+  }
+
+  get responseState(): InteractionResponseState {
+    return this.response.state;
+  }
+
+  set responseState(nextState: InteractionResponseState) {
+    this.response.state = nextState;
+  }
+
+  protected async callback(type: InteractionResponseType, data?: unknown) {
+    this.response.recordCallback(type);
+    return await createInteractionCallback(
+      this.client.rest,
+      this.id,
+      this.token,
+      data === undefined ? { type } : { type, data },
+    );
+  }
+
+  async reply(payload: MessagePayload): Promise<unknown> {
+    const action = this.response.nextReplyAction();
+    if (action === "edit") {
+      return await this.editReply(payload);
+    }
+    if (action === "follow-up") {
+      return await this.followUp(payload);
+    }
+    return await this.callback(
+      InteractionResponseType.ChannelMessageWithSource,
+      serializePayload(payload),
+    );
+  }
+
+  async defer(options?: { ephemeral?: boolean }): Promise<unknown> {
+    return await this.callback(
+      InteractionResponseType.DeferredChannelMessageWithSource,
+      options?.ephemeral ? { flags: 64 } : undefined,
+    );
+  }
+
+  async acknowledge(): Promise<unknown> {
+    return await this.defer();
+  }
+
+  async editReply(payload: MessagePayload): Promise<unknown> {
+    const body = serializePayload(payload);
+    const query = needsComponentsV2Query(body) ? { with_components: true } : undefined;
+    const result = query
+      ? await editWebhookMessage(
+          this.client.rest,
+          this.client.options.clientId,
+          this.token,
+          "@original",
+          { body },
+          query,
+        )
+      : await editWebhookMessage(
+          this.client.rest,
+          this.client.options.clientId,
+          this.token,
+          "@original",
+          { body },
+        );
+    this.response.recordReplyEdit();
+    return result;
+  }
+
+  async deleteReply(): Promise<unknown> {
+    return await deleteWebhookMessage(
+      this.client.rest,
+      this.client.options.clientId,
+      this.token,
+      "@original",
+    );
+  }
+
+  async fetchReply(): Promise<unknown> {
+    return await getWebhookMessage(
+      this.client.rest,
+      this.client.options.clientId,
+      this.token,
+      "@original",
+    );
+  }
+
+  async replyAndWaitForComponent(payload: MessagePayload, timeoutMs = 300_000) {
+    const result = await this.reply(payload);
+    const rawMessage = isRawMessage(result) ? result : await this.fetchReply();
+    if (!isRawMessage(rawMessage)) {
+      throw new Error("Discord interaction reply did not return a message");
+    }
+    const message = new Message(this.client, rawMessage as APIMessage);
+    return await this.client.componentHandler.waitForMessageComponent(message, timeoutMs);
+  }
+
+  async followUp(payload: MessagePayload): Promise<unknown> {
+    const body = serializePayload(payload);
+    return await createWebhookMessage(
+      this.client.rest,
+      this.client.options.clientId,
+      this.token,
+      { body },
+      needsComponentsV2Query(body) ? { with_components: true } : undefined,
+    );
+  }
+}
+
+export class CommandInteraction extends BaseInteraction {
+  readonly options: OptionsHandler;
+  constructor(
+    client: InteractionClient,
+    rawData: APIApplicationCommandInteraction & RawInteraction,
+  ) {
+    super(client, rawData);
+    this.options = new OptionsHandler(
+      rawData.data.options,
+      client,
+      rawData.data.resolved?.channels,
+    );
+  }
+}
+
+export class AutocompleteInteraction extends CommandInteraction {
+  async respond(choices: Array<{ name: string; value: string | number }>): Promise<unknown> {
+    return await this.callback(InteractionResponseType.ApplicationCommandAutocompleteResult, {
+      choices,
+    });
+  }
+}
+
+export class BaseComponentInteraction extends BaseInteraction {
+  readonly values: string[];
+
+  constructor(client: InteractionClient, rawData: APIMessageComponentInteraction & RawInteraction) {
+    super(client, rawData);
+    this.message =
+      rawData.message && typeof rawData.message === "object"
+        ? new Message(client, rawData.message)
+        : null;
+    this.values = Array.isArray(rawData.data.values) ? rawData.data.values.map(String) : [];
+  }
+
+  async update(payload: MessagePayload): Promise<unknown> {
+    return await this.callback(InteractionResponseType.UpdateMessage, serializePayload(payload));
+  }
+  async acknowledge(): Promise<unknown> {
+    return await this.callback(InteractionResponseType.DeferredMessageUpdate);
+  }
+  async showModal(modal: Modal): Promise<unknown> {
+    return await this.callback(InteractionResponseType.Modal, modal.serialize());
+  }
+
+  async editAndWaitForComponent(
+    payload: MessagePayload,
+    message: Message | null = this.message,
+    timeoutMs = 300_000,
+  ) {
+    if (!message) {
+      return null;
+    }
+    const editedMessage = await message.edit(payload);
+    return await this.client.componentHandler.waitForMessageComponent(editedMessage, timeoutMs);
+  }
+}
+
+export class ButtonInteraction extends BaseComponentInteraction {}
+export class StringSelectMenuInteraction extends BaseComponentInteraction {}
+export class UserSelectMenuInteraction extends BaseComponentInteraction {}
+export class RoleSelectMenuInteraction extends BaseComponentInteraction {}
+export class MentionableSelectMenuInteraction extends BaseComponentInteraction {}
+export class ChannelSelectMenuInteraction extends BaseComponentInteraction {}
+
+export class ModalInteraction extends BaseInteraction {
+  readonly fields: ModalFields;
+  constructor(client: InteractionClient, rawData: APIModalSubmitInteraction & RawInteraction) {
+    super(client, rawData);
+    this.fields = new ModalFields(
+      extractModalFields(rawData.data.components ?? []),
+      rawData.data.resolved,
+      client,
+    );
+  }
+  async acknowledge(): Promise<unknown> {
+    return await this.callback(InteractionResponseType.DeferredMessageUpdate);
+  }
+}
+
+export function createInteraction(client: InteractionClient, rawData: RawInteraction) {
+  assertDiscordInteractionPayload(rawData);
+  if (rawData.type === InteractionType.ApplicationCommandAutocomplete) {
+    return new AutocompleteInteraction(client, toCommandRawInteraction(rawData));
+  }
+  if (rawData.type === InteractionType.ApplicationCommand) {
+    return new CommandInteraction(client, toCommandRawInteraction(rawData));
+  }
+  if (rawData.type === InteractionType.ModalSubmit) {
+    return new ModalInteraction(client, toModalSubmitRawInteraction(rawData));
+  }
+  if (rawData.type === InteractionType.MessageComponent) {
+    const componentRawData = toMessageComponentRawInteraction(rawData);
+    switch (rawData.data?.component_type) {
+      case ComponentType.Button:
+        return new ButtonInteraction(client, componentRawData);
+      case ComponentType.StringSelect:
+        return new StringSelectMenuInteraction(client, componentRawData);
+      case ComponentType.UserSelect:
+        return new UserSelectMenuInteraction(client, componentRawData);
+      case ComponentType.RoleSelect:
+        return new RoleSelectMenuInteraction(client, componentRawData);
+      case ComponentType.MentionableSelect:
+        return new MentionableSelectMenuInteraction(client, componentRawData);
+      case ComponentType.ChannelSelect:
+        return new ChannelSelectMenuInteraction(client, componentRawData);
+      default:
+        return new BaseComponentInteraction(client, componentRawData);
+    }
+  }
+  return new BaseInteraction(client, rawData);
+}
+
+export function parseComponentInteractionData(
+  component: { customIdParser: (id: string) => { data: ComponentData } },
+  customId: string,
+): ComponentData {
+  return component.customIdParser(customId).data;
+}
+
+function isRawMessage(value: unknown): value is { id: string; channel_id: string } {
+  return (
+    Boolean(value) &&
+    typeof value === "object" &&
+    typeof (value as { id?: unknown }).id === "string" &&
+    typeof (value as { channel_id?: unknown }).channel_id === "string"
+  );
+}

package/src/internal/listeners.ts

@@ -0,0 +1,85 @@
+import {
+  GatewayDispatchEvents,
+  type APIMessage,
+  type APIReaction,
+  type GatewayPresenceUpdateDispatchData,
+  type GatewayThreadUpdateDispatchData,
+} from "discord-api-types/v10";
+import type { Client } from "./client.js";
+import { Guild, Message, User } from "./structures.js";
+
+export type DiscordMessageDispatchData = {
+  id?: string;
+  channel_id: string;
+  channelId?: string;
+  guild_id?: string;
+  message: Message;
+  author: User | null;
+  member?: { roles?: string[]; nick?: string | null; nickname?: string | null };
+  rawMember?: { roles?: string[]; nick?: string | null; nickname?: string | null };
+  guild?: Guild | null;
+  channel?: unknown;
+};
+
+export type DiscordReactionDispatchData = {
+  user_id?: string;
+  channel_id: string;
+  message_id: string;
+  guild_id?: string;
+  emoji: APIReaction["emoji"];
+  burst?: boolean;
+  type?: number;
+  user: User;
+  rawMember?: { roles?: string[] };
+  guild?: Guild | null;
+  message: Message<true> | { fetch(): Promise<{ author?: User | null }> };
+  rawMessage?: APIMessage;
+};
+
+export abstract class BaseListener {
+  abstract readonly type: string;
+  abstract handle(data: unknown, client: Client): Promise<void> | void;
+}
+
+export abstract class ReadyListener extends BaseListener {
+  readonly type = GatewayDispatchEvents.Ready;
+}
+
+export abstract class ResumedListener extends BaseListener {
+  readonly type = GatewayDispatchEvents.Resumed;
+}
+
+export abstract class MessageCreateListener extends BaseListener {
+  readonly type = GatewayDispatchEvents.MessageCreate;
+  abstract override handle(data: DiscordMessageDispatchData, client: Client): Promise<void> | void;
+}
+
+export abstract class InteractionCreateListener extends BaseListener {
+  readonly type = GatewayDispatchEvents.InteractionCreate;
+}
+
+export abstract class MessageReactionAddListener extends BaseListener {
+  readonly type = GatewayDispatchEvents.MessageReactionAdd;
+  abstract override handle(data: DiscordReactionDispatchData, client: Client): Promise<void> | void;
+}
+
+export abstract class MessageReactionRemoveListener extends BaseListener {
+  readonly type = GatewayDispatchEvents.MessageReactionRemove;
+  abstract override handle(data: DiscordReactionDispatchData, client: Client): Promise<void> | void;
+}
+
+export abstract class PresenceUpdateListener extends BaseListener {
+  readonly type = GatewayDispatchEvents.PresenceUpdate;
+  abstract override handle(
+    data: GatewayPresenceUpdateDispatchData,
+    client: Client,
+  ): Promise<void> | void;
+}
+
+export abstract class ThreadUpdateListener extends BaseListener {
+  readonly type = GatewayDispatchEvents.ThreadUpdate;
+  abstract override handle(
+    data: GatewayThreadUpdateDispatchData,
+    client: Client,
+  ): Promise<void> | void;
+}

package/src/internal/live-smoke.live.test.ts

@@ -0,0 +1,26 @@
+import { Routes } from "discord-api-types/v10";
+import { isLiveTestEnabled } from "openclaw/plugin-sdk/test-env";
+import { describe, expect, it } from "vitest";
+import { parseApplicationIdFromToken } from "../probe.js";
+import { RequestClient } from "./rest.js";
+
+const TOKEN = process.env.DISCORD_BOT_TOKEN ?? "";
+const LIVE = isLiveTestEnabled(["DISCORD_LIVE_TEST"]) && TOKEN.length > 0;
+const describeLive = LIVE ? describe : describe.skip;
+
+describeLive("discord live smoke", () => {
+  it("resolves bot identity and gateway metadata", async () => {
+    const rest = new RequestClient(TOKEN, { queueRequests: false, timeout: 15_000 });
+
+    const me = (await rest.get(Routes.user("@me"))) as { id?: string; bot?: boolean };
+    expect(me.bot).toBe(true);
+    expect(me.id).toBe(parseApplicationIdFromToken(TOKEN));
+
+    const gateway = (await rest.get(Routes.gatewayBot())) as {
+      url?: string;
+      session_start_limit?: { max_concurrency?: number };
+    };
+    expect(gateway.url).toMatch(/^wss:\/\//);
+    expect(gateway.session_start_limit?.max_concurrency).toBeGreaterThan(0);
+  });
+});

package/src/internal/modal-fields.ts

@@ -0,0 +1,95 @@
+import { type APIRole, type APIUser } from "discord-api-types/v10";
+import { Role, User, type StructureClient } from "./structures.js";
+
+type ModalResolvedData = {
+  roles?: Record<string, { id: string; name?: string }>;
+  users?: Record<string, { id: string; username?: string; discriminator?: string }>;
+};
+
+export function extractModalFields(components: unknown[]): Record<string, string | string[]> {
+  const out: Record<string, string | string[]> = {};
+  for (const component of flattenModalComponents(components)) {
+    const raw = component as { custom_id?: unknown; value?: unknown; values?: unknown };
+    if (typeof raw.custom_id !== "string") {
+      continue;
+    }
+    if (Array.isArray(raw.values)) {
+      out[raw.custom_id] = raw.values.map(String);
+    } else if (
+      typeof raw.value === "string" ||
+      typeof raw.value === "number" ||
+      typeof raw.value === "boolean"
+    ) {
+      out[raw.custom_id] = String(raw.value);
+    }
+  }
+  return out;
+}
+
+function flattenModalComponents(components: unknown[]): unknown[] {
+  const out: unknown[] = [];
+  for (const entry of components) {
+    if (!entry || typeof entry !== "object") {
+      continue;
+    }
+    const component = entry as { component?: unknown; components?: unknown[] };
+    if (component.component && typeof component.component === "object") {
+      out.push(component.component);
+    }
+    if (Array.isArray(component.components)) {
+      out.push(...flattenModalComponents(component.components));
+    }
+    out.push(entry);
+  }
+  return out;
+}
+
+export class ModalFields {
+  constructor(
+    private values: Record<string, string | string[]>,
+    private resolved?: ModalResolvedData,
+    private client?: StructureClient,
+  ) {}
+
+  private value(id: string, required: boolean): string | string[] | undefined {
+    const value = this.values[id];
+    if (required && (value === undefined || (Array.isArray(value) && value.length === 0))) {
+      throw new Error(`Missing required modal field ${id}`);
+    }
+    return value;
+  }
+
+  getText(id: string, required = false): string | null {
+    const value = this.value(id, required);
+    return typeof value === "string" ? value : null;
+  }
+
+  getStringSelect(id: string, required = false): string[] {
+    const value = this.value(id, required);
+    if (Array.isArray(value)) {
+      return value;
+    }
+    return typeof value === "string" ? [value] : [];
+  }
+
+  getRoleSelect(id: string, required = false): Role[] {
+    const values = this.getStringSelect(id, required);
+    return values.map((roleId) => {
+      const raw = this.resolved?.roles?.[roleId];
+      return raw
+        ? new Role(this.client!, { id: roleId, name: raw.name ?? "" } as APIRole)
+        : new Role<true>(this.client!, roleId);
+    });
+  }
+
+  getUserSelect(id: string, required = false): User[] {
+    const values = this.getStringSelect(id, required);
+    return values.map((userId) => {
+      const raw = this.resolved?.users?.[userId];
+      return new User(this.client!, {
+        id: userId,
+        username: raw?.username ?? "",
+      } as APIUser);
+    });
+  }
+}

package/src/internal/payload.ts

@@ -0,0 +1,69 @@
+import { MessageFlags, type APIEmbed } from "discord-api-types/v10";
+import { Embed } from "./embeds.js";
+
+export type MessagePayloadFile = {
+  name: string;
+  data: Blob | Uint8Array | ArrayBuffer;
+  description?: string;
+  duration_secs?: number;
+  waveform?: string;
+};
+export type MessagePayloadObject = {
+  content?: string;
+  embeds?: Array<APIEmbed | Embed>;
+  components?: TopLevelComponents[];
+  allowedMentions?: unknown;
+  allowed_mentions?: unknown;
+  flags?: number;
+  tts?: boolean;
+  files?: MessagePayloadFile[];
+  poll?: unknown;
+  ephemeral?: boolean;
+  stickers?: [string, string, string] | [string, string] | [string];
+};
+export type MessagePayload = string | MessagePayloadObject;
+export type TopLevelComponents = {
+  isV2?: boolean;
+  serialize: () => unknown;
+};
+
+function clean<T extends Record<string, unknown>>(value: T): T {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)) as T;
+}
+
+function serializeAnyComponent(component: { serialize: () => unknown }): unknown {
+  return component.serialize();
+}
+
+function payloadHasV2Components(payload: MessagePayloadObject): boolean {
+  return Boolean(payload.components?.some((component) => component.isV2));
+}
+
+function normalizePayloadFlags(payload: MessagePayloadObject): number | undefined {
+  const flags = payload.ephemeral ? (payload.flags ?? 0) | MessageFlags.Ephemeral : payload.flags;
+  if (!payloadHasV2Components(payload)) {
+    return flags;
+  }
+  if (payload.content || payload.embeds?.length) {
+    throw new Error("Discord Components V2 payloads cannot include content or embeds");
+  }
+  return (flags ?? 0) | MessageFlags.IsComponentsV2;
+}
+
+export function serializePayload(payload: MessagePayload) {
+  if (typeof payload === "string") {
+    return { content: payload };
+  }
+  const flags = normalizePayloadFlags(payload);
+  return clean({
+    content: payload.content,
+    embeds: payload.embeds?.map((entry) => ("serialize" in entry ? entry.serialize() : entry)),
+    components: payload.components?.map((entry) => serializeAnyComponent(entry)),
+    allowed_mentions: payload.allowed_mentions ?? payload.allowedMentions,
+    flags,
+    tts: payload.tts,
+    files: payload.files,
+    poll: payload.poll,
+    sticker_ids: payload.stickers,
+  });
+}