@kodelyth/discord 2026.5.42 → 2026.6.1

package/src/internal/command-deploy.ts

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

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

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