@openclaw/discord 2026.3.13 → 2026.5.1-beta.1

package/src/internal/components.message.ts

@@ -0,0 +1,279 @@
+import {
+  ButtonStyle,
+  ComponentType,
+  type APIActionRowComponent,
+  type APIButtonComponent,
+  type APIChannelSelectComponent,
+  type APIComponentInMessageActionRow,
+  type APIContainerComponent,
+  type APIFileComponent,
+  type APIMediaGalleryComponent,
+  type APISectionComponent,
+  type APISeparatorComponent,
+  type APIStringSelectComponent,
+  type APITextDisplayComponent,
+  type APIThumbnailComponent,
+} from "discord-api-types/v10";
+import {
+  BaseComponent,
+  BaseMessageInteractiveComponent,
+  clean,
+  colorToNumber,
+} from "./components.base.js";
+
+abstract class BaseButton extends BaseMessageInteractiveComponent {
+  readonly type = ComponentType.Button;
+  abstract label: string;
+  emoji?: { name: string; id?: string; animated?: boolean };
+  style: ButtonStyle = ButtonStyle.Primary;
+  disabled = false;
+}
+
+export abstract class Button extends BaseButton {
+  serialize(): APIButtonComponent {
+    return clean({
+      type: this.type,
+      style: this.style,
+      custom_id: this.customId,
+      label: this.label,
+      emoji: this.emoji,
+      disabled: this.disabled || undefined,
+    }) as APIButtonComponent;
+  }
+}
+
+export abstract class LinkButton extends BaseButton {
+  customId = "";
+  abstract url: string;
+  style = ButtonStyle.Link;
+  async run(): Promise<never> {
+    throw new Error("Link buttons do not run handlers");
+  }
+  serialize(): APIButtonComponent {
+    return clean({
+      type: this.type,
+      style: this.style,
+      label: this.label,
+      emoji: this.emoji,
+      disabled: this.disabled || undefined,
+      url: this.url,
+    }) as APIButtonComponent;
+  }
+}
+
+export abstract class AnySelectMenu extends BaseMessageInteractiveComponent {
+  placeholder?: string;
+  minValues?: number;
+  maxValues?: number;
+  disabled = false;
+  required?: boolean;
+  abstract serializeOptions(): Record<string, unknown>;
+  serialize() {
+    return clean({
+      ...this.serializeOptions(),
+      custom_id: this.customId,
+      placeholder: this.placeholder,
+      min_values: this.minValues,
+      max_values: this.maxValues,
+      disabled: this.disabled || undefined,
+      required: this.required,
+    });
+  }
+}
+
+export abstract class StringSelectMenu extends AnySelectMenu {
+  readonly type = ComponentType.StringSelect;
+  abstract options: APIStringSelectComponent["options"];
+  serializeOptions() {
+    return { type: this.type, options: this.options };
+  }
+}
+
+export abstract class UserSelectMenu extends AnySelectMenu {
+  readonly type = ComponentType.UserSelect;
+  defaultValues?: unknown[];
+  serializeOptions() {
+    return { type: this.type, default_values: this.defaultValues };
+  }
+}
+
+export abstract class RoleSelectMenu extends AnySelectMenu {
+  readonly type = ComponentType.RoleSelect;
+  defaultValues?: unknown[];
+  serializeOptions() {
+    return { type: this.type, default_values: this.defaultValues };
+  }
+}
+
+export abstract class MentionableSelectMenu extends AnySelectMenu {
+  readonly type = ComponentType.MentionableSelect;
+  defaultValues?: unknown[];
+  serializeOptions() {
+    return { type: this.type, default_values: this.defaultValues };
+  }
+}
+
+export abstract class ChannelSelectMenu extends AnySelectMenu {
+  readonly type = ComponentType.ChannelSelect;
+  channelTypes?: APIChannelSelectComponent["channel_types"];
+  defaultValues?: unknown[];
+  serializeOptions() {
+    return {
+      type: this.type,
+      default_values: this.defaultValues,
+      channel_types: this.channelTypes,
+    };
+  }
+}
+
+export class Row<T extends BaseMessageInteractiveComponent> extends BaseComponent {
+  readonly type = ComponentType.ActionRow;
+  readonly isV2 = false;
+  components: T[];
+  constructor(components: T[] = []) {
+    super();
+    this.components = components;
+  }
+  addComponent(component: T): void {
+    this.components.push(component);
+  }
+  removeComponent(component: T): void {
+    this.components = this.components.filter((entry) => entry !== component);
+  }
+  removeAllComponents(): void {
+    this.components = [];
+  }
+  serialize(): APIActionRowComponent<APIComponentInMessageActionRow> {
+    return {
+      type: this.type,
+      components: this.components.map(
+        (entry) => entry.serialize() as APIComponentInMessageActionRow,
+      ),
+    };
+  }
+}
+
+export class TextDisplay extends BaseComponent {
+  readonly type = ComponentType.TextDisplay;
+  readonly isV2 = true;
+  constructor(public content?: string) {
+    super();
+  }
+  serialize(): APITextDisplayComponent {
+    return clean({ type: this.type, content: this.content }) as APITextDisplayComponent;
+  }
+}
+
+export class Separator extends BaseComponent {
+  readonly type = ComponentType.Separator;
+  readonly isV2 = true;
+  divider = true;
+  spacing: 1 | 2 | "small" | "large" = "small";
+  constructor(options?: { spacing?: Separator["spacing"]; divider?: boolean }) {
+    super();
+    this.spacing = options?.spacing ?? this.spacing;
+    this.divider = options?.divider ?? this.divider;
+  }
+  serialize(): APISeparatorComponent {
+    return clean({
+      type: this.type,
+      divider: this.divider,
+      spacing: this.spacing === "large" ? 2 : this.spacing === "small" ? 1 : this.spacing,
+    }) as APISeparatorComponent;
+  }
+}
+
+export class Thumbnail extends BaseComponent {
+  readonly type = ComponentType.Thumbnail;
+  readonly isV2 = true;
+  constructor(public url?: string) {
+    super();
+  }
+  serialize(): APIThumbnailComponent {
+    return clean({
+      type: this.type,
+      media: this.url ? { url: this.url } : undefined,
+    }) as APIThumbnailComponent;
+  }
+}
+
+export class Section extends BaseComponent {
+  readonly type = ComponentType.Section;
+  readonly isV2 = true;
+  constructor(
+    public components: TextDisplay[] = [],
+    public accessory?: Thumbnail | Button | LinkButton,
+  ) {
+    super();
+  }
+  serialize(): APISectionComponent {
+    return clean({
+      type: this.type,
+      components: this.components.map((entry) => entry.serialize()),
+      accessory: this.accessory?.serialize(),
+    }) as APISectionComponent;
+  }
+}
+
+export class MediaGallery extends BaseComponent {
+  readonly type = ComponentType.MediaGallery;
+  readonly isV2 = true;
+  constructor(public items: Array<{ url: string; description?: string; spoiler?: boolean }> = []) {
+    super();
+  }
+  serialize(): APIMediaGalleryComponent {
+    return {
+      type: this.type,
+      items: this.items.map((entry) => ({
+        media: { url: entry.url },
+        description: entry.description,
+        spoiler: entry.spoiler,
+      })),
+    };
+  }
+}
+
+export class File extends BaseComponent {
+  readonly type = ComponentType.File;
+  readonly isV2 = true;
+  constructor(
+    public file?: `attachment://${string}`,
+    public spoiler = false,
+  ) {
+    super();
+  }
+  serialize(): APIFileComponent {
+    return clean({
+      type: this.type,
+      file: this.file ? { url: this.file } : undefined,
+      spoiler: this.spoiler || undefined,
+    }) as APIFileComponent;
+  }
+}
+
+export class Container extends BaseComponent {
+  readonly type = ComponentType.Container;
+  readonly isV2 = true;
+  components: Array<
+    Row<BaseMessageInteractiveComponent> | TextDisplay | Section | MediaGallery | Separator | File
+  >;
+  accentColor?: string | number;
+  spoiler = false;
+  constructor(
+    components: Container["components"] = [],
+    options?: { accentColor?: string | number; spoiler?: boolean },
+  ) {
+    super();
+    this.components = components;
+    this.accentColor = options?.accentColor;
+    this.spoiler = options?.spoiler ?? false;
+  }
+  serialize(): APIContainerComponent {
+    return clean({
+      type: this.type,
+      components: this.components.map((entry) => entry.serialize()),
+      accent_color: colorToNumber(this.accentColor),
+      spoiler: this.spoiler || undefined,
+    }) as APIContainerComponent;
+  }
+}

package/src/internal/components.modal.ts

@@ -0,0 +1,95 @@
+import { ComponentType, TextInputStyle, type APITextInputComponent } from "discord-api-types/v10";
+import { BaseModalComponent, clean, parseCustomId, type ComponentData } from "./components.base.js";
+import { AnySelectMenu, TextDisplay } from "./components.message.js";
+
+export abstract class TextInput extends BaseModalComponent {
+  readonly type = ComponentType.TextInput;
+  customIdParser = parseCustomId;
+  style: TextInputStyle = TextInputStyle.Short;
+  minLength?: number;
+  maxLength?: number;
+  required?: boolean;
+  value?: string;
+  placeholder?: string;
+  serialize(): APITextInputComponent {
+    return clean({
+      type: this.type,
+      custom_id: this.customId,
+      style: this.style,
+      min_length: this.minLength,
+      max_length: this.maxLength,
+      required: this.required,
+      value: this.value,
+      placeholder: this.placeholder,
+    }) as APITextInputComponent;
+  }
+}
+
+export abstract class CheckboxGroup extends BaseModalComponent {
+  readonly type = 22;
+  options: Array<{ value: string; label: string; description?: string; default?: boolean }> = [];
+  required?: boolean;
+  minValues?: number;
+  maxValues?: number;
+  serialize() {
+    return clean({
+      type: this.type,
+      custom_id: this.customId,
+      options: this.options,
+      required: this.required,
+      min_values: this.minValues,
+      max_values: this.maxValues,
+    });
+  }
+}
+
+export abstract class RadioGroup extends BaseModalComponent {
+  readonly type = 21;
+  options: Array<{ value: string; label: string; description?: string; default?: boolean }> = [];
+  required?: boolean;
+  minValues?: number;
+  maxValues?: number;
+  serialize() {
+    return clean({
+      type: this.type,
+      custom_id: this.customId,
+      options: this.options,
+      required: this.required,
+      min_values: this.minValues,
+      max_values: this.maxValues,
+    });
+  }
+}
+
+export abstract class Label extends BaseModalComponent {
+  readonly type = ComponentType.Label;
+  abstract label: string;
+  description?: string;
+  customId = "";
+  constructor(public component?: TextInput | AnySelectMenu | CheckboxGroup | RadioGroup) {
+    super();
+  }
+  serialize() {
+    return clean({
+      type: this.type,
+      label: this.label,
+      description: this.description,
+      component: this.component?.serialize(),
+    });
+  }
+}
+
+export abstract class Modal {
+  abstract title: string;
+  components: Array<Label | TextDisplay> = [];
+  abstract customId: string;
+  customIdParser = parseCustomId;
+  abstract run(interaction: unknown, data: ComponentData): unknown;
+  serialize() {
+    return {
+      title: this.title,
+      custom_id: this.customId,
+      components: this.components.map((entry) => entry.serialize()),
+    };
+  }
+}

package/src/internal/components.ts

@@ -0,0 +1,31 @@
+export {
+  BaseComponent,
+  BaseMessageInteractiveComponent,
+  BaseModalComponent,
+  clean,
+  colorToNumber,
+  parseCustomId,
+  type ComponentData,
+  type ComponentParserResult,
+  type ConditionalComponentOption,
+} from "./components.base.js";
+export {
+  AnySelectMenu,
+  Button,
+  ChannelSelectMenu,
+  Container,
+  File,
+  LinkButton,
+  MediaGallery,
+  MentionableSelectMenu,
+  RoleSelectMenu,
+  Row,
+  Section,
+  Separator,
+  StringSelectMenu,
+  TextDisplay,
+  Thumbnail,
+  UserSelectMenu,
+} from "./components.message.js";
+export { CheckboxGroup, Label, Modal, RadioGroup, TextInput } from "./components.modal.js";
+export { serializePayload, type MessagePayload, type MessagePayloadObject } from "./payload.js";

package/src/internal/discord.ts

@@ -0,0 +1,11 @@
+export * from "discord-api-types/v10";
+export * from "./api.js";
+export * from "./client.js";
+export * from "./commands.js";
+export * from "./components.js";
+export * from "./embeds.js";
+export * from "./interactions.js";
+export * from "./listeners.js";
+export * from "./payload.js";
+export * from "./rest.js";
+export * from "./structures.js";

package/src/internal/embeds.ts

@@ -0,0 +1,35 @@
+import type { APIEmbed } from "discord-api-types/v10";
+
+function clean<T extends Record<string, unknown>>(value: T): T {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)) as T;
+}
+
+export class Embed {
+  title?: string;
+  description?: string;
+  url?: string;
+  timestamp?: string;
+  color?: number;
+  footer?: APIEmbed["footer"];
+  image?: string | APIEmbed["image"];
+  thumbnail?: string | APIEmbed["thumbnail"];
+  author?: APIEmbed["author"];
+  fields?: APIEmbed["fields"];
+  constructor(embed?: APIEmbed) {
+    Object.assign(this, embed);
+  }
+  serialize(): APIEmbed {
+    return clean({
+      title: this.title,
+      description: this.description,
+      url: this.url,
+      timestamp: this.timestamp,
+      color: this.color,
+      footer: this.footer,
+      image: typeof this.image === "string" ? { url: this.image } : this.image,
+      thumbnail: typeof this.thumbnail === "string" ? { url: this.thumbnail } : this.thumbnail,
+      author: this.author,
+      fields: this.fields,
+    }) as APIEmbed;
+  }
+}

package/src/internal/entity-cache.ts

@@ -0,0 +1,98 @@
+import { GatewayDispatchEvents } from "discord-api-types/v10";
+import { getChannel, getGuild, getGuildMember, getUser } from "./api.js";
+import type { RequestClient } from "./rest.js";
+import { Guild, GuildMember, User, channelFactory, type StructureClient } from "./structures.js";
+
+type CacheEntry<T> = {
+  expiresAt: number;
+  value: T;
+};
+
+const DEFAULT_REST_CACHE_TTL_MS = 30_000;
+
+export class DiscordEntityCache {
+  private readonly entries = new Map<string, CacheEntry<unknown>>();
+
+  constructor(
+    private readonly params: {
+      client: StructureClient;
+      rest: RequestClient | (() => RequestClient);
+      ttlMs?: number;
+    },
+  ) {}
+
+  async fetchUser(id: string): Promise<User> {
+    return await this.fetchCached(`user:${id}`, async () => {
+      const raw = await getUser(this.rest, id);
+      return new User(this.params.client, raw);
+    });
+  }
+
+  async fetchChannel(id: string) {
+    return await this.fetchCached(`channel:${id}`, async () => {
+      const raw = await getChannel(this.rest, id);
+      return channelFactory(this.params.client, raw);
+    });
+  }
+
+  async fetchGuild(id: string): Promise<Guild> {
+    return await this.fetchCached(`guild:${id}`, async () => {
+      const raw = await getGuild(this.rest, id);
+      return new Guild(this.params.client, raw);
+    });
+  }
+
+  async fetchMember(guildId: string, userId: string): Promise<GuildMember> {
+    return await this.fetchCached(`member:${guildId}:${userId}`, async () => {
+      const raw = await getGuildMember(this.rest, guildId, userId);
+      return new GuildMember(this.params.client, raw);
+    });
+  }
+
+  invalidateForGatewayEvent(type: string, data: unknown): void {
+    const raw = data && typeof data === "object" ? (data as Record<string, unknown>) : {};
+    const channelUpdate: string = GatewayDispatchEvents.ChannelUpdate;
+    const channelDelete: string = GatewayDispatchEvents.ChannelDelete;
+    const guildUpdate: string = GatewayDispatchEvents.GuildUpdate;
+    const guildMemberUpdate: string = GatewayDispatchEvents.GuildMemberUpdate;
+    if (type === channelUpdate || type === channelDelete) {
+      this.deleteId("channel", raw.id);
+    }
+    if (type === guildUpdate) {
+      this.deleteId("guild", raw.id);
+    }
+    if (type === guildMemberUpdate) {
+      const guildId = raw.guild_id;
+      const user = raw.user && typeof raw.user === "object" ? (raw.user as { id?: unknown }) : {};
+      if (typeof guildId === "string" && typeof user.id === "string") {
+        this.entries.delete(`member:${guildId}:${user.id}`);
+        this.entries.delete(`user:${user.id}`);
+      }
+    }
+  }
+
+  private deleteId(prefix: string, id: unknown): void {
+    if (typeof id === "string") {
+      this.entries.delete(`${prefix}:${id}`);
+    }
+  }
+
+  private async fetchCached<T>(key: string, fetcher: () => Promise<T>): Promise<T> {
+    const ttl = this.params.ttlMs ?? DEFAULT_REST_CACHE_TTL_MS;
+    if (ttl > 0) {
+      const cached = this.entries.get(key) as CacheEntry<T> | undefined;
+      if (cached && cached.expiresAt > Date.now()) {
+        return cached.value;
+      }
+    }
+    const value = await fetcher();
+    if (ttl > 0) {
+      this.entries.set(key, { expiresAt: Date.now() + ttl, value });
+    }
+    return value;
+  }
+
+  private get rest(): RequestClient {
+    return typeof this.params.rest === "function" ? this.params.rest() : this.params.rest;
+  }
+}

package/src/internal/event-queue.ts

@@ -0,0 +1,162 @@
+export type DiscordEventQueueOptions = {
+  maxQueueSize?: number;
+  maxConcurrency?: number;
+  listenerTimeout?: number;
+  slowListenerThreshold?: number;
+};
+
+type DiscordEventQueueJob = {
+  eventType: string;
+  listenerName: string;
+  run: () => Promise<void>;
+  resolve: () => void;
+  reject: (error: unknown) => void;
+};
+
+type DiscordEventQueueMetrics = {
+  queueSize: number;
+  processing: number;
+  processed: number;
+  dropped: number;
+  timeouts: number;
+  maxQueueSize: number;
+  maxConcurrency: number;
+};
+
+const DEFAULT_MAX_QUEUE_SIZE = 10_000;
+const DEFAULT_MAX_CONCURRENCY = 50;
+const DEFAULT_LISTENER_TIMEOUT_MS = 120_000;
+const DEFAULT_SLOW_LISTENER_THRESHOLD_MS = 30_000;
+
+export class DiscordEventQueue {
+  private readonly options: Required<DiscordEventQueueOptions>;
+  private readonly queue: DiscordEventQueueJob[] = [];
+  private processing = 0;
+  private processedCount = 0;
+  private droppedCount = 0;
+  private timeoutCount = 0;
+
+  constructor(options: DiscordEventQueueOptions = {}) {
+    this.options = {
+      maxQueueSize: normalizePositiveInteger(options.maxQueueSize, DEFAULT_MAX_QUEUE_SIZE),
+      maxConcurrency: normalizePositiveInteger(options.maxConcurrency, DEFAULT_MAX_CONCURRENCY),
+      listenerTimeout: normalizePositiveInteger(
+        options.listenerTimeout,
+        DEFAULT_LISTENER_TIMEOUT_MS,
+      ),
+      slowListenerThreshold: normalizePositiveInteger(
+        options.slowListenerThreshold,
+        DEFAULT_SLOW_LISTENER_THRESHOLD_MS,
+      ),
+    };
+  }
+
+  enqueue(params: Omit<DiscordEventQueueJob, "resolve" | "reject">): Promise<void> {
+    if (this.queue.length >= this.options.maxQueueSize) {
+      this.droppedCount += 1;
+      return Promise.reject(
+        new Error(
+          `Discord event queue is full for ${params.eventType}; maxQueueSize=${this.options.maxQueueSize}`,
+        ),
+      );
+    }
+    return new Promise<void>((resolve, reject) => {
+      this.queue.push({ ...params, resolve, reject });
+      this.processNext();
+    });
+  }
+
+  getMetrics(): DiscordEventQueueMetrics {
+    return {
+      queueSize: this.queue.length,
+      processing: this.processing,
+      processed: this.processedCount,
+      dropped: this.droppedCount,
+      timeouts: this.timeoutCount,
+      maxQueueSize: this.options.maxQueueSize,
+      maxConcurrency: this.options.maxConcurrency,
+    };
+  }
+
+  private processNext(): void {
+    while (this.processing < this.options.maxConcurrency && this.queue.length > 0) {
+      const job = this.queue.shift();
+      if (!job) {
+        return;
+      }
+      this.processing += 1;
+      void this.runJob(job)
+        .then(job.resolve, job.reject)
+        .finally(() => {
+          this.processing -= 1;
+          this.processedCount += 1;
+          this.processNext();
+        });
+    }
+  }
+
+  private async runJob(job: DiscordEventQueueJob): Promise<void> {
+    const startedAt = Date.now();
+    try {
+      await this.runWithTimeout(job);
+      this.logSlowListener(job, Date.now() - startedAt);
+    } catch (error) {
+      if (isListenerTimeoutError(error)) {
+        this.timeoutCount += 1;
+        console.error(
+          `[EventQueue] Listener ${job.listenerName} timed out after ${this.options.listenerTimeout}ms for event ${job.eventType}`,
+        );
+        return;
+      }
+      console.error(
+        `[EventQueue] Listener ${job.listenerName} failed for event ${job.eventType}:`,
+        error,
+      );
+    }
+  }
+
+  private async runWithTimeout(job: DiscordEventQueueJob): Promise<void> {
+    let timeout: NodeJS.Timeout | undefined;
+    try {
+      await Promise.race([
+        job.run(),
+        new Promise<never>((_, reject) => {
+          timeout = setTimeout(() => {
+            reject(createListenerTimeoutError(this.options.listenerTimeout));
+          }, this.options.listenerTimeout);
+          timeout.unref?.();
+        }),
+      ]);
+    } finally {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+    }
+  }
+
+  private logSlowListener(job: DiscordEventQueueJob, durationMs: number): void {
+    if (durationMs < this.options.slowListenerThreshold) {
+      return;
+    }
+    console.warn(
+      `[EventQueue] Slow listener detected: ${job.listenerName} took ${durationMs}ms for event ${job.eventType}`,
+    );
+  }
+}
+
+function normalizePositiveInteger(value: number | undefined, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return fallback;
+  }
+  return Math.max(1, Math.floor(value));
+}
+
+function createListenerTimeoutError(timeoutMs: number): Error {
+  const error = new Error(`Listener timeout after ${timeoutMs}ms`);
+  error.name = "DiscordEventQueueListenerTimeoutError";
+  return error;
+}
+
+function isListenerTimeoutError(error: unknown): boolean {
+  return error instanceof Error && error.name === "DiscordEventQueueListenerTimeoutError";
+}