@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/send.types.ts

@@ -0,0 +1,191 @@
+import type { MessageReceipt } from "klaw/plugin-sdk/channel-message";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import type { RetryConfig } from "klaw/plugin-sdk/retry-runtime";
+import type { RequestClient } from "./internal/discord.js";
+
+export class DiscordSendError extends Error {
+  kind?: "missing-permissions" | "dm-blocked";
+  channelId?: string;
+  missingPermissions?: string[];
+  discordCode?: number;
+  status?: number;
+
+  constructor(message: string, opts?: Partial<DiscordSendError>) {
+    super(message);
+    this.name = "DiscordSendError";
+    if (opts) {
+      Object.assign(this, opts);
+    }
+  }
+
+  override toString() {
+    return this.message;
+  }
+}
+
+export const DISCORD_MAX_EMOJI_BYTES = 256 * 1024;
+export const DISCORD_MAX_STICKER_BYTES = 512 * 1024;
+export const DISCORD_MAX_EVENT_COVER_BYTES = 8 * 1024 * 1024;
+
+export type DiscordSendResult = {
+  messageId: string;
+  channelId: string;
+  receipt: MessageReceipt;
+};
+
+export type DiscordRuntimeAccountContext = {
+  cfg: KlawConfig;
+  accountId: string;
+};
+
+export type DiscordReactOpts = {
+  cfg: KlawConfig;
+  accountId?: string;
+  token?: string;
+  rest?: RequestClient;
+  verbose?: boolean;
+  retry?: RetryConfig;
+};
+
+export type DiscordReactionRuntimeContext = DiscordRuntimeAccountContext & {
+  rest: RequestClient;
+};
+
+export type DiscordReactionUser = {
+  id: string;
+  username?: string;
+  tag?: string;
+};
+
+export type DiscordReactionSummary = {
+  emoji: { id?: string | null; name?: string | null; raw: string };
+  count: number;
+  users: DiscordReactionUser[];
+};
+
+export type DiscordPermissionsSummary = {
+  channelId: string;
+  guildId?: string;
+  permissions: string[];
+  raw: string;
+  isDm: boolean;
+  channelType?: number;
+};
+
+export type DiscordMessageQuery = {
+  limit?: number;
+  before?: string;
+  after?: string;
+  around?: string;
+};
+
+export type DiscordMessageEdit = {
+  content?: string;
+  flags?: number;
+};
+
+export type DiscordThreadCreate = {
+  messageId?: string;
+  name: string;
+  autoArchiveMinutes?: number;
+  content?: string;
+  /** Discord thread type (default: PublicThread for standalone threads). */
+  type?: number;
+  /** Tag IDs to apply when creating a forum/media thread (Discord `applied_tags`). */
+  appliedTags?: string[];
+};
+
+export type DiscordThreadList = {
+  guildId: string;
+  channelId?: string;
+  includeArchived?: boolean;
+  before?: string;
+  limit?: number;
+};
+
+export type DiscordSearchQuery = {
+  guildId: string;
+  content: string;
+  channelIds?: string[];
+  authorIds?: string[];
+  limit?: number;
+};
+
+export type DiscordRoleChange = {
+  guildId: string;
+  userId: string;
+  roleId: string;
+};
+
+export type DiscordModerationTarget = {
+  guildId: string;
+  userId: string;
+  reason?: string;
+};
+
+export type DiscordTimeoutTarget = DiscordModerationTarget & {
+  until?: string;
+  durationMinutes?: number;
+};
+
+export type DiscordEmojiUpload = {
+  guildId: string;
+  name: string;
+  mediaUrl: string;
+  roleIds?: string[];
+};
+
+export type DiscordStickerUpload = {
+  guildId: string;
+  name: string;
+  description: string;
+  tags: string;
+  mediaUrl: string;
+};
+
+export type DiscordChannelCreate = {
+  guildId: string;
+  name: string;
+  type?: number;
+  parentId?: string;
+  topic?: string;
+  position?: number;
+  nsfw?: boolean;
+};
+
+type DiscordForumTag = {
+  id?: string;
+  name: string;
+  moderated?: boolean;
+  emoji_id?: string | null;
+  emoji_name?: string | null;
+};
+
+export type DiscordChannelEdit = {
+  channelId: string;
+  name?: string;
+  topic?: string;
+  position?: number;
+  parentId?: string | null;
+  nsfw?: boolean;
+  rateLimitPerUser?: number;
+  archived?: boolean;
+  locked?: boolean;
+  autoArchiveDuration?: number;
+  availableTags?: DiscordForumTag[];
+};
+
+export type DiscordChannelMove = {
+  guildId: string;
+  channelId: string;
+  parentId?: string | null;
+  position?: number;
+};
+
+export type DiscordChannelPermissionSet = {
+  channelId: string;
+  targetId: string;
+  targetType: 0 | 1;
+  allow?: string;
+  deny?: string;
+};

package/src/send.typing.test.ts

@@ -0,0 +1,41 @@
+import { 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_CONFIG } from "./test-support/config.js";
+
+const resolveDiscordRestMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./client.js", () => ({
+  resolveDiscordRest: resolveDiscordRestMock,
+}));
+
+let sendTypingDiscord: typeof import("./send.typing.js").sendTypingDiscord;
+
+beforeAll(async () => {
+  ({ sendTypingDiscord } = await import("./send.typing.js"));
+});
+
+beforeEach(() => {
+  resolveDiscordRestMock.mockReset();
+});
+
+describe("sendTypingDiscord", () => {
+  it("sends a typing event to the resolved Discord channel route", async () => {
+    const post = vi.fn(async () => undefined);
+    resolveDiscordRestMock.mockReturnValue({
+      post,
+    } as unknown as RequestClient);
+
+    const result = await sendTypingDiscord("12345", {
+      cfg: EMPTY_DISCORD_TEST_CONFIG,
+      accountId: "ops",
+    });
+
+    expect(resolveDiscordRestMock).toHaveBeenCalledWith({
+      cfg: EMPTY_DISCORD_TEST_CONFIG,
+      accountId: "ops",
+    });
+    expect(post).toHaveBeenCalledWith(Routes.channelTyping("12345"));
+    expect(result).toEqual({ ok: true, channelId: "12345" });
+  });
+});

package/src/send.typing.ts

@@ -0,0 +1,9 @@
+import { resolveDiscordRest } from "./client.js";
+import { sendChannelTyping } from "./internal/discord.js";
+import type { DiscordReactOpts } from "./send.types.js";
+
+export async function sendTypingDiscord(channelId: string, opts: DiscordReactOpts) {
+  const rest = resolveDiscordRest(opts);
+  await sendChannelTyping(rest, channelId);
+  return { ok: true, channelId };
+}

package/src/send.voice.ts

@@ -0,0 +1,136 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { recordChannelActivity } from "klaw/plugin-sdk/channel-activity-runtime";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { extensionForMime, maxBytesForKind, unlinkIfExists } from "klaw/plugin-sdk/media-runtime";
+import { requireRuntimeConfig } from "klaw/plugin-sdk/plugin-config-runtime";
+import type { RetryConfig } from "klaw/plugin-sdk/retry-runtime";
+import { tempWorkspace, resolvePreferredKlawTmpDir } from "klaw/plugin-sdk/temp-path";
+import { loadWebMediaRaw } from "klaw/plugin-sdk/web-media";
+import { resolveDiscordAccount } from "./accounts.js";
+import type { RequestClient } from "./internal/discord.js";
+import { parseAndResolveRecipient } from "./recipient-resolution.js";
+import { createDiscordSendResult } from "./send.receipt.js";
+import { buildDiscordSendError, createDiscordClient, resolveChannelId } from "./send.shared.js";
+import type { DiscordSendResult } from "./send.types.js";
+import {
+  ensureOggOpus,
+  getVoiceMessageMetadata,
+  sendDiscordVoiceMessage,
+} from "./voice-message.js";
+
+type VoiceMessageOpts = {
+  cfg: KlawConfig;
+  token?: string;
+  accountId?: string;
+  verbose?: boolean;
+  rest?: RequestClient;
+  replyTo?: string;
+  retry?: RetryConfig;
+  silent?: boolean;
+};
+
+function toDiscordSendResult(
+  result: { id?: string | null; channel_id?: string | null },
+  fallbackChannelId: string,
+): DiscordSendResult {
+  return createDiscordSendResult({
+    result,
+    fallbackChannelId,
+    kind: "voice",
+  });
+}
+
+async function materializeVoiceMessageInput(
+  mediaUrl: string,
+): Promise<{ filePath: string; cleanup: () => Promise<void> }> {
+  // Security: reuse the standard media loader so we apply SSRF guards + allowed-local-root checks.
+  // Then write to a private temp file so ffmpeg/ffprobe never sees the original URL/path string.
+  const media = await loadWebMediaRaw(mediaUrl, maxBytesForKind("audio"));
+  const extFromName = media.fileName ? path.extname(media.fileName) : "";
+  const extFromMime = media.contentType ? extensionForMime(media.contentType) : "";
+  const ext = extFromName || extFromMime || ".bin";
+  const workspace = await tempWorkspace({
+    rootDir: resolvePreferredKlawTmpDir(),
+    prefix: "voice-src-",
+  });
+  const filePath = await workspace.write(`input${ext}`, media.buffer);
+  return { filePath, cleanup: async () => await workspace.cleanup() };
+}
+
+/**
+ * Send a voice message to Discord.
+ *
+ * Voice messages are a special Discord feature that displays audio with a waveform
+ * visualization. They require OGG/Opus format and cannot include text content.
+ *
+ * @param to - Recipient (user ID for DM or channel ID)
+ * @param audioPath - Path to local audio file (will be converted to OGG/Opus if needed)
+ * @param opts - Send options
+ */
+export async function sendVoiceMessageDiscord(
+  to: string,
+  audioPath: string,
+  opts: VoiceMessageOpts,
+): Promise<DiscordSendResult> {
+  const { filePath: localInputPath, cleanup: cleanupLocalInput } =
+    await materializeVoiceMessageInput(audioPath);
+  let oggPath: string | null = null;
+  let oggCleanup = false;
+  let token: string | undefined;
+  let rest: RequestClient | undefined;
+  let channelId: string | undefined;
+  const cfg = requireRuntimeConfig(opts.cfg, "Discord voice send");
+
+  try {
+    const accountInfo = resolveDiscordAccount({
+      cfg,
+      accountId: opts.accountId,
+    });
+    const client = createDiscordClient({ ...opts, cfg });
+    token = client.token;
+    rest = client.rest;
+    const request = client.request;
+    const recipient = await parseAndResolveRecipient(to, cfg, opts.accountId);
+    channelId = (await resolveChannelId(rest, recipient, request)).channelId;
+
+    const ogg = await ensureOggOpus(localInputPath);
+    oggPath = ogg.path;
+    oggCleanup = ogg.cleanup;
+
+    const metadata = await getVoiceMessageMetadata(oggPath);
+    const audioBuffer = await fs.readFile(oggPath);
+    const result = await sendDiscordVoiceMessage(
+      rest,
+      channelId,
+      audioBuffer,
+      metadata,
+      opts.replyTo,
+      request,
+      opts.silent,
+      token,
+    );
+
+    recordChannelActivity({
+      channel: "discord",
+      accountId: accountInfo.accountId,
+      direction: "outbound",
+    });
+
+    return toDiscordSendResult(result, channelId);
+  } catch (err) {
+    if (channelId && rest && token) {
+      throw await buildDiscordSendError(err, {
+        channelId,
+        cfg,
+        rest,
+        token,
+        hasMedia: true,
+      });
+    }
+    throw err;
+  } finally {
+    await unlinkIfExists(oggCleanup ? oggPath : null);
+    await cleanupLocalInput();
+  }
+}

package/src/send.webhook-activity.test.ts

@@ -0,0 +1,152 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const recordChannelActivityMock = vi.hoisted(() => vi.fn());
+const loadConfigMock = vi.hoisted(() => vi.fn(() => ({ channels: { discord: {} } })));
+let dateNowSpy: ReturnType<typeof vi.spyOn>;
+
+vi.mock("klaw/plugin-sdk/plugin-config-runtime", async () => {
+  const actual = await vi.importActual<typeof import("klaw/plugin-sdk/plugin-config-runtime")>(
+    "klaw/plugin-sdk/plugin-config-runtime",
+  );
+  return {
+    ...actual,
+    requireRuntimeConfig: (cfg: unknown) => cfg ?? loadConfigMock(),
+  };
+});
+
+vi.mock("klaw/plugin-sdk/channel-activity-runtime", async () => {
+  const actual = await vi.importActual<typeof import("klaw/plugin-sdk/channel-activity-runtime")>(
+    "klaw/plugin-sdk/channel-activity-runtime",
+  );
+  return {
+    ...actual,
+    recordChannelActivity: (...args: unknown[]) => recordChannelActivityMock(...args),
+  };
+});
+
+let sendWebhookMessageDiscord: typeof import("./send.webhook.js").sendWebhookMessageDiscord;
+
+type MockWithCalls = { mock: { calls: unknown[][] } };
+
+function firstMockCall(mock: MockWithCalls, label: string): unknown[] {
+  const call = mock.mock.calls[0];
+  if (!call) {
+    throw new Error(`expected ${label} call`);
+  }
+  return call;
+}
+
+describe("sendWebhookMessageDiscord activity", () => {
+  beforeAll(async () => {
+    ({ sendWebhookMessageDiscord } = await import("./send.webhook.js"));
+  });
+
+  beforeEach(() => {
+    recordChannelActivityMock.mockClear();
+    loadConfigMock.mockClear();
+    dateNowSpy = vi.spyOn(Date, "now").mockReturnValue(1_700_000_000_000);
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        return new Response(JSON.stringify({ id: "msg-1", channel_id: "thread-1" }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        });
+      }),
+    );
+  });
+
+  afterEach(() => {
+    dateNowSpy.mockRestore();
+    vi.unstubAllGlobals();
+  });
+
+  it("records outbound channel activity for webhook sends", async () => {
+    const cfg = {
+      channels: {
+        discord: {
+          token: "resolved-token",
+        },
+      },
+    };
+    const result = await sendWebhookMessageDiscord("hello world", {
+      cfg,
+      webhookId: "wh-1",
+      webhookToken: "tok-1",
+      accountId: "runtime",
+      threadId: "thread-1",
+    });
+
+    expect(result).toEqual({
+      messageId: "msg-1",
+      channelId: "thread-1",
+      receipt: {
+        primaryPlatformMessageId: "msg-1",
+        platformMessageIds: ["msg-1"],
+        parts: [
+          {
+            platformMessageId: "msg-1",
+            kind: "text",
+            index: 0,
+            threadId: "thread-1",
+            raw: {
+              channel: "discord",
+              messageId: "msg-1",
+              channelId: "thread-1",
+            },
+          },
+        ],
+        threadId: "thread-1",
+        sentAt: 1_700_000_000_000,
+        raw: [
+          {
+            channel: "discord",
+            messageId: "msg-1",
+            channelId: "thread-1",
+          },
+        ],
+      },
+    });
+    expect(recordChannelActivityMock).toHaveBeenCalledWith({
+      channel: "discord",
+      accountId: "runtime",
+      direction: "outbound",
+    });
+    expect(loadConfigMock).not.toHaveBeenCalled();
+  });
+
+  it("rewrites configured mention aliases for webhook sends", async () => {
+    const cfg = {
+      channels: {
+        discord: {
+          token: "resolved-token",
+          mentionAliases: {
+            opslead: "123456789012345678",
+          },
+        },
+      },
+    };
+    await sendWebhookMessageDiscord("hello @OpsLead", {
+      cfg,
+      webhookId: "wh-1",
+      webhookToken: "tok-1",
+      accountId: "runtime",
+      threadId: "thread-1",
+    });
+
+    const fetchMock = vi.mocked(fetch);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(firstMockCall(fetchMock, "fetch")).toEqual([
+      "https://discord.com/api/v10/webhooks/wh-1/tok-1?wait=true&thread_id=thread-1",
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          content: "hello <@123456789012345678>",
+        }),
+      },
+    ]);
+  });
+});