@gakr-gakr/discord 0.1.0

package/src/send.types.ts

@@ -0,0 +1,191 @@
+import type { MessageReceipt } from "autobot/plugin-sdk/channel-message";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import type { RetryConfig } from "autobot/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;
+  receipt: MessageReceipt;
+};
+
+export type DiscordRuntimeAccountContext = {
+  cfg: AutoBotConfig;
+  accountId: string;
+};
+
+export type DiscordReactOpts = {
+  cfg: AutoBotConfig;
+  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;
+  flags?: number;
+};
+
+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.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,140 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { recordChannelActivity } from "autobot/plugin-sdk/channel-activity-runtime";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import {
+  extensionForMime,
+  maxBytesForKind,
+  unlinkIfExists,
+} from "autobot/plugin-sdk/media-runtime";
+import { requireRuntimeConfig } from "autobot/plugin-sdk/plugin-config-runtime";
+import type { RetryConfig } from "autobot/plugin-sdk/retry-runtime";
+import { tempWorkspace, resolvePreferredAutoBotTmpDir } from "autobot/plugin-sdk/temp-path";
+import { loadWebMediaRaw } from "autobot/plugin-sdk/web-media";
+import { resolveDiscordAccount } from "./accounts.js";
+import type { RequestClient } from "./internal/discord.js";
+import { parseAndResolveRecipient } from "./recipient-resolution.js";
+import { createDiscordSendResult } from "./send.receipt.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: AutoBotConfig;
+  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 createDiscordSendResult({
+    result,
+    fallbackChannelId,
+    kind: "voice",
+  });
+}
+
+async function materializeVoiceMessageInput(
+  mediaUrl: string,
+): Promise<{ filePath: string; cleanup: () => Promise<void> }> {
+  // 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 workspace = await tempWorkspace({
+    rootDir: resolvePreferredAutoBotTmpDir(),
+    prefix: "voice-src-",
+  });
+  const filePath = await workspace.write(`input${ext}`, media.buffer);
+  return { filePath, cleanup: async () => await workspace.cleanup() };
+}
+
+/**
+ * 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, cleanup: cleanupLocalInput } =
+    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 cleanupLocalInput();
+  }
+}

package/src/send.webhook.ts

@@ -0,0 +1,137 @@
+import { recordChannelActivity } from "autobot/plugin-sdk/channel-activity-runtime";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { normalizeOptionalString } from "autobot/plugin-sdk/string-coerce-runtime";
+import { resolveDiscordClientAccountContext } from "./client.js";
+import {
+  DiscordError,
+  RateLimitError,
+  readDiscordCode,
+  readDiscordMessage,
+  readRetryAfter,
+} from "./internal/rest-errors.js";
+import { rewriteDiscordKnownMentions } from "./mentions.js";
+import { createDiscordSendResult } from "./send.receipt.js";
+import type { DiscordSendResult } from "./send.types.js";
+
+type DiscordWebhookSendOpts = {
+  cfg: AutoBotConfig;
+  webhookId: string;
+  webhookToken: string;
+  accountId?: string;
+  threadId?: string | number;
+  replyTo?: string;
+  username?: string;
+  avatarUrl?: string;
+  wait?: boolean;
+};
+
+function resolveWebhookExecutionUrl(params: {
+  webhookId: string;
+  webhookToken: string;
+  threadId?: string | number;
+  wait?: boolean;
+}) {
+  const baseUrl = new URL(
+    `https://discord.com/api/v10/webhooks/${encodeURIComponent(params.webhookId)}/${encodeURIComponent(params.webhookToken)}`,
+  );
+  baseUrl.searchParams.set("wait", params.wait === false ? "false" : "true");
+  if (params.threadId !== undefined && params.threadId !== null && params.threadId !== "") {
+    baseUrl.searchParams.set("thread_id", String(params.threadId));
+  }
+  return baseUrl.toString();
+}
+
+function coerceWebhookErrorBody(raw: string): unknown {
+  if (!raw) {
+    return undefined;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return { message: raw.slice(0, 200) };
+  }
+}
+
+async function throwWebhookResponseError(response: Response): Promise<never> {
+  const raw = await response.text().catch(() => "");
+  const parsed = coerceWebhookErrorBody(raw);
+  if (response.status === 429) {
+    throw new RateLimitError(response, {
+      message: readDiscordMessage(parsed, "Rate limited"),
+      retry_after: readRetryAfter(parsed, response, 1),
+      code: readDiscordCode(parsed),
+      global:
+        parsed && typeof parsed === "object" && "global" in parsed
+          ? Boolean((parsed as { global?: unknown }).global)
+          : false,
+    });
+  }
+  throw new DiscordError(response, parsed);
+}
+
+export async function sendWebhookMessageDiscord(
+  text: string,
+  opts: DiscordWebhookSendOpts,
+): Promise<DiscordSendResult> {
+  const webhookId = normalizeOptionalString(opts.webhookId) ?? "";
+  const webhookToken = normalizeOptionalString(opts.webhookToken) ?? "";
+  if (!webhookId || !webhookToken) {
+    throw new Error("Discord webhook id/token are required");
+  }
+
+  const replyTo = normalizeOptionalString(opts.replyTo) ?? "";
+  const messageReference = replyTo ? { message_id: replyTo, fail_if_not_exists: false } : undefined;
+  const { account, proxyFetch } = resolveDiscordClientAccountContext({
+    cfg: opts.cfg,
+    accountId: opts.accountId,
+  });
+  const rewrittenText = rewriteDiscordKnownMentions(text, {
+    accountId: account.accountId,
+    mentionAliases: account.config.mentionAliases,
+  });
+
+  const response = await (proxyFetch ?? fetch)(
+    resolveWebhookExecutionUrl({
+      webhookId,
+      webhookToken,
+      threadId: opts.threadId,
+      wait: opts.wait,
+    }),
+    {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        content: rewrittenText,
+        username: normalizeOptionalString(opts.username),
+        avatar_url: normalizeOptionalString(opts.avatarUrl),
+        ...(messageReference ? { message_reference: messageReference } : {}),
+      }),
+    },
+  );
+  if (!response.ok) {
+    await throwWebhookResponseError(response);
+  }
+
+  const payload = (await response.json().catch(() => ({}))) as {
+    id?: string;
+    channel_id?: string;
+  };
+  try {
+    recordChannelActivity({
+      channel: "discord",
+      accountId: account.accountId,
+      direction: "outbound",
+    });
+  } catch {
+    // Best-effort telemetry only.
+  }
+  return createDiscordSendResult({
+    result: payload,
+    fallbackChannelId: opts.threadId ? String(opts.threadId) : "",
+    kind: "text",
+    ...(opts.threadId != null ? { threadId: opts.threadId } : {}),
+    ...(replyTo ? { replyToId: replyTo } : {}),
+  });
+}

package/src/session-contract.ts

@@ -0,0 +1,3 @@
+export function deriveLegacySessionChatType(sessionKey: string): "channel" | undefined {
+  return /^discord:(?:[^:]+:)?guild-[^:]+:channel-[^:]+$/.test(sessionKey) ? "channel" : undefined;
+}

package/src/session-key-normalization.ts

@@ -0,0 +1,47 @@
+import { normalizeLowercaseStringOrEmpty } from "autobot/plugin-sdk/string-coerce-runtime";
+
+type DiscordSessionKeyContext = {
+  ChatType?: string;
+  From?: string;
+  SenderId?: string;
+};
+
+function normalizeDiscordChatType(raw?: string): "direct" | "group" | "channel" | undefined {
+  const normalized = normalizeLowercaseStringOrEmpty(raw);
+  if (!normalized) {
+    return undefined;
+  }
+  if (normalized === "dm") {
+    return "direct";
+  }
+  if (normalized === "group" || normalized === "channel" || normalized === "direct") {
+    return normalized;
+  }
+  return undefined;
+}
+
+export function normalizeExplicitDiscordSessionKey(
+  sessionKey: string,
+  ctx: DiscordSessionKeyContext,
+): string {
+  let normalized = normalizeLowercaseStringOrEmpty(sessionKey);
+  if (normalizeDiscordChatType(ctx.ChatType) !== "direct") {
+    return normalized;
+  }
+
+  normalized = normalized.replace(/^(discord:)dm:/, "$1direct:");
+  normalized = normalized.replace(/^(agent:[^:]+:discord:)dm:/, "$1direct:");
+  const match = normalized.match(/^((?:agent:[^:]+:)?)discord:channel:([^:]+)$/);
+  if (!match) {
+    return normalized;
+  }
+
+  const from = normalizeLowercaseStringOrEmpty(ctx.From);
+  const senderId = normalizeLowercaseStringOrEmpty(ctx.SenderId);
+  const fromDiscordId =
+    from.startsWith("discord:") && !from.includes(":channel:") && !from.includes(":group:")
+      ? from.slice("discord:".length)
+      : "";
+  const directId = senderId || fromDiscordId;
+  return directId && directId === match[2] ? `${match[1]}discord:direct:${match[2]}` : normalized;
+}

package/src/setup-account-state.ts

@@ -0,0 +1,144 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "autobot/plugin-sdk/account-id";
+import { listCombinedAccountIds } from "autobot/plugin-sdk/account-resolution";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import {
+  hasConfiguredSecretInput,
+  normalizeSecretInputString,
+} from "autobot/plugin-sdk/secret-input";
+import { resolveDefaultDiscordAccountId } from "./accounts.js";
+import { mergeDiscordAccountConfig, resolveDiscordAccountConfig } from "./accounts.js";
+import type { DiscordAccountConfig } from "./runtime-api.js";
+import { resolveDiscordToken } from "./token.js";
+
+type InspectedDiscordSetupAccount = {
+  accountId: string;
+  enabled: boolean;
+  token: string;
+  tokenSource: "env" | "config" | "none";
+  tokenStatus: "available" | "configured_unavailable" | "missing";
+  configured: boolean;
+  config: DiscordAccountConfig;
+};
+
+function inspectConfiguredToken(value: unknown): {
+  token: string;
+  tokenSource: "config";
+  tokenStatus: "available" | "configured_unavailable";
+} | null {
+  const normalized = normalizeSecretInputString(value);
+  if (normalized) {
+    return {
+      token: normalized.replace(/^Bot\s+/i, ""),
+      tokenSource: "config",
+      tokenStatus: "available",
+    };
+  }
+  if (hasConfiguredSecretInput(value)) {
+    return {
+      token: "",
+      tokenSource: "config",
+      tokenStatus: "configured_unavailable",
+    };
+  }
+  return null;
+}
+
+export function listDiscordSetupAccountIds(cfg: AutoBotConfig): string[] {
+  const accounts = cfg.channels?.discord?.accounts;
+  return listCombinedAccountIds({
+    configuredAccountIds:
+      accounts && typeof accounts === "object" && !Array.isArray(accounts)
+        ? Object.keys(accounts).map((accountId) => normalizeAccountId(accountId))
+        : [],
+    implicitAccountId: DEFAULT_ACCOUNT_ID,
+  });
+}
+
+export function resolveDefaultDiscordSetupAccountId(cfg: AutoBotConfig): string {
+  return resolveDefaultDiscordAccountId(cfg);
+}
+
+export function resolveDiscordSetupAccountConfig(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+}): { accountId: string; config: DiscordAccountConfig } {
+  const accountId = normalizeAccountId(
+    params.accountId ?? resolveDefaultDiscordSetupAccountId(params.cfg),
+  );
+  return {
+    accountId,
+    config: mergeDiscordAccountConfig(params.cfg, accountId),
+  };
+}
+
+export function inspectDiscordSetupAccount(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+}): InspectedDiscordSetupAccount {
+  const { accountId, config } = resolveDiscordSetupAccountConfig(params);
+  const enabled = params.cfg.channels?.discord?.enabled !== false && config.enabled !== false;
+  const accountConfig = resolveDiscordAccountConfig(params.cfg, accountId);
+  const hasAccountToken = Boolean(
+    accountConfig &&
+    Object.prototype.hasOwnProperty.call(accountConfig as Record<string, unknown>, "token"),
+  );
+  const accountToken = inspectConfiguredToken(accountConfig?.token);
+  if (accountToken) {
+    return {
+      accountId,
+      enabled,
+      token: accountToken.token,
+      tokenSource: accountToken.tokenSource,
+      tokenStatus: accountToken.tokenStatus,
+      configured: true,
+      config,
+    };
+  }
+  if (hasAccountToken) {
+    return {
+      accountId,
+      enabled,
+      token: "",
+      tokenSource: "none",
+      tokenStatus: "missing",
+      configured: false,
+      config,
+    };
+  }
+
+  const channelToken = inspectConfiguredToken(params.cfg.channels?.discord?.token);
+  if (channelToken) {
+    return {
+      accountId,
+      enabled,
+      token: channelToken.token,
+      tokenSource: channelToken.tokenSource,
+      tokenStatus: channelToken.tokenStatus,
+      configured: true,
+      config,
+    };
+  }
+
+  const tokenResolution = resolveDiscordToken(params.cfg, { accountId });
+  if (tokenResolution.token) {
+    return {
+      accountId,
+      enabled,
+      token: tokenResolution.token,
+      tokenSource: tokenResolution.source,
+      tokenStatus: "available",
+      configured: true,
+      config,
+    };
+  }
+
+  return {
+    accountId,
+    enabled,
+    token: "",
+    tokenSource: "none",
+    tokenStatus: "missing",
+    configured: false,
+    config,
+  };
+}

package/src/setup-adapter.ts

@@ -0,0 +1,14 @@
+import {
+  createEnvPatchedAccountSetupAdapter,
+  type ChannelSetupAdapter,
+} from "autobot/plugin-sdk/setup-runtime";
+
+const channel = "discord" as const;
+
+export const discordSetupAdapter: ChannelSetupAdapter = createEnvPatchedAccountSetupAdapter({
+  channelKey: channel,
+  defaultAccountOnlyEnvError: "DISCORD_BOT_TOKEN can only be used for the default account.",
+  missingCredentialError: "Discord requires token (or --use-env).",
+  hasCredentials: (input) => Boolean(input.token),
+  buildPatch: (input) => (input.token ? { token: input.token } : {}),
+});