@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/internal/interaction-dispatch.ts

@@ -0,0 +1,162 @@
+import { InteractionType, type APIInteraction } from "discord-api-types/v10";
+import {
+  type BaseCommand,
+  deferCommandInteractionIfNeeded,
+  resolveFocusedCommandOptionAutocompleteHandler,
+} from "./commands.js";
+import {
+  AutocompleteInteraction,
+  BaseComponentInteraction,
+  CommandInteraction,
+  ModalInteraction,
+  createInteraction,
+  parseComponentInteractionData,
+  type RawInteraction,
+} from "./interactions.js";
+
+type DispatchComponent = {
+  defer: boolean | ((interaction: BaseComponentInteraction) => boolean);
+  ephemeral: boolean | ((interaction: BaseComponentInteraction) => boolean);
+  run(interaction: BaseComponentInteraction, data: Record<string, unknown>): unknown;
+  customIdParser(id: string): { data: Record<string, unknown> };
+};
+
+type DispatchModal = {
+  run(interaction: ModalInteraction, data: Record<string, unknown>): unknown;
+  customIdParser(id: string): { data: Record<string, unknown> };
+};
+
+type DispatchClient = Parameters<typeof createInteraction>[0] & {
+  commands: BaseCommand[];
+  componentHandler: {
+    resolve(customId: string, options?: { componentType?: number }): DispatchComponent | undefined;
+    resolveOneOffComponent(params: {
+      channelId?: string;
+      customId: string;
+      messageId?: string;
+      values?: string[];
+    }): boolean;
+  };
+  modalHandler: { resolve(customId: string): DispatchModal | undefined };
+};
+
+export async function dispatchInteraction(
+  client: DispatchClient,
+  rawData: APIInteraction,
+): Promise<void> {
+  const interaction = createInteraction(client, rawData as RawInteraction);
+  if (rawData.type === InteractionType.ApplicationCommandAutocomplete) {
+    const command = client.commands.find((entry) => entry.name === readInteractionName(rawData));
+    if (!command) {
+      return;
+    }
+    const autocompleteInteraction = interaction as AutocompleteInteraction;
+    const optionAutocomplete = resolveFocusedCommandOptionAutocompleteHandler(
+      command,
+      autocompleteInteraction,
+    );
+    if (optionAutocomplete) {
+      await optionAutocomplete(autocompleteInteraction);
+      return;
+    }
+    if ("autocomplete" in command) {
+      await (
+        command as { autocomplete: (interaction: AutocompleteInteraction) => Promise<void> }
+      ).autocomplete(autocompleteInteraction);
+    }
+    return;
+  }
+  if (rawData.type === InteractionType.ApplicationCommand) {
+    const command = client.commands.find((entry) => entry.name === readInteractionName(rawData));
+    if (command && "run" in command) {
+      await deferCommandInteractionIfNeeded(command, interaction as CommandInteraction);
+      await (command as { run: (interaction: CommandInteraction) => Promise<void> }).run(
+        interaction as CommandInteraction,
+      );
+    }
+    return;
+  }
+  if (rawData.type === InteractionType.MessageComponent) {
+    const customId = readCustomId(rawData);
+    if (!customId) {
+      return;
+    }
+    const componentInteraction = interaction as BaseComponentInteraction;
+    if (
+      client.componentHandler.resolveOneOffComponent({
+        channelId: readMessageChannelId(rawData),
+        customId,
+        messageId: readMessageId(rawData),
+        values: readComponentValues(rawData),
+      })
+    ) {
+      await componentInteraction.acknowledge();
+      return;
+    }
+    const component = client.componentHandler.resolve(customId, {
+      componentType: (rawData as { data?: { component_type?: number } }).data?.component_type,
+    });
+    if (component) {
+      await deferComponentInteractionIfNeeded(component, componentInteraction);
+      await component.run(componentInteraction, parseComponentInteractionData(component, customId));
+    }
+    return;
+  }
+  if (rawData.type === InteractionType.ModalSubmit) {
+    const customId = readCustomId(rawData);
+    if (!customId) {
+      return;
+    }
+    const modal = client.modalHandler.resolve(customId);
+    if (modal) {
+      await modal.run(interaction as ModalInteraction, modal.customIdParser(customId).data);
+    }
+  }
+}
+
+function resolveConditionalComponentOption(
+  value: boolean | ((interaction: BaseComponentInteraction) => boolean),
+  interaction: BaseComponentInteraction,
+): boolean {
+  return typeof value === "function" ? value(interaction) : value;
+}
+
+async function deferComponentInteractionIfNeeded(
+  component: {
+    defer: boolean | ((interaction: BaseComponentInteraction) => boolean);
+    ephemeral: boolean | ((interaction: BaseComponentInteraction) => boolean);
+  },
+  interaction: BaseComponentInteraction,
+): Promise<void> {
+  if (!resolveConditionalComponentOption(component.defer, interaction)) {
+    return;
+  }
+  if (resolveConditionalComponentOption(component.ephemeral, interaction)) {
+    await interaction.defer({ ephemeral: true });
+    return;
+  }
+  await interaction.acknowledge();
+}
+
+function readInteractionName(rawData: APIInteraction): string | undefined {
+  return (rawData as { data?: { name?: string } }).data?.name;
+}
+
+function readCustomId(rawData: APIInteraction): string | undefined {
+  return (rawData as { data?: { custom_id?: string } }).data?.custom_id;
+}
+
+function readComponentValues(rawData: APIInteraction): string[] | undefined {
+  const values = (rawData as { data?: { values?: unknown } }).data?.values;
+  return Array.isArray(values) ? values.map(String) : undefined;
+}
+
+function readMessageId(rawData: APIInteraction): string | undefined {
+  const messageId = (rawData as { message?: { id?: unknown } }).message?.id;
+  return typeof messageId === "string" ? messageId : undefined;
+}
+
+function readMessageChannelId(rawData: APIInteraction): string | undefined {
+  const channelId = (rawData as { message?: { channel_id?: unknown } }).message?.channel_id;
+  return typeof channelId === "string" ? channelId : undefined;
+}

package/src/internal/interaction-options.ts

@@ -0,0 +1,98 @@
+import {
+  type APIApplicationCommandInteractionDataBasicOption,
+  type APIApplicationCommandInteractionDataOption,
+  type APIChannel,
+  type APIInteractionDataResolvedChannel,
+} from "discord-api-types/v10";
+import { channelFactory, type DiscordChannel, type StructureClient } from "./structures.js";
+
+type OptionsClient = StructureClient & {
+  fetchChannel(id: string): Promise<DiscordChannel>;
+};
+
+function readFocusedOption(
+  options: APIApplicationCommandInteractionDataOption[] | undefined,
+): APIApplicationCommandInteractionDataBasicOption | undefined {
+  for (const option of options ?? []) {
+    if ("focused" in option && option.focused) {
+      return option as APIApplicationCommandInteractionDataBasicOption;
+    }
+    const child = readFocusedOption(readChildOptions(option));
+    if (child) {
+      return child;
+    }
+  }
+  return undefined;
+}
+
+function findOption(
+  options: APIApplicationCommandInteractionDataOption[] | undefined,
+  name: string,
+): APIApplicationCommandInteractionDataOption | undefined {
+  for (const option of options ?? []) {
+    if (option.name === name) {
+      return option;
+    }
+    const child = findOption(readChildOptions(option), name);
+    if (child) {
+      return child;
+    }
+  }
+  return undefined;
+}
+
+function readChildOptions(
+  option: APIApplicationCommandInteractionDataOption,
+): APIApplicationCommandInteractionDataOption[] | undefined {
+  if (!("options" in option) || !Array.isArray(option.options)) {
+    return undefined;
+  }
+  return option.options;
+}
+
+export class OptionsHandler {
+  constructor(
+    private rawOptions: APIApplicationCommandInteractionDataOption[] | undefined,
+    private client: OptionsClient,
+    private resolvedChannels: Record<string, APIInteractionDataResolvedChannel> | undefined,
+  ) {}
+
+  getString(name: string): string | null {
+    const option = findOption(this.rawOptions, name);
+    const value = option && "value" in option ? option.value : undefined;
+    return typeof value === "string" ? value : null;
+  }
+
+  getNumber(name: string): number | null {
+    const option = findOption(this.rawOptions, name);
+    const value = option && "value" in option ? option.value : undefined;
+    return typeof value === "number" ? value : null;
+  }
+
+  getBoolean(name: string): boolean | null {
+    const option = findOption(this.rawOptions, name);
+    const value = option && "value" in option ? option.value : undefined;
+    return typeof value === "boolean" ? value : null;
+  }
+
+  async getChannel(name: string, required = false) {
+    const option = findOption(this.rawOptions, name);
+    const value = option && "value" in option ? option.value : undefined;
+    const id = typeof value === "string" ? value : undefined;
+    const resolved = id ? this.resolvedChannels?.[id] : undefined;
+    if (resolved) {
+      return channelFactory(this.client, resolved as APIChannel);
+    }
+    if (id) {
+      return await this.client.fetchChannel(id);
+    }
+    if (required) {
+      throw new Error(`Missing required channel option ${name}`);
+    }
+    return null;
+  }
+
+  getFocused(): APIApplicationCommandInteractionDataBasicOption | undefined {
+    return readFocusedOption(this.rawOptions);
+  }
+}

package/src/internal/interaction-response.ts

@@ -0,0 +1,53 @@
+import { InteractionResponseType, MessageFlags } from "discord-api-types/v10";
+
+export type InteractionResponseState =
+  | "unacknowledged"
+  | "deferred"
+  | "deferred-update"
+  | "replied";
+
+type InteractionReplyAction = "initial" | "edit" | "follow-up";
+
+export class InteractionResponseController {
+  state: InteractionResponseState = "unacknowledged";
+
+  get acknowledged(): boolean {
+    return this.state !== "unacknowledged";
+  }
+
+  recordCallback(type: InteractionResponseType): void {
+    if (type === InteractionResponseType.DeferredChannelMessageWithSource) {
+      this.state = "deferred";
+      return;
+    }
+    if (type === InteractionResponseType.DeferredMessageUpdate) {
+      this.state = "deferred-update";
+      return;
+    }
+    this.state = "replied";
+  }
+
+  nextReplyAction(): InteractionReplyAction {
+    if (this.state === "deferred" || this.state === "deferred-update") {
+      return "edit";
+    }
+    if (this.state === "unacknowledged") {
+      return "initial";
+    }
+    return "follow-up";
+  }
+
+  recordReplyEdit(): void {
+    this.state = "replied";
+  }
+}
+
+export function needsComponentsV2Query(body: unknown): boolean {
+  return (
+    body !== null &&
+    typeof body === "object" &&
+    "flags" in body &&
+    typeof (body as { flags?: unknown }).flags === "number" &&
+    ((body as { flags: number }).flags & MessageFlags.IsComponentsV2) !== 0
+  );
+}

package/src/internal/interactions.test.ts

@@ -0,0 +1,329 @@
+import {
+  ComponentType,
+  type GuildMemberFlags,
+  InteractionResponseType,
+  InteractionType,
+  MessageFlags,
+} from "discord-api-types/v10";
+import { describe, expect, it, vi } from "vitest";
+import { Container, TextDisplay } from "./components.js";
+import {
+  BaseInteraction,
+  ModalInteraction,
+  createInteraction,
+  type RawInteraction,
+} from "./interactions.js";
+import { Message } from "./structures.js";
+import {
+  attachRestMock,
+  createInternalComponentInteractionPayload,
+  createInternalInteractionPayload,
+  createInternalModalInteractionPayload,
+  createInternalTestClient,
+} from "./test-builders.test-support.js";
+
+describe("BaseInteraction", () => {
+  it("edits the original interaction response after defer", async () => {
+    const post = vi.fn(async () => undefined);
+    const patch = vi.fn(async () => undefined);
+    const client = createInternalTestClient();
+    attachRestMock(client, { patch, post });
+    const interaction = new BaseInteraction(
+      client,
+      createInternalInteractionPayload({ id: "interaction1", token: "token1" }),
+    );
+
+    await interaction.defer({ ephemeral: true });
+    await interaction.reply({ content: "done", ephemeral: true });
+
+    expect(post).toHaveBeenNthCalledWith(1, "/interactions/interaction1/token1/callback", {
+      body: {
+        type: InteractionResponseType.DeferredChannelMessageWithSource,
+        data: { flags: 64 },
+      },
+    });
+    expect(patch).toHaveBeenCalledWith("/webhooks/app1/token1/messages/%40original", {
+      body: { content: "done", flags: 64 },
+    });
+  });
+
+  it("uses with_components for Components V2 follow-ups", async () => {
+    const post = vi.fn(async () => undefined);
+    const client = createInternalTestClient();
+    attachRestMock(client, { post });
+    const interaction = new BaseInteraction(
+      client,
+      createInternalInteractionPayload({ id: "interaction1", token: "token1" }),
+    );
+
+    await interaction.reply("first");
+    await interaction.reply({
+      components: [new Container([new TextDisplay("done")])],
+    });
+
+    expect(post).toHaveBeenNthCalledWith(
+      2,
+      "/webhooks/app1/token1",
+      {
+        body: {
+          components: [
+            {
+              type: 17,
+              components: [{ type: 10, content: "done" }],
+            },
+          ],
+          flags: MessageFlags.IsComponentsV2,
+        },
+      },
+      { with_components: true },
+    );
+  });
+
+  it("uses with_components when editing deferred Components V2 replies", async () => {
+    const post = vi.fn(async () => undefined);
+    const patch = vi.fn(async () => undefined);
+    const client = createInternalTestClient();
+    attachRestMock(client, { patch, post });
+    const interaction = new BaseInteraction(
+      client,
+      createInternalInteractionPayload({ id: "interaction1", token: "token1" }),
+    );
+
+    await interaction.defer();
+    await interaction.reply({
+      components: [new Container([new TextDisplay("done")])],
+    });
+
+    expect(patch).toHaveBeenCalledWith(
+      "/webhooks/app1/token1/messages/%40original",
+      {
+        body: {
+          components: [
+            {
+              type: 17,
+              components: [{ type: 10, content: "done" }],
+            },
+          ],
+          flags: MessageFlags.IsComponentsV2,
+        },
+      },
+      { with_components: true },
+    );
+  });
+
+  it("edits the original component message after acknowledge", async () => {
+    const post = vi.fn(async () => undefined);
+    const patch = vi.fn(async () => undefined);
+    const client = createInternalTestClient();
+    attachRestMock(client, { patch, post });
+    const interaction = createInteraction(
+      client,
+      createInternalComponentInteractionPayload({
+        id: "interaction1",
+        token: "token1",
+        data: {
+          component_type: ComponentType.Button,
+          custom_id: "button1",
+        },
+      }),
+    );
+
+    await interaction.acknowledge();
+    await interaction.reply({ content: "updated", components: [] });
+
+    expect(post).toHaveBeenCalledTimes(1);
+    expect(post).toHaveBeenCalledWith("/interactions/interaction1/token1/callback", {
+      body: { type: InteractionResponseType.DeferredMessageUpdate },
+    });
+    expect(patch).toHaveBeenCalledWith("/webhooks/app1/token1/messages/%40original", {
+      body: { content: "updated", components: [] },
+    });
+  });
+
+  it("rejects malformed interaction payloads at the boundary", () => {
+    expect(() =>
+      createInteraction(createInternalTestClient(), {
+        id: "interaction1",
+        type: 3,
+      } as unknown as RawInteraction),
+    ).toThrow(/Invalid Discord interaction payload/);
+  });
+
+  it("preserves guild member user identity fields", () => {
+    const interaction = createInteraction(
+      createInternalTestClient(),
+      createInternalInteractionPayload({
+        id: "interaction1",
+        token: "token1",
+        type: InteractionType.ApplicationCommand,
+        guild_id: "guild1",
+        member: {
+          roles: [],
+          permissions: "0",
+          flags: 0 as GuildMemberFlags,
+          joined_at: "2026-01-01T00:00:00.000Z",
+          deaf: false,
+          mute: false,
+          user: {
+            id: "user1",
+            username: "alice",
+            global_name: "Alice Cooper",
+            discriminator: "1234",
+            avatar: null,
+          },
+        },
+      }),
+    );
+
+    expect(interaction.user?.id).toBe("user1");
+    expect(interaction.user?.username).toBe("alice");
+    expect(interaction.user?.globalName).toBe("Alice Cooper");
+    expect(interaction.user?.discriminator).toBe("1234");
+  });
+
+  it("waits for a one-off component reply without invoking registered handlers", async () => {
+    const get = vi.fn(async () => ({
+      id: "message1",
+      channel_id: "channel1",
+      author: {
+        id: "bot1",
+        username: "bot",
+        discriminator: "0000",
+        global_name: null,
+        avatar: null,
+      },
+      content: "pick",
+      timestamp: "2026-05-01T00:00:00.000Z",
+    }));
+    const post = vi.fn(async () => undefined);
+    const client = createInternalTestClient();
+    attachRestMock(client, { get, post });
+    const interaction = new BaseInteraction(
+      client,
+      createInternalInteractionPayload({ id: "interaction1", token: "token1" }),
+    );
+
+    const wait = interaction.replyAndWaitForComponent({ content: "pick" }, 1_000);
+    await vi.waitFor(() =>
+      expect(get).toHaveBeenCalledWith("/webhooks/app1/token1/messages/%40original"),
+    );
+
+    await client.handleInteraction(
+      createInternalComponentInteractionPayload({
+        id: "component-interaction1",
+        token: "component-token1",
+        data: { custom_id: "button1" },
+        message: {
+          id: "message1",
+          channel_id: "channel1",
+          author: {
+            id: "bot1",
+            username: "bot",
+            discriminator: "0000",
+            global_name: null,
+            avatar: null,
+          },
+          content: "pick",
+          timestamp: "2026-05-01T00:00:00.000Z",
+          edited_timestamp: null,
+          tts: false,
+          mention_everyone: false,
+          mentions: [],
+          mention_roles: [],
+          attachments: [],
+          embeds: [],
+          pinned: false,
+          type: 0,
+        },
+      }),
+    );
+
+    const result = await wait;
+    if (!result.success) {
+      throw new Error("expected component wait to succeed");
+    }
+    expect(result.customId).toBe("button1");
+    expect(result.message).toBeInstanceOf(Message);
+    expect(result.message?.id).toBe("message1");
+    expect(result.message?.channelId).toBe("channel1");
+    expect(result.values).toBeUndefined();
+    expect(post).toHaveBeenNthCalledWith(
+      2,
+      "/interactions/component-interaction1/component-token1/callback",
+      {
+        body: { type: InteractionResponseType.DeferredMessageUpdate },
+      },
+    );
+  });
+});
+
+describe("ModalInteraction", () => {
+  it("reads submitted fields from Components V2 label wrappers", () => {
+    const interaction = createInteraction(
+      createInternalTestClient(),
+      createInternalModalInteractionPayload({
+        id: "interaction1",
+        token: "token1",
+        data: {
+          components: [
+            {
+              type: ComponentType.Label,
+              component: {
+                type: ComponentType.TextInput,
+                custom_id: "title",
+                value: "Hello",
+              },
+            },
+          ],
+        },
+      }),
+    );
+
+    expect(interaction).toBeInstanceOf(ModalInteraction);
+    expect((interaction as ModalInteraction).fields.getText("title")).toBe("Hello");
+  });
+
+  it("acknowledges modal submits as message updates", async () => {
+    const post = vi.fn(async () => undefined);
+    const client = createInternalTestClient();
+    attachRestMock(client, { post });
+    const interaction = createInteraction(
+      client,
+      createInternalModalInteractionPayload({
+        id: "interaction1",
+        token: "token1",
+      }),
+    );
+
+    await (interaction as ModalInteraction).acknowledge();
+
+    expect(post).toHaveBeenCalledWith("/interactions/interaction1/token1/callback", {
+      body: { type: InteractionResponseType.DeferredMessageUpdate },
+    });
+  });
+
+  it("edits the original modal source message after acknowledge", async () => {
+    const post = vi.fn(async () => undefined);
+    const patch = vi.fn(async () => undefined);
+    const client = createInternalTestClient();
+    attachRestMock(client, { patch, post });
+    const interaction = createInteraction(
+      client,
+      createInternalModalInteractionPayload({
+        id: "interaction1",
+        token: "token1",
+      }),
+    );
+
+    await (interaction as ModalInteraction).acknowledge();
+    await interaction.reply({ content: "cleared", components: [] });
+
+    expect(post).toHaveBeenCalledTimes(1);
+    expect(post).toHaveBeenCalledWith("/interactions/interaction1/token1/callback", {
+      body: { type: InteractionResponseType.DeferredMessageUpdate },
+    });
+    expect(patch).toHaveBeenCalledWith("/webhooks/app1/token1/messages/%40original", {
+      body: { content: "cleared", components: [] },
+    });
+  });
+});