@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/internal/client.ts

@@ -0,0 +1,310 @@
+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;
+  commandDeployHashStorePath?: string;
+  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,
+      hashStorePath: this.options.commandDeployHashStorePath,
+      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.test.ts

@@ -0,0 +1,197 @@
+import type { APIApplicationCommand } from "discord-api-types/v10";
+import { describe, expect, test } from "vitest";
+import { testing } from "./command-deploy.js";
+
+const { commandsEqual } = testing;
+
+/**
+ * Regression tests for Discord slash-command reconcile/deploy equality.
+ *
+ * These protect against a class of bugs where Discord's server-side storage
+ * normalization causes our desired descriptor to re-compare unequal to the
+ * command Discord returns, which leads to a spurious `PATCH` on every
+ * gateway startup and, under the per-application rate limit, a cascade of
+ * `429` responses that silently drop some commands until the next restart.
+ */
+describe("commandsEqual", () => {
+  // Shape of what Discord returns on `GET /applications/{appId}/commands`.
+  // Fields like `version`, `dm_permission`, `nsfw`, `application_id` are
+  // always present on the server side but absent from our locally-serialized
+  // desired descriptors — they must therefore be ignored by the comparator.
+  function currentFromDiscord(
+    overrides: Partial<APIApplicationCommand> = {},
+  ): APIApplicationCommand {
+    return {
+      id: "cmd-1",
+      application_id: "app",
+      type: 1,
+      name: "ping",
+      description: "ping the bot",
+      version: "v1",
+      default_member_permissions: null,
+      dm_permission: true,
+      nsfw: false,
+      ...overrides,
+    } as APIApplicationCommand;
+  }
+
+  // Shape of what a `BaseCommand.serialize()` produces locally.
+  function desiredFromLocal(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+    return {
+      name: "ping",
+      description: "ping the bot",
+      type: 1,
+      default_member_permissions: null,
+      ...overrides,
+    };
+  }
+
+  test("ignores Discord server-side default fields (dm_permission, nsfw, version, id, application_id)", () => {
+    expect(commandsEqual(currentFromDiscord(), desiredFromLocal())).toBe(true);
+  });
+
+  test("ignores Discord null localization maps when local command omits them", () => {
+    const current = currentFromDiscord({
+      name_localizations: null,
+      description_localizations: null,
+      options: [
+        {
+          type: 3,
+          name: "name",
+          name_localizations: null,
+          description: "Skill name",
+          description_localizations: null,
+        } as any,
+      ],
+    });
+    const desired = desiredFromLocal({
+      options: [{ name: "name", description: "Skill name", type: 3 }],
+    });
+    expect(commandsEqual(current, desired)).toBe(true);
+  });
+
+  test("treats `required: false` on an option as equivalent to field absent", () => {
+    const current = currentFromDiscord({
+      name: "skill",
+      description: "Run a skill.",
+      options: [{ type: 3, name: "name", description: "Skill name" } as any],
+    });
+    const desired = desiredFromLocal({
+      name: "skill",
+      description: "Run a skill.",
+      options: [{ name: "name", description: "Skill name", type: 3, required: false }],
+    });
+    expect(commandsEqual(current, desired)).toBe(true);
+  });
+
+  test("keeps `required: true` meaningful", () => {
+    const current = currentFromDiscord({
+      name: "skill",
+      description: "Run a skill.",
+      options: [{ type: 3, name: "name", description: "Skill name" } as any],
+    });
+    const desired = desiredFromLocal({
+      name: "skill",
+      description: "Run a skill.",
+      options: [{ name: "name", description: "Skill name", type: 3, required: true }],
+    });
+    expect(commandsEqual(current, desired)).toBe(false);
+  });
+
+  test("treats CJK descriptions with `\\n` separators as equal to Discord's collapsed form", () => {
+    // Discord server collapses whitespace between CJK characters when storing
+    // command descriptions, so our local desired `\n`-separated description
+    // round-trips back without the newline.
+    const current = currentFromDiscord({
+      description:
+        "将任意文本转化为杂志质感 HTML 信息卡片，并自动截图保存为图片。支持直接输入 URL。",
+    });
+    const desired = desiredFromLocal({
+      description:
+        "将任意文本转化为杂志质感 HTML 信息卡片，并自动截图保存为图片。\n支持直接输入 URL。",
+    });
+    expect(commandsEqual(current, desired)).toBe(true);
+  });
+
+  test("treats mixed CJK/ASCII descriptions with consecutive whitespace as equal to collapsed form", () => {
+    const current = currentFromDiscord({
+      description: "联网操作策略框架。访问需登录站点时触发。",
+    });
+    const desired = desiredFromLocal({
+      description: "联网操作策略框架。\n\n访问需登录站点时触发。",
+    });
+    expect(commandsEqual(current, desired)).toBe(true);
+  });
+
+  test("treats localized descriptions with CJK whitespace as equal to Discord's collapsed form", () => {
+    const current = currentFromDiscord({
+      description_localizations: {
+        "zh-CN": "第一行说明。第二行说明。",
+      },
+    });
+    const desired = desiredFromLocal({
+      description_localizations: {
+        "zh-CN": "第一行说明。\n第二行说明。",
+      },
+    });
+    expect(commandsEqual(current, desired)).toBe(true);
+  });
+
+  test("treats option localized descriptions with CJK whitespace as equal to Discord's collapsed form", () => {
+    const current = currentFromDiscord({
+      name: "skill",
+      description: "Run a skill.",
+      options: [
+        {
+          type: 3,
+          name: "name",
+          description: "Skill name",
+          description_localizations: { "zh-CN": "技能名称。直接输入。" },
+        } as any,
+      ],
+    });
+    const desired = desiredFromLocal({
+      name: "skill",
+      description: "Run a skill.",
+      options: [
+        {
+          name: "name",
+          description: "Skill name",
+          description_localizations: { "zh-CN": "技能名称。\n直接输入。" },
+          type: 3,
+        },
+      ],
+    });
+    expect(commandsEqual(current, desired)).toBe(true);
+  });
+
+  test("keeps localized substantive description differences meaningful", () => {
+    const current = currentFromDiscord({
+      description_localizations: {
+        "zh-CN": "旧说明",
+      },
+    });
+    const desired = desiredFromLocal({
+      description_localizations: {
+        "zh-CN": "新说明",
+      },
+    });
+    expect(commandsEqual(current, desired)).toBe(false);
+  });
+
+  test("keeps substantive description differences meaningful", () => {
+    const current = currentFromDiscord({ description: "old text" });
+    const desired = desiredFromLocal({ description: "new text" });
+    expect(commandsEqual(current, desired)).toBe(false);
+  });
+
+  test("treats ASCII `\\n` as whitespace and collapses it to space for comparison", () => {
+    // For pure ASCII descriptions, `\n` collapses to a single space so
+    // "ping the bot" == "ping\nthe bot". The contract is: whitespace
+    // differences (ASCII or CJK-boundary) are never substantive after
+    // Discord's server normalization.
+    const current = currentFromDiscord({ description: "ping the bot" });
+    const desired = desiredFromLocal({ description: "ping\nthe bot" });
+    expect(commandsEqual(current, desired)).toBe(true);
+  });
+});