@openclaw/discord 2026.3.13 → 2026.5.1-beta.1

package/src/monitor/thread-bindings.discord-api.test.ts

@@ -0,0 +1,229 @@
+import { ChannelType } from "discord-api-types/v10";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import * as discordClientModule from "../client.js";
+import * as discordSendModule from "../send.js";
+import { EMPTY_DISCORD_TEST_CONFIG } from "../test-support/config.js";
+import type { ThreadBindingRecord } from "./thread-bindings.types.js";
+
+const DEFAULT_SEND_RESULT = {
+  messageId: "msg-1",
+  channelId: "thread-1",
+};
+
+const restGet = vi.fn<(...args: unknown[]) => Promise<unknown>>();
+const sendMessageDiscord = vi.fn<typeof discordSendModule.sendMessageDiscord>();
+const sendWebhookMessageDiscord = vi.fn<typeof discordSendModule.sendWebhookMessageDiscord>();
+const createDiscordRestClient = vi.fn<typeof discordClientModule.createDiscordRestClient>(
+  () =>
+    ({
+      rest: {
+        get: restGet,
+      },
+    }) as unknown as ReturnType<typeof discordClientModule.createDiscordRestClient>,
+);
+
+let maybeSendBindingMessage: typeof import("./thread-bindings.discord-api.js").maybeSendBindingMessage;
+let resolveChannelIdForBinding: typeof import("./thread-bindings.discord-api.js").resolveChannelIdForBinding;
+
+beforeAll(async () => {
+  ({ maybeSendBindingMessage, resolveChannelIdForBinding } =
+    await import("./thread-bindings.discord-api.js"));
+});
+
+function resolveTestChannelIdForBinding(
+  params: Omit<Parameters<typeof resolveChannelIdForBinding>[0], "cfg"> & {
+    cfg?: OpenClawConfig;
+  },
+) {
+  return resolveChannelIdForBinding({
+    cfg: EMPTY_DISCORD_TEST_CONFIG,
+    ...params,
+  });
+}
+
+describe("resolveChannelIdForBinding", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    restGet.mockReset();
+    sendMessageDiscord.mockReset().mockResolvedValue(DEFAULT_SEND_RESULT);
+    sendWebhookMessageDiscord.mockReset().mockResolvedValue(DEFAULT_SEND_RESULT);
+    createDiscordRestClient.mockReset().mockImplementation(
+      () =>
+        ({
+          rest: {
+            get: restGet,
+          },
+        }) as unknown as ReturnType<typeof discordClientModule.createDiscordRestClient>,
+    );
+    vi.spyOn(discordClientModule, "createDiscordRestClient").mockImplementation(
+      (...args) =>
+        createDiscordRestClient(...args) as unknown as ReturnType<
+          typeof discordClientModule.createDiscordRestClient
+        >,
+    );
+    vi.spyOn(discordSendModule, "sendMessageDiscord").mockImplementation((...args) =>
+      sendMessageDiscord(...args),
+    );
+    vi.spyOn(discordSendModule, "sendWebhookMessageDiscord").mockImplementation((...args) =>
+      sendWebhookMessageDiscord(...args),
+    );
+  });
+
+  it("returns explicit channelId without resolving route", async () => {
+    const resolved = await resolveTestChannelIdForBinding({
+      accountId: "default",
+      threadId: "thread-1",
+      channelId: "channel-explicit",
+    });
+
+    expect(resolved).toBe("channel-explicit");
+    expect(createDiscordRestClient).not.toHaveBeenCalled();
+    expect(restGet).not.toHaveBeenCalled();
+  });
+
+  it("normalizes prefixed explicit channelId without resolving route", async () => {
+    const resolved = await resolveTestChannelIdForBinding({
+      accountId: "default",
+      threadId: "thread-1",
+      channelId: "channel:123456789012345678",
+    });
+
+    expect(resolved).toBe("123456789012345678");
+    expect(createDiscordRestClient).not.toHaveBeenCalled();
+    expect(restGet).not.toHaveBeenCalled();
+  });
+
+  it("strips channel prefix before resolving route", async () => {
+    restGet.mockResolvedValueOnce({
+      id: "123456789012345678",
+      type: ChannelType.GuildText,
+    });
+
+    const resolved = await resolveTestChannelIdForBinding({
+      accountId: "default",
+      threadId: "channel:123456789012345678",
+    });
+
+    expect(resolved).toBe("123456789012345678");
+    const route = JSON.stringify(restGet.mock.calls[0]?.[0] ?? null);
+    expect(route).toContain("123456789012345678");
+    expect(route).not.toContain("channel:");
+  });
+
+  it("returns parent channel for thread channels", async () => {
+    restGet.mockResolvedValueOnce({
+      id: "thread-1",
+      type: ChannelType.PublicThread,
+      parent_id: "channel-parent",
+    });
+
+    const resolved = await resolveTestChannelIdForBinding({
+      accountId: "default",
+      threadId: "thread-1",
+    });
+
+    expect(resolved).toBe("channel-parent");
+  });
+
+  it("forwards cfg when resolving channel id through Discord client", async () => {
+    const cfg = {
+      channels: { discord: { token: "tok" } },
+    } as OpenClawConfig;
+    restGet.mockResolvedValueOnce({
+      id: "thread-1",
+      type: ChannelType.PublicThread,
+      parent_id: "channel-parent",
+    });
+
+    await resolveTestChannelIdForBinding({
+      cfg,
+      accountId: "default",
+      threadId: "thread-1",
+    });
+
+    const createDiscordRestClientCalls = createDiscordRestClient.mock.calls as unknown[][];
+    expect(
+      (createDiscordRestClientCalls[0]?.[0] as { cfg?: OpenClawConfig } | undefined)?.cfg,
+    ).toBe(cfg);
+  });
+
+  it("keeps non-thread channel id even when parent_id exists", async () => {
+    restGet.mockResolvedValueOnce({
+      id: "channel-text",
+      type: ChannelType.GuildText,
+      parent_id: "category-1",
+    });
+
+    const resolved = await resolveTestChannelIdForBinding({
+      accountId: "default",
+      threadId: "channel-text",
+    });
+
+    expect(resolved).toBe("channel-text");
+  });
+
+  it("keeps forum channel id instead of parent category", async () => {
+    restGet.mockResolvedValueOnce({
+      id: "forum-1",
+      type: ChannelType.GuildForum,
+      parent_id: "category-1",
+    });
+
+    const resolved = await resolveTestChannelIdForBinding({
+      accountId: "default",
+      threadId: "forum-1",
+    });
+
+    expect(resolved).toBe("forum-1");
+  });
+});
+
+describe("maybeSendBindingMessage", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    sendMessageDiscord.mockReset().mockResolvedValue(DEFAULT_SEND_RESULT);
+    sendWebhookMessageDiscord.mockReset().mockResolvedValue(DEFAULT_SEND_RESULT);
+    vi.spyOn(discordSendModule, "sendMessageDiscord").mockImplementation((...args) =>
+      sendMessageDiscord(...args),
+    );
+    vi.spyOn(discordSendModule, "sendWebhookMessageDiscord").mockImplementation((...args) =>
+      sendWebhookMessageDiscord(...args),
+    );
+  });
+
+  it("forwards cfg to webhook send path", async () => {
+    const cfg = {
+      channels: { discord: { token: "tok" } },
+    } as OpenClawConfig;
+    const record = {
+      accountId: "default",
+      channelId: "parent-1",
+      threadId: "thread-1",
+      targetKind: "subagent",
+      targetSessionKey: "agent:main:subagent:test",
+      agentId: "main",
+      boundBy: "test",
+      boundAt: Date.now(),
+      lastActivityAt: Date.now(),
+      webhookId: "wh_1",
+      webhookToken: "tok_1",
+    } satisfies ThreadBindingRecord;
+
+    await maybeSendBindingMessage({
+      cfg,
+      record,
+      text: "hello webhook",
+    });
+
+    expect(sendWebhookMessageDiscord).toHaveBeenCalledTimes(1);
+    expect(sendWebhookMessageDiscord.mock.calls[0]?.[1]).toMatchObject({
+      cfg,
+      webhookId: "wh_1",
+      webhookToken: "tok_1",
+      accountId: "default",
+      threadId: "thread-1",
+    });
+    expect(sendMessageDiscord).not.toHaveBeenCalled();
+  });
+});

package/src/monitor/thread-bindings.discord-api.ts

@@ -0,0 +1,318 @@
+import { ChannelType } from "discord-api-types/v10";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { logVerbose } from "openclaw/plugin-sdk/runtime-env";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+import { createDiscordRestClient } from "../client.js";
+import { createChannelWebhook, getChannel } from "../internal/discord.js";
+import { sendMessageDiscord, sendWebhookMessageDiscord } from "../send.js";
+import { createThreadDiscord } from "../send.messages.js";
+import { resolveDiscordChannelId } from "../target-parsing.js";
+import { resolveThreadBindingPersonaFromRecord } from "./thread-bindings.persona.js";
+import {
+  BINDINGS_BY_THREAD_ID,
+  REUSABLE_WEBHOOKS_BY_ACCOUNT_CHANNEL,
+  rememberReusableWebhook,
+  toReusableWebhookKey,
+} from "./thread-bindings.state.js";
+import {
+  DISCORD_UNKNOWN_CHANNEL_ERROR_CODE,
+  type ThreadBindingRecord,
+} from "./thread-bindings.types.js";
+
+function buildThreadTarget(threadId: string): string {
+  return /^(channel:|user:)/i.test(threadId) ? threadId : `channel:${threadId}`;
+}
+
+export function isThreadArchived(raw: unknown): boolean {
+  if (!raw || typeof raw !== "object") {
+    return false;
+  }
+  const asRecord = raw as {
+    archived?: unknown;
+    thread_metadata?: { archived?: unknown };
+    threadMetadata?: { archived?: unknown };
+  };
+  if (asRecord.archived === true) {
+    return true;
+  }
+  if (asRecord.thread_metadata?.archived === true) {
+    return true;
+  }
+  if (asRecord.threadMetadata?.archived === true) {
+    return true;
+  }
+  return false;
+}
+
+function isThreadChannelType(type: unknown): boolean {
+  return (
+    type === ChannelType.PublicThread ||
+    type === ChannelType.PrivateThread ||
+    type === ChannelType.AnnouncementThread
+  );
+}
+
+function normalizeDiscordBindingChannelId(raw?: string | null): string | null {
+  const trimmed = normalizeOptionalString(raw) ?? "";
+  if (!trimmed) {
+    return null;
+  }
+  try {
+    return resolveDiscordChannelId(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+export function summarizeDiscordError(err: unknown): string {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  if (typeof err === "string") {
+    return err;
+  }
+  if (
+    typeof err === "number" ||
+    typeof err === "boolean" ||
+    typeof err === "bigint" ||
+    typeof err === "symbol"
+  ) {
+    return String(err);
+  }
+  return "error";
+}
+
+function extractNumericDiscordErrorValue(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return Math.trunc(value);
+  }
+  if (typeof value === "string" && /^\d+$/.test(value.trim())) {
+    return Number(value);
+  }
+  return undefined;
+}
+
+function extractDiscordErrorStatus(err: unknown): number | undefined {
+  if (!err || typeof err !== "object") {
+    return undefined;
+  }
+  const candidate = err as {
+    status?: unknown;
+    statusCode?: unknown;
+    response?: { status?: unknown };
+  };
+  return (
+    extractNumericDiscordErrorValue(candidate.status) ??
+    extractNumericDiscordErrorValue(candidate.statusCode) ??
+    extractNumericDiscordErrorValue(candidate.response?.status)
+  );
+}
+
+function extractDiscordErrorCode(err: unknown): number | undefined {
+  if (!err || typeof err !== "object") {
+    return undefined;
+  }
+  const candidate = err as {
+    code?: unknown;
+    rawError?: { code?: unknown };
+    body?: { code?: unknown };
+    response?: { body?: { code?: unknown }; data?: { code?: unknown } };
+  };
+  return (
+    extractNumericDiscordErrorValue(candidate.code) ??
+    extractNumericDiscordErrorValue(candidate.rawError?.code) ??
+    extractNumericDiscordErrorValue(candidate.body?.code) ??
+    extractNumericDiscordErrorValue(candidate.response?.body?.code) ??
+    extractNumericDiscordErrorValue(candidate.response?.data?.code)
+  );
+}
+
+export function isDiscordThreadGoneError(err: unknown): boolean {
+  const code = extractDiscordErrorCode(err);
+  if (code === DISCORD_UNKNOWN_CHANNEL_ERROR_CODE) {
+    return true;
+  }
+  const status = extractDiscordErrorStatus(err);
+  // 404: deleted/unknown channel. 403: bot no longer has access.
+  return status === 404 || status === 403;
+}
+
+export async function maybeSendBindingMessage(params: {
+  cfg: OpenClawConfig;
+  record: ThreadBindingRecord;
+  text: string;
+  preferWebhook?: boolean;
+}) {
+  const text = params.text.trim();
+  if (!text) {
+    return;
+  }
+  const record = params.record;
+  if (params.preferWebhook !== false && record.webhookId && record.webhookToken) {
+    try {
+      await sendWebhookMessageDiscord(text, {
+        cfg: params.cfg,
+        webhookId: record.webhookId,
+        webhookToken: record.webhookToken,
+        accountId: record.accountId,
+        threadId: record.threadId,
+        username: resolveThreadBindingPersonaFromRecord(record),
+      });
+      return;
+    } catch (err) {
+      logVerbose(`discord thread binding webhook send failed: ${summarizeDiscordError(err)}`);
+    }
+  }
+  try {
+    await sendMessageDiscord(buildThreadTarget(record.threadId), text, {
+      cfg: params.cfg,
+      accountId: record.accountId,
+    });
+  } catch (err) {
+    logVerbose(`discord thread binding fallback send failed: ${summarizeDiscordError(err)}`);
+  }
+}
+
+export async function createWebhookForChannel(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  token?: string;
+  channelId: string;
+}): Promise<{ webhookId?: string; webhookToken?: string }> {
+  try {
+    const rest = createDiscordRestClient({
+      cfg: params.cfg,
+      accountId: params.accountId,
+      token: params.token,
+    }).rest;
+    const created = await createChannelWebhook(rest, params.channelId, {
+      body: {
+        name: "OpenClaw Agents",
+      },
+    });
+    const webhookId = normalizeOptionalString(created?.id) ?? "";
+    const webhookToken = normalizeOptionalString(created?.token) ?? "";
+    if (!webhookId || !webhookToken) {
+      return {};
+    }
+    return { webhookId, webhookToken };
+  } catch (err) {
+    logVerbose(
+      `discord thread binding webhook create failed for ${params.channelId}: ${summarizeDiscordError(err)}`,
+    );
+    return {};
+  }
+}
+
+export function findReusableWebhook(params: { accountId: string; channelId: string }): {
+  webhookId?: string;
+  webhookToken?: string;
+} {
+  const reusableKey = toReusableWebhookKey({
+    accountId: params.accountId,
+    channelId: params.channelId,
+  });
+  const cached = REUSABLE_WEBHOOKS_BY_ACCOUNT_CHANNEL.get(reusableKey);
+  if (cached) {
+    return {
+      webhookId: cached.webhookId,
+      webhookToken: cached.webhookToken,
+    };
+  }
+  for (const record of BINDINGS_BY_THREAD_ID.values()) {
+    if (record.accountId !== params.accountId) {
+      continue;
+    }
+    if (record.channelId !== params.channelId) {
+      continue;
+    }
+    if (!record.webhookId || !record.webhookToken) {
+      continue;
+    }
+    rememberReusableWebhook(record);
+    return {
+      webhookId: record.webhookId,
+      webhookToken: record.webhookToken,
+    };
+  }
+  return {};
+}
+
+export async function resolveChannelIdForBinding(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  token?: string;
+  threadId: string;
+  channelId?: string;
+}): Promise<string | null> {
+  const explicit = normalizeDiscordBindingChannelId(params.channelId);
+  if (explicit) {
+    return explicit;
+  }
+  const lookupThreadId = normalizeDiscordBindingChannelId(params.threadId);
+  if (!lookupThreadId) {
+    return null;
+  }
+  try {
+    const rest = createDiscordRestClient({
+      cfg: params.cfg,
+      accountId: params.accountId,
+      token: params.token,
+    }).rest;
+    const channel = (await getChannel(rest, lookupThreadId)) as {
+      id?: string;
+      type?: number;
+      parent_id?: string;
+      parentId?: string;
+    };
+    const channelId = normalizeOptionalString(channel?.id) ?? "";
+    const type = channel?.type;
+    const parentId =
+      typeof channel?.parent_id === "string"
+        ? channel.parent_id.trim()
+        : typeof channel?.parentId === "string"
+          ? channel.parentId.trim()
+          : "";
+    // Only thread channels should resolve to their parent channel.
+    // Non-thread channels (text/forum/media) must keep their own ID.
+    if (parentId && isThreadChannelType(type)) {
+      return parentId;
+    }
+    return channelId || null;
+  } catch (err) {
+    logVerbose(
+      `discord thread binding channel resolve failed for ${lookupThreadId}: ${summarizeDiscordError(err)}`,
+    );
+    return null;
+  }
+}
+
+export async function createThreadForBinding(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  token?: string;
+  channelId: string;
+  threadName: string;
+}): Promise<string | null> {
+  try {
+    const created = await createThreadDiscord(
+      params.channelId,
+      {
+        name: params.threadName,
+        autoArchiveMinutes: 60,
+      },
+      {
+        cfg: params.cfg,
+        accountId: params.accountId,
+        token: params.token,
+      },
+    );
+    const createdId = normalizeOptionalString(created?.id) ?? "";
+    return createdId || null;
+  } catch (err) {
+    logVerbose(
+      `discord thread binding auto-thread create failed for ${params.channelId}: ${summarizeDiscordError(err)}`,
+    );
+    return null;
+  }
+}