@openclaw/discord 2026.3.13 → 2026.5.2-beta.1

package/src/resolve-users.ts

@@ -0,0 +1,184 @@
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalString,
+} from "openclaw/plugin-sdk/text-runtime";
+import { fetchDiscord } from "./api.js";
+import { listGuilds, type DiscordGuildSummary } from "./guilds.js";
+import {
+  buildDiscordUnresolvedResults,
+  filterDiscordGuilds,
+  resolveDiscordAllowlistToken,
+} from "./resolve-allowlist-common.js";
+
+type DiscordUser = {
+  id: string;
+  username: string;
+  discriminator?: string;
+  global_name?: string;
+  bot?: boolean;
+};
+
+type DiscordMember = {
+  user: DiscordUser;
+  nick?: string | null;
+};
+
+export type DiscordUserResolution = {
+  input: string;
+  resolved: boolean;
+  id?: string;
+  name?: string;
+  guildId?: string;
+  guildName?: string;
+  note?: string;
+};
+
+function parseDiscordUserInput(raw: string): {
+  userId?: string;
+  guildId?: string;
+  guildName?: string;
+  userName?: string;
+} {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return {};
+  }
+  const mention = trimmed.match(/^<@!?(\d+)>$/);
+  if (mention) {
+    return { userId: mention[1] };
+  }
+  const prefixed = trimmed.match(/^(?:user:|discord:)?(\d+)$/i);
+  if (prefixed) {
+    return { userId: prefixed[1] };
+  }
+  const split = trimmed.includes("/") ? trimmed.split("/") : trimmed.split("#");
+  if (split.length >= 2) {
+    const guild = split[0]?.trim();
+    const user = split.slice(1).join("#").trim();
+    if (guild && /^\d+$/.test(guild)) {
+      return { guildId: guild, userName: user };
+    }
+    return { guildName: guild, userName: user };
+  }
+  return { userName: trimmed.replace(/^@/, "") };
+}
+
+function scoreDiscordMember(member: DiscordMember, query: string): number {
+  const q = normalizeLowercaseStringOrEmpty(query);
+  const user = member.user;
+  const candidates = [user.username, user.global_name, member.nick ?? undefined]
+    .map((value) => {
+      const normalized = normalizeOptionalString(value);
+      return normalized ? normalizeLowercaseStringOrEmpty(normalized) : undefined;
+    })
+    .filter(Boolean) as string[];
+  let score = 0;
+  if (candidates.some((value) => value === q)) {
+    score += 3;
+  }
+  if (candidates.some((value) => value?.includes(q))) {
+    score += 1;
+  }
+  if (!user.bot) {
+    score += 1;
+  }
+  return score;
+}
+
+export async function resolveDiscordUserAllowlist(params: {
+  token: string;
+  entries: string[];
+  fetcher?: typeof fetch;
+}): Promise<DiscordUserResolution[]> {
+  const token = resolveDiscordAllowlistToken(params.token);
+  if (!token) {
+    return buildDiscordUnresolvedResults(params.entries, (input) => ({
+      input,
+      resolved: false,
+    }));
+  }
+  const fetcher = params.fetcher ?? fetch;
+
+  // Lazy-load guilds: only fetch when an entry actually needs username search.
+  // This prevents listGuilds() failures (permissions, network) from blocking
+  // resolution of plain user-id entries that don't need guild data at all.
+  let guilds: DiscordGuildSummary[] | null = null;
+  const getGuilds = async (): Promise<DiscordGuildSummary[]> => {
+    if (!guilds) {
+      guilds = await listGuilds(token, fetcher);
+    }
+    return guilds;
+  };
+
+  const results: DiscordUserResolution[] = [];
+
+  for (const input of params.entries) {
+    const parsed = parseDiscordUserInput(input);
+    if (parsed.userId) {
+      results.push({
+        input,
+        resolved: true,
+        id: parsed.userId,
+      });
+      continue;
+    }
+
+    const query = parsed.userName?.trim();
+    if (!query) {
+      results.push({ input, resolved: false });
+      continue;
+    }
+
+    const allGuilds = await getGuilds();
+    const guildList = filterDiscordGuilds(allGuilds, {
+      guildId: parsed.guildId,
+      guildName: parsed.guildName?.trim(),
+    });
+
+    let best: { member: DiscordMember; guild: DiscordGuildSummary; score: number } | null = null;
+    let matches = 0;
+
+    for (const guild of guildList) {
+      const paramsObj = new URLSearchParams({
+        query,
+        limit: "25",
+      });
+      const members = await fetchDiscord<DiscordMember[]>(
+        `/guilds/${guild.id}/members/search?${paramsObj.toString()}`,
+        token,
+        fetcher,
+      );
+      for (const member of members) {
+        const score = scoreDiscordMember(member, query);
+        if (score === 0) {
+          continue;
+        }
+        matches += 1;
+        if (!best || score > best.score) {
+          best = { member, guild, score };
+        }
+      }
+    }
+
+    if (best) {
+      const user = best.member.user;
+      const name =
+        normalizeOptionalString(best.member.nick) ??
+        normalizeOptionalString(user.global_name) ??
+        normalizeOptionalString(user.username);
+      results.push({
+        input,
+        resolved: true,
+        id: user.id,
+        name,
+        guildId: best.guild.id,
+        guildName: best.guild.name,
+        note: matches > 1 ? "multiple matches; chose best" : undefined,
+      });
+    } else {
+      results.push({ input, resolved: false });
+    }
+  }
+
+  return results;
+}

package/src/retry.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it, vi } from "vitest";
+import { isRetryableDiscordDeliveryError } from "./delivery-retry.js";
+import { DiscordError, RateLimitError } from "./internal/discord.js";
+import { createDiscordRetryRunner, isRetryableDiscordTransientError } from "./retry.js";
+
+const ZERO_DELAY_RETRY = { attempts: 2, minDelayMs: 0, maxDelayMs: 0, jitter: 0 };
+
+function createRateLimitError(retryAfter = 0): RateLimitError {
+  const response = new Response(null, {
+    status: 429,
+    headers: {
+      "X-RateLimit-Scope": "user",
+      "X-RateLimit-Bucket": "bucket-1",
+    },
+  });
+  const RateLimitErrorCtor = RateLimitError as unknown as new (
+    response: Response,
+    body: { message: string; retry_after: number; global: boolean },
+  ) => RateLimitError;
+  return new RateLimitErrorCtor(response, {
+    message: "rate limited",
+    retry_after: retryAfter,
+    global: false,
+  });
+}
+
+describe("isRetryableDiscordTransientError", () => {
+  it.each([
+    ["rate limit", createRateLimitError()],
+    ["408 status", Object.assign(new Error("request timeout"), { status: 408 })],
+    ["502 status", Object.assign(new Error("bad gateway"), { status: 502 })],
+    ["503 statusCode", Object.assign(new Error("service unavailable"), { statusCode: 503 })],
+    ["fetch failed", new TypeError("fetch failed")],
+    ["ECONNRESET", Object.assign(new Error("socket hang up"), { code: "ECONNRESET" })],
+    ["ETIMEDOUT cause", new Error("request failed", { cause: { code: "ETIMEDOUT" } })],
+    ["abort", Object.assign(new Error("aborted"), { name: "AbortError" })],
+  ])("retries %s", (_name, err) => {
+    expect(isRetryableDiscordTransientError(err)).toBe(true);
+  });
+
+  it.each([
+    ["400 status", Object.assign(new Error("bad request"), { status: 400 })],
+    ["403 status", Object.assign(new Error("missing permissions"), { statusCode: 403 })],
+    ["unknown channel", new Error("Unknown Channel")],
+    ["plain string", "fetch failed"],
+  ])("does not retry %s", (_name, err) => {
+    expect(isRetryableDiscordTransientError(err)).toBe(false);
+  });
+});
+
+describe("createDiscordRetryRunner", () => {
+  it("retries transient transport errors", async () => {
+    const fn = vi.fn().mockRejectedValueOnce(new TypeError("fetch failed")).mockResolvedValue("ok");
+    const runner = createDiscordRetryRunner({ retry: ZERO_DELAY_RETRY });
+
+    await expect(runner(fn, "send")).resolves.toBe("ok");
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("stops after configured transient retry attempts", async () => {
+    const fn = vi.fn().mockRejectedValue(new TypeError("fetch failed"));
+    const runner = createDiscordRetryRunner({ retry: ZERO_DELAY_RETRY });
+
+    await expect(runner(fn, "send")).rejects.toThrow("fetch failed");
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("isRetryableDiscordDeliveryError", () => {
+  it("retries status-coded errors from injected delivery dependencies", () => {
+    expect(
+      isRetryableDiscordDeliveryError(Object.assign(new Error("bad gateway"), { status: 502 })),
+    ).toBe(true);
+  });
+
+  it("does not retry Discord client errors after the request runner handled them", () => {
+    const err = new DiscordError(new Response("upstream", { status: 502 }), {
+      message: "Bad Gateway",
+    });
+
+    expect(isRetryableDiscordDeliveryError(err)).toBe(false);
+  });
+});

package/src/retry.ts

@@ -0,0 +1,98 @@
+import {
+  collectErrorGraphCandidates,
+  extractErrorCode,
+  formatErrorMessage,
+  readErrorName,
+} from "openclaw/plugin-sdk/error-runtime";
+import {
+  createRateLimitRetryRunner,
+  type RetryConfig,
+  type RetryRunner,
+} from "openclaw/plugin-sdk/retry-runtime";
+import { RateLimitError } from "./internal/discord.js";
+
+const DISCORD_RETRY_DEFAULTS = {
+  attempts: 3,
+  minDelayMs: 500,
+  maxDelayMs: 30_000,
+  jitter: 0.1,
+} satisfies RetryConfig;
+
+const DISCORD_RETRYABLE_STATUS_CODES = new Set([408, 429]);
+const DISCORD_RETRYABLE_ERROR_CODES = new Set([
+  "EAI_AGAIN",
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ENETUNREACH",
+  "ENOTFOUND",
+  "EPIPE",
+  "ETIMEDOUT",
+  "UND_ERR_BODY_TIMEOUT",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+  "UND_ERR_SOCKET",
+]);
+const DISCORD_TRANSIENT_MESSAGE_RE =
+  /\b(?:bad gateway|fetch failed|network error|networkerror|service unavailable|socket hang up|temporarily unavailable|timed out|timeout)\b|connection (?:closed|reset|refused)/i;
+
+function readDiscordErrorStatus(err: unknown): number | undefined {
+  if (!err || typeof err !== "object") {
+    return undefined;
+  }
+  const raw =
+    "status" in err && err.status !== undefined
+      ? err.status
+      : "statusCode" in err && err.statusCode !== undefined
+        ? err.statusCode
+        : undefined;
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    return raw;
+  }
+  if (typeof raw === "string" && /^\d+$/.test(raw)) {
+    return Number(raw);
+  }
+  return undefined;
+}
+
+export function isRetryableDiscordTransientError(err: unknown): boolean {
+  if (err instanceof RateLimitError) {
+    return true;
+  }
+  for (const candidate of collectErrorGraphCandidates(err, (current) => [
+    current.cause,
+    current.error,
+  ])) {
+    const status = readDiscordErrorStatus(candidate);
+    if (status !== undefined && (DISCORD_RETRYABLE_STATUS_CODES.has(status) || status >= 500)) {
+      return true;
+    }
+    const code = extractErrorCode(candidate);
+    if (code && DISCORD_RETRYABLE_ERROR_CODES.has(code.toUpperCase())) {
+      return true;
+    }
+    if (readErrorName(candidate) === "AbortError") {
+      return true;
+    }
+    if (
+      (candidate instanceof Error || (candidate !== null && typeof candidate === "object")) &&
+      DISCORD_TRANSIENT_MESSAGE_RE.test(formatErrorMessage(candidate))
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function createDiscordRetryRunner(params: {
+  retry?: RetryConfig;
+  configRetry?: RetryConfig;
+  verbose?: boolean;
+}): RetryRunner {
+  return createRateLimitRetryRunner({
+    ...params,
+    defaults: DISCORD_RETRY_DEFAULTS,
+    logLabel: "discord",
+    shouldRetry: isRetryableDiscordTransientError,
+    retryAfterMs: (err) => (err instanceof RateLimitError ? err.retryAfter * 1000 : undefined),
+  });
+}

package/src/runtime-api.ts

@@ -0,0 +1,64 @@
+export {
+  buildComputedAccountStatusSnapshot,
+  buildTokenChannelStatusSummary,
+  PAIRING_APPROVED_MESSAGE,
+  projectCredentialSnapshotFields,
+  resolveConfiguredFromCredentialStatuses,
+} from "openclaw/plugin-sdk/channel-status";
+export { buildChannelConfigSchema, DiscordConfigSchema } from "../config-api.js";
+export type {
+  ChannelMessageActionAdapter,
+  ChannelMessageActionContext,
+  ChannelMessageActionName,
+} from "openclaw/plugin-sdk/channel-contract";
+export type {
+  ChannelPlugin,
+  OpenClawPluginApi,
+  PluginRuntime,
+} from "openclaw/plugin-sdk/channel-plugin-common";
+export type {
+  DiscordAccountConfig,
+  DiscordActionConfig,
+  DiscordConfig,
+  OpenClawConfig,
+} from "openclaw/plugin-sdk/config-types";
+export {
+  jsonResult,
+  readNumberParam,
+  readStringArrayParam,
+  readStringParam,
+  resolvePollMaxSelections,
+} from "openclaw/plugin-sdk/channel-actions";
+export type { ActionGate } from "openclaw/plugin-sdk/channel-actions";
+export { readBooleanParam } from "openclaw/plugin-sdk/boolean-param";
+export {
+  assertMediaNotDataUrl,
+  parseAvailableTags,
+  readReactionParams,
+  withNormalizedTimestamp,
+} from "openclaw/plugin-sdk/channel-actions";
+export {
+  createHybridChannelConfigAdapter,
+  createScopedChannelConfigAdapter,
+  createScopedAccountConfigAccessors,
+  createScopedChannelConfigBase,
+  createTopLevelChannelConfigAdapter,
+} from "openclaw/plugin-sdk/channel-config-helpers";
+export {
+  createAccountActionGate,
+  createAccountListHelpers,
+} from "openclaw/plugin-sdk/account-helpers";
+export { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+export {
+  emptyPluginConfigSchema,
+  formatPairingApproveHint,
+} from "openclaw/plugin-sdk/channel-plugin-common";
+export { loadOutboundMediaFromUrl } from "openclaw/plugin-sdk/outbound-media";
+export { resolveAccountEntry } from "openclaw/plugin-sdk/routing";
+export {
+  hasConfiguredSecretInput,
+  normalizeResolvedSecretInputString,
+  normalizeSecretInputString,
+} from "openclaw/plugin-sdk/secret-input";
+export { getChatChannelMeta } from "./channel-api.js";
+export { resolveDiscordOutboundSessionRoute } from "./outbound-session-route.js";

package/src/runtime.ts

@@ -1,6 +1,23 @@
-import { createPluginRuntimeStore } from "openclaw/plugin-sdk/compat";
-import type { PluginRuntime } from "openclaw/plugin-sdk/discord";
+import type { PluginRuntime } from "openclaw/plugin-sdk/channel-core";
+import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
 
-const { setRuntime: setDiscordRuntime, getRuntime: getDiscordRuntime } =
-  createPluginRuntimeStore<PluginRuntime>("Discord runtime not initialized");
-export { getDiscordRuntime, setDiscordRuntime };
+type DiscordChannelRuntime = {
+  messageActions?: typeof import("./channel-actions.js").discordMessageActions;
+  sendMessageDiscord?: typeof import("./send.js").sendMessageDiscord;
+};
+
+export type DiscordRuntime = PluginRuntime & {
+  channel: PluginRuntime["channel"] & {
+    discord?: DiscordChannelRuntime;
+  };
+};
+
+const {
+  setRuntime: setDiscordRuntime,
+  tryGetRuntime: getOptionalDiscordRuntime,
+  getRuntime: getDiscordRuntime,
+} = createPluginRuntimeStore<DiscordRuntime>({
+  pluginId: "discord",
+  errorMessage: "Discord runtime not initialized",
+});
+export { getDiscordRuntime, getOptionalDiscordRuntime, setDiscordRuntime };

package/src/secret-config-contract.ts

@@ -0,0 +1,140 @@
+import {
+  collectNestedChannelFieldAssignments,
+  collectSimpleChannelFieldAssignments,
+  getChannelSurface,
+  isBaseFieldActiveForChannelSurface,
+  isEnabledFlag,
+  isRecord,
+  type ResolverContext,
+  type SecretDefaults,
+  type SecretTargetRegistryEntry,
+} from "openclaw/plugin-sdk/channel-secret-basic-runtime";
+import { collectNestedChannelTtsAssignments } from "openclaw/plugin-sdk/channel-secret-tts-runtime";
+
+export const secretTargetRegistryEntries: SecretTargetRegistryEntry[] = [
+  {
+    id: "channels.discord.accounts.*.pluralkit.token",
+    targetType: "channels.discord.accounts.*.pluralkit.token",
+    configFile: "openclaw.json",
+    pathPattern: "channels.discord.accounts.*.pluralkit.token",
+    secretShape: "secret_input",
+    expectedResolvedValue: "string",
+    includeInPlan: true,
+    includeInConfigure: true,
+    includeInAudit: true,
+  },
+  {
+    id: "channels.discord.accounts.*.token",
+    targetType: "channels.discord.accounts.*.token",
+    configFile: "openclaw.json",
+    pathPattern: "channels.discord.accounts.*.token",
+    secretShape: "secret_input",
+    expectedResolvedValue: "string",
+    includeInPlan: true,
+    includeInConfigure: true,
+    includeInAudit: true,
+  },
+  {
+    id: "channels.discord.accounts.*.voice.tts.providers.*.apiKey",
+    targetType: "channels.discord.accounts.*.voice.tts.providers.*.apiKey",
+    configFile: "openclaw.json",
+    pathPattern: "channels.discord.accounts.*.voice.tts.providers.*.apiKey",
+    secretShape: "secret_input",
+    expectedResolvedValue: "string",
+    includeInPlan: true,
+    includeInConfigure: true,
+    includeInAudit: true,
+    providerIdPathSegmentIndex: 6,
+  },
+  {
+    id: "channels.discord.pluralkit.token",
+    targetType: "channels.discord.pluralkit.token",
+    configFile: "openclaw.json",
+    pathPattern: "channels.discord.pluralkit.token",
+    secretShape: "secret_input",
+    expectedResolvedValue: "string",
+    includeInPlan: true,
+    includeInConfigure: true,
+    includeInAudit: true,
+  },
+  {
+    id: "channels.discord.token",
+    targetType: "channels.discord.token",
+    configFile: "openclaw.json",
+    pathPattern: "channels.discord.token",
+    secretShape: "secret_input",
+    expectedResolvedValue: "string",
+    includeInPlan: true,
+    includeInConfigure: true,
+    includeInAudit: true,
+  },
+  {
+    id: "channels.discord.voice.tts.providers.*.apiKey",
+    targetType: "channels.discord.voice.tts.providers.*.apiKey",
+    configFile: "openclaw.json",
+    pathPattern: "channels.discord.voice.tts.providers.*.apiKey",
+    secretShape: "secret_input",
+    expectedResolvedValue: "string",
+    includeInPlan: true,
+    includeInConfigure: true,
+    includeInAudit: true,
+    providerIdPathSegmentIndex: 4,
+  },
+];
+
+export function collectRuntimeConfigAssignments(params: {
+  config: { channels?: Record<string, unknown> };
+  defaults?: SecretDefaults;
+  context: ResolverContext;
+}): void {
+  const resolved = getChannelSurface(params.config, "discord");
+  if (!resolved) {
+    return;
+  }
+  const { channel: discord, surface } = resolved;
+  collectSimpleChannelFieldAssignments({
+    channelKey: "discord",
+    field: "token",
+    channel: discord,
+    surface,
+    defaults: params.defaults,
+    context: params.context,
+    topInactiveReason: "no enabled account inherits this top-level Discord token.",
+    accountInactiveReason: "Discord account is disabled.",
+  });
+  collectNestedChannelFieldAssignments({
+    channelKey: "discord",
+    nestedKey: "pluralkit",
+    field: "token",
+    channel: discord,
+    surface,
+    defaults: params.defaults,
+    context: params.context,
+    topLevelActive:
+      isBaseFieldActiveForChannelSurface(surface, "pluralkit") &&
+      isRecord(discord.pluralkit) &&
+      isEnabledFlag(discord.pluralkit),
+    topInactiveReason:
+      "no enabled Discord surface inherits this top-level PluralKit config or PluralKit is disabled.",
+    accountActive: ({ account, enabled }) =>
+      enabled && isRecord(account.pluralkit) && isEnabledFlag(account.pluralkit),
+    accountInactiveReason: "Discord account is disabled or PluralKit is disabled for this account.",
+  });
+  collectNestedChannelTtsAssignments({
+    channelKey: "discord",
+    nestedKey: "voice",
+    channel: discord,
+    surface,
+    defaults: params.defaults,
+    context: params.context,
+    topLevelActive:
+      isBaseFieldActiveForChannelSurface(surface, "voice") &&
+      isRecord(discord.voice) &&
+      isEnabledFlag(discord.voice),
+    topInactiveReason:
+      "no enabled Discord surface inherits this top-level voice config or voice is disabled.",
+    accountActive: ({ account, enabled }) =>
+      enabled && isRecord(account.voice) && isEnabledFlag(account.voice),
+    accountInactiveReason: "Discord account is disabled or voice is disabled for this account.",
+  });
+}

package/src/security-audit.runtime.ts

@@ -0,0 +1 @@
+export { collectDiscordSecurityAuditFindings } from "./security-audit.js";