@kodelyth/discord 2026.5.42 → 2026.6.1

package/src/internal/client.ts

@@ -1,310 +0,0 @@
-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

@@ -1,197 +0,0 @@
-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);
-  });
-});