@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/internal/command-deploy.ts

@@ -0,0 +1,352 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { ApplicationCommandType, type APIApplicationCommand } from "discord-api-types/v10";
+import { privateFileStore } from "klaw/plugin-sdk/security-runtime";
+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>();
+  private hashesLoaded = false;
+
+  constructor(
+    private readonly params: {
+      clientId: string;
+      commands: BaseCommand[];
+      devGuilds?: string[];
+      hashStorePath?: 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);
+    await this.loadPersistedHashes();
+    if (!options.force && this.hashes.get(key) === hash) {
+      return;
+    }
+    await deploy();
+    this.hashes.set(key, hash);
+    await this.persistHashes();
+  }
+
+  private async loadPersistedHashes(): Promise<void> {
+    if (this.hashesLoaded) {
+      return;
+    }
+    this.hashesLoaded = true;
+    const storePath = this.params.hashStorePath;
+    if (!storePath) {
+      return;
+    }
+    try {
+      const parsed = await privateFileStore(path.dirname(storePath)).readJsonIfExists<{
+        hashes?: unknown;
+      }>(path.basename(storePath));
+      if (!parsed?.hashes || typeof parsed.hashes !== "object") {
+        return;
+      }
+      for (const [key, value] of Object.entries(parsed.hashes)) {
+        if (typeof value === "string" && key.trim() && value.trim()) {
+          this.hashes.set(key, value);
+        }
+      }
+    } catch {
+      // Best-effort cache only. A corrupt or missing file should never block startup.
+    }
+  }
+
+  private async persistHashes(): Promise<void> {
+    const storePath = this.params.hashStorePath;
+    if (!storePath) {
+      return;
+    }
+    try {
+      await privateFileStore(path.dirname(storePath)).writeJson(
+        path.basename(storePath),
+        {
+          version: 1,
+          updatedAt: new Date().toISOString(),
+          hashes: Object.fromEntries(
+            [...this.hashes.entries()].toSorted(([left], [right]) => left.localeCompare(right)),
+          ),
+        },
+        { trailingNewline: true },
+      );
+    } catch {
+      // The cache is only an optimization to avoid redundant Discord writes.
+    }
+  }
+
+  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([
+    "application_id",
+    "description_localized",
+    "dm_permission",
+    "guild_id",
+    "id",
+    "name_localized",
+    "nsfw",
+    "version",
+    "default_permission",
+  ]);
+  return stableComparableObject(
+    Object.fromEntries(
+      Object.entries(value).filter(([key, entry]) => !omit.has(key) && entry !== undefined),
+    ),
+  );
+}
+
+const unorderedCommandArrayFields = new Set(["channel_types", "contexts", "integration_types"]);
+const optionComparisonOmittedFields = new Set([
+  "contexts",
+  "default_member_permissions",
+  "description_localized",
+  "integration_types",
+  "name_localized",
+]);
+const nullableLocalizationFields = new Set(["description_localizations", "name_localizations"]);
+
+function stableComparableObject(value: unknown, path: string[] = []): unknown {
+  if (Array.isArray(value)) {
+    const normalized = value.map((entry) => stableComparableObject(entry, path));
+    const key = path.at(-1);
+    if (
+      key &&
+      unorderedCommandArrayFields.has(key) &&
+      normalized.every(
+        (entry) =>
+          typeof entry === "string" || typeof entry === "number" || typeof entry === "boolean",
+      )
+    ) {
+      return normalized.toSorted((left, right) => String(left).localeCompare(String(right)));
+    }
+    return normalized;
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .filter(([key, entry]) => {
+        if (entry === undefined) {
+          return false;
+        }
+        if (entry === null && nullableLocalizationFields.has(key)) {
+          return false;
+        }
+        if (path.includes("options") && optionComparisonOmittedFields.has(key)) {
+          return false;
+        }
+        if ((key === "required" || key === "autocomplete") && entry === false) {
+          return false;
+        }
+        return true;
+      })
+      .toSorted(([a], [b]) => a.localeCompare(b))
+      .map(([key, entry]) => [
+        key,
+        shouldNormalizeDescriptionValue(path, key, entry)
+          ? normalizeDescriptionForComparison(entry)
+          : stableComparableObject(entry, [...path, key]),
+      ]),
+  );
+}
+
+function shouldNormalizeDescriptionValue(
+  path: string[],
+  key: string,
+  entry: unknown,
+): entry is string {
+  return (
+    typeof entry === "string" &&
+    (key === "description" || path.at(-1) === "description_localizations")
+  );
+}
+
+/**
+ * Normalize a Discord command description for equality comparison.
+ *
+ * Discord's server-side storage performs two transformations that our local
+ * desired descriptors do not:
+ *
+ * 1. Consecutive whitespace (including `\n`) is collapsed to a single space.
+ * 2. Whitespace between two CJK (Chinese, Japanese, Korean) characters is
+ *    removed entirely. So a local description `"第一行。\n第二行。"` is stored
+ *    as `"第一行。第二行。"` on Discord and returned without the `\n`.
+ *
+ * Without this normalization every startup for any CJK-heavy deployment reads
+ * back Discord's collapsed form, computes a diff against the local `\n`-form,
+ * decides the command needs updating, and issues a `PATCH`. Under the global
+ * per-application rate limit this quickly produces 429 bursts and some
+ * commands silently fail to register (see the Discord deploy 429 reports).
+ *
+ * Applying the same transformation to both sides before comparison makes the
+ * equality check match Discord's storage semantics and prevents spurious
+ * reconcile writes on every startup.
+ */
+function normalizeDescriptionForComparison(description: string): string {
+  const collapsed = description.replace(/\s+/g, " ");
+  // Matches whitespace surrounded by CJK code points. Run twice because a
+  // single `replace` consumes the boundary characters, which can leave
+  // adjacent matches (e.g. "字 字 字") partially unhandled.
+  const cjkBoundaryWhitespace =
+    /([\u3000-\u303F\u4E00-\u9FFF\uFF00-\uFFEF])\s+([\u3000-\u303F\u4E00-\u9FFF\uFF00-\uFFEF])/g;
+  return collapsed
+    .replace(cjkBoundaryWhitespace, "$1$2")
+    .replace(cjkBoundaryWhitespace, "$1$2")
+    .trim();
+}
+
+function commandsEqual(a: unknown, b: unknown) {
+  return JSON.stringify(comparableCommand(a)) === JSON.stringify(comparableCommand(b));
+}
+
+export const testing = {
+  commandsEqual,
+  comparableCommand,
+  normalizeDescriptionForComparison,
+} as const;
+
+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");
+}
+export { testing as __testing };

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 {
+  override 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;
+}