@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/internal/test-builders.test-support.ts

@@ -0,0 +1,167 @@
+import { ComponentType, InteractionType } from "discord-api-types/v10";
+import { vi, type Mock } from "vitest";
+import { Client, type ClientOptions } from "./client.js";
+import type { BaseCommand } from "./commands.js";
+import type { RawInteraction } from "./interactions.js";
+import type { QueuedRequest, RequestClient, RequestData } from "./rest.js";
+
+type RestMock = Partial<Record<"get" | "post" | "patch" | "put" | "delete", Mock>>;
+type RestMethod = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+type RawInteractionOverrides = Omit<Partial<RawInteraction>, "data" | "type"> &
+  Pick<RawInteraction, "id" | "token"> & {
+    data?: Record<string, unknown>;
+  };
+
+type FakeRestCall = {
+  method: RestMethod;
+  path: string;
+  data?: RequestData;
+  query?: QueuedRequest["query"];
+};
+
+type FakeRestClient = RequestClient & {
+  calls: FakeRestCall[];
+  enqueueResponse: (value: unknown) => void;
+};
+
+export function createDeferred<T>() {
+  let resolve: ((value: T) => void) | undefined;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve: resolve! };
+}
+
+export function createJsonResponse(body: unknown, init?: ResponseInit): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    ...init,
+  });
+}
+
+export function createAbortableFetchMock() {
+  let receivedSignal: AbortSignal | undefined;
+  const fetch = vi.fn(
+    (_input: string | URL | Request, init?: RequestInit) =>
+      new Promise<Response>((_resolve, reject) => {
+        receivedSignal = init?.signal ?? undefined;
+        init?.signal?.addEventListener("abort", () => {
+          reject(new DOMException("The operation was aborted.", "AbortError"));
+        });
+      }),
+  );
+  return {
+    fetch,
+    get receivedSignal() {
+      return receivedSignal;
+    },
+  };
+}
+
+export function createInternalTestClient(
+  commands: BaseCommand[] = [],
+  options?: Partial<ClientOptions>,
+): Client {
+  return new Client(
+    {
+      baseUrl: "http://localhost",
+      clientId: "app1",
+      publicKey: "public",
+      token: "token",
+      ...options,
+    },
+    { commands },
+  );
+}
+
+function createRestMock(overrides: RestMock = {}): RestMock & RequestClient {
+  return {
+    get: vi.fn(async () => undefined),
+    post: vi.fn(async () => undefined),
+    patch: vi.fn(async () => undefined),
+    put: vi.fn(async () => undefined),
+    delete: vi.fn(async () => undefined),
+    ...overrides,
+  } as RestMock & RequestClient;
+}
+
+export function attachRestMock(client: Client, rest: RestMock): RestMock & RequestClient {
+  const mock = createRestMock(rest);
+  client.rest = mock;
+  return mock;
+}
+
+export function createFakeRestClient(responses: unknown[] = []): FakeRestClient {
+  const calls: FakeRestCall[] = [];
+  const queued = [...responses];
+  const request = async (
+    method: RestMethod,
+    path: string,
+    data?: RequestData,
+    query?: QueuedRequest["query"],
+  ) => {
+    calls.push({ method, path, data, query });
+    return queued.shift();
+  };
+  return {
+    calls,
+    enqueueResponse: (value: unknown) => {
+      queued.push(value);
+    },
+    get: async (path, query) => await request("GET", path, undefined, query),
+    post: async (path, data, query) => await request("POST", path, data, query),
+    patch: async (path, data, query) => await request("PATCH", path, data, query),
+    put: async (path, data, query) => await request("PUT", path, data, query),
+    delete: async (path, data, query) => await request("DELETE", path, data, query),
+  } as FakeRestClient;
+}
+
+export function createInternalInteractionPayload(
+  overrides: Partial<RawInteraction> & Pick<RawInteraction, "id" | "token">,
+): RawInteraction {
+  return {
+    application_id: "app1",
+    type: InteractionType.ApplicationCommand,
+    version: 1,
+    data: {
+      id: "command1",
+      name: "test",
+      type: 1,
+    },
+    ...overrides,
+  } as unknown as RawInteraction;
+}
+
+export function createInternalComponentInteractionPayload(
+  overrides: RawInteractionOverrides,
+): RawInteraction {
+  const { data, ...rest } = overrides;
+  return {
+    application_id: "app1",
+    version: 1,
+    data: {
+      component_type: ComponentType.Button,
+      custom_id: "component1",
+      ...data,
+    },
+    ...rest,
+    type: InteractionType.MessageComponent,
+  } as unknown as RawInteraction;
+}
+
+export function createInternalModalInteractionPayload(
+  overrides: RawInteractionOverrides,
+): RawInteraction {
+  const { data, ...rest } = overrides;
+  return {
+    application_id: "app1",
+    version: 1,
+    data: {
+      custom_id: "modal1",
+      components: [],
+      ...data,
+    },
+    ...rest,
+    type: InteractionType.ModalSubmit,
+  } as unknown as RawInteraction;
+}

package/src/internal/voice.ts

@@ -0,0 +1,49 @@
+import type {
+  DiscordGatewayAdapterCreator,
+  DiscordGatewayAdapterLibraryMethods,
+} from "@discordjs/voice";
+import type { GatewaySendPayload } from "discord-api-types/v10";
+import { Plugin, type Client } from "./client.js";
+import type { GatewayPlugin } from "./gateway.js";
+
+export class VoicePlugin extends Plugin {
+  readonly id = "voice";
+  protected client?: Client;
+  readonly adapters = new Map<string, DiscordGatewayAdapterLibraryMethods>();
+  private gatewayPlugin?: GatewayPlugin;
+
+  override registerClient(client: Client): void {
+    this.client = client;
+    this.gatewayPlugin = client.getPlugin<GatewayPlugin>("gateway");
+    if (!this.gatewayPlugin) {
+      throw new Error("Discord voice cannot be used without a gateway connection.");
+    }
+  }
+
+  getGateway(_guildId: string): GatewayPlugin | undefined {
+    return this.gatewayPlugin;
+  }
+
+  getGatewayAdapterCreator(guildId: string): DiscordGatewayAdapterCreator {
+    const gateway = this.getGateway(guildId);
+    if (!gateway) {
+      throw new Error("Discord voice cannot be used without a gateway connection.");
+    }
+    return (methods) => {
+      this.adapters.set(guildId, methods);
+      return {
+        sendPayload(payload) {
+          try {
+            gateway.send(payload as GatewaySendPayload, true);
+            return true;
+          } catch {
+            return false;
+          }
+        },
+        destroy: () => {
+          this.adapters.delete(guildId);
+        },
+      };
+    };
+  }
+}

package/src/media-detection.ts

@@ -0,0 +1,28 @@
+import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
+
+const DISCORD_VIDEO_MEDIA_EXTENSIONS = new Set([".avi", ".m4v", ".mkv", ".mov", ".mp4", ".webm"]);
+
+function normalizeMediaPathForExtension(mediaUrl: string): string {
+  const trimmed = mediaUrl.trim();
+  if (!trimmed) {
+    return "";
+  }
+  try {
+    const parsed = new URL(trimmed);
+    return normalizeLowercaseStringOrEmpty(parsed.pathname);
+  } catch {
+    const withoutHash = trimmed.split("#", 1)[0] ?? trimmed;
+    const withoutQuery = withoutHash.split("?", 1)[0] ?? withoutHash;
+    return normalizeLowercaseStringOrEmpty(withoutQuery);
+  }
+}
+
+export function isLikelyDiscordVideoMedia(mediaUrl: string): boolean {
+  const normalized = normalizeMediaPathForExtension(mediaUrl);
+  for (const ext of DISCORD_VIDEO_MEDIA_EXTENSIONS) {
+    if (normalized.endsWith(ext)) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/mentions.test.ts

@@ -0,0 +1,111 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  resetDiscordDirectoryCacheForTest,
+  rememberDiscordDirectoryUser,
+} from "./directory-cache.js";
+import { formatMention, rewriteDiscordKnownMentions } from "./mentions.js";
+
+describe("formatMention", () => {
+  it("formats user mentions from ids", () => {
+    expect(formatMention({ userId: "123456789" })).toBe("<@123456789>");
+  });
+
+  it("formats role mentions from ids", () => {
+    expect(formatMention({ roleId: "987654321" })).toBe("<@&987654321>");
+  });
+
+  it("formats channel mentions from ids", () => {
+    expect(formatMention({ channelId: "777555333" })).toBe("<#777555333>");
+  });
+
+  it("throws when no mention id is provided", () => {
+    expect(() => formatMention({})).toThrow(/exactly one/i);
+  });
+
+  it("throws when more than one mention id is provided", () => {
+    expect(() => formatMention({ userId: "1", roleId: "2" })).toThrow(/exactly one/i);
+  });
+});
+
+describe("rewriteDiscordKnownMentions", () => {
+  beforeEach(() => {
+    resetDiscordDirectoryCacheForTest();
+  });
+
+  it("rewrites @name mentions when a cached user id exists", () => {
+    rememberDiscordDirectoryUser({
+      accountId: "default",
+      userId: "123456789",
+      handles: ["Alice", "@alice_user", "alice#1234"],
+    });
+    const rewritten = rewriteDiscordKnownMentions("ping @Alice and @alice_user", {
+      accountId: "default",
+    });
+    expect(rewritten).toBe("ping <@123456789> and <@123456789>");
+  });
+
+  it("rewrites configured mention aliases before the cache", () => {
+    rememberDiscordDirectoryUser({
+      accountId: "default",
+      userId: "111111111",
+      handles: ["vladislava"],
+    });
+    const rewritten = rewriteDiscordKnownMentions("ping @Vladislava and @BuildBot#1234", {
+      accountId: "default",
+      mentionAliases: {
+        BuildBot: "222222222",
+        Vladislava: "333333333",
+      },
+    });
+    expect(rewritten).toBe("ping <@333333333> and <@222222222>");
+  });
+
+  it("supports configured aliases with a leading @ key", () => {
+    const rewritten = rewriteDiscordKnownMentions("ping @OpsLead", {
+      accountId: "default",
+      mentionAliases: {
+        "@opslead": "444444444",
+      },
+    });
+    expect(rewritten).toBe("ping <@444444444>");
+  });
+
+  it("preserves unknown mentions and reserved mentions", () => {
+    rememberDiscordDirectoryUser({
+      accountId: "default",
+      userId: "123456789",
+      handles: ["alice"],
+    });
+    const rewritten = rewriteDiscordKnownMentions("hello @unknown @everyone @here", {
+      accountId: "default",
+    });
+    expect(rewritten).toBe("hello @unknown @everyone @here");
+  });
+
+  it("does not rewrite mentions inside markdown code spans", () => {
+    rememberDiscordDirectoryUser({
+      accountId: "default",
+      userId: "123456789",
+      handles: ["alice"],
+    });
+    const rewritten = rewriteDiscordKnownMentions(
+      "inline `@alice` fence ```\n@alice\n``` text @alice",
+      {
+        accountId: "default",
+      },
+    );
+    expect(rewritten).toBe("inline `@alice` fence ```\n@alice\n``` text <@123456789>");
+  });
+
+  it("is account-scoped", () => {
+    rememberDiscordDirectoryUser({
+      accountId: "ops",
+      userId: "999888777",
+      handles: ["alice"],
+    });
+    const defaultRewrite = rewriteDiscordKnownMentions("@alice", { accountId: "default" });
+    const opsRewrite = rewriteDiscordKnownMentions("@alice", { accountId: "ops" });
+    expect(defaultRewrite).toBe("@alice");
+    expect(opsRewrite).toBe("<@999888777>");
+  });
+});

package/src/mentions.ts

@@ -0,0 +1,147 @@
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalString,
+  normalizeOptionalStringifiedId,
+} from "klaw/plugin-sdk/string-coerce-runtime";
+import { resolveDiscordDirectoryUserId } from "./directory-cache.js";
+
+type DiscordMentionAliasesConfig = Record<string, string>;
+
+const MARKDOWN_CODE_SEGMENT_PATTERN = /```[\s\S]*?```|`[^`\n]*`/g;
+const MENTION_CANDIDATE_PATTERN = /(^|[\s([{"'.,;:!?])@([a-z0-9_.-]{2,32}(?:#[0-9]{4})?)/gi;
+const DISCORD_RESERVED_MENTIONS = new Set(["everyone", "here"]);
+const DISCORD_DISCRIMINATOR_SUFFIX = /#\d{4}$/;
+
+function normalizeSnowflake(value: string | number | bigint): string | null {
+  const text = normalizeOptionalStringifiedId(value) ?? "";
+  if (!/^\d+$/.test(text)) {
+    return null;
+  }
+  return text;
+}
+
+export function formatMention(params: {
+  userId?: string | number | bigint | null;
+  roleId?: string | number | bigint | null;
+  channelId?: string | number | bigint | null;
+}): string {
+  const userId = params.userId == null ? null : normalizeSnowflake(params.userId);
+  const roleId = params.roleId == null ? null : normalizeSnowflake(params.roleId);
+  const channelId = params.channelId == null ? null : normalizeSnowflake(params.channelId);
+  const values = [
+    userId ? { kind: "user" as const, id: userId } : null,
+    roleId ? { kind: "role" as const, id: roleId } : null,
+    channelId ? { kind: "channel" as const, id: channelId } : null,
+  ].filter((entry): entry is { kind: "user" | "role" | "channel"; id: string } => Boolean(entry));
+  if (values.length !== 1) {
+    throw new Error("formatMention requires exactly one of userId, roleId, or channelId");
+  }
+  const target = values[0];
+  if (target.kind === "user") {
+    return `<@${target.id}>`;
+  }
+  if (target.kind === "role") {
+    return `<@&${target.id}>`;
+  }
+  return `<#${target.id}>`;
+}
+
+function normalizeHandleKey(raw: string): string | null {
+  let handle = normalizeOptionalString(raw) ?? "";
+  if (!handle) {
+    return null;
+  }
+  if (handle.startsWith("@")) {
+    handle = normalizeOptionalString(handle.slice(1)) ?? "";
+  }
+  if (!handle || /\s/.test(handle)) {
+    return null;
+  }
+  return normalizeLowercaseStringOrEmpty(handle);
+}
+
+function resolveConfiguredMentionAlias(
+  handle: string,
+  mentionAliases?: DiscordMentionAliasesConfig | null,
+): string | undefined {
+  const key = normalizeHandleKey(handle);
+  if (!key || !mentionAliases) {
+    return undefined;
+  }
+  const withoutDiscriminator = key.replace(DISCORD_DISCRIMINATOR_SUFFIX, "");
+  for (const [rawAlias, rawUserId] of Object.entries(mentionAliases)) {
+    const alias = normalizeHandleKey(rawAlias);
+    if (!alias) {
+      continue;
+    }
+    const aliasWithoutDiscriminator = alias.replace(DISCORD_DISCRIMINATOR_SUFFIX, "");
+    if (
+      alias === key ||
+      (withoutDiscriminator && withoutDiscriminator !== key && alias === withoutDiscriminator) ||
+      (aliasWithoutDiscriminator &&
+        aliasWithoutDiscriminator !== alias &&
+        aliasWithoutDiscriminator === key)
+    ) {
+      const userId = normalizeSnowflake(rawUserId);
+      if (userId) {
+        return userId;
+      }
+    }
+  }
+  return undefined;
+}
+
+function rewritePlainTextMentions(
+  text: string,
+  params: {
+    accountId?: string | null;
+    mentionAliases?: DiscordMentionAliasesConfig | null;
+  },
+): string {
+  if (!text.includes("@")) {
+    return text;
+  }
+  return text.replace(MENTION_CANDIDATE_PATTERN, (match, prefix, rawHandle) => {
+    const handle = normalizeOptionalString(rawHandle) ?? "";
+    if (!handle) {
+      return match;
+    }
+    const lookup = normalizeLowercaseStringOrEmpty(handle);
+    if (DISCORD_RESERVED_MENTIONS.has(lookup)) {
+      return match;
+    }
+    const userId =
+      resolveConfiguredMentionAlias(handle, params.mentionAliases) ??
+      resolveDiscordDirectoryUserId({
+        accountId: params.accountId,
+        handle,
+      });
+    if (!userId) {
+      return match;
+    }
+    return `${String(prefix ?? "")}${formatMention({ userId })}`;
+  });
+}
+
+export function rewriteDiscordKnownMentions(
+  text: string,
+  params: {
+    accountId?: string | null;
+    mentionAliases?: DiscordMentionAliasesConfig | null;
+  },
+): string {
+  if (!text.includes("@")) {
+    return text;
+  }
+  let rewritten = "";
+  let offset = 0;
+  MARKDOWN_CODE_SEGMENT_PATTERN.lastIndex = 0;
+  for (const match of text.matchAll(MARKDOWN_CODE_SEGMENT_PATTERN)) {
+    const matchIndex = match.index ?? 0;
+    rewritten += rewritePlainTextMentions(text.slice(offset, matchIndex), params);
+    rewritten += match[0];
+    offset = matchIndex + match[0].length;
+  }
+  rewritten += rewritePlainTextMentions(text.slice(offset), params);
+  return rewritten;
+}

package/src/monitor/ack-reactions.ts

@@ -0,0 +1,70 @@
+import {
+  createStatusReactionController,
+  logAckFailure,
+  type StatusReactionAdapter,
+} from "klaw/plugin-sdk/channel-feedback";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { logVerbose } from "klaw/plugin-sdk/runtime-env";
+import { createDiscordRuntimeAccountContext } from "../client.js";
+import type { RequestClient } from "../internal/discord.js";
+import { reactMessageDiscord, removeReactionDiscord } from "../send.js";
+import type { DiscordReactionRuntimeContext } from "../send.types.js";
+
+export function createDiscordAckReactionContext(params: {
+  rest: RequestClient;
+  cfg: KlawConfig;
+  accountId: string;
+}): DiscordReactionRuntimeContext {
+  return {
+    rest: params.rest,
+    ...createDiscordRuntimeAccountContext({
+      cfg: params.cfg,
+      accountId: params.accountId,
+    }),
+  };
+}
+
+export function createDiscordAckReactionAdapter(params: {
+  channelId: string;
+  messageId: string;
+  reactionContext: DiscordReactionRuntimeContext;
+}): StatusReactionAdapter {
+  return {
+    setReaction: async (emoji) => {
+      await reactMessageDiscord(params.channelId, params.messageId, emoji, params.reactionContext);
+    },
+    removeReaction: async (emoji) => {
+      await removeReactionDiscord(
+        params.channelId,
+        params.messageId,
+        emoji,
+        params.reactionContext,
+      );
+    },
+  };
+}
+
+export function queueInitialDiscordAckReaction(params: {
+  enabled: boolean;
+  shouldSendAckReaction: boolean;
+  ackReaction: string | undefined;
+  statusReactions: ReturnType<typeof createStatusReactionController>;
+  reactionAdapter: StatusReactionAdapter;
+  target: string;
+}) {
+  if (params.enabled) {
+    void params.statusReactions.setQueued();
+    return;
+  }
+  if (!params.shouldSendAckReaction || !params.ackReaction) {
+    return;
+  }
+  void params.reactionAdapter.setReaction(params.ackReaction).catch((err) => {
+    logAckFailure({
+      log: logVerbose,
+      channel: "discord",
+      target: params.target,
+      error: err,
+    });
+  });
+}