@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/send.shared.ts

@@ -0,0 +1,469 @@
+import { PollLayoutType } from "discord-api-types/payloads/v10";
+import type { RESTAPIPoll } from "discord-api-types/rest/v10";
+import type { APIChannel } from "discord-api-types/v10";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { buildOutboundMediaLoadOptions } from "klaw/plugin-sdk/media-runtime";
+import { extensionForMime } from "klaw/plugin-sdk/media-runtime";
+import {
+  normalizePollDurationHours,
+  normalizePollInput,
+  type OutboundMediaAccess,
+  type PollInput,
+} from "klaw/plugin-sdk/media-runtime";
+import { requireRuntimeConfig } from "klaw/plugin-sdk/plugin-config-runtime";
+import type { ChunkMode } from "klaw/plugin-sdk/reply-chunking";
+import { resolveTextChunksWithFallback } from "klaw/plugin-sdk/reply-payload";
+import type { RetryRunner } from "klaw/plugin-sdk/retry-runtime";
+import { loadWebMedia } from "klaw/plugin-sdk/web-media";
+import { chunkDiscordTextWithMode } from "./chunk.js";
+import { createDiscordClient, resolveDiscordRest, type DiscordClientOpts } from "./client.js";
+import {
+  createChannelMessage,
+  createUserDmChannel,
+  getChannel,
+  RequestClient,
+} from "./internal/discord.js";
+import { parseAndResolveRecipient } from "./recipient-resolution.js";
+import { fetchChannelPermissionsDiscord, isThreadChannelType } from "./send.permissions.js";
+import { DiscordSendError } from "./send.types.js";
+
+const DISCORD_TEXT_LIMIT = 2000;
+const DISCORD_MAX_STICKERS = 3;
+const DISCORD_POLL_MAX_ANSWERS = 10;
+const DISCORD_POLL_MAX_DURATION_HOURS = 32 * 24;
+const DISCORD_MISSING_PERMISSIONS = 50013;
+const DISCORD_CANNOT_DM = 50007;
+
+type DiscordRequest = RetryRunner;
+
+export {
+  buildDiscordMessagePayload,
+  buildDiscordMessageRequest,
+  resolveDiscordMessageFlags,
+  resolveDiscordSendComponents,
+  resolveDiscordSendEmbeds,
+  stripUndefinedFields,
+  SUPPRESS_EMBEDS_FLAG,
+  SUPPRESS_NOTIFICATIONS_FLAG,
+  type DiscordSendComponentFactory,
+  type DiscordSendComponents,
+  type DiscordSendEmbeds,
+} from "./send.message-request.js";
+import {
+  buildDiscordMessageRequest,
+  resolveDiscordMessageFlags,
+  resolveDiscordSendComponents,
+  resolveDiscordSendEmbeds,
+  type DiscordSendComponents,
+  type DiscordSendEmbeds,
+} from "./send.message-request.js";
+type DiscordRecipient =
+  | {
+      kind: "user";
+      id: string;
+    }
+  | {
+      kind: "channel";
+      id: string;
+    };
+
+function normalizeReactionEmoji(raw: string) {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    throw new Error("emoji required");
+  }
+  const customMatch = trimmed.match(/^<a?:([^:>]+):(\d+)>$/);
+  const identifier = customMatch
+    ? `${customMatch[1]}:${customMatch[2]}`
+    : trimmed.replace(/[\uFE0E\uFE0F]/g, "");
+  return encodeURIComponent(identifier);
+}
+
+function normalizeStickerIds(raw: string[]) {
+  const ids = raw.map((entry) => entry.trim()).filter(Boolean);
+  if (ids.length === 0) {
+    throw new Error("At least one sticker id is required");
+  }
+  if (ids.length > DISCORD_MAX_STICKERS) {
+    throw new Error("Discord supports up to 3 stickers per message");
+  }
+  return ids;
+}
+
+function normalizeEmojiName(raw: string, label: string) {
+  const name = raw.trim();
+  if (!name) {
+    throw new Error(`${label} is required`);
+  }
+  return name;
+}
+
+function normalizeDiscordPollInput(input: PollInput): RESTAPIPoll {
+  const poll = normalizePollInput(input, {
+    maxOptions: DISCORD_POLL_MAX_ANSWERS,
+  });
+  const duration = normalizePollDurationHours(poll.durationHours, {
+    defaultHours: 24,
+    maxHours: DISCORD_POLL_MAX_DURATION_HOURS,
+  });
+  return {
+    question: { text: poll.question },
+    answers: poll.options.map((answer) => ({ poll_media: { text: answer } })),
+    duration,
+    allow_multiselect: poll.maxSelections > 1,
+    layout_type: PollLayoutType.Default,
+  };
+}
+
+function getDiscordErrorCode(err: unknown) {
+  if (!err || typeof err !== "object") {
+    return undefined;
+  }
+  const candidate =
+    "code" in err && err.code !== undefined
+      ? err.code
+      : "rawError" in err && err.rawError && typeof err.rawError === "object"
+        ? (err.rawError as { code?: unknown }).code
+        : undefined;
+  if (typeof candidate === "number") {
+    return candidate;
+  }
+  if (typeof candidate === "string" && /^\d+$/.test(candidate)) {
+    return Number(candidate);
+  }
+  return undefined;
+}
+
+function getDiscordErrorStatus(err: unknown) {
+  if (!err || typeof err !== "object") {
+    return undefined;
+  }
+  const candidate =
+    "status" in err && err.status !== undefined
+      ? err.status
+      : "statusCode" in err && err.statusCode !== undefined
+        ? err.statusCode
+        : undefined;
+  if (typeof candidate === "number" && Number.isFinite(candidate)) {
+    return candidate;
+  }
+  if (typeof candidate === "string" && /^\d+$/.test(candidate)) {
+    return Number(candidate);
+  }
+  return undefined;
+}
+
+async function buildDiscordSendError(
+  err: unknown,
+  ctx: {
+    channelId: string;
+    cfg: KlawConfig;
+    rest: RequestClient;
+    token: string;
+    hasMedia: boolean;
+  },
+) {
+  if (err instanceof DiscordSendError) {
+    return err;
+  }
+  const code = getDiscordErrorCode(err);
+  if (code === DISCORD_CANNOT_DM) {
+    return new DiscordSendError(
+      `discord dm failed: user blocks dms or privacy settings disallow it (code=${code})`,
+      { kind: "dm-blocked", discordCode: code, status: getDiscordErrorStatus(err) },
+    );
+  }
+  if (code !== DISCORD_MISSING_PERMISSIONS) {
+    return err;
+  }
+
+  let missing: string[] = [];
+  let probedChannelType: number | undefined;
+  try {
+    const permissions = await fetchChannelPermissionsDiscord(ctx.channelId, {
+      rest: ctx.rest,
+      token: ctx.token,
+      cfg: ctx.cfg,
+    });
+    probedChannelType = permissions.channelType;
+    const current = new Set(permissions.permissions);
+    const required = ["ViewChannel", "SendMessages"];
+    if (isThreadChannelType(probedChannelType)) {
+      required.push("SendMessagesInThreads");
+    }
+    if (ctx.hasMedia) {
+      required.push("AttachFiles");
+    }
+    missing = required.filter((permission) => !current.has(permission));
+  } catch {
+    /* ignore permission probe errors */
+  }
+
+  const status = getDiscordErrorStatus(err);
+  const apiDetails = [`code=${code}`, status != null ? `status=${status}` : undefined]
+    .filter(Boolean)
+    .join(" ");
+  const probedPermissions = ["ViewChannel", "SendMessages"];
+  if (isThreadChannelType(probedChannelType)) {
+    probedPermissions.push("SendMessagesInThreads");
+  }
+  if (ctx.hasMedia) {
+    probedPermissions.push("AttachFiles");
+  }
+  const probeSummary = probedPermissions.join("/");
+  const missingLabel = missing.length
+    ? `discord missing permissions in channel ${ctx.channelId}: ${missing.join(", ")}`
+    : `discord missing permissions in channel ${ctx.channelId}; permission probe did not identify missing ${probeSummary}`;
+  return new DiscordSendError(
+    `${missingLabel} (${apiDetails}). bot might be blocked by channel/thread overrides, archived thread state, reply target visibility, or app-role position`,
+    {
+      kind: "missing-permissions",
+      channelId: ctx.channelId,
+      missingPermissions: missing,
+      discordCode: code,
+      status,
+    },
+  );
+}
+
+async function resolveChannelId(
+  rest: RequestClient,
+  recipient: DiscordRecipient,
+  request: DiscordRequest,
+): Promise<{ channelId: string; dm?: boolean }> {
+  if (recipient.kind === "channel") {
+    return { channelId: recipient.id };
+  }
+  const dmChannel = (await request(
+    () => createUserDmChannel(rest, recipient.id),
+    "dm-channel",
+  )) as { id: string };
+  if (!dmChannel?.id) {
+    throw new Error("Failed to create Discord DM channel");
+  }
+  return { channelId: dmChannel.id, dm: true };
+}
+
+async function resolveDiscordTargetChannelId(
+  raw: string,
+  opts: DiscordClientOpts & { cfg: KlawConfig },
+): Promise<{ channelId: string; dm?: boolean }> {
+  const cfg = requireRuntimeConfig(opts.cfg, "Discord target channel resolution");
+  const recipient = await parseAndResolveRecipient(raw, cfg, opts.accountId, {
+    defaultKind: "channel",
+  });
+  const { rest, request } = createDiscordClient(opts);
+  return await resolveChannelId(rest, recipient, request);
+}
+
+export async function resolveDiscordChannelType(
+  rest: RequestClient,
+  channelId: string,
+): Promise<number | undefined> {
+  try {
+    const channel = (await getChannel(rest, channelId)) as APIChannel | undefined;
+    return channel?.type;
+  } catch {
+    return undefined;
+  }
+}
+
+export function buildDiscordTextChunks(
+  text: string,
+  opts: { maxLinesPerMessage?: number; chunkMode?: ChunkMode; maxChars?: number } = {},
+): string[] {
+  if (!text) {
+    return [];
+  }
+  const chunks = chunkDiscordTextWithMode(text, {
+    maxChars: opts.maxChars ?? DISCORD_TEXT_LIMIT,
+    maxLines: opts.maxLinesPerMessage,
+    chunkMode: opts.chunkMode,
+  });
+  return resolveTextChunksWithFallback(text, chunks);
+}
+
+export function toDiscordFileBlob(data: Blob | Uint8Array): Blob {
+  if (data instanceof Blob) {
+    return data;
+  }
+  const arrayBuffer = new ArrayBuffer(data.byteLength);
+  new Uint8Array(arrayBuffer).set(data);
+  return new Blob([arrayBuffer]);
+}
+
+async function sendDiscordText(
+  rest: RequestClient,
+  channelId: string,
+  text: string,
+  replyTo: string | undefined,
+  request: DiscordRequest,
+  maxLinesPerMessage?: number,
+  components?: DiscordSendComponents,
+  embeds?: DiscordSendEmbeds,
+  chunkMode?: ChunkMode,
+  silent?: boolean,
+  suppressEmbeds?: boolean,
+  maxChars?: number,
+) {
+  if (!text.trim()) {
+    throw new Error("Message must be non-empty for Discord sends");
+  }
+  const chunks = buildDiscordTextChunks(text, { maxLinesPerMessage, chunkMode, maxChars });
+  const sendChunk = async (chunk: string, isFirst: boolean) => {
+    const chunkComponents = resolveDiscordSendComponents({
+      components,
+      text: chunk,
+      isFirst,
+    });
+    const chunkEmbeds = resolveDiscordSendEmbeds({ embeds, isFirst });
+    const flags = resolveDiscordMessageFlags({
+      silent,
+      suppressEmbeds: suppressEmbeds && !chunkEmbeds?.length,
+    });
+    const body = buildDiscordMessageRequest({
+      text: chunk,
+      components: chunkComponents,
+      embeds: chunkEmbeds,
+      flags,
+      replyTo,
+    });
+    return (await request(
+      () => createChannelMessage<{ id: string; channel_id: string }>(rest, channelId, { body }),
+      "text",
+    )) as { id: string; channel_id: string };
+  };
+  if (chunks.length === 1) {
+    const result = await sendChunk(chunks[0], true);
+    return { ...result, platformMessageIds: result.id ? [result.id] : [] };
+  }
+  const platformMessageIds: string[] = [];
+  let last: { id: string; channel_id: string } | null = null;
+  for (const [index, chunk] of chunks.entries()) {
+    last = await sendChunk(chunk, index === 0);
+    if (last.id) {
+      platformMessageIds.push(last.id);
+    }
+  }
+  if (!last) {
+    throw new Error("Discord send failed (empty chunk result)");
+  }
+  return { ...last, platformMessageIds };
+}
+
+async function sendDiscordMedia(
+  rest: RequestClient,
+  channelId: string,
+  text: string,
+  mediaUrl: string,
+  filename: string | undefined,
+  mediaAccess: OutboundMediaAccess | undefined,
+  mediaLocalRoots: readonly string[] | undefined,
+  mediaReadFile: ((filePath: string) => Promise<Buffer>) | undefined,
+  maxBytes: number | undefined,
+  replyTo: string | undefined,
+  request: DiscordRequest,
+  maxLinesPerMessage?: number,
+  components?: DiscordSendComponents,
+  embeds?: DiscordSendEmbeds,
+  chunkMode?: ChunkMode,
+  silent?: boolean,
+  suppressEmbeds?: boolean,
+  maxChars?: number,
+) {
+  const media = await loadWebMedia(
+    mediaUrl,
+    buildOutboundMediaLoadOptions({ maxBytes, mediaAccess, mediaLocalRoots, mediaReadFile }),
+  );
+  const requestedFileName = filename?.trim();
+  const resolvedFileName =
+    requestedFileName ||
+    media.fileName ||
+    (media.contentType ? `upload${extensionForMime(media.contentType) ?? ""}` : "") ||
+    "upload";
+  const chunks = text
+    ? buildDiscordTextChunks(text, { maxLinesPerMessage, chunkMode, maxChars })
+    : [];
+  const caption = chunks[0] ?? "";
+  const fileData = toDiscordFileBlob(media.buffer);
+  const captionComponents = resolveDiscordSendComponents({
+    components,
+    text: caption,
+    isFirst: true,
+  });
+  const captionEmbeds = resolveDiscordSendEmbeds({ embeds, isFirst: true });
+  const flags = resolveDiscordMessageFlags({
+    silent,
+    suppressEmbeds: suppressEmbeds && !captionEmbeds?.length,
+  });
+  const body = buildDiscordMessageRequest({
+    text: caption,
+    components: captionComponents,
+    embeds: captionEmbeds,
+    flags,
+    replyTo,
+    files: [
+      {
+        data: fileData,
+        name: resolvedFileName,
+      },
+    ],
+  });
+  const res = (await request(
+    () => createChannelMessage<{ id: string; channel_id: string }>(rest, channelId, { body }),
+    "media",
+  )) as { id: string; channel_id: string };
+  const platformMessageIds = res.id ? [res.id] : [];
+  for (const chunk of chunks.slice(1)) {
+    if (!chunk.trim()) {
+      continue;
+    }
+    const followup = await sendDiscordText(
+      rest,
+      channelId,
+      chunk,
+      replyTo,
+      request,
+      maxLinesPerMessage,
+      undefined,
+      undefined,
+      chunkMode,
+      silent,
+      suppressEmbeds,
+      maxChars,
+    );
+    for (const id of followup.platformMessageIds) {
+      if (id) {
+        platformMessageIds.push(id);
+      }
+    }
+  }
+  return { ...res, platformMessageIds };
+}
+
+function buildReactionIdentifier(emoji: { id?: string | null; name?: string | null }) {
+  if (emoji.id && emoji.name) {
+    return `${emoji.name}:${emoji.id}`;
+  }
+  return emoji.name ?? "";
+}
+
+function formatReactionEmoji(emoji: { id?: string | null; name?: string | null }) {
+  return buildReactionIdentifier(emoji);
+}
+
+export {
+  buildDiscordSendError,
+  buildReactionIdentifier,
+  createDiscordClient,
+  formatReactionEmoji,
+  normalizeDiscordPollInput,
+  normalizeEmojiName,
+  normalizeReactionEmoji,
+  normalizeStickerIds,
+  resolveChannelId,
+  resolveDiscordTargetChannelId,
+  resolveDiscordRest,
+  sendDiscordMedia,
+  sendDiscordText,
+};

package/src/send.test-harness.ts

@@ -0,0 +1,56 @@
+import type { MockFn } from "klaw/plugin-sdk/plugin-test-runtime";
+import { vi } from "vitest";
+
+type DiscordWebMediaMockFactoryResult = {
+  loadWebMedia: MockFn;
+  loadWebMediaRaw: MockFn;
+};
+
+type DiscordRestFactoryResult = {
+  rest: import("./internal/discord.js").RequestClient;
+  postMock: MockFn;
+  putMock: MockFn;
+  getMock: MockFn;
+  patchMock: MockFn;
+  deleteMock: MockFn;
+};
+
+export function discordWebMediaMockFactory(): DiscordWebMediaMockFactoryResult {
+  return {
+    loadWebMedia: vi.fn().mockResolvedValue({
+      buffer: Buffer.from("img"),
+      fileName: "photo.jpg",
+      contentType: "image/jpeg",
+      kind: "image",
+    }),
+    loadWebMediaRaw: vi.fn().mockResolvedValue({
+      buffer: Buffer.from("img"),
+      fileName: "asset.png",
+      contentType: "image/png",
+      kind: "image",
+    }),
+  };
+}
+
+export function makeDiscordRest(): DiscordRestFactoryResult {
+  const postMock = vi.fn() as unknown as MockFn;
+  const putMock = vi.fn() as unknown as MockFn;
+  const getMock = vi.fn() as unknown as MockFn;
+  const patchMock = vi.fn() as unknown as MockFn;
+  const deleteMock = vi.fn() as unknown as MockFn;
+
+  return {
+    rest: {
+      post: postMock,
+      put: putMock,
+      get: getMock,
+      patch: patchMock,
+      delete: deleteMock,
+    } as unknown as import("./internal/discord.js").RequestClient,
+    postMock,
+    putMock,
+    getMock,
+    patchMock,
+    deleteMock,
+  };
+}

package/src/send.ts

@@ -0,0 +1,82 @@
+export {
+  createChannelDiscord,
+  deleteChannelDiscord,
+  editChannelDiscord,
+  moveChannelDiscord,
+  removeChannelPermissionDiscord,
+  setChannelPermissionDiscord,
+} from "./send.channels.js";
+export {
+  listGuildEmojisDiscord,
+  uploadEmojiDiscord,
+  uploadStickerDiscord,
+} from "./send.emojis-stickers.js";
+export {
+  addRoleDiscord,
+  banMemberDiscord,
+  createScheduledEventDiscord,
+  resolveEventCoverImage,
+  fetchChannelInfoDiscord,
+  fetchMemberInfoDiscord,
+  fetchRoleInfoDiscord,
+  fetchVoiceStatusDiscord,
+  kickMemberDiscord,
+  listGuildChannelsDiscord,
+  listScheduledEventsDiscord,
+  removeRoleDiscord,
+  timeoutMemberDiscord,
+} from "./send.guild.js";
+export {
+  createThreadDiscord,
+  deleteMessageDiscord,
+  DiscordThreadInitialMessageError,
+  editMessageDiscord,
+  fetchMessageDiscord,
+  listPinsDiscord,
+  listThreadsDiscord,
+  pinMessageDiscord,
+  readMessagesDiscord,
+  searchMessagesDiscord,
+  unpinMessageDiscord,
+} from "./send.messages.js";
+export { sendMessageDiscord, sendPollDiscord, sendStickerDiscord } from "./send.outbound.js";
+export { sendWebhookMessageDiscord } from "./send.webhook.js";
+export { sendVoiceMessageDiscord } from "./send.voice.js";
+export { sendTypingDiscord } from "./send.typing.js";
+export {
+  canViewDiscordGuildChannel,
+  fetchChannelPermissionsDiscord,
+  hasAllGuildPermissionsDiscord,
+  hasAnyGuildPermissionDiscord,
+  fetchMemberGuildPermissionsDiscord,
+} from "./send.permissions.js";
+export {
+  fetchReactionsDiscord,
+  reactMessageDiscord,
+  removeOwnReactionsDiscord,
+  removeReactionDiscord,
+} from "./send.reactions.js";
+export type {
+  DiscordChannelCreate,
+  DiscordChannelEdit,
+  DiscordChannelMove,
+  DiscordChannelPermissionSet,
+  DiscordEmojiUpload,
+  DiscordMessageEdit,
+  DiscordMessageQuery,
+  DiscordModerationTarget,
+  DiscordReactionRuntimeContext,
+  DiscordPermissionsSummary,
+  DiscordReactionSummary,
+  DiscordReactionUser,
+  DiscordReactOpts,
+  DiscordRuntimeAccountContext,
+  DiscordRoleChange,
+  DiscordSearchQuery,
+  DiscordSendResult,
+  DiscordStickerUpload,
+  DiscordThreadCreate,
+  DiscordThreadList,
+  DiscordTimeoutTarget,
+} from "./send.types.js";
+export { DiscordSendError } from "./send.types.js";