@gakr-gakr/discord 0.1.0

package/src/send.components.ts

@@ -0,0 +1,391 @@
+import { ChannelType } from "discord-api-types/v10";
+import { recordChannelActivity } from "autobot/plugin-sdk/channel-activity-runtime";
+import type { MarkdownTableMode, AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import type { OutboundMediaAccess } from "autobot/plugin-sdk/media-runtime";
+import { requireRuntimeConfig } from "autobot/plugin-sdk/plugin-config-runtime";
+import type { ChunkMode } from "autobot/plugin-sdk/reply-chunking";
+import { resolveDiscordAccount } from "./accounts.js";
+import { registerDiscordComponentEntries } from "./components-registry.js";
+import {
+  buildDiscordComponentMessage,
+  buildDiscordComponentMessageFlags,
+  resolveDiscordComponentAttachmentName,
+  type DiscordComponentBuildResult,
+  type DiscordComponentMessageSpec,
+} from "./components.js";
+import {
+  createChannelMessage,
+  editChannelMessage,
+  serializePayload,
+  type MessagePayloadFile,
+  type MessagePayloadObject,
+  type RequestClient,
+} from "./internal/discord.js";
+import { parseAndResolveRecipient } from "./recipient-resolution.js";
+import { loadOutboundMediaFromUrl } from "./runtime-api.js";
+import { sendMessageDiscord } from "./send.outbound.js";
+import { createDiscordSendResult } from "./send.receipt.js";
+import {
+  buildDiscordSendError,
+  createDiscordClient,
+  resolveChannelId,
+  resolveDiscordChannelType,
+  toDiscordFileBlob,
+  stripUndefinedFields,
+  SUPPRESS_NOTIFICATIONS_FLAG,
+} from "./send.shared.js";
+import type { DiscordSendResult } from "./send.types.js";
+
+const DISCORD_FORUM_LIKE_TYPES = new Set<number>([ChannelType.GuildForum, ChannelType.GuildMedia]);
+
+function extractComponentAttachmentNames(spec: DiscordComponentMessageSpec): string[] {
+  const names: string[] = [];
+  for (const block of spec.blocks ?? []) {
+    if (block.type === "file") {
+      names.push(resolveDiscordComponentAttachmentName(block.file));
+    }
+  }
+  return names;
+}
+
+function hasComponentAttachmentBlock(spec: DiscordComponentMessageSpec): boolean {
+  return (spec.blocks ?? []).some((block) => block.type === "file");
+}
+
+function withImplicitComponentAttachmentBlock(
+  spec: DiscordComponentMessageSpec,
+  attachmentName: string | undefined,
+): DiscordComponentMessageSpec {
+  if (!attachmentName || hasComponentAttachmentBlock(spec)) {
+    return spec;
+  }
+  // Discord File components must point at the uploaded attachment name. Add the
+  // matching file block automatically so callers do not have to duplicate it.
+  return {
+    ...spec,
+    blocks: [
+      ...(spec.blocks ?? []),
+      {
+        type: "file",
+        file: `attachment://${attachmentName}`,
+      },
+    ],
+  };
+}
+
+function hasClassicOnlyBlocks(spec: DiscordComponentMessageSpec): boolean {
+  return (spec.blocks ?? []).every((block) => block.type === "text" || block.type === "file");
+}
+
+function hasUnsupportedClassicFeatures(spec: DiscordComponentMessageSpec): boolean {
+  return Boolean(spec.modal || spec.container);
+}
+
+function hasAtMostOneNonSpoilerFile(spec: DiscordComponentMessageSpec): boolean {
+  let fileBlockCount = 0;
+  for (const block of spec.blocks ?? []) {
+    if (block.type !== "file") {
+      continue;
+    }
+    fileBlockCount += 1;
+    if (block.spoiler) {
+      return false;
+    }
+  }
+  return fileBlockCount <= 1;
+}
+
+type ClassicDiscordMessageDecision =
+  | {
+      mode: "classic";
+      reason: "plain-text-single-file";
+    }
+  | {
+      mode: "components";
+      reason: "unsupported-feature" | "unsupported-block" | "multiple-or-spoiler-files";
+    };
+
+/**
+ * Keep the downgrade rules explicit because this path is only safe when the
+ * spec means exactly what a plain Discord message can represent.
+ */
+function getClassicDiscordMessageDecision(
+  spec: DiscordComponentMessageSpec,
+): ClassicDiscordMessageDecision {
+  if (hasUnsupportedClassicFeatures(spec)) {
+    return { mode: "components", reason: "unsupported-feature" };
+  }
+  if (!hasClassicOnlyBlocks(spec)) {
+    return { mode: "components", reason: "unsupported-block" };
+  }
+  if (!hasAtMostOneNonSpoilerFile(spec)) {
+    return { mode: "components", reason: "multiple-or-spoiler-files" };
+  }
+  return { mode: "classic", reason: "plain-text-single-file" };
+}
+
+function collapseClassicComponentText(spec: DiscordComponentMessageSpec): string {
+  const parts: string[] = [];
+  const addPart = (value: string | undefined) => {
+    if (typeof value !== "string") {
+      return;
+    }
+    const trimmed = value.trim();
+    if (!trimmed || parts.includes(trimmed)) {
+      return;
+    }
+    parts.push(trimmed);
+  };
+
+  addPart(spec.text);
+  for (const block of spec.blocks ?? []) {
+    if (block.type === "text") {
+      addPart(block.text);
+    }
+  }
+  return parts.join("\n\n");
+}
+
+type DiscordComponentSendOpts = {
+  cfg: AutoBotConfig;
+  accountId?: string;
+  token?: string;
+  rest?: RequestClient;
+  silent?: boolean;
+  replyTo?: string;
+  sessionKey?: string;
+  agentId?: string;
+  mediaUrl?: string;
+  mediaAccess?: OutboundMediaAccess;
+  mediaLocalRoots?: readonly string[];
+  mediaReadFile?: (filePath: string) => Promise<Buffer>;
+  filename?: string;
+  textLimit?: number;
+  maxLinesPerMessage?: number;
+  tableMode?: MarkdownTableMode;
+  chunkMode?: ChunkMode;
+  suppressEmbeds?: boolean;
+};
+
+export function registerBuiltDiscordComponentMessage(params: {
+  buildResult: DiscordComponentBuildResult;
+  messageId: string;
+}): void {
+  registerDiscordComponentEntries({
+    entries: params.buildResult.entries,
+    modals: params.buildResult.modals,
+    messageId: params.messageId,
+  });
+}
+
+async function buildDiscordComponentPayload(params: {
+  spec: DiscordComponentMessageSpec;
+  opts: DiscordComponentSendOpts;
+  accountId: string;
+}): Promise<{
+  body: ReturnType<typeof stripUndefinedFields>;
+  buildResult: ReturnType<typeof buildDiscordComponentMessage>;
+}> {
+  const messageReference = params.opts.replyTo
+    ? { message_id: params.opts.replyTo, fail_if_not_exists: false }
+    : undefined;
+
+  let spec = params.spec;
+  let resolvedFileName: string | undefined;
+  let files: MessagePayloadFile[] | undefined;
+  if (params.opts.mediaUrl) {
+    const media = await loadOutboundMediaFromUrl(params.opts.mediaUrl, {
+      mediaAccess: params.opts.mediaAccess,
+      mediaLocalRoots: params.opts.mediaLocalRoots,
+      mediaReadFile: params.opts.mediaReadFile,
+    });
+    const filenameOverride = params.opts.filename?.trim();
+    resolvedFileName = filenameOverride || media.fileName || "upload";
+    spec = withImplicitComponentAttachmentBlock(spec, resolvedFileName);
+    const fileData = toDiscordFileBlob(media.buffer);
+    files = [{ data: fileData, name: resolvedFileName }];
+  }
+
+  const attachmentNames = extractComponentAttachmentNames(spec);
+  const uniqueAttachmentNames = [...new Set(attachmentNames)];
+  if (uniqueAttachmentNames.length > 1) {
+    throw new Error(
+      "Discord component attachments currently support a single file. Use media-gallery for multiple files.",
+    );
+  }
+  const expectedAttachmentName = uniqueAttachmentNames[0];
+  if (expectedAttachmentName && resolvedFileName && expectedAttachmentName !== resolvedFileName) {
+    throw new Error(
+      `Component file block expects attachment "${expectedAttachmentName}", but the uploaded file is "${resolvedFileName}". Update components.blocks[].file or provide a matching filename.`,
+    );
+  }
+  if (!params.opts.mediaUrl && expectedAttachmentName) {
+    throw new Error(
+      "Discord component file blocks require a media attachment (media/path/filePath).",
+    );
+  }
+
+  const buildResult = buildDiscordComponentMessage({
+    spec,
+    sessionKey: params.opts.sessionKey,
+    agentId: params.opts.agentId,
+    accountId: params.accountId,
+  });
+  const flags = buildDiscordComponentMessageFlags(buildResult.components);
+  const finalFlags = params.opts.silent
+    ? (flags ?? 0) | SUPPRESS_NOTIFICATIONS_FLAG
+    : (flags ?? undefined);
+
+  const payload: MessagePayloadObject = {
+    components: buildResult.components,
+    ...(finalFlags ? { flags: finalFlags } : {}),
+    ...(files ? { files } : {}),
+  };
+  const body = stripUndefinedFields({
+    ...serializePayload(payload),
+    ...(messageReference ? { message_reference: messageReference } : {}),
+  });
+
+  return { body, buildResult };
+}
+
+export async function sendDiscordComponentMessage(
+  to: string,
+  spec: DiscordComponentMessageSpec,
+  opts: DiscordComponentSendOpts,
+): Promise<DiscordSendResult> {
+  const classicDecision = getClassicDiscordMessageDecision(spec);
+  if (opts.mediaUrl && classicDecision.mode === "classic") {
+    return await sendMessageDiscord(to, collapseClassicComponentText(spec), {
+      cfg: opts.cfg,
+      accountId: opts.accountId,
+      token: opts.token,
+      rest: opts.rest,
+      mediaUrl: opts.mediaUrl,
+      filename: opts.filename,
+      mediaLocalRoots: opts.mediaLocalRoots,
+      mediaReadFile: opts.mediaReadFile,
+      mediaAccess: opts.mediaAccess,
+      replyTo: opts.replyTo,
+      silent: opts.silent,
+      textLimit: opts.textLimit,
+      maxLinesPerMessage: opts.maxLinesPerMessage,
+      tableMode: opts.tableMode,
+      chunkMode: opts.chunkMode,
+      ...(opts.suppressEmbeds === undefined ? {} : { suppressEmbeds: opts.suppressEmbeds }),
+    });
+  }
+
+  const cfg = requireRuntimeConfig(opts.cfg, "Discord component send");
+  const accountInfo = resolveDiscordAccount({ cfg, accountId: opts.accountId });
+  const { token, rest, request } = createDiscordClient({ ...opts, cfg });
+  const recipient = await parseAndResolveRecipient(to, cfg, opts.accountId);
+  const { channelId } = await resolveChannelId(rest, recipient, request);
+
+  const channelType = await resolveDiscordChannelType(rest, channelId);
+
+  if (channelType && DISCORD_FORUM_LIKE_TYPES.has(channelType)) {
+    throw new Error("Discord components are not supported in forum-style channels");
+  }
+
+  const { body, buildResult } = await buildDiscordComponentPayload({
+    spec,
+    opts,
+    accountId: accountInfo.accountId,
+  });
+
+  let result: { id: string; channel_id: string };
+  try {
+    result = (await request(
+      () =>
+        createChannelMessage<{ id: string; channel_id: string }>(rest, channelId, {
+          body,
+        }),
+      "components",
+    )) as { id: string; channel_id: string };
+  } catch (err) {
+    throw await buildDiscordSendError(err, {
+      channelId,
+      cfg,
+      rest,
+      token,
+      hasMedia: Boolean(opts.mediaUrl),
+    });
+  }
+
+  registerBuiltDiscordComponentMessage({
+    buildResult,
+    messageId: result.id,
+  });
+
+  recordChannelActivity({
+    channel: "discord",
+    accountId: accountInfo.accountId,
+    direction: "outbound",
+  });
+
+  return createDiscordSendResult({
+    result,
+    fallbackChannelId: channelId,
+    kind: "card",
+    ...(opts.replyTo ? { replyToId: opts.replyTo } : {}),
+  });
+}
+
+export async function editDiscordComponentMessage(
+  to: string,
+  messageId: string,
+  spec: DiscordComponentMessageSpec,
+  opts: DiscordComponentSendOpts,
+): Promise<DiscordSendResult> {
+  const cfg = requireRuntimeConfig(opts.cfg, "Discord component edit");
+  const accountInfo = resolveDiscordAccount({ cfg, accountId: opts.accountId });
+  const { token, rest, request } = createDiscordClient({ ...opts, cfg });
+  const recipient = await parseAndResolveRecipient(to, cfg, opts.accountId);
+  const { channelId } = await resolveChannelId(rest, recipient, request);
+  const { body, buildResult } = await buildDiscordComponentPayload({
+    spec,
+    opts,
+    accountId: accountInfo.accountId,
+  });
+
+  let result: { id: string; channel_id: string };
+  try {
+    result = (await request(
+      () =>
+        editChannelMessage(rest, channelId, messageId, {
+          body,
+        }) as Promise<{ id: string; channel_id: string }>,
+      "components",
+    )) as { id: string; channel_id: string };
+  } catch (err) {
+    throw await buildDiscordSendError(err, {
+      channelId,
+      cfg,
+      rest,
+      token,
+      hasMedia: Boolean(opts.mediaUrl),
+    });
+  }
+
+  registerBuiltDiscordComponentMessage({
+    buildResult,
+    messageId: result.id ?? messageId,
+  });
+
+  recordChannelActivity({
+    channel: "discord",
+    accountId: accountInfo.accountId,
+    direction: "outbound",
+  });
+
+  return createDiscordSendResult({
+    result: {
+      id: result.id ?? messageId,
+      channel_id: result.channel_id,
+    },
+    fallbackChannelId: channelId,
+    kind: "card",
+    ...(opts.replyTo ? { replyToId: opts.replyTo } : {}),
+  });
+}

package/src/send.emojis-stickers.ts

@@ -0,0 +1,57 @@
+import { normalizeOptionalLowercaseString } from "autobot/plugin-sdk/string-coerce-runtime";
+import { loadWebMediaRaw } from "autobot/plugin-sdk/web-media";
+import { createGuildEmoji, createGuildSticker, listGuildEmojis } from "./internal/discord.js";
+import { normalizeEmojiName, resolveDiscordRest } from "./send.shared.js";
+import type { DiscordEmojiUpload, DiscordReactOpts, DiscordStickerUpload } from "./send.types.js";
+import { DISCORD_MAX_EMOJI_BYTES, DISCORD_MAX_STICKER_BYTES } from "./send.types.js";
+
+export async function listGuildEmojisDiscord(guildId: string, opts: DiscordReactOpts) {
+  const rest = resolveDiscordRest(opts);
+  return await listGuildEmojis(rest, guildId);
+}
+
+export async function uploadEmojiDiscord(payload: DiscordEmojiUpload, opts: DiscordReactOpts) {
+  const rest = resolveDiscordRest(opts);
+  const media = await loadWebMediaRaw(payload.mediaUrl, DISCORD_MAX_EMOJI_BYTES);
+  const contentType = normalizeOptionalLowercaseString(media.contentType);
+  if (
+    !contentType ||
+    !["image/png", "image/jpeg", "image/jpg", "image/gif"].includes(contentType)
+  ) {
+    throw new Error("Discord emoji uploads require a PNG, JPG, or GIF image");
+  }
+  const image = `data:${contentType};base64,${media.buffer.toString("base64")}`;
+  const roleIds = (payload.roleIds ?? []).map((id) => id.trim()).filter(Boolean);
+  return await createGuildEmoji(rest, payload.guildId, {
+    body: {
+      name: normalizeEmojiName(payload.name, "Emoji name"),
+      image,
+      roles: roleIds.length ? roleIds : undefined,
+    },
+  });
+}
+
+export async function uploadStickerDiscord(payload: DiscordStickerUpload, opts: DiscordReactOpts) {
+  const rest = resolveDiscordRest(opts);
+  const media = await loadWebMediaRaw(payload.mediaUrl, DISCORD_MAX_STICKER_BYTES);
+  const contentType = normalizeOptionalLowercaseString(media.contentType);
+  if (!contentType || !["image/png", "image/apng", "application/json"].includes(contentType)) {
+    throw new Error("Discord sticker uploads require a PNG, APNG, or Lottie JSON file");
+  }
+  return await createGuildSticker(rest, payload.guildId, {
+    multipartStyle: "form",
+    body: {
+      name: normalizeEmojiName(payload.name, "Sticker name"),
+      description: normalizeEmojiName(payload.description, "Sticker description"),
+      tags: normalizeEmojiName(payload.tags, "Sticker tags"),
+      files: [
+        {
+          data: media.buffer,
+          fieldName: "file",
+          name: media.fileName ?? "sticker",
+          contentType,
+        },
+      ],
+    },
+  });
+}

package/src/send.guild.ts

@@ -0,0 +1,170 @@
+import type {
+  APIGuildMember,
+  APIGuildScheduledEvent,
+  APIRole,
+  APIVoiceState,
+  RESTPostAPIGuildScheduledEventJSONBody,
+} from "discord-api-types/v10";
+import { normalizeOptionalLowercaseString } from "autobot/plugin-sdk/string-coerce-runtime";
+import { loadWebMediaRaw } from "autobot/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