@gakr-gakr/discord 0.1.0

package/src/internal/test-builders.test-support.ts

@@ -0,0 +1,167 @@
+import { ComponentType, InteractionType } from "discord-api-types/v10";
+import { vi, type Mock } from "vitest";
+import { Client, type ClientOptions } from "./client.js";
+import type { BaseCommand } from "./commands.js";
+import type { RawInteraction } from "./interactions.js";
+import type { QueuedRequest, RequestClient, RequestData } from "./rest.js";
+
+type RestMock = Partial<Record<"get" | "post" | "patch" | "put" | "delete", Mock>>;
+type RestMethod = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+type RawInteractionOverrides = Omit<Partial<RawInteraction>, "data" | "type"> &
+  Pick<RawInteraction, "id" | "token"> & {
+    data?: Record<string, unknown>;
+  };
+
+type FakeRestCall = {
+  method: RestMethod;
+  path: string;
+  data?: RequestData;
+  query?: QueuedRequest["query"];
+};
+
+type FakeRestClient = RequestClient & {
+  calls: FakeRestCall[];
+  enqueueResponse: (value: unknown) => void;
+};
+
+export function createDeferred<T>() {
+  let resolve: ((value: T) => void) | undefined;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve: resolve! };
+}
+
+export function createJsonResponse(body: unknown, init?: ResponseInit): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    ...init,
+  });
+}
+
+export function createAbortableFetchMock() {
+  let receivedSignal: AbortSignal | undefined;
+  const fetch = vi.fn(
+    (_input: string | URL | Request, init?: RequestInit) =>
+      new Promise<Response>((_resolve, reject) => {
+        receivedSignal = init?.signal ?? undefined;
+        init?.signal?.addEventListener("abort", () => {
+          reject(new DOMException("The operation was aborted.", "AbortError"));
+        });
+      }),
+  );
+  return {
+    fetch,
+    get receivedSignal() {
+      return receivedSignal;
+    },
+  };
+}
+
+export function createInternalTestClient(
+  commands: BaseCommand[] = [],
+  options?: Partial<ClientOptions>,
+): Client {
+  return new Client(
+    {
+      baseUrl: "http://localhost",
+      clientId: "app1",
+      publicKey: "public",
+      token: "token",
+      ...options,
+    },
+    { commands },
+  );
+}
+
+function createRestMock(overrides: RestMock = {}): RestMock & RequestClient {
+  return {
+    get: vi.fn(async () => undefined),
+    post: vi.fn(async () => undefined),
+    patch: vi.fn(async () => undefined),
+    put: vi.fn(async () => undefined),
+    delete: vi.fn(async () => undefined),
+    ...overrides,
+  } as RestMock & RequestClient;
+}
+
+export function attachRestMock(client: Client, rest: RestMock): RestMock & RequestClient {
+  const mock = createRestMock(rest);
+  client.rest = mock;
+  return mock;
+}
+
+export function createFakeRestClient(responses: unknown[] = []): FakeRestClient {
+  const calls: FakeRestCall[] = [];
+  const queued = [...responses];
+  const request = async (
+    method: RestMethod,
+    path: string,
+    data?: RequestData,
+    query?: QueuedRequest["query"],
+  ) => {
+    calls.push({ method, path, data, query });
+    return queued.shift();
+  };
+  return {
+    calls,
+    enqueueResponse: (value: unknown) => {
+      queued.push(value);
+    },
+    get: async (path, query) => await request("GET", path, undefined, query),
+    post: async (path, data, query) => await request("POST", path, data, query),
+    patch: async (path, data, query) => await request("PATCH", path, data, query),
+    put: async (path, data, query) => await request("PUT", path, data, query),
+    delete: async (path, data, query) => await request("DELETE", path, data, query),
+  } as FakeRestClient;
+}
+
+export function createInternalInteractionPayload(
+  overrides: Partial<RawInteraction> & Pick<RawInteraction, "id" | "token">,
+): RawInteraction {
+  return {
+    application_id: "app1",
+    type: InteractionType.ApplicationCommand,
+    version: 1,
+    data: {
+      id: "command1",
+      name: "test",
+      type: 1,
+    },
+    ...overrides,
+  } as unknown as RawInteraction;
+}
+
+export function createInternalComponentInteractionPayload(
+  overrides: RawInteractionOverrides,
+): RawInteraction {
+  const { data, ...rest } = overrides;
+  return {
+    application_id: "app1",
+    version: 1,
+    data: {
+      component_type: ComponentType.Button,
+      custom_id: "component1",
+      ...data,
+    },
+    ...rest,
+    type: InteractionType.MessageComponent,
+  } as unknown as RawInteraction;
+}
+
+export function createInternalModalInteractionPayload(
+  overrides: RawInteractionOverrides,
+): RawInteraction {
+  const { data, ...rest } = overrides;
+  return {
+    application_id: "app1",
+    version: 1,
+    data: {
+      custom_id: "modal1",
+      components: [],
+      ...data,
+    },
+    ...rest,
+    type: InteractionType.ModalSubmit,
+  } as unknown as RawInteraction;
+}

package/src/internal/voice.ts

@@ -0,0 +1,49 @@
+import type {
+  DiscordGatewayAdapterCreator,
+  DiscordGatewayAdapterLibraryMethods,
+} from "@discordjs/voice";
+import type { GatewaySendPayload } from "discord-api-types/v10";
+import { Plugin, type Client } from "./client.js";
+import type { GatewayPlugin } from "./gateway.js";
+
+export class VoicePlugin extends Plugin {
+  readonly id = "voice";
+  protected client?: Client;
+  readonly adapters = new Map<string, DiscordGatewayAdapterLibraryMethods>();
+  private gatewayPlugin?: GatewayPlugin;
+
+  override registerClient(client: Client): void {
+    this.client = client;
+    this.gatewayPlugin = client.getPlugin<GatewayPlugin>("gateway");
+    if (!this.gatewayPlugin) {
+      throw new Error("Discord voice cannot be used without a gateway connection.");
+    }
+  }
+
+  getGateway(_guildId: string): GatewayPlugin | undefined {
+    return this.gatewayPlugin;
+  }
+
+  getGatewayAdapterCreator(guildId: string): DiscordGatewayAdapterCreator {
+    const gateway = this.getGateway(guildId);
+    if (!gateway) {
+      throw new Error("Discord voice cannot be used without a gateway connection.");
+    }
+    return (methods) => {
+      this.adapters.set(guildId, methods);
+      return {
+        sendPayload(payload) {
+          try {
+            gateway.send(payload as GatewaySendPayload, true);
+            return true;
+          } catch {
+            return false;
+          }
+        },
+        destroy: () => {
+          this.adapters.delete(guildId);
+        },
+      };
+    };
+  }
+}

package/src/media-detection.ts

@@ -0,0 +1,28 @@
+import { normalizeLowercaseStringOrEmpty } from "autobot/plugin-sdk/string-coerce-runtime";
+
+const DISCORD_VIDEO_MEDIA_EXTENSIONS = new Set([".avi", ".m4v", ".mkv", ".mov", ".mp4", ".webm"]);
+
+function normalizeMediaPathForExtension(mediaUrl: string): string {
+  const trimmed = mediaUrl.trim();
+  if (!trimmed) {
+    return "";
+  }
+  try {
+    const parsed = new URL(trimmed);
+    return normalizeLowercaseStringOrEmpty(parsed.pathname);
+  } catch {
+    const withoutHash = trimmed.split("#", 1)[0] ?? trimmed;
+    const withoutQuery = withoutHash.split("?", 1)[0] ?? withoutHash;
+    return normalizeLowercaseStringOrEmpty(withoutQuery);
+  }
+}
+
+export function isLikelyDiscordVideoMedia(mediaUrl: string): boolean {
+  const normalized = normalizeMediaPathForExtension(mediaUrl);
+  for (const ext of DISCORD_VIDEO_MEDIA_EXTENSIONS) {
+    if (normalized.endsWith(ext)) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/mentions.ts

@@ -0,0 +1,147 @@
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalString,
+  normalizeOptionalStringifiedId,
+} from "autobot/plugin-sdk/string-coerce-runtime";
+import { resolveDiscordDirectoryUserId } from "./directory-cache.js";
+
+type DiscordMentionAliasesConfig = Record<string, string>;
+
+const MARKDOWN_CODE_SEGMENT_PATTERN = /```[\s\S]*?```|`[^`\n]*`/g;
+const MENTION_CANDIDATE_PATTERN = /(^|[\s([{"'.,;:!?])@([a-z0-9_.-]{2,32}(?:#[0-9]{4})?)/gi;
+const DISCORD_RESERVED_MENTIONS = new Set(["everyone", "here"]);
+const DISCORD_DISCRIMINATOR_SUFFIX = /#\d{4}$/;
+
+function normalizeSnowflake(value: string | number | bigint): string | null {
+  const text = normalizeOptionalStringifiedId(value) ?? "";
+  if (!/^\d+$/.test(text)) {
+    return null;
+  }
+  return text;
+}
+
+export function formatMention(params: {
+  userId?: string | number | bigint | null;
+  roleId?: string | number | bigint | null;
+  channelId?: string | number | bigint | null;
+}): string {
+  const userId = params.userId == null ? null : normalizeSnowflake(params.userId);
+  const roleId = params.roleId == null ? null : normalizeSnowflake(params.roleId);
+  const channelId = params.channelId == null ? null : normalizeSnowflake(params.channelId);
+  const values = [
+    userId ? { kind: "user" as const, id: userId } : null,
+    roleId ? { kind: "role" as const, id: roleId } : null,
+    channelId ? { kind: "channel" as const, id: channelId } : null,
+  ].filter((entry): entry is { kind: "user" | "role" | "channel"; id: string } => Boolean(entry));
+  if (values.length !== 1) {
+    throw new Error("formatMention requires exactly one of userId, roleId, or channelId");
+  }
+  const target = values[0];
+  if (target.kind === "user") {
+    return `<@${target.id}>`;
+  }
+  if (target.kind === "role") {
+    return `<@&${target.id}>`;
+  }
+  return `<#${target.id}>`;
+}
+
+function normalizeHandleKey(raw: string): string | null {
+  let handle = normalizeOptionalString(raw) ?? "";
+  if (!handle) {
+    return null;
+  }
+  if (handle.startsWith("@")) {
+    handle = normalizeOptionalString(handle.slice(1)) ?? "";
+  }
+  if (!handle || /\s/.test(handle)) {
+    return null;
+  }
+  return normalizeLowercaseStringOrEmpty(handle);
+}
+
+function resolveConfiguredMentionAlias(
+  handle: string,
+  mentionAliases?: DiscordMentionAliasesConfig | null,
+): string | undefined {
+  const key = normalizeHandleKey(handle);
+  if (!key || !mentionAliases) {
+    return undefined;
+  }
+  const withoutDiscriminator = key.replace(DISCORD_DISCRIMINATOR_SUFFIX, "");
+  for (const [rawAlias, rawUserId] of Object.entries(mentionAliases)) {
+    const alias = normalizeHandleKey(rawAlias);
+    if (!alias) {
+      continue;
+    }
+    const aliasWithoutDiscriminator = alias.replace(DISCORD_DISCRIMINATOR_SUFFIX, "");
+    if (
+      alias === key ||
+      (withoutDiscriminator && withoutDiscriminator !== key && alias === withoutDiscriminator) ||
+      (aliasWithoutDiscriminator &&
+        aliasWithoutDiscriminator !== alias &&
+        aliasWithoutDiscriminator === key)
+    ) {
+      const userId = normalizeSnowflake(rawUserId);
+      if (userId) {
+        return userId;
+      }
+    }
+  }
+  return undefined;
+}
+
+function rewritePlainTextMentions(
+  text: string,
+  params: {
+    accountId?: string | null;
+    mentionAliases?: DiscordMentionAliasesConfig | null;
+  },
+): string {
+  if (!text.includes("@")) {
+    return text;
+  }
+  return text.replace(MENTION_CANDIDATE_PATTERN, (match, prefix, rawHandle) => {
+    const handle = normalizeOptionalString(rawHandle) ?? "";
+    if (!handle) {
+      return match;
+    }
+    const lookup = normalizeLowercaseStringOrEmpty(handle);
+    if (DISCORD_RESERVED_MENTIONS.has(lookup)) {
+      return match;
+    }
+    const userId =
+      resolveConfiguredMentionAlias(handle, params.mentionAliases) ??
+      resolveDiscordDirectoryUserId({
+        accountId: params.accountId,
+        handle,
+      });
+    if (!userId) {
+      return match;
+    }
+    return `${String(prefix ?? "")}${formatMention({ userId })}`;
+  });
+}
+
+export function rewriteDiscordKnownMentions(
+  text: string,
+  params: {
+    accountId?: string | null;
+    mentionAliases?: DiscordMentionAliasesConfig | null;
+  },
+): string {
+  if (!text.includes("@")) {
+    return text;
+  }
+  let rewritten = "";
+  let offset = 0;
+  MARKDOWN_CODE_SEGMENT_PATTERN.lastIndex = 0;
+  for (const match of text.matchAll(MARKDOWN_CODE_SEGMENT_PATTERN)) {
+    const matchIndex = match.index ?? 0;
+    rewritten += rewritePlainTextMentions(text.slice(offset, matchIndex), params);
+    rewritten += match[0];
+    offset = matchIndex + match[0].length;
+  }
+  rewritten += rewritePlainTextMentions(text.slice(offset), params);
+  return rewritten;
+}

package/src/monitor/ack-reactions.ts

@@ -0,0 +1,70 @@
+import {
+  createStatusReactionController,
+  logAckFailure,
+  type StatusReactionAdapter,
+} from "autobot/plugin-sdk/channel-feedback";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { logVerbose } from "autobot/plugin-sdk/runtime-env";
+import { createDiscordRuntimeAccountContext } from "../client.js";
+import type { RequestClient } from "../internal/discord.js";
+import { reactMessageDiscord, removeReactionDiscord } from "../send.js";
+import type { DiscordReactionRuntimeContext } from "../send.types.js";
+
+export function createDiscordAckReactionContext(params: {
+  rest: RequestClient;
+  cfg: AutoBotConfig;
+  accountId: string;
+}): DiscordReactionRuntimeContext {
+  return {
+    rest: params.rest,
+    ...createDiscordRuntimeAccountContext({
+      cfg: params.cfg,
+      accountId: params.accountId,
+    }),
+  };
+}
+
+export function createDiscordAckReactionAdapter(params: {
+  channelId: string;
+  messageId: string;
+  reactionContext: DiscordReactionRuntimeContext;
+}): StatusReactionAdapter {
+  return {
+    setReaction: async (emoji) => {
+      await reactMessageDiscord(params.channelId, params.messageId, emoji, params.reactionContext);
+    },
+    removeReaction: async (emoji) => {
+      await removeReactionDiscord(
+        params.channelId,
+        params.messageId,
+        emoji,
+        params.reactionContext,
+      );
+    },
+  };
+}
+
+export function queueInitialDiscordAckReaction(params: {
+  enabled: boolean;
+  shouldSendAckReaction: boolean;
+  ackReaction: string | undefined;
+  statusReactions: ReturnType<typeof createStatusReactionController>;
+  reactionAdapter: StatusReactionAdapter;
+  target: string;
+}) {
+  if (params.enabled) {
+    void params.statusReactions.setQueued();
+    return;
+  }
+  if (!params.shouldSendAckReaction || !params.ackReaction) {
+    return;
+  }
+  void params.reactionAdapter.setReaction(params.ackReaction).catch((err) => {
+    logAckFailure({
+      log: logVerbose,
+      channel: "discord",
+      target: params.target,
+      error: err,
+    });
+  });
+}

package/src/monitor/agent-components-auth.ts

@@ -0,0 +1,7 @@
+export { resolveInteractionContextWithDmAuth } from "./agent-components-dm-auth.js";
+export {
+  ensureAgentComponentInteractionAllowed,
+  ensureComponentUserAllowed,
+  resolveAuthorizedComponentInteraction,
+  resolveComponentCommandAuthorized,
+} from "./agent-components-guild-auth.js";

package/src/monitor/agent-components-context.ts

@@ -0,0 +1,154 @@
+import { ChannelType } from "discord-api-types/v10";
+import { logError } from "autobot/plugin-sdk/logging-core";
+import { resolveAgentRoute } from "autobot/plugin-sdk/routing";
+import {
+  type AgentComponentContext,
+  type AgentComponentInteraction,
+  type AgentComponentMessageInteraction,
+  type ComponentInteractionContext,
+  type DiscordChannelContext,
+} from "./agent-components.types.js";
+import { normalizeDiscordDisplaySlug, normalizeDiscordSlug } from "./allow-list.js";
+import { resolveDiscordChannelInfoSafe } from "./channel-access.js";
+
+function formatUsername(user: { username: string; discriminator?: string | null }): string {
+  if (user.discriminator && user.discriminator !== "0") {
+    return `${user.username}#${user.discriminator}`;
+  }
+  return user.username;
+}
+
+function isThreadChannelType(channelType: number | undefined): boolean {
+  return (
+    channelType === ChannelType.PublicThread ||
+    channelType === ChannelType.PrivateThread ||
+    channelType === ChannelType.AnnouncementThread
+  );
+}
+
+export function resolveAgentComponentRoute(params: {
+  ctx: AgentComponentContext;
+  rawGuildId: string | undefined;
+  memberRoleIds: string[];
+  isDirectMessage: boolean;
+  isGroupDm: boolean;
+  userId: string;
+  channelId: string;
+  parentId: string | undefined;
+}) {
+  return resolveAgentRoute({
+    cfg: params.ctx.cfg,
+    channel: "discord",
+    accountId: params.ctx.accountId,
+    guildId: params.rawGuildId,
+    memberRoleIds: params.memberRoleIds,
+    peer: {
+      kind: params.isDirectMessage ? "direct" : params.isGroupDm ? "group" : "channel",
+      id: params.isDirectMessage ? params.userId : params.channelId,
+    },
+    parentPeer: params.parentId ? { kind: "channel", id: params.parentId } : undefined,
+  });
+}
+
+export async function ackComponentInteraction(params: {
+  interaction: AgentComponentInteraction;
+  replyOpts: { ephemeral?: boolean };
+  label: string;
+}) {
+  try {
+    await params.interaction.reply({
+      content: "✓",
+      ...params.replyOpts,
+    });
+  } catch (err) {
+    logError(`${params.label}: failed to acknowledge interaction: ${String(err)}`);
+  }
+}
+
+export function resolveDiscordChannelContext(
+  interaction: AgentComponentInteraction,
+): DiscordChannelContext {
+  const channel = interaction.channel;
+  const channelInfo = resolveDiscordChannelInfoSafe(channel);
+  const channelName = channelInfo.name;
+  const channelSlug = channelName ? normalizeDiscordSlug(channelName) : "";
+  const displayChannelSlug = channelName ? normalizeDiscordDisplaySlug(channelName) : "";
+  const channelType = channelInfo.type;
+  const isThread = isThreadChannelType(channelType);
+
+  let parentId: string | undefined;
+  let parentName: string | undefined;
+  let parentSlug = "";
+  if (isThread) {
+    parentId = channelInfo.parentId;
+    parentName = channelInfo.parentName;
+    if (parentName) {
+      parentSlug = normalizeDiscordSlug(parentName);
+    }
+  }
+
+  return {
+    channelName,
+    channelSlug,
+    displayChannelSlug,
+    channelType,
+    isThread,
+    parentId,
+    parentName,
+    parentSlug,
+  };
+}
+
+export async function resolveComponentInteractionContext(params: {
+  interaction: AgentComponentInteraction;
+  label: string;
+  defer?: boolean;
+}): Promise<ComponentInteractionContext | null> {
+  const { interaction, label } = params;
+  const channelId = interaction.rawData.channel_id;
+  if (!channelId) {
+    logError(`${label}: missing channel_id in interaction`);
+    return null;
+  }
+
+  const user = interaction.user;
+  if (!user) {
+    logError(`${label}: missing user in interaction`);
+    return null;
+  }
+
+  const shouldDefer = params.defer !== false && "defer" in interaction;
+  let didDefer = false;
+  if (shouldDefer) {
+    try {
+      await (interaction as AgentComponentMessageInteraction).defer({ ephemeral: true });
+      didDefer = true;
+    } catch (err) {
+      logError(`${label}: failed to defer interaction: ${String(err)}`);
+    }
+  }
+  const replyOpts = didDefer ? {} : { ephemeral: true };
+
+  const username = formatUsername(user);
+  const userId = user.id;
+  const rawGuildId = interaction.rawData.guild_id;
+  const channelType = resolveDiscordChannelContext(interaction).channelType;
+  const isGroupDm = channelType === ChannelType.GroupDM;
+  const isDirectMessage =
+    channelType === ChannelType.DM || (!rawGuildId && !isGroupDm && channelType == null);
+  const memberRoleIds = Array.isArray(interaction.rawData.member?.roles)
+    ? interaction.rawData.member.roles.map((roleId: string) => roleId)
+    : [];
+
+  return {
+    channelId,
+    user,
+    username,
+    userId,
+    replyOpts,
+    rawGuildId,
+    isDirectMessage,
+    isGroupDm,
+    memberRoleIds,
+  };
+}