@openclaw/discord 2026.3.13 → 2026.5.1-beta.1

package/src/internal/client.ts

@@ -0,0 +1,246 @@
+import type { APIApplicationCommand, APIInteraction } from "discord-api-types/v10";
+import { DiscordCommandDeployer, type DeployCommandOptions } from "./command-deploy.js";
+import type { BaseCommand } from "./commands.js";
+import { BaseMessageInteractiveComponent, parseCustomId, type Modal } from "./components.js";
+import { DiscordEntityCache } from "./entity-cache.js";
+import { DiscordEventQueue, type DiscordEventQueueOptions } from "./event-queue.js";
+import { dispatchInteraction } from "./interaction-dispatch.js";
+import { RequestClient, type RequestClientOptions } from "./rest.js";
+import type { Guild, GuildMember, User } from "./structures.js";
+
+export interface Route {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  path: `/${string}`;
+  handler(req: Request, ctx?: Context): Response | Promise<Response>;
+  protected?: boolean;
+  disabled?: boolean;
+}
+
+export interface Context {
+  waitUntil?(promise: Promise<unknown>): void;
+  env?: unknown;
+}
+
+export abstract class Plugin {
+  abstract readonly id: string;
+  registerClient?(client: Client): Promise<void> | void;
+  registerRoutes?(client: Client): Promise<void> | void;
+  onRequest?(req: Request, ctx: Context): Promise<Response | undefined> | Response | undefined;
+}
+
+export type AnyListener = {
+  type: string;
+  handle(data: unknown, client: Client): Promise<void> | void;
+};
+
+export interface ClientOptions {
+  baseUrl: string;
+  clientId: string;
+  deploySecret?: string;
+  publicKey: string | string[];
+  token: string;
+  requestOptions?: RequestClientOptions;
+  autoDeploy?: boolean;
+  disableDeployRoute?: boolean;
+  disableInteractionsRoute?: boolean;
+  disableEventsRoute?: boolean;
+  devGuilds?: string[];
+  eventQueue?: DiscordEventQueueOptions;
+  restCacheTtlMs?: number;
+}
+
+export class ComponentRegistry<
+  T extends { customId: string; customIdParser?: typeof parseCustomId; type?: number },
+> {
+  private entries = new Map<string, T[]>();
+  private wildcardEntries: T[] = [];
+
+  register(entry: T): void {
+    const key = parseRegistryKey(entry.customId, entry.customIdParser);
+    if (key === "*") {
+      if (!this.wildcardEntries.includes(entry)) {
+        this.wildcardEntries.push(entry);
+      }
+      return;
+    }
+    const entries = this.entries.get(key) ?? [];
+    if (!entries.includes(entry)) {
+      entries.push(entry);
+      this.entries.set(key, entries);
+    }
+  }
+
+  resolve(customId: string, options?: { componentType?: number }): T | undefined {
+    for (const entries of this.entries.values()) {
+      const match = entries.find((entry) => {
+        if (options?.componentType !== undefined && entry.type !== options.componentType) {
+          return false;
+        }
+        const parser = entry.customIdParser ?? parseCustomId;
+        return parseRegistryKey(entry.customId, parser) === parseRegistryKey(customId, parser);
+      });
+      if (match) {
+        return match;
+      }
+    }
+    return this.wildcardEntries.find((entry) => {
+      if (options?.componentType !== undefined && entry.type !== options.componentType) {
+        return false;
+      }
+      return true;
+    });
+  }
+}
+
+function parseRegistryKey(customId: string, parser: typeof parseCustomId = parseCustomId): string {
+  return parser(customId).key;
+}
+
+export class Client {
+  routes: Route[] = [];
+  plugins: Array<{ id: string; plugin: Plugin }> = [];
+  options: ClientOptions;
+  commands: BaseCommand[];
+  listeners: AnyListener[];
+  rest: RequestClient;
+  componentHandler = new ComponentRegistry<BaseMessageInteractiveComponent>();
+  private commandDeployer: DiscordCommandDeployer;
+  private entityCache: DiscordEntityCache;
+  private eventQueue?: DiscordEventQueue;
+  modalHandler = new ComponentRegistry<Modal>();
+  shardId?: number;
+  totalShards?: number;
+
+  constructor(
+    options: ClientOptions,
+    handlers: {
+      commands?: BaseCommand[];
+      listeners?: AnyListener[];
+      components?: BaseMessageInteractiveComponent[];
+      modals?: Modal[];
+    },
+    plugins: Plugin[] = [],
+  ) {
+    if (!options.clientId) {
+      throw new Error("Missing Discord application ID");
+    }
+    if (!options.token) {
+      throw new Error("Missing Discord bot token");
+    }
+    this.options = { ...options, baseUrl: options.baseUrl.replace(/\/+$/, "") };
+    this.commands = handlers.commands ?? [];
+    this.listeners = handlers.listeners ?? [];
+    this.rest = new RequestClient(options.token, options.requestOptions);
+    this.eventQueue = this.options.eventQueue
+      ? new DiscordEventQueue(this.options.eventQueue)
+      : undefined;
+    this.entityCache = new DiscordEntityCache({
+      client: this,
+      rest: () => this.rest,
+      ttlMs: this.options.restCacheTtlMs,
+    });
+    this.commandDeployer = new DiscordCommandDeployer({
+      clientId: this.options.clientId,
+      commands: this.commands,
+      devGuilds: this.options.devGuilds,
+      rest: () => this.rest,
+    });
+    for (const component of handlers.components ?? []) {
+      this.componentHandler.register(component);
+    }
+    for (const command of this.commands) {
+      for (const component of command.components ?? []) {
+        this.componentHandler.register(component);
+      }
+    }
+    for (const modal of handlers.modals ?? []) {
+      this.modalHandler.register(modal);
+    }
+    for (const plugin of plugins) {
+      void plugin.registerClient?.(this);
+      void plugin.registerRoutes?.(this);
+      this.plugins.push({ id: plugin.id, plugin });
+    }
+  }
+
+  getPlugin<T = Plugin>(id: string): T | undefined {
+    return this.plugins.find((entry) => entry.id === id)?.plugin as T | undefined;
+  }
+
+  registerListener(listener: AnyListener): AnyListener {
+    if (!this.listeners.includes(listener)) {
+      this.listeners.push(listener);
+    }
+    return listener;
+  }
+
+  unregisterListener(listener: AnyListener): boolean {
+    const index = this.listeners.indexOf(listener);
+    if (index < 0) {
+      return false;
+    }
+    this.listeners.splice(index, 1);
+    return true;
+  }
+
+  getRuntimeMetrics() {
+    return {
+      request: this.rest.getSchedulerMetrics(),
+      eventQueue: this.eventQueue?.getMetrics(),
+    };
+  }
+
+  async fetchUser(id: string): Promise<User> {
+    return await this.entityCache.fetchUser(id);
+  }
+
+  async fetchChannel(id: string) {
+    return await this.entityCache.fetchChannel(id);
+  }
+
+  async fetchGuild(id: string): Promise<Guild> {
+    return await this.entityCache.fetchGuild(id);
+  }
+
+  async fetchMember(guildId: string, userId: string): Promise<GuildMember> {
+    return await this.entityCache.fetchMember(guildId, userId);
+  }
+
+  async getDiscordCommands(): Promise<APIApplicationCommand[]> {
+    return await this.commandDeployer.getCommands();
+  }
+
+  async deployCommands(options: DeployCommandOptions = {}) {
+    return await this.commandDeployer.deploy(options);
+  }
+
+  async reconcileCommands() {
+    return await this.deployCommands({ mode: "reconcile" });
+  }
+
+  async handleInteraction(rawData: APIInteraction, _ctx?: Context): Promise<void> {
+    await dispatchInteraction(this, rawData);
+  }
+
+  async dispatchGatewayEvent(type: string, data: unknown): Promise<void> {
+    this.entityCache.invalidateForGatewayEvent(type, data);
+    const listeners = this.listeners.filter((entry) => entry.type === type);
+    if (!this.eventQueue) {
+      for (const listener of listeners) {
+        await listener.handle(data, this);
+      }
+      return;
+    }
+    await Promise.all(
+      listeners.map((listener) =>
+        this.eventQueue!.enqueue({
+          eventType: type,
+          listenerName: listener.constructor.name || "AnonymousListener",
+          run: async () => {
+            await listener.handle(data, this);
+          },
+        }),
+      ),
+    );
+  }
+}

package/src/internal/command-deploy.ts

@@ -0,0 +1,202 @@
+import { createHash } from "node:crypto";
+import { ApplicationCommandType, type APIApplicationCommand } from "discord-api-types/v10";
+import {
+  createApplicationCommand,
+  deleteApplicationCommand,
+  editApplicationCommand,
+  listApplicationCommands,
+  overwriteApplicationCommands,
+  overwriteGuildApplicationCommands,
+} from "./api.js";
+import type { BaseCommand } from "./commands.js";
+import type { RequestClient } from "./rest.js";
+
+export type DeployCommandOptions = {
+  mode?: "overwrite" | "reconcile";
+  force?: boolean;
+};
+
+type SerializedCommand = ReturnType<BaseCommand["serialize"]>;
+
+export class DiscordCommandDeployer {
+  private readonly hashes = new Map<string, string>();
+
+  constructor(
+    private readonly params: {
+      clientId: string;
+      commands: BaseCommand[];
+      devGuilds?: string[];
+      rest: () => RequestClient;
+    },
+  ) {}
+
+  async getCommands(): Promise<APIApplicationCommand[]> {
+    return await listApplicationCommands(this.rest, this.params.clientId);
+  }
+
+  async deploy(options: DeployCommandOptions = {}) {
+    const commands = this.params.commands.filter((command) => command.name !== "*");
+    const globalCommands = commands.filter((command) => !command.guildIds);
+    const serializedGlobal = globalCommands.map((command) => command.serialize());
+    for (const [guildId, entries] of groupGuildCommands(commands)) {
+      await this.putCommandSetIfChanged(
+        `guild:${guildId}`,
+        entries,
+        async () => {
+          await overwriteGuildApplicationCommands(
+            this.rest,
+            this.params.clientId,
+            guildId,
+            entries,
+          );
+        },
+        options,
+      );
+    }
+    if (this.params.devGuilds?.length) {
+      for (const guildId of this.params.devGuilds) {
+        const entries = commands.map((command) => command.serialize());
+        await this.putCommandSetIfChanged(
+          `dev-guild:${guildId}`,
+          entries,
+          async () => {
+            await overwriteGuildApplicationCommands(
+              this.rest,
+              this.params.clientId,
+              guildId,
+              entries,
+            );
+          },
+          options,
+        );
+      }
+      return { mode: options.mode ?? "reconcile", usedDevGuilds: true };
+    }
+    if (options.mode !== "overwrite") {
+      await this.putCommandSetIfChanged(
+        "global:reconcile",
+        serializedGlobal,
+        async () => {
+          await this.reconcileGlobalCommands(serializedGlobal);
+        },
+        options,
+      );
+      return { mode: "reconcile" as const, usedDevGuilds: false };
+    }
+    await this.putCommandSetIfChanged(
+      "global:overwrite",
+      serializedGlobal,
+      async () => {
+        await overwriteApplicationCommands(this.rest, this.params.clientId, serializedGlobal);
+      },
+      options,
+    );
+    return { mode: "overwrite" as const, usedDevGuilds: false };
+  }
+
+  private async reconcileGlobalCommands(desired: SerializedCommand[]) {
+    const existing = await this.getCommands();
+    const existingByKey = new Map(existing.map((command) => [stableCommandKey(command), command]));
+    const desiredKeys = new Set<string>();
+    for (const command of desired) {
+      const key = stableCommandKey(command as APIApplicationCommand);
+      desiredKeys.add(key);
+      const current = existingByKey.get(key);
+      if (!current) {
+        await createApplicationCommand(this.rest, this.params.clientId, command);
+        continue;
+      }
+      if (!commandsEqual(current, command)) {
+        await editApplicationCommand(this.rest, this.params.clientId, current.id, command);
+      }
+    }
+    for (const command of existing) {
+      if (!desiredKeys.has(stableCommandKey(command))) {
+        await deleteApplicationCommand(this.rest, this.params.clientId, command.id);
+      }
+    }
+  }
+
+  private async putCommandSetIfChanged(
+    key: string,
+    commands: SerializedCommand[],
+    deploy: () => Promise<void>,
+    options: { force?: boolean },
+  ): Promise<void> {
+    const hash = stableCommandSetHash(commands);
+    if (!options.force && this.hashes.get(key) === hash) {
+      return;
+    }
+    await deploy();
+    this.hashes.set(key, hash);
+  }
+
+  private get rest(): RequestClient {
+    return this.params.rest();
+  }
+}
+
+function groupGuildCommands(commands: BaseCommand[]): Map<string, SerializedCommand[]> {
+  const guildCommands = new Map<string, SerializedCommand[]>();
+  for (const command of commands.filter((entry) => entry.guildIds)) {
+    for (const guildId of command.guildIds ?? []) {
+      const entries = guildCommands.get(guildId) ?? [];
+      entries.push(command.serialize());
+      guildCommands.set(guildId, entries);
+    }
+  }
+  return guildCommands;
+}
+
+function stableCommandKey(command: Pick<APIApplicationCommand, "name" | "type">) {
+  return `${command.type ?? ApplicationCommandType.ChatInput}:${command.name}`;
+}
+
+function comparableCommand(value: unknown): unknown {
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const omit = new Set([
+    "id",
+    "application_id",
+    "guild_id",
+    "version",
+    "default_permission",
+    "nsfw",
+  ]);
+  return stableComparableObject(
+    Object.fromEntries(
+      Object.entries(value).filter(([key, entry]) => !omit.has(key) && entry !== undefined),
+    ),
+  );
+}
+
+function stableComparableObject(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((entry) => stableComparableObject(entry));
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .filter(([, entry]) => entry !== undefined)
+      .toSorted(([a], [b]) => a.localeCompare(b))
+      .map(([key, entry]) => [key, stableComparableObject(entry)]),
+  );
+}
+
+function commandsEqual(a: unknown, b: unknown) {
+  return JSON.stringify(comparableCommand(a)) === JSON.stringify(comparableCommand(b));
+}
+
+function stableCommandSetHash(commands: SerializedCommand[]): string {
+  const stable = commands
+    .map((command) => stableComparableObject(command))
+    .toSorted((a, b) =>
+      stableCommandKey(a as APIApplicationCommand).localeCompare(
+        stableCommandKey(b as APIApplicationCommand),
+      ),
+    );
+  return createHash("sha256").update(JSON.stringify(stable)).digest("hex");
+}

package/src/internal/commands.ts

@@ -0,0 +1,188 @@
+import {
+  ApplicationCommandOptionType,
+  ApplicationCommandType,
+  InteractionContextType,
+  type RESTPostAPIApplicationCommandsJSONBody,
+} from "discord-api-types/v10";
+import type { BaseMessageInteractiveComponent } from "./components.js";
+import type { AutocompleteInteraction, CommandInteraction } from "./interactions.js";
+
+export type ConditionalCommandOption = (interaction: unknown) => boolean;
+export type CommandOption = Record<string, unknown> & {
+  name: string;
+  description?: string;
+  type: ApplicationCommandOptionType;
+  required?: boolean;
+  choices?: Array<{ name: string; value: string | number | boolean }>;
+  autocomplete?: boolean | ((interaction: AutocompleteInteraction) => Promise<void>);
+};
+export type CommandOptions = CommandOption[];
+
+type RawSubcommandOption = {
+  name?: unknown;
+  type?: unknown;
+  options?: RawSubcommandOption[];
+};
+
+function clean<T extends Record<string, unknown>>(value: T): T {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)) as T;
+}
+
+function resolveConditionalCommandOption(
+  value: boolean | ConditionalCommandOption,
+  interaction: unknown,
+): boolean {
+  return typeof value === "function" ? value(interaction) : value;
+}
+
+export async function deferCommandInteractionIfNeeded(
+  command: BaseCommand,
+  interaction: CommandInteraction,
+): Promise<void> {
+  if (!resolveConditionalCommandOption(command.defer, interaction)) {
+    return;
+  }
+  await interaction.defer({
+    ephemeral: resolveConditionalCommandOption(command.ephemeral, interaction),
+  });
+}
+
+function readRawCommandOptions(interaction: CommandInteraction): RawSubcommandOption[] {
+  const options = (interaction.rawData as { data?: { options?: unknown } }).data?.options;
+  return Array.isArray(options) ? (options as RawSubcommandOption[]) : [];
+}
+
+function findSelectedSubcommand(
+  subcommands: Command[],
+  interaction: CommandInteraction,
+): Command | undefined {
+  const subcommandName = readRawCommandOptions(interaction).find(
+    (option) => option.type === ApplicationCommandOptionType.Subcommand,
+  )?.name;
+  return typeof subcommandName === "string"
+    ? subcommands.find((command) => command.name === subcommandName)
+    : undefined;
+}
+
+function findCommandOption(
+  options: CommandOptions | undefined,
+  name: string | undefined,
+): CommandOption | undefined {
+  if (!name) {
+    return undefined;
+  }
+  return options?.find((option) => option.name === name);
+}
+
+function hasCommandOptions(
+  command: BaseCommand,
+): command is BaseCommand & { options?: CommandOptions } {
+  return "options" in command;
+}
+
+export function resolveFocusedCommandOptionAutocompleteHandler(
+  command: BaseCommand,
+  interaction: AutocompleteInteraction,
+): ((interaction: AutocompleteInteraction) => Promise<void>) | undefined {
+  const focusedName = interaction.options.getFocused()?.name;
+  const options =
+    "subcommands" in command && Array.isArray(command.subcommands)
+      ? findSelectedSubcommand(command.subcommands, interaction)?.options
+      : hasCommandOptions(command)
+        ? command.options
+        : undefined;
+  const autocomplete = findCommandOption(options, focusedName)?.autocomplete;
+  return typeof autocomplete === "function" ? autocomplete : undefined;
+}
+
+export abstract class BaseCommand {
+  id?: string;
+  abstract name: string;
+  description?: string;
+  nameLocalizations?: Record<string, string>;
+  descriptionLocalizations?: Record<string, string>;
+  defer: boolean | ConditionalCommandOption = false;
+  ephemeral: boolean | ConditionalCommandOption = false;
+  abstract type: ApplicationCommandType;
+  integrationTypes = [0, 1];
+  contexts = [
+    InteractionContextType.Guild,
+    InteractionContextType.BotDM,
+    InteractionContextType.PrivateChannel,
+  ];
+  permission?: bigint | bigint[];
+  components?: BaseMessageInteractiveComponent[];
+  guildIds?: string[];
+  abstract serializeOptions(): unknown[] | undefined;
+  serialize(): RESTPostAPIApplicationCommandsJSONBody {
+    return clean({
+      name: this.name,
+      name_localizations: this.nameLocalizations,
+      description:
+        this.type === ApplicationCommandType.ChatInput ? (this.description ?? "") : undefined,
+      description_localizations: this.descriptionLocalizations,
+      type: this.type,
+      options: this.serializeOptions() as RESTPostAPIApplicationCommandsJSONBody["options"],
+      integration_types: this.integrationTypes,
+      contexts: this.contexts,
+      default_member_permissions: Array.isArray(this.permission)
+        ? this.permission.reduce((sum, entry) => sum | entry, 0n).toString()
+        : this.permission
+          ? this.permission.toString()
+          : null,
+    }) as RESTPostAPIApplicationCommandsJSONBody;
+  }
+}
+
+export abstract class Command extends BaseCommand {
+  options?: CommandOptions;
+  type = ApplicationCommandType.ChatInput;
+  abstract run(interaction: unknown): unknown;
+  async autocomplete(interaction: unknown): Promise<void> {
+    throw new Error(
+      `The ${(interaction as { rawData?: { data?: { name?: string } } }).rawData?.data?.name ?? this.name} command does not support autocomplete`,
+    );
+  }
+  async preCheck(interaction: unknown): Promise<unknown> {
+    return Boolean(interaction) || true;
+  }
+  serializeOptions() {
+    return this.options?.map((option) => {
+      if (typeof option.autocomplete === "function") {
+        const { autocomplete: _autocomplete, ...rest } = option;
+        return { ...rest, autocomplete: true };
+      }
+      return option;
+    }) as unknown[];
+  }
+}
+
+export abstract class CommandWithSubcommands extends BaseCommand {
+  type = ApplicationCommandType.ChatInput;
+  abstract subcommands: Command[];
+  async run(interaction: CommandInteraction): Promise<unknown> {
+    const subcommand = findSelectedSubcommand(this.subcommands, interaction);
+    if (!subcommand) {
+      const subcommandName = readRawCommandOptions(interaction).find(
+        (option) => option.type === ApplicationCommandOptionType.Subcommand,
+      )?.name;
+      throw new Error(
+        `Unknown Discord subcommand: ${typeof subcommandName === "string" ? subcommandName : "<missing>"}`,
+      );
+    }
+    await deferCommandInteractionIfNeeded(subcommand, interaction);
+    return await subcommand.run(interaction);
+  }
+  serializeOptions() {
+    return this.subcommands.map((command) =>
+      clean({
+        name: command.name,
+        name_localizations: command.nameLocalizations,
+        description: command.description ?? "",
+        description_localizations: command.descriptionLocalizations,
+        type: ApplicationCommandOptionType.Subcommand,
+        options: command.serializeOptions(),
+      }),
+    );
+  }
+}

package/src/internal/components.base.ts

@@ -0,0 +1,65 @@
+import type { BaseComponentInteraction } from "./interactions.js";
+
+export type ComponentParserResult = {
+  key: string;
+  data: Record<string, string | boolean>;
+};
+export type ComponentData<
+  T extends keyof ComponentParserResult["data"] = keyof ComponentParserResult["data"],
+> = {
+  [K in T]: ComponentParserResult["data"][K];
+};
+export type ConditionalComponentOption = (interaction: BaseComponentInteraction) => boolean;
+
+export function parseCustomId(id: string): ComponentParserResult {
+  const [rawKey, ...parts] = id.split(";");
+  const [keyPart, firstValue] = rawKey.split("=");
+  const key = keyPart.includes(":") ? keyPart.split(":")[0] : keyPart;
+  const data: ComponentParserResult["data"] = {};
+  const entries = firstValue === undefined ? parts : [rawKey.slice(key.length + 1), ...parts];
+  for (const entry of entries) {
+    const index = entry.indexOf("=");
+    if (index < 0) {
+      continue;
+    }
+    const name = entry.slice(0, index).replace(/^[^:]+:/, "");
+    const raw = entry.slice(index + 1);
+    data[name] = raw === "true" ? true : raw === "false" ? false : raw;
+  }
+  return { key, data };
+}
+
+export function clean<T extends Record<string, unknown>>(value: T): T {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)) as T;
+}
+
+export function colorToNumber(value: string | number | undefined): number | undefined {
+  if (typeof value === "number") {
+    return value;
+  }
+  if (typeof value === "string" && /^#?[0-9a-f]{6}$/i.test(value)) {
+    return Number.parseInt(value.replace(/^#/, ""), 16);
+  }
+  return undefined;
+}
+
+export abstract class BaseComponent {
+  abstract readonly type: number;
+  readonly isV2: boolean = false;
+  abstract serialize(): unknown;
+}
+
+export abstract class BaseMessageInteractiveComponent extends BaseComponent {
+  readonly isV2 = false;
+  defer: boolean | ConditionalComponentOption = false;
+  ephemeral: boolean | ConditionalComponentOption = false;
+  abstract customId: string;
+  customIdParser = parseCustomId;
+  run(_interaction: BaseComponentInteraction, _data: ComponentData): unknown {
+    return undefined;
+  }
+}
+
+export abstract class BaseModalComponent extends BaseComponent {
+  abstract customId: string;
+}