@openclaw/discord 2026.3.13 → 2026.5.2-beta.1

package/src/internal/client.test.ts

@@ -0,0 +1,408 @@
+import { ApplicationCommandType, ComponentType, Routes } from "discord-api-types/v10";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Client, ComponentRegistry, type AnyListener } from "./client.js";
+import { BaseCommand } from "./commands.js";
+import { Button, StringSelectMenu, parseCustomId } from "./components.js";
+import { attachRestMock, createInternalTestClient } from "./test-builders.test-support.js";
+
+function createDeferred<T = void>(): {
+  promise: Promise<T>;
+  resolve: (value: T | PromiseLike<T>) => void;
+  reject: (reason?: unknown) => void;
+} {
+  let resolve: (value: T | PromiseLike<T>) => void = () => {};
+  let reject: (reason?: unknown) => void = () => {};
+  const promise = new Promise<T>((promiseResolve, promiseReject) => {
+    resolve = promiseResolve;
+    reject = promiseReject;
+  });
+  return { promise, resolve, reject };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.useRealTimers();
+});
+
+function createTestCommand(params: {
+  name: string;
+  guildIds?: string[];
+  options?: unknown[];
+}): BaseCommand {
+  return new (class extends BaseCommand {
+    name = params.name;
+    description = `${params.name} command`;
+    type = ApplicationCommandType.ChatInput;
+    guildIds = params.guildIds;
+    serializeOptions() {
+      return params.options;
+    }
+  })();
+}
+
+describe("ComponentRegistry", () => {
+  it("preserves digit-only custom id values as strings", () => {
+    const parsed = parseCustomId("agent:user=123456789012345678;count=42;enabled=true");
+
+    expect(parsed.data.user).toBe("123456789012345678");
+    expect(parsed.data.count).toBe("42");
+    expect(parsed.data.enabled).toBe(true);
+  });
+
+  it("resolves wildcard parser entries by component type", () => {
+    const registry = new ComponentRegistry<Button | StringSelectMenu>();
+    class WildcardButton extends Button {
+      label = "button";
+      customId = "__button_wildcard__";
+      customIdParser = (id: string) =>
+        id === this.customId || id.startsWith("occomp:")
+          ? { key: "*", data: {} }
+          : parseCustomId(id);
+    }
+    class WildcardSelect extends StringSelectMenu {
+      customId = "__select_wildcard__";
+      options = [];
+      customIdParser = (id: string) =>
+        id === this.customId || id.startsWith("occomp:")
+          ? { key: "*", data: {} }
+          : parseCustomId(id);
+    }
+    const button = new WildcardButton();
+    const select = new WildcardSelect();
+
+    registry.register(button);
+    registry.register(select);
+
+    expect(registry.resolve("occomp:cid=one", { componentType: ComponentType.Button })).toBe(
+      button,
+    );
+    expect(registry.resolve("occomp:cid=one", { componentType: ComponentType.StringSelect })).toBe(
+      select,
+    );
+  });
+
+  it("uses each registered component parser when resolving specific keys", () => {
+    const registry = new ComponentRegistry<Button>();
+    class EncodedButton extends Button {
+      label = "button";
+      customId = "encoded:seed=one";
+      customIdParser = (id: string) => ({
+        key: id.startsWith("encoded:") ? "encoded" : parseCustomId(id).key,
+        data: {},
+      });
+    }
+    const button = new EncodedButton();
+
+    registry.register(button);
+
+    expect(registry.resolve("encoded:payload=two", { componentType: ComponentType.Button })).toBe(
+      button,
+    );
+  });
+});
+
+describe("Client.deployCommands", () => {
+  it("bulk overwrites all guild commands for the same guild together", async () => {
+    const client = createInternalTestClient([
+      createTestCommand({ name: "one", guildIds: ["g1"] }),
+      createTestCommand({ name: "two", guildIds: ["g1"] }),
+    ]);
+    const put = vi.fn(async () => undefined);
+    attachRestMock(client, { put });
+
+    await client.deployCommands({ mode: "overwrite" });
+
+    expect(put).toHaveBeenCalledWith(Routes.applicationGuildCommands("app1", "g1"), {
+      body: [expect.objectContaining({ name: "one" }), expect.objectContaining({ name: "two" })],
+    });
+    expect(put).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not patch semantically unchanged nested command options", async () => {
+    const client = createInternalTestClient([
+      createTestCommand({
+        name: "one",
+        options: [{ type: 3, name: "value", description: "Value" }],
+      }),
+    ]);
+    const get = vi.fn(async () => [
+      {
+        id: "cmd1",
+        application_id: "app1",
+        type: ApplicationCommandType.ChatInput,
+        name: "one",
+        description: "one command",
+        options: [{ description: "Value", name: "value", type: 3 }],
+        default_member_permissions: null,
+        integration_types: [0, 1],
+        contexts: [0, 1, 2],
+      },
+    ]);
+    const patch = vi.fn(async () => undefined);
+    const post = vi.fn(async () => undefined);
+    const deleteRequest = vi.fn(async () => undefined);
+    attachRestMock(client, { get, patch, post, delete: deleteRequest });
+
+    await client.deployCommands({ mode: "reconcile" });
+
+    expect(patch).not.toHaveBeenCalled();
+    expect(post).not.toHaveBeenCalled();
+    expect(deleteRequest).not.toHaveBeenCalled();
+  });
+
+  it("does not patch live-only command metadata or reordered unordered arrays", async () => {
+    const client = createInternalTestClient([
+      createTestCommand({
+        name: "one",
+        options: [
+          {
+            type: 3,
+            name: "value",
+            description: "Value",
+            required: false,
+            autocomplete: false,
+            channel_types: [1, 0],
+          },
+        ],
+      }),
+    ]);
+    const get = vi.fn(async () => [
+      {
+        id: "cmd1",
+        application_id: "app1",
+        type: ApplicationCommandType.ChatInput,
+        name: "one",
+        name_localized: "one",
+        description: "one command",
+        description_localized: "one command",
+        options: [
+          {
+            type: 3,
+            name: "value",
+            description: "Value",
+            description_localized: "Value",
+            channel_types: [0, 1],
+          },
+        ],
+        default_member_permissions: null,
+        dm_permission: true,
+        integration_types: [1, 0],
+        contexts: [2, 1, 0],
+        guild_id: undefined,
+        version: "1",
+      },
+    ]);
+    const patch = vi.fn(async () => undefined);
+    const post = vi.fn(async () => undefined);
+    const deleteRequest = vi.fn(async () => undefined);
+    attachRestMock(client, { get, patch, post, delete: deleteRequest });
+
+    await client.deployCommands({ mode: "reconcile" });
+
+    expect(patch).not.toHaveBeenCalled();
+    expect(post).not.toHaveBeenCalled();
+    expect(deleteRequest).not.toHaveBeenCalled();
+  });
+
+  it("patches changed option localization maps", async () => {
+    const client = createInternalTestClient([
+      createTestCommand({
+        name: "one",
+        options: [
+          {
+            type: 3,
+            name: "value",
+            name_localizations: { de: "wert" },
+            description: "Value",
+            description_localizations: { de: "Wert" },
+          },
+        ],
+      }),
+    ]);
+    const get = vi.fn(async () => [
+      {
+        id: "cmd1",
+        application_id: "app1",
+        type: ApplicationCommandType.ChatInput,
+        name: "one",
+        description: "one command",
+        options: [
+          {
+            type: 3,
+            name: "value",
+            name_localizations: { de: "alter-wert" },
+            description: "Value",
+            description_localizations: { de: "Alter Wert" },
+          },
+        ],
+      },
+    ]);
+    const patch = vi.fn(async () => undefined);
+    const post = vi.fn(async () => undefined);
+    const deleteRequest = vi.fn(async () => undefined);
+    attachRestMock(client, { get, patch, post, delete: deleteRequest });
+
+    await client.deployCommands({ mode: "reconcile" });
+
+    expect(patch).toHaveBeenCalledWith(
+      Routes.applicationCommand("app1", "cmd1"),
+      expect.objectContaining({
+        body: expect.objectContaining({
+          options: [
+            expect.objectContaining({
+              name_localizations: { de: "wert" },
+              description_localizations: { de: "Wert" },
+            }),
+          ],
+        }),
+      }),
+    );
+    expect(post).not.toHaveBeenCalled();
+    expect(deleteRequest).not.toHaveBeenCalled();
+  });
+
+  it("skips command deploy when the serialized command set is unchanged", async () => {
+    const client = createInternalTestClient([createTestCommand({ name: "one" })]);
+    const get = vi.fn(async () => []);
+    const post = vi.fn(async () => undefined);
+    attachRestMock(client, { get, post });
+
+    await client.deployCommands({ mode: "reconcile" });
+    await client.deployCommands({ mode: "reconcile" });
+
+    expect(get).toHaveBeenCalledTimes(1);
+    expect(post).toHaveBeenCalledTimes(1);
+  });
+
+  it("caches REST object fetches briefly and invalidates from gateway updates", async () => {
+    const client = createInternalTestClient();
+    const get = vi.fn(async () => ({ id: "c1", type: 0, name: "general" }));
+    attachRestMock(client, { get });
+
+    await client.fetchChannel("c1");
+    await client.fetchChannel("c1");
+    expect(get).toHaveBeenCalledTimes(1);
+
+    await client.dispatchGatewayEvent("CHANNEL_UPDATE", { id: "c1" });
+    await client.fetchChannel("c1");
+    expect(get).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("Client gateway event queue", () => {
+  function createQueuedClient(params: {
+    listeners: AnyListener[];
+    eventQueue?: ConstructorParameters<typeof Client>[0]["eventQueue"];
+  }): Client {
+    return new Client(
+      {
+        baseUrl: "http://localhost",
+        clientId: "app1",
+        publicKey: "public",
+        token: "token",
+        eventQueue: params.eventQueue,
+      },
+      { listeners: params.listeners },
+    );
+  }
+
+  it("uses OpenClaw Discord event queue defaults", () => {
+    const client = createQueuedClient({
+      listeners: [],
+      eventQueue: {},
+    });
+
+    expect(client.getRuntimeMetrics().eventQueue).toEqual(
+      expect.objectContaining({
+        maxQueueSize: 10_000,
+        maxConcurrency: 50,
+      }),
+    );
+  });
+
+  it("times out hung queued listeners", async () => {
+    vi.useFakeTimers();
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const listener = {
+      type: "READY",
+      handle: vi.fn(async () => await new Promise<void>(() => {})),
+    } satisfies AnyListener;
+    const client = createQueuedClient({
+      listeners: [listener],
+      eventQueue: { listenerTimeout: 10, maxConcurrency: 1 },
+    });
+
+    const dispatch = client.dispatchGatewayEvent("READY", {});
+    await vi.advanceTimersByTimeAsync(10);
+
+    await expect(dispatch).resolves.toBeUndefined();
+    expect(errorSpy).toHaveBeenCalledWith(
+      "[EventQueue] Listener Object timed out after 10ms for event READY",
+    );
+    expect(client.getRuntimeMetrics().eventQueue).toEqual(
+      expect.objectContaining({ processed: 1, timeouts: 1 }),
+    );
+  });
+
+  it("limits queued listener concurrency", async () => {
+    const started: string[] = [];
+    const releaseFirst = createDeferred();
+    const releaseSecond = createDeferred();
+    const first = {
+      type: "READY",
+      handle: vi.fn(async () => {
+        started.push("first");
+        await releaseFirst.promise;
+      }),
+    } satisfies AnyListener;
+    const second = {
+      type: "READY",
+      handle: vi.fn(async () => {
+        started.push("second");
+        await releaseSecond.promise;
+      }),
+    } satisfies AnyListener;
+    const client = createQueuedClient({
+      listeners: [first, second],
+      eventQueue: { maxConcurrency: 1, listenerTimeout: 1_000 },
+    });
+
+    const dispatch = client.dispatchGatewayEvent("READY", {});
+    await vi.waitFor(() => expect(started).toEqual(["first"]));
+
+    releaseFirst.resolve();
+    await vi.waitFor(() => expect(started).toEqual(["first", "second"]));
+    releaseSecond.resolve();
+    await expect(dispatch).resolves.toBeUndefined();
+  });
+
+  it("rejects when queued listener work exceeds maxQueueSize", async () => {
+    const releases: Array<() => void> = [];
+    const listener = {
+      type: "READY",
+      handle: vi.fn(
+        async () =>
+          await new Promise<void>((resolve) => {
+            releases.push(resolve);
+          }),
+      ),
+    } satisfies AnyListener;
+    const client = createQueuedClient({
+      listeners: [listener],
+      eventQueue: { maxConcurrency: 1, maxQueueSize: 1, listenerTimeout: 1_000 },
+    });
+
+    const first = client.dispatchGatewayEvent("READY", {});
+    await vi.waitFor(() => expect(listener.handle).toHaveBeenCalledTimes(1));
+    const second = client.dispatchGatewayEvent("READY", {});
+
+    await expect(client.dispatchGatewayEvent("READY", {})).rejects.toThrow(
+      "Discord event queue is full for READY; maxQueueSize=1",
+    );
+
+    releases.shift()?.();
+    await vi.waitFor(() => expect(listener.handle).toHaveBeenCalledTimes(2));
+    releases.shift()?.();
+    await expect(Promise.all([first, second])).resolves.toEqual([undefined, undefined]);
+  });
+});

package/src/internal/client.ts

@@ -0,0 +1,308 @@
+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, Message, 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;
+}
+
+type OneOffComponentResult =
+  | { success: true; customId: string; message: Message; values?: string[] }
+  | { success: false; message: Message; reason: "timed out" };
+
+export class ComponentRegistry<
+  T extends { customId: string; customIdParser?: typeof parseCustomId; type?: number },
+> {
+  private entries = new Map<string, T[]>();
+  private oneOffComponents = new Map<
+    string,
+    { message: Message; resolve(result: OneOffComponentResult): void; timer: NodeJS.Timeout }
+  >();
+  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;
+    });
+  }
+
+  waitForMessageComponent(message: Message, timeoutMs: number): Promise<OneOffComponentResult> {
+    const key = createOneOffComponentKey(message.id, message.channelId);
+    return new Promise((resolve) => {
+      const existing = this.oneOffComponents.get(key);
+      if (existing) {
+        clearTimeout(existing.timer);
+        existing.resolve({ success: false, message, reason: "timed out" });
+      }
+      const timer = setTimeout(
+        () => {
+          this.oneOffComponents.delete(key);
+          resolve({ success: false, message, reason: "timed out" });
+        },
+        Math.max(0, timeoutMs),
+      );
+      timer.unref?.();
+      this.oneOffComponents.set(key, {
+        message,
+        timer,
+        resolve,
+      });
+    });
+  }
+
+  resolveOneOffComponent(params: {
+    channelId?: string;
+    customId: string;
+    messageId?: string;
+    values?: string[];
+  }): boolean {
+    if (!params.messageId || !params.channelId) {
+      return false;
+    }
+    const entry = this.oneOffComponents.get(
+      createOneOffComponentKey(params.messageId, params.channelId),
+    );
+    if (!entry) {
+      return false;
+    }
+    clearTimeout(entry.timer);
+    this.oneOffComponents.delete(createOneOffComponentKey(params.messageId, params.channelId));
+    entry.resolve({
+      success: true,
+      customId: params.customId,
+      message: entry.message,
+      values: params.values,
+    });
+    return true;
+  }
+}
+
+function parseRegistryKey(customId: string, parser: typeof parseCustomId = parseCustomId): string {
+  return parser(customId).key;
+}
+
+function createOneOffComponentKey(messageId: string, channelId: string): string {
+  return `${messageId}:${channelId}`;
+}
+
+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);
+          },
+        }),
+      ),
+    );
+  }
+}