@openclaw/discord 2026.3.13 → 2026.5.2-beta.1

package/src/send.types.ts

@@ -0,0 +1,188 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import type { RetryConfig } from "openclaw/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;
+};
+
+export type DiscordRuntimeAccountContext = {
+  cfg: OpenClawConfig;
+  accountId: string;
+};
+
+export type DiscordReactOpts = {
+  cfg: OpenClawConfig;
+  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;
+};
+
+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,134 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { recordChannelActivity } from "openclaw/plugin-sdk/channel-activity-runtime";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import {
+  extensionForMime,
+  maxBytesForKind,
+  unlinkIfExists,
+} from "openclaw/plugin-sdk/media-runtime";
+import { requireRuntimeConfig } from "openclaw/plugin-sdk/plugin-config-runtime";
+import type { RetryConfig } from "openclaw/plugin-sdk/retry-runtime";
+import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/temp-path";
+import { loadWebMediaRaw } from "openclaw/plugin-sdk/web-media";
+import { resolveDiscordAccount } from "./accounts.js";
+import type { RequestClient } from "./internal/discord.js";
+import { parseAndResolveRecipient } from "./recipient-resolution.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: OpenClawConfig;
+  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 {
+    messageId: result.id || "unknown",
+    channelId: result.channel_id ?? fallbackChannelId,
+  };
+}
+
+async function materializeVoiceMessageInput(mediaUrl: string): Promise<{ filePath: string }> {
+  // 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 tempDir = resolvePreferredOpenClawTmpDir();
+  const filePath = path.join(tempDir, `voice-src-${crypto.randomUUID()}${ext}`);
+  await fs.writeFile(filePath, media.buffer, { mode: 0o600 });
+  return { filePath };
+}
+
+/**
+ * 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 } = 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 unlinkIfExists(localInputPath);
+  }
+}

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

@@ -0,0 +1,105 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const recordChannelActivityMock = vi.hoisted(() => vi.fn());
+const loadConfigMock = vi.hoisted(() => vi.fn(() => ({ channels: { discord: {} } })));
+
+vi.mock("openclaw/plugin-sdk/plugin-config-runtime", async () => {
+  const actual = await vi.importActual<typeof import("openclaw/plugin-sdk/plugin-config-runtime")>(
+    "openclaw/plugin-sdk/plugin-config-runtime",
+  );
+  return {
+    ...actual,
+    requireRuntimeConfig: (cfg: unknown) => cfg ?? loadConfigMock(),
+  };
+});
+
+vi.mock("openclaw/plugin-sdk/channel-activity-runtime", async () => {
+  const actual = await vi.importActual<
+    typeof import("openclaw/plugin-sdk/channel-activity-runtime")
+  >("openclaw/plugin-sdk/channel-activity-runtime");
+  return {
+    ...actual,
+    recordChannelActivity: (...args: unknown[]) => recordChannelActivityMock(...args),
+  };
+});
+
+let sendWebhookMessageDiscord: typeof import("./send.webhook.js").sendWebhookMessageDiscord;
+
+describe("sendWebhookMessageDiscord activity", () => {
+  beforeAll(async () => {
+    ({ sendWebhookMessageDiscord } = await import("./send.webhook.js"));
+  });
+
+  beforeEach(() => {
+    recordChannelActivityMock.mockClear();
+    loadConfigMock.mockClear();
+    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(() => {
+    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",
+    });
+    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",
+    });
+
+    expect(fetch).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({
+        body: expect.stringContaining('"content":"hello <@123456789012345678>"'),
+      }),
+    );
+  });
+});

package/src/send.webhook.proxy.test.ts

@@ -0,0 +1,191 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { sendWebhookMessageDiscord } from "./send.webhook.js";
+
+const makeProxyFetchMock = vi.hoisted(() => vi.fn());
+
+vi.mock("openclaw/plugin-sdk/fetch-runtime", async () => {
+  const actual = await vi.importActual<typeof import("openclaw/plugin-sdk/fetch-runtime")>(
+    "openclaw/plugin-sdk/fetch-runtime",
+  );
+  return {
+    ...actual,
+    makeProxyFetch: makeProxyFetchMock,
+  };
+});
+
+describe("sendWebhookMessageDiscord proxy support", () => {
+  beforeEach(() => {
+    makeProxyFetchMock.mockReset();
+    vi.restoreAllMocks();
+  });
+
+  it("falls back to global fetch when the Discord proxy URL is invalid", async () => {
+    makeProxyFetchMock.mockImplementation(() => {
+      throw new Error("bad proxy");
+    });
+    const globalFetchMock = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(new Response(JSON.stringify({ id: "msg-0" }), { status: 200 }));
+
+    const cfg = {
+      channels: {
+        discord: {
+          token: "Bot test-token",
+          proxy: "bad-proxy",
+        },
+      },
+    } as OpenClawConfig;
+
+    await sendWebhookMessageDiscord("hello", {
+      cfg,
+      accountId: "default",
+      webhookId: "123",
+      webhookToken: "abc",
+      wait: true,
+    });
+
+    expect(makeProxyFetchMock).not.toHaveBeenCalledWith("bad-proxy");
+    expect(globalFetchMock).toHaveBeenCalled();
+    globalFetchMock.mockRestore();
+  });
+
+  it("uses proxy fetch when a Discord proxy is configured", async () => {
+    const proxiedFetch = vi
+      .fn()
+      .mockResolvedValue(new Response(JSON.stringify({ id: "msg-1" }), { status: 200 }));
+    makeProxyFetchMock.mockReturnValue(proxiedFetch);
+
+    const cfg = {
+      channels: {
+        discord: {
+          token: "Bot test-token",
+          proxy: "http://127.0.0.1:8080",
+        },
+      },
+    } as OpenClawConfig;
+
+    await sendWebhookMessageDiscord("hello", {
+      cfg,
+      accountId: "default",
+      webhookId: "123",
+      webhookToken: "abc",
+      wait: true,
+    });
+
+    expect(makeProxyFetchMock).toHaveBeenCalledWith("http://127.0.0.1:8080");
+    expect(proxiedFetch).toHaveBeenCalledOnce();
+  });
+
+  it("uses global fetch when the Discord proxy URL is remote", async () => {
+    const globalFetchMock = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(new Response(JSON.stringify({ id: "msg-remote" }), { status: 200 }));
+
+    const cfg = {
+      channels: {
+        discord: {
+          token: "Bot test-token",
+          proxy: "http://proxy.test:8080",
+        },
+      },
+    } as OpenClawConfig;
+
+    await sendWebhookMessageDiscord("hello", {
+      cfg,
+      accountId: "default",
+      webhookId: "123",
+      webhookToken: "abc",
+      wait: true,
+    });
+
+    expect(makeProxyFetchMock).not.toHaveBeenCalledWith("http://proxy.test:8080");
+    expect(globalFetchMock).toHaveBeenCalled();
+    globalFetchMock.mockRestore();
+  });
+
+  it("uses global fetch when no proxy is configured", async () => {
+    makeProxyFetchMock.mockReturnValue(undefined);
+    const globalFetchMock = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(new Response(JSON.stringify({ id: "msg-2" }), { status: 200 }));
+
+    const cfg = {
+      channels: {
+        discord: {
+          token: "Bot test-token",
+        },
+      },
+    } as OpenClawConfig;
+
+    await sendWebhookMessageDiscord("hello", {
+      cfg,
+      accountId: "default",
+      webhookId: "123",
+      webhookToken: "abc",
+      wait: true,
+    });
+
+    expect(globalFetchMock).toHaveBeenCalled();
+    globalFetchMock.mockRestore();
+  });
+
+  it("throws typed rate limit errors for webhook 429 responses", async () => {
+    const globalFetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ message: "Slow down", retry_after: 0.25, global: false }), {
+        status: 429,
+      }),
+    );
+
+    const cfg = {
+      channels: {
+        discord: {
+          token: "Bot test-token",
+        },
+      },
+    } as OpenClawConfig;
+
+    await expect(
+      sendWebhookMessageDiscord("hello", {
+        cfg,
+        accountId: "default",
+        webhookId: "123",
+        webhookToken: "abc",
+        wait: true,
+      }),
+    ).rejects.toMatchObject({
+      name: "RateLimitError",
+      status: 429,
+      retryAfter: 0.25,
+    });
+    globalFetchMock.mockRestore();
+  });
+
+  it("throws typed status errors for webhook server failures", async () => {
+    const globalFetchMock = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(new Response("upstream unavailable", { status: 503 }));
+
+    const cfg = {
+      channels: {
+        discord: {
+          token: "Bot test-token",
+        },
+      },
+    } as OpenClawConfig;
+
+    await expect(
+      sendWebhookMessageDiscord("hello", {
+        cfg,
+        accountId: "default",
+        webhookId: "123",
+        webhookToken: "abc",
+        wait: true,
+      }),
+    ).rejects.toMatchObject({
+      name: "DiscordError",
+      status: 503,
+    });
+    globalFetchMock.mockRestore();
+  });
+});