@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/send.outbound.ts

@@ -0,0 +1,459 @@
+import { ChannelType } from "discord-api-types/v10";
+import { recordChannelActivity } from "klaw/plugin-sdk/channel-activity-runtime";
+import type { MarkdownTableMode, KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { resolveMarkdownTableMode } from "klaw/plugin-sdk/markdown-table-runtime";
+import type { OutboundMediaAccess, PollInput } from "klaw/plugin-sdk/media-runtime";
+import { requireRuntimeConfig } from "klaw/plugin-sdk/plugin-config-runtime";
+import { resolveChunkMode, type ChunkMode } from "klaw/plugin-sdk/reply-chunking";
+import type { RetryConfig } from "klaw/plugin-sdk/retry-runtime";
+import { normalizeOptionalString } from "klaw/plugin-sdk/string-coerce-runtime";
+import { convertMarkdownTables } from "klaw/plugin-sdk/text-chunking";
+import { resolveDiscordAccount } from "./accounts.js";
+import { createChannelMessage, createThread, type RequestClient } from "./internal/discord.js";
+import { rewriteDiscordKnownMentions } from "./mentions.js";
+import { parseAndResolveRecipient } from "./recipient-resolution.js";
+import { createDiscordSendResult, type DiscordReceiptResultSource } from "./send.receipt.js";
+import {
+  buildDiscordMessageRequest,
+  buildDiscordSendError,
+  buildDiscordTextChunks,
+  createDiscordClient,
+  normalizeDiscordPollInput,
+  normalizeStickerIds,
+  resolveDiscordMessageFlags,
+  resolveChannelId,
+  resolveDiscordChannelType,
+  resolveDiscordSendComponents,
+  resolveDiscordSendEmbeds,
+  sendDiscordMedia,
+  sendDiscordText,
+  type DiscordSendComponents,
+  type DiscordSendEmbeds,
+} from "./send.shared.js";
+import type { DiscordSendResult } from "./send.types.js";
+type DiscordSendOpts = {
+  cfg: KlawConfig;
+  token?: string;
+  accountId?: string;
+  mediaUrl?: string;
+  filename?: string;
+  mediaAccess?: OutboundMediaAccess;
+  mediaLocalRoots?: readonly string[];
+  mediaReadFile?: (filePath: string) => Promise<Buffer>;
+  verbose?: boolean;
+  rest?: RequestClient;
+  replyTo?: string;
+  retry?: RetryConfig;
+  textLimit?: number;
+  maxLinesPerMessage?: number;
+  tableMode?: MarkdownTableMode;
+  chunkMode?: ChunkMode;
+  components?: DiscordSendComponents;
+  embeds?: DiscordSendEmbeds;
+  silent?: boolean;
+  suppressEmbeds?: boolean;
+};
+
+type DiscordClientRequest = ReturnType<typeof createDiscordClient>["request"];
+
+const DEFAULT_DISCORD_MEDIA_MAX_MB = 100;
+
+type DiscordChannelMessageResult = DiscordReceiptResultSource;
+
+async function sendDiscordThreadTextChunks(params: {
+  rest: RequestClient;
+  threadId: string;
+  chunks: readonly string[];
+  request: DiscordClientRequest;
+  maxLinesPerMessage?: number;
+  chunkMode: ReturnType<typeof resolveChunkMode>;
+  maxChars?: number;
+  silent?: boolean;
+  suppressEmbeds?: boolean;
+}): Promise<void> {
+  for (const chunk of params.chunks) {
+    await sendDiscordText(
+      params.rest,
+      params.threadId,
+      chunk,
+      undefined,
+      params.request,
+      params.maxLinesPerMessage,
+      undefined,
+      undefined,
+      params.chunkMode,
+      params.silent,
+      params.suppressEmbeds,
+      params.maxChars,
+    );
+  }
+}
+
+function resolveDiscordSuppressEmbeds(params: {
+  configured?: boolean;
+  override?: boolean;
+}): boolean {
+  return params.override ?? params.configured ?? true;
+}
+
+/** Discord thread names are capped at 100 characters. */
+const DISCORD_THREAD_NAME_LIMIT = 100;
+
+/** Derive a thread title from the first non-empty line of the message text. */
+function deriveForumThreadName(text: string): string {
+  const firstLine =
+    normalizeOptionalString(text.split("\n").find((line) => normalizeOptionalString(line))) ?? "";
+  return firstLine.slice(0, DISCORD_THREAD_NAME_LIMIT) || new Date().toISOString().slice(0, 16);
+}
+
+/** Forum/Media channels cannot receive regular messages; detect them here. */
+function isForumLikeType(channelType?: number): boolean {
+  return channelType === ChannelType.GuildForum || channelType === ChannelType.GuildMedia;
+}
+
+function toDiscordSendResult(
+  result: DiscordChannelMessageResult,
+  fallbackChannelId: string,
+  params: {
+    kind?: Parameters<typeof createDiscordSendResult>[0]["kind"];
+    threadId?: string | number;
+    replyToId?: string;
+  } = {},
+): DiscordSendResult {
+  const resultParams: Parameters<typeof createDiscordSendResult>[0] = {
+    result,
+    fallbackChannelId,
+    kind: params.kind ?? "text",
+  };
+  if (params.threadId != null) {
+    resultParams.threadId = params.threadId;
+  }
+  if (params.replyToId) {
+    resultParams.replyToId = params.replyToId;
+  }
+  return createDiscordSendResult(resultParams);
+}
+
+async function resolveDiscordSendTarget(
+  to: string,
+  opts: DiscordSendOpts,
+): Promise<{ rest: RequestClient; request: DiscordClientRequest; channelId: string }> {
+  const cfg = requireRuntimeConfig(opts.cfg, "Discord send target resolution");
+  const { rest, request } = createDiscordClient({ ...opts, cfg });
+  const recipient = await parseAndResolveRecipient(to, cfg, opts.accountId);
+  const { channelId } = await resolveChannelId(rest, recipient, request);
+  return { rest, request, channelId };
+}
+
+export async function sendMessageDiscord(
+  to: string,
+  text: string,
+  opts: DiscordSendOpts,
+): Promise<DiscordSendResult> {
+  const cfg = requireRuntimeConfig(opts.cfg, "Discord send");
+  const accountInfo = resolveDiscordAccount({
+    cfg,
+    accountId: opts.accountId,
+  });
+  const tableMode = resolveMarkdownTableMode({
+    cfg,
+    channel: "discord",
+    accountId: accountInfo.accountId,
+  });
+  const effectiveTableMode = opts.tableMode ?? tableMode;
+  const chunkMode = opts.chunkMode ?? resolveChunkMode(cfg, "discord", accountInfo.accountId);
+  const maxLinesPerMessage = opts.maxLinesPerMessage ?? accountInfo.config.maxLinesPerMessage;
+  const suppressEmbeds = resolveDiscordSuppressEmbeds({
+    configured: accountInfo.config.suppressEmbeds,
+    override: opts.suppressEmbeds,
+  });
+  const textLimit =
+    typeof opts.textLimit === "number" && Number.isFinite(opts.textLimit)
+      ? Math.max(1, Math.min(Math.floor(opts.textLimit), 2000))
+      : undefined;
+  const mediaMaxBytes =
+    typeof accountInfo.config.mediaMaxMb === "number"
+      ? accountInfo.config.mediaMaxMb * 1024 * 1024
+      : DEFAULT_DISCORD_MEDIA_MAX_MB * 1024 * 1024;
+  const textWithTables = convertMarkdownTables(text ?? "", effectiveTableMode);
+  const textWithMentions = rewriteDiscordKnownMentions(textWithTables, {
+    accountId: accountInfo.accountId,
+    mentionAliases: accountInfo.config.mentionAliases,
+  });
+  const { token, rest, request } = createDiscordClient({ ...opts, cfg });
+  const recipient = await parseAndResolveRecipient(to, cfg, opts.accountId);
+  const { channelId } = await resolveChannelId(rest, recipient, request);
+
+  // Forum/Media channels reject POST /messages; auto-create a thread post instead.
+  const channelType = await resolveDiscordChannelType(rest, channelId);
+
+  if (isForumLikeType(channelType)) {
+    const threadName = deriveForumThreadName(textWithTables);
+    const chunks = buildDiscordTextChunks(textWithMentions, {
+      maxLinesPerMessage,
+      chunkMode,
+      maxChars: textLimit,
+    });
+    const starterContent = chunks[0]?.trim() ? chunks[0] : threadName;
+    const starterComponents = resolveDiscordSendComponents({
+      components: opts.components,
+      text: starterContent,
+      isFirst: true,
+    });
+    const starterEmbeds = resolveDiscordSendEmbeds({ embeds: opts.embeds, isFirst: true });
+    const starterFlags = resolveDiscordMessageFlags({
+      silent: opts.silent,
+      suppressEmbeds: suppressEmbeds && !starterEmbeds?.length,
+    });
+    const starterBody = buildDiscordMessageRequest({
+      text: starterContent,
+      components: starterComponents,
+      embeds: starterEmbeds,
+      flags: starterFlags,
+    });
+    let threadRes: { id: string; message?: { id: string; channel_id: string } };
+    try {
+      threadRes = (await request(
+        () =>
+          createThread<{ id: string; message?: { id: string; channel_id: string } }>(
+            rest,
+            channelId,
+            {
+              body: {
+                name: threadName,
+                message: starterBody,
+              },
+            },
+          ),
+        "forum-thread",
+      )) as { id: string; message?: { id: string; channel_id: string } };
+    } catch (err) {
+      throw await buildDiscordSendError(err, {
+        channelId,
+        cfg,
+        rest,
+        token,
+        hasMedia: Boolean(opts.mediaUrl),
+      });
+    }
+
+    const threadId = threadRes.id;
+    const messageId = threadRes.message?.id ?? threadId;
+    const resultChannelId = threadRes.message?.channel_id ?? threadId;
+    const remainingChunks = chunks.slice(1);
+
+    try {
+      if (opts.mediaUrl) {
+        const [mediaCaption, ...afterMediaChunks] = remainingChunks;
+        await sendDiscordMedia(
+          rest,
+          threadId,
+          mediaCaption ?? "",
+          opts.mediaUrl,
+          opts.filename,
+          opts.mediaAccess,
+          opts.mediaLocalRoots,
+          opts.mediaReadFile,
+          mediaMaxBytes,
+          undefined,
+          request,
+          maxLinesPerMessage,
+          undefined,
+          undefined,
+          chunkMode,
+          opts.silent,
+          suppressEmbeds,
+          textLimit,
+        );
+        await sendDiscordThreadTextChunks({
+          rest,
+          threadId,
+          chunks: afterMediaChunks,
+          request,
+          maxLinesPerMessage,
+          chunkMode,
+          maxChars: textLimit,
+          silent: opts.silent,
+          suppressEmbeds,
+        });
+      } else {
+        await sendDiscordThreadTextChunks({
+          rest,
+          threadId,
+          chunks: remainingChunks,
+          request,
+          maxLinesPerMessage,
+          chunkMode,
+          maxChars: textLimit,
+          silent: opts.silent,
+          suppressEmbeds,
+        });
+      }
+    } catch (err) {
+      throw await buildDiscordSendError(err, {
+        channelId: threadId,
+        cfg,
+        rest,
+        token,
+        hasMedia: Boolean(opts.mediaUrl),
+      });
+    }
+
+    recordChannelActivity({
+      channel: "discord",
+      accountId: accountInfo.accountId,
+      direction: "outbound",
+    });
+    return toDiscordSendResult(
+      {
+        id: messageId,
+        channel_id: resultChannelId,
+      },
+      channelId,
+      { kind: opts.mediaUrl ? "media" : "text", threadId },
+    );
+  }
+
+  let result: DiscordChannelMessageResult;
+  try {
+    if (opts.mediaUrl) {
+      result = await sendDiscordMedia(
+        rest,
+        channelId,
+        textWithMentions,
+        opts.mediaUrl,
+        opts.filename,
+        opts.mediaAccess,
+        opts.mediaLocalRoots,
+        opts.mediaReadFile,
+        mediaMaxBytes,
+        opts.replyTo,
+        request,
+        maxLinesPerMessage,
+        opts.components,
+        opts.embeds,
+        chunkMode,
+        opts.silent,
+        suppressEmbeds,
+        textLimit,
+      );
+    } else {
+      result = await sendDiscordText(
+        rest,
+        channelId,
+        textWithMentions,
+        opts.replyTo,
+        request,
+        maxLinesPerMessage,
+        opts.components,
+        opts.embeds,
+        chunkMode,
+        opts.silent,
+        suppressEmbeds,
+        textLimit,
+      );
+    }
+  } catch (err) {
+    throw await buildDiscordSendError(err, {
+      channelId,
+      cfg,
+      rest,
+      token,
+      hasMedia: Boolean(opts.mediaUrl),
+    });
+  }
+
+  recordChannelActivity({
+    channel: "discord",
+    accountId: accountInfo.accountId,
+    direction: "outbound",
+  });
+  return toDiscordSendResult(result, channelId, {
+    kind: opts.mediaUrl ? "media" : opts.components || opts.embeds ? "card" : "text",
+    replyToId: opts.replyTo,
+  });
+}
+
+export async function sendStickerDiscord(
+  to: string,
+  stickerIds: string[],
+  opts: DiscordSendOpts & { content?: string },
+): Promise<DiscordSendResult> {
+  const { rest, request, channelId, rewrittenContent, suppressEmbeds } =
+    await resolveDiscordStructuredSendContext(to, opts);
+  const stickers = normalizeStickerIds(stickerIds);
+  const flags = resolveDiscordMessageFlags({ suppressEmbeds });
+  const res = (await request(
+    () =>
+      createChannelMessage<{ id: string; channel_id: string }>(rest, channelId, {
+        body: {
+          content: rewrittenContent || undefined,
+          sticker_ids: stickers,
+          ...(flags ? { flags } : {}),
+        },
+      }),
+    "sticker",
+  )) as { id: string; channel_id: string };
+  return toDiscordSendResult(res, channelId, { kind: "card" });
+}
+
+export async function sendPollDiscord(
+  to: string,
+  poll: PollInput,
+  opts: DiscordSendOpts & { content?: string },
+): Promise<DiscordSendResult> {
+  const { rest, request, channelId, rewrittenContent, suppressEmbeds } =
+    await resolveDiscordStructuredSendContext(to, opts);
+  if (poll.durationSeconds !== undefined) {
+    throw new Error("Discord polls do not support durationSeconds; use durationHours");
+  }
+  const payload = normalizeDiscordPollInput(poll);
+  const flags = resolveDiscordMessageFlags({ silent: opts.silent, suppressEmbeds });
+  const res = (await request(
+    () =>
+      createChannelMessage<{ id: string; channel_id: string }>(rest, channelId, {
+        body: {
+          content: rewrittenContent || undefined,
+          poll: payload,
+          ...(flags ? { flags } : {}),
+        },
+      }),
+    "poll",
+  )) as { id: string; channel_id: string };
+  return toDiscordSendResult(res, channelId, { kind: "card" });
+}
+
+async function resolveDiscordStructuredSendContext(
+  to: string,
+  opts: DiscordSendOpts & { content?: string },
+): Promise<{
+  rest: RequestClient;
+  request: DiscordClientRequest;
+  channelId: string;
+  rewrittenContent?: string;
+  suppressEmbeds: boolean;
+}> {
+  const cfg = requireRuntimeConfig(opts.cfg, "Discord structured send");
+  const accountInfo = resolveDiscordAccount({
+    cfg,
+    accountId: opts.accountId,
+  });
+  const { rest, request, channelId } = await resolveDiscordSendTarget(to, opts);
+  const content = opts.content?.trim();
+  const rewrittenContent = content
+    ? rewriteDiscordKnownMentions(content, {
+        accountId: accountInfo.accountId,
+        mentionAliases: accountInfo.config.mentionAliases,
+      })
+    : undefined;
+  return {
+    rest,
+    request,
+    channelId,
+    rewrittenContent,
+    suppressEmbeds: resolveDiscordSuppressEmbeds({
+      configured: accountInfo.config.suppressEmbeds,
+      override: opts.suppressEmbeds,
+    }),
+  };
+}

package/src/send.permissions.authz.test.ts

@@ -0,0 +1,190 @@
+import { PermissionFlagsBits, Routes } from "discord-api-types/v10";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { RequestClient } from "./internal/discord.js";
+import { EMPTY_DISCORD_TEST_OPTS } from "./test-support/config.js";
+
+const mockRest = vi.hoisted(() => ({
+  get: vi.fn(),
+}));
+
+vi.mock("./client.js", () => ({
+  resolveDiscordRest: () => mockRest as unknown as RequestClient,
+}));
+
+let fetchMemberGuildPermissionsDiscord: typeof import("./send.permissions.js").fetchMemberGuildPermissionsDiscord;
+let hasAllGuildPermissionsDiscord: typeof import("./send.permissions.js").hasAllGuildPermissionsDiscord;
+let hasAnyGuildPermissionDiscord: typeof import("./send.permissions.js").hasAnyGuildPermissionDiscord;
+
+type RouteMockParams = {
+  guildId?: string;
+  userId?: string;
+  roles: Array<{ id: string; permissions: string | bigint }>;
+  memberRoles: string[];
+};
+
+function mockGuildMemberRoutes(params: RouteMockParams): void {
+  const guildId = params.guildId ?? "guild-1";
+  const userId = params.userId ?? "user-1";
+  mockRest.get.mockImplementation(async (route: string) => {
+    if (route === Routes.guild(guildId)) {
+      return {
+        id: guildId,
+        roles: params.roles.map((role) => ({
+          id: role.id,
+          permissions:
+            typeof role.permissions === "bigint" ? role.permissions.toString() : role.permissions,
+        })),
+      };
+    }
+    if (route === Routes.guildMember(guildId, userId)) {
+      return { id: userId, roles: params.memberRoles };
+    }
+    throw new Error(`Unexpected route: ${route}`);
+  });
+}
+
+describe("discord guild permission authorization", () => {
+  beforeAll(async () => {
+    ({
+      fetchMemberGuildPermissionsDiscord,
+      hasAllGuildPermissionsDiscord,
+      hasAnyGuildPermissionDiscord,
+    } = await import("./send.permissions.js"));
+  });
+
+  beforeEach(() => {
+    mockRest.get.mockReset();
+  });
+
+  describe("fetchMemberGuildPermissionsDiscord", () => {
+    it("returns null when user is not a guild member", async () => {
+      mockRest.get.mockRejectedValueOnce(new Error("404 Member not found"));
+
+      const result = await fetchMemberGuildPermissionsDiscord(
+        "guild-1",
+        "user-1",
+        EMPTY_DISCORD_TEST_OPTS,
+      );
+      expect(result).toBeNull();
+    });
+
+    it("includes @everyone and member roles in computed permissions", async () => {
+      mockGuildMemberRoutes({
+        roles: [
+          { id: "guild-1", permissions: PermissionFlagsBits.ViewChannel },
+          { id: "role-mod", permissions: PermissionFlagsBits.KickMembers },
+        ],
+        memberRoles: ["role-mod"],
+      });
+
+      const result = await fetchMemberGuildPermissionsDiscord(
+        "guild-1",
+        "user-1",
+        EMPTY_DISCORD_TEST_OPTS,
+      );
+      if (result === null) {
+        throw new Error("Expected guild permissions bitfield");
+      }
+      expect((result & PermissionFlagsBits.ViewChannel) === PermissionFlagsBits.ViewChannel).toBe(
+        true,
+      );
+      expect((result & PermissionFlagsBits.KickMembers) === PermissionFlagsBits.KickMembers).toBe(
+        true,
+      );
+    });
+  });
+
+  describe("hasAnyGuildPermissionDiscord", () => {
+    it("returns true when user has required permission", async () => {
+      mockGuildMemberRoutes({
+        roles: [
+          { id: "guild-1", permissions: "0" },
+          { id: "role-mod", permissions: PermissionFlagsBits.KickMembers },
+        ],
+        memberRoles: ["role-mod"],
+      });
+
+      const result = await hasAnyGuildPermissionDiscord(
+        "guild-1",
+        "user-1",
+        [PermissionFlagsBits.KickMembers],
+        EMPTY_DISCORD_TEST_OPTS,
+      );
+      expect(result).toBe(true);
+    });
+
+    it("returns true when user has ADMINISTRATOR", async () => {
+      mockGuildMemberRoutes({
+        roles: [
+          { id: "guild-1", permissions: "0" },
+          {
+            id: "role-admin",
+            permissions: PermissionFlagsBits.Administrator,
+          },
+        ],
+        memberRoles: ["role-admin"],
+      });
+
+      const result = await hasAnyGuildPermissionDiscord(
+        "guild-1",
+        "user-1",
+        [PermissionFlagsBits.KickMembers],
+        EMPTY_DISCORD_TEST_OPTS,
+      );
+      expect(result).toBe(true);
+    });
+
+    it("returns false when user lacks all required permissions", async () => {
+      mockGuildMemberRoutes({
+        roles: [{ id: "guild-1", permissions: PermissionFlagsBits.ViewChannel }],
+        memberRoles: [],
+      });
+
+      const result = await hasAnyGuildPermissionDiscord(
+        "guild-1",
+        "user-1",
+        [PermissionFlagsBits.BanMembers, PermissionFlagsBits.KickMembers],
+        EMPTY_DISCORD_TEST_OPTS,
+      );
+      expect(result).toBe(false);
+    });
+  });
+
+  describe("hasAllGuildPermissionsDiscord", () => {
+    it("returns false when user has only one of multiple required permissions", async () => {
+      mockGuildMemberRoutes({
+        roles: [
+          { id: "guild-1", permissions: "0" },
+          { id: "role-mod", permissions: PermissionFlagsBits.KickMembers },
+        ],
+        memberRoles: ["role-mod"],
+      });
+
+      const result = await hasAllGuildPermissionsDiscord(
+        "guild-1",
+        "user-1",
+        [PermissionFlagsBits.KickMembers, PermissionFlagsBits.BanMembers],
+        EMPTY_DISCORD_TEST_OPTS,
+      );
+      expect(result).toBe(false);
+    });
+
+    it("returns true for hasAll checks when user has ADMINISTRATOR", async () => {
+      mockGuildMemberRoutes({
+        roles: [
+          { id: "guild-1", permissions: "0" },
+          { id: "role-admin", permissions: PermissionFlagsBits.Administrator },
+        ],
+        memberRoles: ["role-admin"],
+      });
+
+      const result = await hasAllGuildPermissionsDiscord(
+        "guild-1",
+        "user-1",
+        [PermissionFlagsBits.KickMembers, PermissionFlagsBits.BanMembers],
+        EMPTY_DISCORD_TEST_OPTS,
+      );
+      expect(result).toBe(true);
+    });
+  });
+});