@openclaw/discord 2026.3.13 → 2026.5.1-beta.1

package/src/send.permissions.ts

@@ -0,0 +1,283 @@
+import type { APIChannel, APIGuild, APIGuildMember, APIRole } from "discord-api-types/v10";
+import { ChannelType, PermissionFlagsBits } from "discord-api-types/v10";
+import { resolveDiscordRest } from "./client.js";
+import {
+  getChannel,
+  getCurrentUser,
+  getGuild,
+  getGuildMember,
+  type RequestClient,
+} from "./internal/discord.js";
+import type { DiscordPermissionsSummary, DiscordReactOpts } from "./send.types.js";
+
+const PERMISSION_ENTRIES = Object.entries(PermissionFlagsBits).filter(
+  ([, value]) => typeof value === "bigint",
+);
+const ALL_PERMISSIONS = PERMISSION_ENTRIES.reduce((acc, [, value]) => acc | value, 0n);
+const ADMINISTRATOR_BIT = PermissionFlagsBits.Administrator;
+
+function addPermissionBits(base: bigint, add?: string) {
+  if (!add) {
+    return base;
+  }
+  return base | BigInt(add);
+}
+
+function removePermissionBits(base: bigint, deny?: string) {
+  if (!deny) {
+    return base;
+  }
+  return base & ~BigInt(deny);
+}
+
+function bitfieldToPermissions(bitfield: bigint) {
+  return PERMISSION_ENTRIES.filter(([, value]) => (bitfield & value) === value)
+    .map(([name]) => name)
+    .toSorted();
+}
+
+function hasAdministrator(bitfield: bigint) {
+  return (bitfield & ADMINISTRATOR_BIT) === ADMINISTRATOR_BIT;
+}
+
+function hasPermissionBit(bitfield: bigint, permission: bigint) {
+  return (bitfield & permission) === permission;
+}
+
+export function isThreadChannelType(channelType?: number) {
+  return (
+    channelType === ChannelType.GuildNewsThread ||
+    channelType === ChannelType.GuildPublicThread ||
+    channelType === ChannelType.GuildPrivateThread
+  );
+}
+
+async function fetchBotUserId(rest: RequestClient) {
+  const me = await getCurrentUser(rest);
+  if (!me?.id) {
+    throw new Error("Failed to resolve bot user id");
+  }
+  return me.id;
+}
+
+function resolveMemberGuildPermissionBits(params: {
+  guild: Pick<APIGuild, "id" | "roles">;
+  member: Pick<APIGuildMember, "roles">;
+}) {
+  const rolesById = new Map<string, APIRole>(
+    (params.guild.roles ?? []).map((role) => [role.id, role]),
+  );
+  const everyoneRole = rolesById.get(params.guild.id);
+  let permissions = 0n;
+  if (everyoneRole?.permissions) {
+    permissions = addPermissionBits(permissions, everyoneRole.permissions);
+  }
+  for (const roleId of params.member.roles ?? []) {
+    const role = rolesById.get(roleId);
+    if (role?.permissions) {
+      permissions = addPermissionBits(permissions, role.permissions);
+    }
+  }
+  return permissions;
+}
+
+function resolveMemberChannelPermissionBits(params: {
+  guildId: string;
+  userId: string;
+  guild: Pick<APIGuild, "id" | "roles">;
+  member: Pick<APIGuildMember, "roles">;
+  channel: APIChannel;
+}) {
+  let permissions = resolveMemberGuildPermissionBits({
+    guild: params.guild,
+    member: params.member,
+  });
+
+  if (hasAdministrator(permissions)) {
+    return ALL_PERMISSIONS;
+  }
+
+  const overwrites =
+    "permission_overwrites" in params.channel ? (params.channel.permission_overwrites ?? []) : [];
+  for (const overwrite of overwrites) {
+    if (overwrite.id === params.guildId) {
+      permissions = removePermissionBits(permissions, overwrite.deny ?? "0");
+      permissions = addPermissionBits(permissions, overwrite.allow ?? "0");
+    }
+  }
+  let roleDeny = 0n;
+  let roleAllow = 0n;
+  for (const overwrite of overwrites) {
+    if (params.member.roles?.includes(overwrite.id)) {
+      roleDeny = addPermissionBits(roleDeny, overwrite.deny ?? "0");
+      roleAllow = addPermissionBits(roleAllow, overwrite.allow ?? "0");
+    }
+  }
+  permissions = permissions & ~roleDeny;
+  permissions = permissions | roleAllow;
+  for (const overwrite of overwrites) {
+    if (overwrite.id === params.userId) {
+      permissions = removePermissionBits(permissions, overwrite.deny ?? "0");
+      permissions = addPermissionBits(permissions, overwrite.allow ?? "0");
+    }
+  }
+
+  return permissions;
+}
+
+/**
+ * Fetch guild-level permissions for a user. This does not include channel-specific overwrites.
+ */
+export async function fetchMemberGuildPermissionsDiscord(
+  guildId: string,
+  userId: string,
+  opts: DiscordReactOpts,
+): Promise<bigint | null> {
+  const rest = resolveDiscordRest(opts);
+  try {
+    const [guild, member] = await Promise.all([
+      getGuild(rest, guildId),
+      getGuildMember(rest, guildId, userId),
+    ]);
+    return resolveMemberGuildPermissionBits({ guild, member });
+  } catch {
+    // Not a guild member, guild not found, or API failure.
+    return null;
+  }
+}
+
+export async function canViewDiscordGuildChannel(
+  guildId: string,
+  channelId: string,
+  userId: string,
+  opts: DiscordReactOpts,
+): Promise<boolean> {
+  const rest = resolveDiscordRest(opts);
+  try {
+    const channel = await getChannel(rest, channelId);
+    const channelGuildId = "guild_id" in channel ? channel.guild_id : undefined;
+    if (channelGuildId !== guildId) {
+      return false;
+    }
+    const [guild, member] = await Promise.all([
+      getGuild(rest, guildId),
+      getGuildMember(rest, guildId, userId),
+    ]);
+    const permissions = resolveMemberChannelPermissionBits({
+      guildId,
+      userId,
+      guild,
+      member,
+      channel,
+    });
+    return hasPermissionBit(permissions, PermissionFlagsBits.ViewChannel);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns true when the user has ADMINISTRATOR or required permission bits
+ * matching the provided predicate.
+ */
+async function hasGuildPermissionsDiscord(
+  guildId: string,
+  userId: string,
+  requiredPermissions: bigint[],
+  check: (permissions: bigint, requiredPermissions: bigint[]) => boolean,
+  opts: DiscordReactOpts,
+): Promise<boolean> {
+  const permissions = await fetchMemberGuildPermissionsDiscord(guildId, userId, opts);
+  if (permissions === null) {
+    return false;
+  }
+  if (hasAdministrator(permissions)) {
+    return true;
+  }
+  return check(permissions, requiredPermissions);
+}
+
+/**
+ * Returns true when the user has ADMINISTRATOR or any required permission bit.
+ */
+export async function hasAnyGuildPermissionDiscord(
+  guildId: string,
+  userId: string,
+  requiredPermissions: bigint[],
+  opts: DiscordReactOpts,
+): Promise<boolean> {
+  return await hasGuildPermissionsDiscord(
+    guildId,
+    userId,
+    requiredPermissions,
+    (permissions, required) =>
+      required.some((permission) => hasPermissionBit(permissions, permission)),
+    opts,
+  );
+}
+
+/**
+ * Returns true when the user has ADMINISTRATOR or all required permission bits.
+ */
+export async function hasAllGuildPermissionsDiscord(
+  guildId: string,
+  userId: string,
+  requiredPermissions: bigint[],
+  opts: DiscordReactOpts,
+): Promise<boolean> {
+  return await hasGuildPermissionsDiscord(
+    guildId,
+    userId,
+    requiredPermissions,
+    (permissions, required) =>
+      required.every((permission) => hasPermissionBit(permissions, permission)),
+    opts,
+  );
+}
+
+/**
+ * @deprecated Prefer hasAnyGuildPermissionDiscord or hasAllGuildPermissionsDiscord for clarity.
+ */
+export const hasGuildPermissionDiscord = hasAnyGuildPermissionDiscord;
+
+export async function fetchChannelPermissionsDiscord(
+  channelId: string,
+  opts: DiscordReactOpts,
+): Promise<DiscordPermissionsSummary> {
+  const rest = resolveDiscordRest(opts);
+  const channel = await getChannel(rest, channelId);
+  const channelType = "type" in channel ? channel.type : undefined;
+  const guildId = "guild_id" in channel ? channel.guild_id : undefined;
+  if (!guildId) {
+    return {
+      channelId,
+      permissions: [],
+      raw: "0",
+      isDm: true,
+      channelType,
+    };
+  }
+
+  const botId = await fetchBotUserId(rest);
+  const [guild, member] = await Promise.all([
+    getGuild(rest, guildId),
+    getGuildMember(rest, guildId, botId),
+  ]);
+
+  const permissions = resolveMemberChannelPermissionBits({
+    guildId,
+    userId: botId,
+    guild,
+    member,
+    channel,
+  });
+
+  return {
+    channelId,
+    guildId,
+    permissions: bitfieldToPermissions(permissions),
+    raw: permissions.toString(),
+    isDm: false,
+    channelType,
+  };
+}

package/src/send.reactions.ts

@@ -0,0 +1,155 @@
+import { requireRuntimeConfig } from "openclaw/plugin-sdk/plugin-config-runtime";
+import {
+  createOwnMessageReaction,
+  deleteOwnMessageReaction,
+  getChannelMessage,
+  listMessageReactionUsers,
+} from "./internal/discord.js";
+import {
+  buildReactionIdentifier,
+  createDiscordClient,
+  formatReactionEmoji,
+  normalizeReactionEmoji,
+} from "./send.shared.js";
+import type {
+  DiscordReactionRuntimeContext,
+  DiscordReactionSummary,
+  DiscordReactOpts,
+} from "./send.types.js";
+
+function createDiscordReactionRuntimeClient(opts: DiscordReactionRuntimeContext) {
+  return createDiscordClient(opts);
+}
+
+function resolveDiscordReactionClient(opts: DiscordReactOpts) {
+  if (!opts.cfg) {
+    throw new Error(
+      "Discord reactions requires a resolved runtime config. Load and resolve config at the command or gateway boundary, then pass cfg through the runtime path.",
+    );
+  }
+  const cfg = requireRuntimeConfig(opts.cfg, "Discord reactions");
+  return createDiscordClient({ ...opts, cfg });
+}
+
+function isDiscordReactionRuntimeContext(
+  opts: DiscordReactOpts,
+): opts is DiscordReactionRuntimeContext {
+  return Boolean(opts.rest && opts.cfg && opts.accountId);
+}
+
+export async function reactMessageDiscord(
+  channelId: string,
+  messageId: string,
+  emoji: string,
+  opts: DiscordReactOpts,
+) {
+  const { rest, request } = isDiscordReactionRuntimeContext(opts)
+    ? createDiscordReactionRuntimeClient(opts)
+    : resolveDiscordReactionClient(opts);
+  const encoded = normalizeReactionEmoji(emoji);
+  await request(() => createOwnMessageReaction(rest, channelId, messageId, encoded), "react");
+  return { ok: true };
+}
+
+export async function removeReactionDiscord(
+  channelId: string,
+  messageId: string,
+  emoji: string,
+  opts: DiscordReactOpts,
+) {
+  const { rest } = isDiscordReactionRuntimeContext(opts)
+    ? createDiscordReactionRuntimeClient(opts)
+    : resolveDiscordReactionClient(opts);
+  const encoded = normalizeReactionEmoji(emoji);
+  await deleteOwnMessageReaction(rest, channelId, messageId, encoded);
+  return { ok: true };
+}
+
+export async function removeOwnReactionsDiscord(
+  channelId: string,
+  messageId: string,
+  opts: DiscordReactOpts,
+): Promise<{ ok: true; removed: string[] }> {
+  const { rest } = isDiscordReactionRuntimeContext(opts)
+    ? createDiscordReactionRuntimeClient(opts)
+    : resolveDiscordReactionClient(opts);
+  const message = (await getChannelMessage(rest, channelId, messageId)) as {
+    reactions?: Array<{ emoji: { id?: string | null; name?: string | null } }>;
+  };
+  const identifiers = new Set<string>();
+  for (const reaction of message.reactions ?? []) {
+    const identifier = buildReactionIdentifier(reaction.emoji);
+    if (identifier) {
+      identifiers.add(identifier);
+    }
+  }
+  if (identifiers.size === 0) {
+    return { ok: true, removed: [] };
+  }
+  const removed: string[] = [];
+  await Promise.allSettled(
+    Array.from(identifiers, (identifier) => {
+      removed.push(identifier);
+      return deleteOwnMessageReaction(
+        rest,
+        channelId,
+        messageId,
+        normalizeReactionEmoji(identifier),
+      );
+    }),
+  );
+  return { ok: true, removed };
+}
+
+export async function fetchReactionsDiscord(
+  channelId: string,
+  messageId: string,
+  opts: DiscordReactOpts & { limit?: number },
+): Promise<DiscordReactionSummary[]> {
+  const { rest } = isDiscordReactionRuntimeContext(opts)
+    ? createDiscordReactionRuntimeClient(opts)
+    : resolveDiscordReactionClient(opts);
+  const message = (await getChannelMessage(rest, channelId, messageId)) as {
+    reactions?: Array<{
+      count: number;
+      emoji: { id?: string | null; name?: string | null };
+    }>;
+  };
+  const reactions = message.reactions ?? [];
+  if (reactions.length === 0) {
+    return [];
+  }
+  const limit =
+    typeof opts.limit === "number" && Number.isFinite(opts.limit)
+      ? Math.min(Math.max(Math.floor(opts.limit), 1), 100)
+      : 100;
+
+  const summaries: DiscordReactionSummary[] = [];
+  for (const reaction of reactions) {
+    const identifier = buildReactionIdentifier(reaction.emoji);
+    if (!identifier) {
+      continue;
+    }
+    const encoded = encodeURIComponent(identifier);
+    const users = await listMessageReactionUsers(rest, channelId, messageId, encoded, {
+      limit,
+    });
+    summaries.push({
+      emoji: {
+        id: reaction.emoji.id ?? null,
+        name: reaction.emoji.name ?? null,
+        raw: formatReactionEmoji(reaction.emoji),
+      },
+      count: reaction.count,
+      users: users.map((user) => ({
+        id: user.id,
+        username: user.username,
+        tag:
+          user.username && user.discriminator
+            ? `${user.username}#${user.discriminator}`
+            : user.username,
+      })),
+    });
+  }
+  return summaries;
+}