@openclaw/discord 2026.3.13 → 2026.5.1-beta.1

package/src/send.guild.ts

@@ -0,0 +1,170 @@
+import type {
+  APIGuildMember,
+  APIGuildScheduledEvent,
+  APIRole,
+  APIVoiceState,
+  RESTPostAPIGuildScheduledEventJSONBody,
+} from "discord-api-types/v10";
+import { normalizeOptionalLowercaseString } from "openclaw/plugin-sdk/text-runtime";
+import { loadWebMediaRaw } from "openclaw/plugin-sdk/web-media";
+import {
+  addGuildMemberRole,
+  createGuildBan,
+  createGuildScheduledEvent,
+  getChannel,
+  getGuildMember,
+  getGuildVoiceState,
+  listGuildChannels,
+  listGuildRoles,
+  listGuildScheduledEvents,
+  removeGuildMember,
+  removeGuildMemberRole,
+  timeoutGuildMember,
+  type APIChannel,
+} from "./internal/discord.js";
+import { resolveDiscordRest } from "./send.shared.js";
+import type {
+  DiscordModerationTarget,
+  DiscordReactOpts,
+  DiscordRoleChange,
+  DiscordTimeoutTarget,
+} from "./send.types.js";
+import { DISCORD_MAX_EVENT_COVER_BYTES } from "./send.types.js";
+
+export async function fetchMemberInfoDiscord(
+  guildId: string,
+  userId: string,
+  opts: DiscordReactOpts,
+): Promise<APIGuildMember> {
+  const rest = resolveDiscordRest(opts);
+  return await getGuildMember(rest, guildId, userId);
+}
+
+export async function fetchRoleInfoDiscord(
+  guildId: string,
+  opts: DiscordReactOpts,
+): Promise<APIRole[]> {
+  const rest = resolveDiscordRest(opts);
+  return await listGuildRoles(rest, guildId);
+}
+
+export async function addRoleDiscord(payload: DiscordRoleChange, opts: DiscordReactOpts) {
+  const rest = resolveDiscordRest(opts);
+  await addGuildMemberRole(rest, payload.guildId, payload.userId, payload.roleId);
+  return { ok: true };
+}
+
+export async function removeRoleDiscord(payload: DiscordRoleChange, opts: DiscordReactOpts) {
+  const rest = resolveDiscordRest(opts);
+  await removeGuildMemberRole(rest, payload.guildId, payload.userId, payload.roleId);
+  return { ok: true };
+}
+
+export async function fetchChannelInfoDiscord(
+  channelId: string,
+  opts: DiscordReactOpts,
+): Promise<APIChannel> {
+  const rest = resolveDiscordRest(opts);
+  return await getChannel(rest, channelId);
+}
+
+export async function listGuildChannelsDiscord(
+  guildId: string,
+  opts: DiscordReactOpts,
+): Promise<APIChannel[]> {
+  const rest = resolveDiscordRest(opts);
+  return await listGuildChannels(rest, guildId);
+}
+
+export async function fetchVoiceStatusDiscord(
+  guildId: string,
+  userId: string,
+  opts: DiscordReactOpts,
+): Promise<APIVoiceState> {
+  const rest = resolveDiscordRest(opts);
+  return await getGuildVoiceState(rest, guildId, userId);
+}
+
+export async function listScheduledEventsDiscord(
+  guildId: string,
+  opts: DiscordReactOpts,
+): Promise<APIGuildScheduledEvent[]> {
+  const rest = resolveDiscordRest(opts);
+  return await listGuildScheduledEvents(rest, guildId);
+}
+
+const ALLOWED_EVENT_COVER_TYPES = new Set(["image/png", "image/jpeg", "image/jpg", "image/gif"]);
+
+// Loads an image from a URL or path and returns a data URI suitable for the Discord API.
+export async function resolveEventCoverImage(
+  imageUrl: string,
+  opts?: { localRoots?: readonly string[] },
+): Promise<string> {
+  const media = await loadWebMediaRaw(imageUrl, DISCORD_MAX_EVENT_COVER_BYTES, {
+    localRoots: opts?.localRoots,
+  });
+  const contentType = normalizeOptionalLowercaseString(media.contentType);
+  if (!contentType || !ALLOWED_EVENT_COVER_TYPES.has(contentType)) {
+    throw new Error(
+      `Discord event cover images must be PNG, JPG, or GIF (got ${contentType ?? "unknown"})`,
+    );
+  }
+  return `data:${contentType};base64,${media.buffer.toString("base64")}`;
+}
+
+export async function createScheduledEventDiscord(
+  guildId: string,
+  payload: RESTPostAPIGuildScheduledEventJSONBody,
+  opts: DiscordReactOpts,
+): Promise<APIGuildScheduledEvent> {
+  const rest = resolveDiscordRest(opts);
+  return await createGuildScheduledEvent(rest, guildId, payload);
+}
+
+export async function timeoutMemberDiscord(
+  payload: DiscordTimeoutTarget,
+  opts: DiscordReactOpts,
+): Promise<APIGuildMember> {
+  const rest = resolveDiscordRest(opts);
+  let until = payload.until;
+  if (!until && payload.durationMinutes) {
+    const ms = payload.durationMinutes * 60 * 1000;
+    until = new Date(Date.now() + ms).toISOString();
+  }
+  return await timeoutGuildMember(rest, payload.guildId, payload.userId, {
+    body: { communication_disabled_until: until ?? null },
+    headers: payload.reason
+      ? { "X-Audit-Log-Reason": encodeURIComponent(payload.reason) }
+      : undefined,
+  });
+}
+
+export async function kickMemberDiscord(payload: DiscordModerationTarget, opts: DiscordReactOpts) {
+  const rest = resolveDiscordRest(opts);
+  await removeGuildMember(rest, payload.guildId, payload.userId, {
+    headers: payload.reason
+      ? { "X-Audit-Log-Reason": encodeURIComponent(payload.reason) }
+      : undefined,
+  });
+  return { ok: true };
+}
+
+export async function banMemberDiscord(
+  payload: DiscordModerationTarget & { deleteMessageDays?: number },
+  opts: DiscordReactOpts,
+) {
+  const rest = resolveDiscordRest(opts);
+  const deleteMessageDays =
+    typeof payload.deleteMessageDays === "number" && Number.isFinite(payload.deleteMessageDays)
+      ? Math.min(Math.max(Math.floor(payload.deleteMessageDays), 0), 7)
+      : undefined;
+  await createGuildBan(rest, payload.guildId, payload.userId, {
+    body: deleteMessageDays !== undefined ? { delete_message_days: deleteMessageDays } : undefined,
+    headers: payload.reason
+      ? { "X-Audit-Log-Reason": encodeURIComponent(payload.reason) }
+      : undefined,
+  });
+  return { ok: true };
+}
+
+// Channel management functions

package/src/send.message-request.ts

@@ -0,0 +1,97 @@
+import type { APIEmbed } from "discord-api-types/v10";
+import {
+  Embed,
+  serializePayload,
+  type MessagePayloadFile,
+  type MessagePayloadObject,
+  type TopLevelComponents,
+} from "./internal/discord.js";
+
+export const SUPPRESS_NOTIFICATIONS_FLAG = 1 << 12;
+
+export type DiscordSendComponentFactory = (text: string) => TopLevelComponents[];
+export type DiscordSendComponents = TopLevelComponents[] | DiscordSendComponentFactory;
+export type DiscordSendEmbeds = Array<APIEmbed | Embed>;
+
+export function resolveDiscordSendComponents(params: {
+  components?: DiscordSendComponents;
+  text: string;
+  isFirst: boolean;
+}): TopLevelComponents[] | undefined {
+  if (!params.components || !params.isFirst) {
+    return undefined;
+  }
+  return typeof params.components === "function"
+    ? params.components(params.text)
+    : params.components;
+}
+
+function normalizeDiscordEmbeds(embeds?: DiscordSendEmbeds): Embed[] | undefined {
+  if (!embeds?.length) {
+    return undefined;
+  }
+  return embeds.map((embed) => (embed instanceof Embed ? embed : new Embed(embed)));
+}
+
+export function resolveDiscordSendEmbeds(params: {
+  embeds?: DiscordSendEmbeds;
+  isFirst: boolean;
+}): Embed[] | undefined {
+  if (!params.embeds || !params.isFirst) {
+    return undefined;
+  }
+  return normalizeDiscordEmbeds(params.embeds);
+}
+
+export function buildDiscordMessagePayload(params: {
+  text: string;
+  components?: TopLevelComponents[];
+  embeds?: Embed[];
+  flags?: number;
+  files?: MessagePayloadFile[];
+}): MessagePayloadObject {
+  const payload: MessagePayloadObject = {};
+  const hasV2 = hasV2Components(params.components);
+  const trimmed = params.text.trim();
+  if (!hasV2 && trimmed) {
+    payload.content = params.text;
+  }
+  if (params.components?.length) {
+    payload.components = params.components;
+  }
+  if (!hasV2 && params.embeds?.length) {
+    payload.embeds = params.embeds;
+  }
+  if (params.flags !== undefined) {
+    payload.flags = params.flags;
+  }
+  if (params.files?.length) {
+    payload.files = params.files;
+  }
+  return payload;
+}
+
+export function buildDiscordMessageRequest(params: {
+  text: string;
+  components?: TopLevelComponents[];
+  embeds?: Embed[];
+  files?: MessagePayloadFile[];
+  flags?: number;
+  replyTo?: string;
+}) {
+  const payload = buildDiscordMessagePayload(params);
+  return stripUndefinedFields({
+    ...serializePayload(payload),
+    ...(params.replyTo
+      ? { message_reference: { message_id: params.replyTo, fail_if_not_exists: false } }
+      : {}),
+  });
+}
+
+export function stripUndefinedFields<T extends object>(value: T): T {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)) as T;
+}
+
+function hasV2Components(components?: TopLevelComponents[]): boolean {
+  return Boolean(components?.some((component) => "isV2" in component && component.isV2));
+}

package/src/send.messages.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it, vi } from "vitest";
+
+const restMock = {
+  get: vi.fn(),
+};
+
+vi.mock("./send.shared.js", () => ({
+  resolveDiscordRest: () => restMock,
+}));
+
+const { readMessagesDiscord, searchMessagesDiscord } = await import("./send.messages.js");
+
+describe("readMessagesDiscord", () => {
+  it("returns messages from the REST client", async () => {
+    const messages = [{ id: "1", content: "hello" }];
+    restMock.get.mockResolvedValueOnce(messages);
+
+    const result = await readMessagesDiscord("C1", { limit: 5 }, { cfg: {} as never });
+
+    expect(result).toEqual(messages);
+    expect(restMock.get).toHaveBeenCalledWith(expect.stringContaining("C1"), { limit: 5 });
+  });
+
+  it("propagates REST errors", async () => {
+    restMock.get.mockRejectedValueOnce(new Error("Discord API error"));
+
+    await expect(readMessagesDiscord("C1", {}, { cfg: {} as never })).rejects.toThrow(
+      "Discord API error",
+    );
+  });
+});
+
+describe("searchMessagesDiscord", () => {
+  it("returns search results from the REST client", async () => {
+    const results = { messages: [[{ id: "1" }]], total_results: 1 };
+    restMock.get.mockResolvedValueOnce(results);
+
+    const result = await searchMessagesDiscord(
+      { guildId: "G1", content: "test", limit: 1 },
+      { cfg: {} as never },
+    );
+
+    expect(result).toEqual(results);
+  });
+
+  it("propagates REST errors", async () => {
+    restMock.get.mockRejectedValueOnce(new Error("Discord API error"));
+
+    await expect(
+      searchMessagesDiscord({ guildId: "G1", content: "test" }, { cfg: {} as never }),
+    ).rejects.toThrow("Discord API error");
+  });
+});

package/src/send.messages.ts

@@ -0,0 +1,225 @@
+import type { APIChannel, APIMessage } from "discord-api-types/v10";
+import { ChannelType } from "discord-api-types/v10";
+import {
+  createChannelMessage,
+  createThread,
+  deleteChannelMessage,
+  editChannelMessage,
+  getChannel,
+  getChannelMessage,
+  listChannelArchivedThreads,
+  listGuildActiveThreads,
+  listChannelMessages,
+  listChannelPins,
+  pinChannelMessage,
+  searchGuildMessages,
+  unpinChannelMessage,
+} from "./internal/discord.js";
+import { resolveDiscordRest } from "./send.shared.js";
+import type {
+  DiscordMessageEdit,
+  DiscordMessageQuery,
+  DiscordReactOpts,
+  DiscordSearchQuery,
+  DiscordThreadCreate,
+  DiscordThreadList,
+} from "./send.types.js";
+
+function formatDiscordThreadInitialMessageError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export class DiscordThreadInitialMessageError extends Error {
+  readonly initialMessageError: string;
+  readonly thread: APIChannel;
+
+  constructor(thread: APIChannel, error: unknown) {
+    const initialMessageError = formatDiscordThreadInitialMessageError(error);
+    super(
+      `Discord thread was created, but sending the initial message failed: ${initialMessageError}`,
+    );
+    this.name = "DiscordThreadInitialMessageError";
+    this.initialMessageError = initialMessageError;
+    this.thread = thread;
+  }
+}
+
+export async function readMessagesDiscord(
+  channelId: string,
+  query: DiscordMessageQuery = {},
+  opts: DiscordReactOpts,
+): Promise<APIMessage[]> {
+  const rest = resolveDiscordRest(opts);
+  const limit =
+    typeof query.limit === "number" && Number.isFinite(query.limit)
+      ? Math.min(Math.max(Math.floor(query.limit), 1), 100)
+      : undefined;
+  const params: Record<string, string | number> = {};
+  if (limit) {
+    params.limit = limit;
+  }
+  if (query.before) {
+    params.before = query.before;
+  }
+  if (query.after) {
+    params.after = query.after;
+  }
+  if (query.around) {
+    params.around = query.around;
+  }
+  return await listChannelMessages(rest, channelId, params);
+}
+
+export async function fetchMessageDiscord(
+  channelId: string,
+  messageId: string,
+  opts: DiscordReactOpts,
+): Promise<APIMessage> {
+  const rest = resolveDiscordRest(opts);
+  return await getChannelMessage(rest, channelId, messageId);
+}
+
+export async function editMessageDiscord(
+  channelId: string,
+  messageId: string,
+  payload: DiscordMessageEdit,
+  opts: DiscordReactOpts,
+): Promise<APIMessage> {
+  const rest = resolveDiscordRest(opts);
+  return await editChannelMessage(rest, channelId, messageId, {
+    body: { content: payload.content },
+  });
+}
+
+export async function deleteMessageDiscord(
+  channelId: string,
+  messageId: string,
+  opts: DiscordReactOpts,
+) {
+  const rest = resolveDiscordRest(opts);
+  await deleteChannelMessage(rest, channelId, messageId);
+  return { ok: true };
+}
+
+export async function pinMessageDiscord(
+  channelId: string,
+  messageId: string,
+  opts: DiscordReactOpts,
+) {
+  const rest = resolveDiscordRest(opts);
+  await pinChannelMessage(rest, channelId, messageId);
+  return { ok: true };
+}
+
+export async function unpinMessageDiscord(
+  channelId: string,
+  messageId: string,
+  opts: DiscordReactOpts,
+) {
+  const rest = resolveDiscordRest(opts);
+  await unpinChannelMessage(rest, channelId, messageId);
+  return { ok: true };
+}
+
+export async function listPinsDiscord(
+  channelId: string,
+  opts: DiscordReactOpts,
+): Promise<APIMessage[]> {
+  const rest = resolveDiscordRest(opts);
+  return await listChannelPins(rest, channelId);
+}
+
+export async function createThreadDiscord(
+  channelId: string,
+  payload: DiscordThreadCreate,
+  opts: DiscordReactOpts,
+) {
+  const rest = resolveDiscordRest(opts);
+  const body: Record<string, unknown> = { name: payload.name };
+  if (payload.autoArchiveMinutes) {
+    body.auto_archive_duration = payload.autoArchiveMinutes;
+  }
+  if (!payload.messageId && payload.type !== undefined) {
+    body.type = payload.type;
+  }
+  let channelType: ChannelType | undefined;
+  if (!payload.messageId) {
+    // Only detect channel kind for route-less thread creation.
+    // If this lookup fails, keep prior behavior and let Discord validate.
+    try {
+      const channel = await getChannel(rest, channelId);
+      channelType = channel?.type;
+    } catch {
+      channelType = undefined;
+    }
+  }
+  const isForumLike =
+    channelType === ChannelType.GuildForum || channelType === ChannelType.GuildMedia;
+  if (isForumLike) {
+    const starterContent = payload.content?.trim() ? payload.content : payload.name;
+    body.message = { content: starterContent };
+    if (payload.appliedTags?.length) {
+      body.applied_tags = payload.appliedTags;
+    }
+  }
+  // When creating a standalone thread (no messageId) in a non-forum channel,
+  // default to public thread (type 11). Discord defaults to private (type 12)
+  // which is unexpected for most users. (#14147)
+  if (!payload.messageId && !isForumLike && body.type === undefined) {
+    body.type = ChannelType.PublicThread;
+  }
+  const thread = await createThread(rest, channelId, { body }, payload.messageId);
+
+  // For non-forum channels, send the initial message separately after thread creation.
+  // Forum channels handle this via the `message` field in the request body.
+  if (!isForumLike && payload.content?.trim() && "id" in thread) {
+    try {
+      await createChannelMessage(rest, thread.id, {
+        body: { content: payload.content },
+      });
+    } catch (error) {
+      throw new DiscordThreadInitialMessageError(thread, error);
+    }
+  }
+
+  return thread;
+}
+
+export async function listThreadsDiscord(payload: DiscordThreadList, opts: DiscordReactOpts) {
+  const rest = resolveDiscordRest(opts);
+  if (payload.includeArchived) {
+    if (!payload.channelId) {
+      throw new Error("channelId required to list archived threads");
+    }
+    const params: Record<string, string | number> = {};
+    if (payload.before) {
+      params.before = payload.before;
+    }
+    if (payload.limit) {
+      params.limit = payload.limit;
+    }
+    return await listChannelArchivedThreads(rest, payload.channelId, params);
+  }
+  return await listGuildActiveThreads(rest, payload.guildId);
+}
+
+export async function searchMessagesDiscord(query: DiscordSearchQuery, opts: DiscordReactOpts) {
+  const rest = resolveDiscordRest(opts);
+  const params = new URLSearchParams();
+  params.set("content", query.content);
+  if (query.channelIds?.length) {
+    for (const channelId of query.channelIds) {
+      params.append("channel_id", channelId);
+    }
+  }
+  if (query.authorIds?.length) {
+    for (const authorId of query.authorIds) {
+      params.append("author_id", authorId);
+    }
+  }
+  if (query.limit) {
+    const limit = Math.min(Math.max(Math.floor(query.limit), 1), 25);
+    params.set("limit", String(limit));
+  }
+  return await searchGuildMessages(rest, query.guildId, params);
+}