@openclaw/discord 2026.3.13 → 2026.5.1-beta.1

package/src/internal/structures.ts

@@ -0,0 +1,278 @@
+import {
+  type APIChannel,
+  type APIEmbed,
+  type APIGuild,
+  type APIGuildMember,
+  type APIMessage,
+  type APIRole,
+  type APIUser,
+  type MessageType,
+} from "discord-api-types/v10";
+import {
+  createChannelMessage,
+  createUserDmChannel,
+  deleteChannelMessage,
+  editChannelMessage,
+  getChannelMessage,
+  pinChannelMessage,
+  unpinChannelMessage,
+} from "./api.js";
+import { serializePayload, type MessagePayload } from "./payload.js";
+import type { RequestClient } from "./rest.js";
+
+type RawOrId<T> = T | string | { id: string; channelId?: string };
+export type StructureClient = {
+  rest: RequestClient;
+  fetchUser(id: string): Promise<User>;
+};
+
+export class Base {
+  constructor(protected client: StructureClient) {}
+}
+
+export class User<IsPartial extends boolean = false> extends Base {
+  protected _rawData: APIUser | null;
+  readonly id: string;
+
+  constructor(client: StructureClient, rawDataOrId: IsPartial extends true ? string : APIUser) {
+    super(client);
+    this._rawData = typeof rawDataOrId === "string" ? null : rawDataOrId;
+    this.id = typeof rawDataOrId === "string" ? rawDataOrId : rawDataOrId.id;
+  }
+
+  get rawData(): Readonly<APIUser> {
+    if (!this._rawData) {
+      throw new Error("Partial Discord user has no raw data");
+    }
+    return this._rawData;
+  }
+  get partial(): IsPartial {
+    return (this._rawData === null) as IsPartial;
+  }
+  get username() {
+    return this._rawData?.username ?? "";
+  }
+  get globalName() {
+    return this._rawData?.global_name;
+  }
+  get discriminator() {
+    return this._rawData?.discriminator;
+  }
+  get bot() {
+    return this._rawData?.bot;
+  }
+  get avatar() {
+    return this._rawData?.avatar;
+  }
+  get avatarUrl() {
+    return this.avatar ? `https://cdn.discordapp.com/avatars/${this.id}/${this.avatar}.png` : null;
+  }
+  toString(): string {
+    return `<@${this.id}>`;
+  }
+  async fetch(): Promise<User> {
+    return this.client.fetchUser(this.id);
+  }
+  async createDm() {
+    return await createUserDmChannel(this.client.rest, this.id);
+  }
+  async send(data: MessagePayload): Promise<Message> {
+    const dm = await this.createDm();
+    const message = await createChannelMessage(this.client.rest, dm.id, {
+      body: serializePayload(data),
+    });
+    return new Message(this.client, message);
+  }
+}
+
+export class Role<IsPartial extends boolean = false> extends Base {
+  protected _rawData: APIRole | null;
+  readonly id: string;
+  constructor(client: StructureClient, rawDataOrId: IsPartial extends true ? string : APIRole) {
+    super(client);
+    this._rawData = typeof rawDataOrId === "string" ? null : rawDataOrId;
+    this.id = typeof rawDataOrId === "string" ? rawDataOrId : rawDataOrId.id;
+  }
+  get name() {
+    return this._rawData?.name ?? "";
+  }
+}
+
+export class Guild<IsPartial extends boolean = false> extends Base {
+  protected _rawData: APIGuild | null;
+  readonly id: string;
+  constructor(client: StructureClient, rawDataOrId: IsPartial extends true ? string : APIGuild) {
+    super(client);
+    this._rawData = typeof rawDataOrId === "string" ? null : rawDataOrId;
+    this.id = typeof rawDataOrId === "string" ? rawDataOrId : rawDataOrId.id;
+  }
+  get name() {
+    return this._rawData?.name ?? "";
+  }
+}
+
+export class GuildMember extends Base {
+  constructor(
+    client: StructureClient,
+    public rawData: APIGuildMember,
+  ) {
+    super(client);
+  }
+  get user() {
+    return this.rawData.user ? new User(this.client, this.rawData.user) : null;
+  }
+  get roles() {
+    return (this.rawData.roles ?? []) as Array<string | Role>;
+  }
+  get nickname() {
+    return this.rawData.nick ?? undefined;
+  }
+}
+
+export class Message<IsPartial extends boolean = false> extends Base {
+  protected _rawData: APIMessage | null;
+  readonly id: string;
+  readonly channelId: string;
+
+  constructor(client: StructureClient, rawDataOrIds: RawOrId<APIMessage>) {
+    super(client);
+    this._rawData =
+      typeof rawDataOrIds === "string" || !("author" in rawDataOrIds) ? null : rawDataOrIds;
+    this.id = typeof rawDataOrIds === "string" ? rawDataOrIds : rawDataOrIds.id;
+    this.channelId =
+      typeof rawDataOrIds === "string"
+        ? ""
+        : "channel_id" in rawDataOrIds
+          ? rawDataOrIds.channel_id
+          : (rawDataOrIds.channelId ?? "");
+  }
+
+  get rawData(): Readonly<APIMessage> {
+    if (!this._rawData) {
+      throw new Error("Partial Discord message has no raw data");
+    }
+    return this._rawData;
+  }
+  get partial(): IsPartial {
+    return (this._rawData === null) as IsPartial;
+  }
+  get message(): Message<IsPartial> {
+    return this;
+  }
+  get channel_id() {
+    return this.channelId;
+  }
+  get guild_id() {
+    return (this._rawData as { guild_id?: string } | null)?.guild_id;
+  }
+  get guild() {
+    return this.guild_id ? new Guild<true>(this.client, this.guild_id) : null;
+  }
+  get webhookId() {
+    return this.webhook_id;
+  }
+  get webhook_id() {
+    return (this._rawData as { webhook_id?: string | null } | null)?.webhook_id ?? null;
+  }
+  get member() {
+    const member = (this._rawData as { member?: APIGuildMember } | null)?.member;
+    return member ? new GuildMember(this.client, member) : null;
+  }
+  get rawMember() {
+    return (this._rawData as { member?: APIGuildMember } | null)?.member;
+  }
+  get content() {
+    return this._rawData?.content ?? "";
+  }
+  get author() {
+    return this._rawData?.author ? new User(this.client, this._rawData.author) : null;
+  }
+  get embeds(): APIEmbed[] {
+    return this._rawData?.embeds ?? [];
+  }
+  get attachments() {
+    return this._rawData?.attachments ?? [];
+  }
+  get stickers() {
+    return this._rawData?.sticker_items ?? [];
+  }
+  get mentionedUsers() {
+    return (this._rawData?.mentions ?? []).map((user) => new User(this.client, user));
+  }
+  get mentionedRoles() {
+    return this._rawData?.mention_roles ?? [];
+  }
+  get mentionedEveryone() {
+    return this._rawData?.mention_everyone ?? false;
+  }
+  get timestamp() {
+    return this._rawData?.timestamp;
+  }
+  get type(): MessageType | undefined {
+    return this._rawData?.type;
+  }
+  get messageReference() {
+    return this._rawData?.message_reference;
+  }
+  get referencedMessage() {
+    return this._rawData?.referenced_message
+      ? new Message(this.client, this._rawData.referenced_message)
+      : null;
+  }
+  get thread() {
+    return this._rawData?.thread ? channelFactory(this.client, this._rawData.thread) : null;
+  }
+  async fetch(): Promise<Message> {
+    const raw = await getChannelMessage(this.client.rest, this.channelId, this.id);
+    return new Message(this.client, raw);
+  }
+  async delete(): Promise<void> {
+    await deleteChannelMessage(this.client.rest, this.channelId, this.id);
+  }
+  async edit(data: MessagePayload): Promise<Message> {
+    const raw = await editChannelMessage(this.client.rest, this.channelId, this.id, {
+      body: serializePayload(data),
+    });
+    return new Message(this.client, raw);
+  }
+  async reply(data: MessagePayload): Promise<Message> {
+    const raw = await createChannelMessage(this.client.rest, this.channelId, {
+      body: {
+        ...serializePayload(data),
+        message_reference: { message_id: this.id, fail_if_not_exists: false },
+      },
+    });
+    return new Message(this.client, raw);
+  }
+  async pin(): Promise<void> {
+    await pinChannelMessage(this.client.rest, this.channelId, this.id);
+  }
+  async unpin(): Promise<void> {
+    await unpinChannelMessage(this.client.rest, this.channelId, this.id);
+  }
+}
+
+export type DiscordChannel = APIChannel & {
+  rawData?: APIChannel;
+  guildId?: string;
+  guild?: Guild;
+  name?: string;
+  parentId?: string | null;
+};
+
+export function channelFactory(
+  _client: StructureClient,
+  channelData: APIChannel,
+  _partial?: boolean,
+): DiscordChannel {
+  return {
+    ...channelData,
+    rawData: channelData,
+    guildId: "guild_id" in channelData ? channelData.guild_id : undefined,
+    guild:
+      "guild_id" in channelData && typeof channelData.guild_id === "string"
+        ? new Guild<true>(_client, channelData.guild_id)
+        : undefined,
+    parentId: "parent_id" in channelData ? channelData.parent_id : undefined,
+  } as DiscordChannel;
+}

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

@@ -0,0 +1,163 @@
+import { ComponentType, InteractionType } from "discord-api-types/v10";
+import { vi, type Mock } from "vitest";
+import { Client } 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[] = []): Client {
+  return new Client(
+    {
+      baseUrl: "http://localhost",
+      clientId: "app1",
+      publicKey: "public",
+      token: "token",
+    },
+    { 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;
+
+  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 "openclaw/plugin-sdk/text-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.test.ts

@@ -0,0 +1,111 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  __resetDiscordDirectoryCacheForTest,
+  rememberDiscordDirectoryUser,
+} from "./directory-cache.js";
+import { formatMention, rewriteDiscordKnownMentions } from "./mentions.js";
+
+describe("formatMention", () => {
+  it("formats user mentions from ids", () => {
+    expect(formatMention({ userId: "123456789" })).toBe("<@123456789>");
+  });
+
+  it("formats role mentions from ids", () => {
+    expect(formatMention({ roleId: "987654321" })).toBe("<@&987654321>");
+  });
+
+  it("formats channel mentions from ids", () => {
+    expect(formatMention({ channelId: "777555333" })).toBe("<#777555333>");
+  });
+
+  it("throws when no mention id is provided", () => {
+    expect(() => formatMention({})).toThrow(/exactly one/i);
+  });
+
+  it("throws when more than one mention id is provided", () => {
+    expect(() => formatMention({ userId: "1", roleId: "2" })).toThrow(/exactly one/i);
+  });
+});
+
+describe("rewriteDiscordKnownMentions", () => {
+  beforeEach(() => {
+    __resetDiscordDirectoryCacheForTest();
+  });
+
+  it("rewrites @name mentions when a cached user id exists", () => {
+    rememberDiscordDirectoryUser({
+      accountId: "default",
+      userId: "123456789",
+      handles: ["Alice", "@alice_user", "alice#1234"],
+    });
+    const rewritten = rewriteDiscordKnownMentions("ping @Alice and @alice_user", {
+      accountId: "default",
+    });
+    expect(rewritten).toBe("ping <@123456789> and <@123456789>");
+  });
+
+  it("rewrites configured mention aliases before the cache", () => {
+    rememberDiscordDirectoryUser({
+      accountId: "default",
+      userId: "111111111",
+      handles: ["vladislava"],
+    });
+    const rewritten = rewriteDiscordKnownMentions("ping @Vladislava and @BuildBot#1234", {
+      accountId: "default",
+      mentionAliases: {
+        BuildBot: "222222222",
+        Vladislava: "333333333",
+      },
+    });
+    expect(rewritten).toBe("ping <@333333333> and <@222222222>");
+  });
+
+  it("supports configured aliases with a leading @ key", () => {
+    const rewritten = rewriteDiscordKnownMentions("ping @OpsLead", {
+      accountId: "default",
+      mentionAliases: {
+        "@opslead": "444444444",
+      },
+    });
+    expect(rewritten).toBe("ping <@444444444>");
+  });
+
+  it("preserves unknown mentions and reserved mentions", () => {
+    rememberDiscordDirectoryUser({
+      accountId: "default",
+      userId: "123456789",
+      handles: ["alice"],
+    });
+    const rewritten = rewriteDiscordKnownMentions("hello @unknown @everyone @here", {
+      accountId: "default",
+    });
+    expect(rewritten).toBe("hello @unknown @everyone @here");
+  });
+
+  it("does not rewrite mentions inside markdown code spans", () => {
+    rememberDiscordDirectoryUser({
+      accountId: "default",
+      userId: "123456789",
+      handles: ["alice"],
+    });
+    const rewritten = rewriteDiscordKnownMentions(
+      "inline `@alice` fence ```\n@alice\n``` text @alice",
+      {
+        accountId: "default",
+      },
+    );
+    expect(rewritten).toBe("inline `@alice` fence ```\n@alice\n``` text <@123456789>");
+  });
+
+  it("is account-scoped", () => {
+    rememberDiscordDirectoryUser({
+      accountId: "ops",
+      userId: "999888777",
+      handles: ["alice"],
+    });
+    const defaultRewrite = rewriteDiscordKnownMentions("@alice", { accountId: "default" });
+    const opsRewrite = rewriteDiscordKnownMentions("@alice", { accountId: "ops" });
+    expect(defaultRewrite).toBe("@alice");
+    expect(opsRewrite).toBe("<@999888777>");
+  });
+});