@openclaw/discord 2026.3.13 → 2026.5.1-beta.1

package/src/directory-cache.ts

@@ -0,0 +1,116 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/routing";
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalString,
+  normalizeOptionalStringifiedId,
+} from "openclaw/plugin-sdk/text-runtime";
+
+const DISCORD_DIRECTORY_CACHE_MAX_ENTRIES = 4000;
+const DISCORD_DISCRIMINATOR_SUFFIX = /#\d{4}$/;
+
+const DIRECTORY_HANDLE_CACHE = new Map<string, Map<string, string>>();
+
+function normalizeAccountCacheKey(accountId?: string | null): string {
+  const normalized = normalizeAccountId(accountId ?? DEFAULT_ACCOUNT_ID);
+  return normalized || DEFAULT_ACCOUNT_ID;
+}
+
+function normalizeSnowflake(value: string | number | bigint): string | null {
+  const text = normalizeOptionalStringifiedId(value) ?? "";
+  if (!/^\d+$/.test(text)) {
+    return null;
+  }
+  return text;
+}
+
+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 ensureAccountCache(accountId?: string | null): Map<string, string> {
+  const cacheKey = normalizeAccountCacheKey(accountId);
+  const existing = DIRECTORY_HANDLE_CACHE.get(cacheKey);
+  if (existing) {
+    return existing;
+  }
+  const created = new Map<string, string>();
+  DIRECTORY_HANDLE_CACHE.set(cacheKey, created);
+  return created;
+}
+
+function setCacheEntry(cache: Map<string, string>, key: string, userId: string): void {
+  if (cache.has(key)) {
+    cache.delete(key);
+  }
+  cache.set(key, userId);
+  if (cache.size <= DISCORD_DIRECTORY_CACHE_MAX_ENTRIES) {
+    return;
+  }
+  const oldest = cache.keys().next();
+  if (!oldest.done) {
+    cache.delete(oldest.value);
+  }
+}
+
+export function rememberDiscordDirectoryUser(params: {
+  accountId?: string | null;
+  userId: string | number | bigint;
+  handles: Array<string | null | undefined>;
+}): void {
+  const userId = normalizeSnowflake(params.userId);
+  if (!userId) {
+    return;
+  }
+  const cache = ensureAccountCache(params.accountId);
+  for (const candidate of params.handles) {
+    if (typeof candidate !== "string") {
+      continue;
+    }
+    const handle = normalizeHandleKey(candidate);
+    if (!handle) {
+      continue;
+    }
+    setCacheEntry(cache, handle, userId);
+    const withoutDiscriminator = handle.replace(DISCORD_DISCRIMINATOR_SUFFIX, "");
+    if (withoutDiscriminator && withoutDiscriminator !== handle) {
+      setCacheEntry(cache, withoutDiscriminator, userId);
+    }
+  }
+}
+
+export function resolveDiscordDirectoryUserId(params: {
+  accountId?: string | null;
+  handle: string;
+}): string | undefined {
+  const cache = DIRECTORY_HANDLE_CACHE.get(normalizeAccountCacheKey(params.accountId));
+  if (!cache) {
+    return undefined;
+  }
+  const handle = normalizeHandleKey(params.handle);
+  if (!handle) {
+    return undefined;
+  }
+  const direct = cache.get(handle);
+  if (direct) {
+    return direct;
+  }
+  const withoutDiscriminator = handle.replace(DISCORD_DISCRIMINATOR_SUFFIX, "");
+  if (!withoutDiscriminator || withoutDiscriminator === handle) {
+    return undefined;
+  }
+  return cache.get(withoutDiscriminator);
+}
+
+export function __resetDiscordDirectoryCacheForTest(): void {
+  DIRECTORY_HANDLE_CACHE.clear();
+}

package/src/directory-config.ts

@@ -0,0 +1,58 @@
+import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import {
+  createResolvedDirectoryEntriesLister,
+  type DirectoryConfigParams,
+} from "openclaw/plugin-sdk/directory-config-runtime";
+import {
+  mergeDiscordAccountConfig,
+  resolveDefaultDiscordAccountId,
+  resolveDiscordAccountAllowFrom,
+} from "./accounts.js";
+
+function resolveDiscordDirectoryConfigAccount(
+  cfg: DirectoryConfigParams["cfg"],
+  accountId?: string | null,
+) {
+  const resolvedAccountId = normalizeAccountId(accountId ?? resolveDefaultDiscordAccountId(cfg));
+  const config = mergeDiscordAccountConfig(cfg, resolvedAccountId);
+  return {
+    accountId: resolvedAccountId,
+    config,
+    allowFrom: resolveDiscordAccountAllowFrom({ cfg, accountId: resolvedAccountId }) ?? [],
+    dm: config.dm,
+  };
+}
+
+export const listDiscordDirectoryPeersFromConfig = createResolvedDirectoryEntriesLister<
+  ReturnType<typeof resolveDiscordDirectoryConfigAccount>
+>({
+  kind: "user",
+  resolveAccount: (cfg, accountId) => resolveDiscordDirectoryConfigAccount(cfg, accountId),
+  resolveSources: (account) => {
+    const guildUsers = Object.values(account.config.guilds ?? {}).flatMap((guild) =>
+      (guild.users ?? []).concat(
+        Object.values(guild.channels ?? {}).flatMap((channel) => channel.users ?? []),
+      ),
+    );
+    return [account.allowFrom, Object.keys(account.config.dms ?? {}), guildUsers];
+  },
+  normalizeId: (raw) => {
+    const mention = raw.match(/^<@!?(\d+)>$/);
+    const cleaned = (mention?.[1] ?? raw).replace(/^(discord|user):/i, "").trim();
+    return /^\d+$/.test(cleaned) ? `user:${cleaned}` : null;
+  },
+});
+
+export const listDiscordDirectoryGroupsFromConfig = createResolvedDirectoryEntriesLister<
+  ReturnType<typeof resolveDiscordDirectoryConfigAccount>
+>({
+  kind: "group",
+  resolveAccount: (cfg, accountId) => resolveDiscordDirectoryConfigAccount(cfg, accountId),
+  resolveSources: (account) =>
+    Object.values(account.config.guilds ?? {}).map((guild) => Object.keys(guild.channels ?? {})),
+  normalizeId: (raw) => {
+    const mention = raw.match(/^<#(\d+)>$/);
+    const cleaned = (mention?.[1] ?? raw).replace(/^(discord|channel|group):/i, "").trim();
+    return /^\d+$/.test(cleaned) ? `channel:${cleaned}` : null;
+  },
+});

package/src/directory-contract.test.ts

@@ -0,0 +1,129 @@
+import type { BaseProbeResult, BaseTokenResolution } from "openclaw/plugin-sdk/channel-contract";
+import { expectDirectoryIds } from "openclaw/plugin-sdk/channel-test-helpers";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { describe, expect, expectTypeOf, it } from "vitest";
+import {
+  listDiscordDirectoryGroupsFromConfig,
+  listDiscordDirectoryPeersFromConfig,
+} from "../directory-contract-api.js";
+import type { DiscordProbe } from "./probe.js";
+import type { DiscordTokenResolution } from "./token.js";
+
+describe("Discord directory contract", () => {
+  it("keeps public probe and token resolution aligned with base contracts", () => {
+    expectTypeOf<DiscordProbe>().toMatchTypeOf<BaseProbeResult>();
+    expectTypeOf<DiscordTokenResolution>().toMatchTypeOf<BaseTokenResolution>();
+  });
+
+  it("lists peers/groups from config (numeric ids only)", async () => {
+    const cfg = {
+      channels: {
+        discord: {
+          token: "discord-test",
+          dm: { allowFrom: ["<@111>", "<@!333>", "nope"] },
+          dms: { "222": {} },
+          guilds: {
+            "123": {
+              users: ["<@12345>", " discord:444 ", "not-an-id"],
+              channels: {
+                "555": {},
+                "<#777>": {},
+                "channel:666": {},
+                general: {},
+              },
+            },
+          },
+        },
+      },
+    } as unknown as OpenClawConfig;
+
+    await expectDirectoryIds(
+      listDiscordDirectoryPeersFromConfig,
+      cfg,
+      ["user:111", "user:12345", "user:222", "user:333", "user:444"],
+      { sorted: true },
+    );
+    await expectDirectoryIds(
+      listDiscordDirectoryGroupsFromConfig,
+      cfg,
+      ["channel:555", "channel:666", "channel:777"],
+      { sorted: true },
+    );
+  });
+
+  it("keeps directories readable when tokens are unresolved SecretRefs", async () => {
+    const envSecret = {
+      source: "env",
+      provider: "default",
+      id: "MISSING_TEST_SECRET",
+    } as const;
+    const cfg = {
+      channels: {
+        discord: {
+          token: envSecret,
+          dm: { allowFrom: ["<@111>"] },
+          guilds: {
+            "123": {
+              channels: {
+                "555": {},
+              },
+            },
+          },
+        },
+      },
+    } as unknown as OpenClawConfig;
+
+    await expectDirectoryIds(listDiscordDirectoryPeersFromConfig, cfg, ["user:111"]);
+    await expectDirectoryIds(listDiscordDirectoryGroupsFromConfig, cfg, ["channel:555"]);
+  });
+
+  it("uses account legacy dm.allowFrom before inherited root allowFrom", async () => {
+    const cfg = {
+      channels: {
+        discord: {
+          allowFrom: ["<@111>"],
+          accounts: {
+            work: {
+              dm: { allowFrom: ["<@222>"] },
+            },
+          },
+        },
+      },
+    } as unknown as OpenClawConfig;
+
+    const entries = await listDiscordDirectoryPeersFromConfig({
+      cfg,
+      accountId: "work",
+      query: null,
+      limit: null,
+    });
+    expect(entries.map((entry) => entry.id)).toEqual(["user:222"]);
+  });
+
+  it("applies query and limit filtering for config-backed directories", async () => {
+    const cfg = {
+      channels: {
+        discord: {
+          token: "discord-test",
+          guilds: {
+            "123": {
+              channels: {
+                "555": {},
+                "666": {},
+                "777": {},
+              },
+            },
+          },
+        },
+      },
+    } as unknown as OpenClawConfig;
+
+    const groups = await listDiscordDirectoryGroupsFromConfig({
+      cfg,
+      accountId: "default",
+      query: "666",
+      limit: 5,
+    });
+    expect(groups.map((entry) => entry.id)).toEqual(["channel:666"]);
+  });
+});

package/src/directory-live.test.ts

@@ -0,0 +1,126 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import type { DirectoryConfigParams } from "openclaw/plugin-sdk/directory-runtime";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { listDiscordDirectoryGroupsLive, listDiscordDirectoryPeersLive } from "./directory-live.js";
+
+function makeParams(overrides: Partial<DirectoryConfigParams> = {}): DirectoryConfigParams {
+  return {
+    cfg: {
+      channels: {
+        discord: {
+          token: "test-token",
+        },
+      },
+    } as OpenClawConfig,
+    accountId: "default",
+    ...overrides,
+  };
+}
+
+function jsonResponse(value: unknown): Response {
+  return new Response(JSON.stringify(value), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function resolveFetchUrl(input: string | URL | Request): string {
+  return typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+}
+
+describe("discord directory live lookups", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.stubEnv("DISCORD_BOT_TOKEN", "");
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("returns empty group directory when token is missing", async () => {
+    const rows = await listDiscordDirectoryGroupsLive({
+      ...makeParams(),
+      cfg: { channels: { discord: { token: "" } } } as OpenClawConfig,
+      query: "general",
+    });
+
+    expect(rows).toEqual([]);
+  });
+
+  it("returns empty peer directory without query and skips guild listing", async () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch");
+
+    const rows = await listDiscordDirectoryPeersLive(makeParams({ query: "  " }));
+
+    expect(rows).toEqual([]);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("filters group channels by query and respects limit", async () => {
+    vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+      const url = resolveFetchUrl(input);
+      if (url.endsWith("/users/@me/guilds")) {
+        return jsonResponse([
+          { id: "g1", name: "Guild 1" },
+          { id: "g2", name: "Guild 2" },
+        ]);
+      }
+      if (url.endsWith("/guilds/g1/channels")) {
+        return jsonResponse([
+          { id: "c1", name: "general" },
+          { id: "c2", name: "random" },
+        ]);
+      }
+      if (url.endsWith("/guilds/g2/channels")) {
+        return jsonResponse([{ id: "c3", name: "announcements" }]);
+      }
+      return jsonResponse([]);
+    });
+
+    const rows = await listDiscordDirectoryGroupsLive(makeParams({ query: "an", limit: 2 }));
+
+    expect(rows).toEqual([
+      expect.objectContaining({ kind: "group", id: "channel:c2", name: "random" }),
+      expect.objectContaining({ kind: "group", id: "channel:c3", name: "announcements" }),
+    ]);
+  });
+
+  it("returns ranked peer results and caps member search by limit", async () => {
+    vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+      const url = resolveFetchUrl(input);
+      if (url.endsWith("/users/@me/guilds")) {
+        return jsonResponse([{ id: "g1", name: "Guild 1" }]);
+      }
+      if (url.includes("/guilds/g1/members/search?")) {
+        const params = new URL(url).searchParams;
+        expect(params.get("query")).toBe("alice");
+        expect(params.get("limit")).toBe("2");
+        return jsonResponse([
+          { user: { id: "u1", username: "alice", bot: false }, nick: "Ali" },
+          { user: { id: "u2", username: "alice-bot", bot: true }, nick: null },
+          { user: { id: "u3", username: "ignored", bot: false }, nick: null },
+        ]);
+      }
+      return jsonResponse([]);
+    });
+
+    const rows = await listDiscordDirectoryPeersLive(makeParams({ query: "alice", limit: 2 }));
+
+    expect(rows).toEqual([
+      expect.objectContaining({
+        kind: "user",
+        id: "user:u1",
+        name: "Ali",
+        handle: "@alice",
+        rank: 1,
+      }),
+      expect.objectContaining({
+        kind: "user",
+        id: "user:u2",
+        handle: "@alice-bot",
+        rank: 0,
+      }),
+    ]);
+  });
+});

package/src/directory-live.ts

@@ -0,0 +1,135 @@
+import type {
+  ChannelDirectoryEntry,
+  DirectoryConfigParams,
+} from "openclaw/plugin-sdk/directory-runtime";
+import { normalizeOptionalLowercaseString } from "openclaw/plugin-sdk/text-runtime";
+import { resolveDiscordAccount } from "./accounts.js";
+import { fetchDiscord } from "./api.js";
+import { rememberDiscordDirectoryUser } from "./directory-cache.js";
+import { normalizeDiscordSlug } from "./monitor/allow-list.js";
+import { normalizeDiscordToken } from "./token.js";
+
+type DiscordGuild = { id: string; name: string };
+type DiscordUser = { id: string; username: string; global_name?: string; bot?: boolean };
+type DiscordMember = { user: DiscordUser; nick?: string | null };
+type DiscordChannel = { id: string; name?: string | null };
+type DiscordDirectoryAccess = { token: string; query: string; accountId: string };
+
+function normalizeQuery(value?: string | null): string {
+  return normalizeOptionalLowercaseString(value) ?? "";
+}
+
+function buildUserRank(user: DiscordUser): number {
+  return user.bot ? 0 : 1;
+}
+
+function resolveDiscordDirectoryAccess(
+  params: DirectoryConfigParams,
+): DiscordDirectoryAccess | null {
+  const account = resolveDiscordAccount({ cfg: params.cfg, accountId: params.accountId });
+  const token = normalizeDiscordToken(account.token, "channels.discord.token");
+  if (!token) {
+    return null;
+  }
+  return { token, query: normalizeQuery(params.query), accountId: account.accountId };
+}
+
+async function listDiscordGuilds(token: string): Promise<DiscordGuild[]> {
+  const rawGuilds = await fetchDiscord<DiscordGuild[]>("/users/@me/guilds", token);
+  return rawGuilds.filter((guild) => guild.id && guild.name);
+}
+
+export async function listDiscordDirectoryGroupsLive(
+  params: DirectoryConfigParams,
+): Promise<ChannelDirectoryEntry[]> {
+  const access = resolveDiscordDirectoryAccess(params);
+  if (!access) {
+    return [];
+  }
+  const { token, query } = access;
+  const guilds = await listDiscordGuilds(token);
+  const rows: ChannelDirectoryEntry[] = [];
+
+  for (const guild of guilds) {
+    const channels = await fetchDiscord<DiscordChannel[]>(`/guilds/${guild.id}/channels`, token);
+    for (const channel of channels) {
+      const name = channel.name?.trim();
+      if (!name) {
+        continue;
+      }
+      if (query && !normalizeDiscordSlug(name).includes(normalizeDiscordSlug(query))) {
+        continue;
+      }
+      rows.push({
+        kind: "group",
+        id: `channel:${channel.id}`,
+        name,
+        handle: `#${name}`,
+        raw: channel,
+      });
+      if (typeof params.limit === "number" && params.limit > 0 && rows.length >= params.limit) {
+        return rows;
+      }
+    }
+  }
+
+  return rows;
+}
+
+export async function listDiscordDirectoryPeersLive(
+  params: DirectoryConfigParams,
+): Promise<ChannelDirectoryEntry[]> {
+  const access = resolveDiscordDirectoryAccess(params);
+  if (!access) {
+    return [];
+  }
+  const { token, query, accountId } = access;
+  if (!query) {
+    return [];
+  }
+
+  const guilds = await listDiscordGuilds(token);
+  const rows: ChannelDirectoryEntry[] = [];
+  const limit = typeof params.limit === "number" && params.limit > 0 ? params.limit : 25;
+
+  for (const guild of guilds) {
+    const paramsObj = new URLSearchParams({
+      query,
+      limit: String(Math.min(limit, 100)),
+    });
+    const members = await fetchDiscord<DiscordMember[]>(
+      `/guilds/${guild.id}/members/search?${paramsObj.toString()}`,
+      token,
+    );
+    for (const member of members) {
+      const user = member.user;
+      if (!user?.id) {
+        continue;
+      }
+      rememberDiscordDirectoryUser({
+        accountId,
+        userId: user.id,
+        handles: [
+          user.username,
+          user.global_name,
+          member.nick,
+          user.username ? `@${user.username}` : null,
+        ],
+      });
+      const name = member.nick?.trim() || user.global_name?.trim() || user.username?.trim();
+      rows.push({
+        kind: "user",
+        id: `user:${user.id}`,
+        name: name || undefined,
+        handle: user.username ? `@${user.username}` : undefined,
+        rank: buildUserRank(user),
+        raw: member,
+      });
+      if (rows.length >= limit) {
+        return rows;
+      }
+    }
+  }
+
+  return rows;
+}