@openclaw/feishu 2026.2.24 → 2026.3.1

package/src/monitor.reaction.test.ts

@@ -0,0 +1,235 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+import { describe, expect, it, vi } from "vitest";
+import { resolveReactionSyntheticEvent, type FeishuReactionCreatedEvent } from "./monitor.js";
+
+const cfg = {} as ClawdbotConfig;
+
+function makeReactionEvent(
+  overrides: Partial<FeishuReactionCreatedEvent> = {},
+): FeishuReactionCreatedEvent {
+  return {
+    message_id: "om_msg1",
+    reaction_type: { emoji_type: "THUMBSUP" },
+    operator_type: "user",
+    user_id: { open_id: "ou_user1" },
+    ...overrides,
+  };
+}
+
+describe("resolveReactionSyntheticEvent", () => {
+  it("filters app self-reactions", async () => {
+    const event = makeReactionEvent({ operator_type: "app" });
+    const result = await resolveReactionSyntheticEvent({
+      cfg,
+      accountId: "default",
+      event,
+      botOpenId: "ou_bot",
+    });
+    expect(result).toBeNull();
+  });
+
+  it("filters Typing reactions", async () => {
+    const event = makeReactionEvent({ reaction_type: { emoji_type: "Typing" } });
+    const result = await resolveReactionSyntheticEvent({
+      cfg,
+      accountId: "default",
+      event,
+      botOpenId: "ou_bot",
+    });
+    expect(result).toBeNull();
+  });
+
+  it("fails closed when bot open_id is unavailable", async () => {
+    const event = makeReactionEvent();
+    const result = await resolveReactionSyntheticEvent({
+      cfg,
+      accountId: "default",
+      event,
+    });
+    expect(result).toBeNull();
+  });
+
+  it("drops reactions when reactionNotifications is off", async () => {
+    const event = makeReactionEvent();
+    const result = await resolveReactionSyntheticEvent({
+      cfg: {
+        channels: {
+          feishu: {
+            reactionNotifications: "off",
+          },
+        },
+      } as ClawdbotConfig,
+      accountId: "default",
+      event,
+      botOpenId: "ou_bot",
+      fetchMessage: async () => ({
+        messageId: "om_msg1",
+        chatId: "oc_group",
+        senderOpenId: "ou_bot",
+        senderType: "app",
+        content: "hello",
+        contentType: "text",
+      }),
+    });
+    expect(result).toBeNull();
+  });
+
+  it("filters reactions on non-bot messages", async () => {
+    const event = makeReactionEvent();
+    const result = await resolveReactionSyntheticEvent({
+      cfg,
+      accountId: "default",
+      event,
+      botOpenId: "ou_bot",
+      fetchMessage: async () => ({
+        messageId: "om_msg1",
+        chatId: "oc_group",
+        senderOpenId: "ou_other",
+        senderType: "user",
+        content: "hello",
+        contentType: "text",
+      }),
+    });
+    expect(result).toBeNull();
+  });
+
+  it("allows non-bot reactions when reactionNotifications is all", async () => {
+    const event = makeReactionEvent();
+    const result = await resolveReactionSyntheticEvent({
+      cfg: {
+        channels: {
+          feishu: {
+            reactionNotifications: "all",
+          },
+        },
+      } as ClawdbotConfig,
+      accountId: "default",
+      event,
+      botOpenId: "ou_bot",
+      fetchMessage: async () => ({
+        messageId: "om_msg1",
+        chatId: "oc_group",
+        senderOpenId: "ou_other",
+        senderType: "user",
+        content: "hello",
+        contentType: "text",
+      }),
+      uuid: () => "fixed-uuid",
+    });
+    expect(result?.message.message_id).toBe("om_msg1:reaction:THUMBSUP:fixed-uuid");
+  });
+
+  it("drops unverified reactions when sender verification times out", async () => {
+    const event = makeReactionEvent();
+    const result = await resolveReactionSyntheticEvent({
+      cfg,
+      accountId: "default",
+      event,
+      botOpenId: "ou_bot",
+      verificationTimeoutMs: 1,
+      fetchMessage: async () =>
+        await new Promise<never>(() => {
+          // Never resolves
+        }),
+    });
+    expect(result).toBeNull();
+  });
+
+  it("uses event chat context when provided", async () => {
+    const event = makeReactionEvent({
+      chat_id: "oc_group_from_event",
+      chat_type: "group",
+    });
+    const result = await resolveReactionSyntheticEvent({
+      cfg,
+      accountId: "default",
+      event,
+      botOpenId: "ou_bot",
+      fetchMessage: async () => ({
+        messageId: "om_msg1",
+        chatId: "oc_group_from_lookup",
+        senderOpenId: "ou_bot",
+        content: "hello",
+        contentType: "text",
+      }),
+      uuid: () => "fixed-uuid",
+    });
+
+    expect(result).toEqual({
+      sender: {
+        sender_id: { open_id: "ou_user1" },
+        sender_type: "user",
+      },
+      message: {
+        message_id: "om_msg1:reaction:THUMBSUP:fixed-uuid",
+        chat_id: "oc_group_from_event",
+        chat_type: "group",
+        message_type: "text",
+        content: JSON.stringify({
+          text: "[reacted with THUMBSUP to message om_msg1]",
+        }),
+      },
+    });
+  });
+
+  it("falls back to reacted message chat_id when event chat_id is absent", async () => {
+    const event = makeReactionEvent();
+    const result = await resolveReactionSyntheticEvent({
+      cfg,
+      accountId: "default",
+      event,
+      botOpenId: "ou_bot",
+      fetchMessage: async () => ({
+        messageId: "om_msg1",
+        chatId: "oc_group_from_lookup",
+        senderOpenId: "ou_bot",
+        content: "hello",
+        contentType: "text",
+      }),
+      uuid: () => "fixed-uuid",
+    });
+
+    expect(result?.message.chat_id).toBe("oc_group_from_lookup");
+    expect(result?.message.chat_type).toBe("p2p");
+  });
+
+  it("falls back to sender p2p chat when lookup returns empty chat_id", async () => {
+    const event = makeReactionEvent();
+    const result = await resolveReactionSyntheticEvent({
+      cfg,
+      accountId: "default",
+      event,
+      botOpenId: "ou_bot",
+      fetchMessage: async () => ({
+        messageId: "om_msg1",
+        chatId: "",
+        senderOpenId: "ou_bot",
+        content: "hello",
+        contentType: "text",
+      }),
+      uuid: () => "fixed-uuid",
+    });
+
+    expect(result?.message.chat_id).toBe("p2p:ou_user1");
+    expect(result?.message.chat_type).toBe("p2p");
+  });
+
+  it("logs and drops reactions when lookup throws", async () => {
+    const log = vi.fn();
+    const event = makeReactionEvent();
+    const result = await resolveReactionSyntheticEvent({
+      cfg,
+      accountId: "acct1",
+      event,
+      botOpenId: "ou_bot",
+      fetchMessage: async () => {
+        throw new Error("boom");
+      },
+      logger: log,
+    });
+    expect(result).toBeNull();
+    expect(log).toHaveBeenCalledWith(
+      expect.stringContaining("ignoring reaction on non-bot/unverified message om_msg1"),
+    );
+  });
+});

package/src/monitor.startup.test.ts

@@ -0,0 +1,187 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const probeFeishuMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./probe.js", () => ({
+  probeFeishu: probeFeishuMock,
+}));
+
+vi.mock("./client.js", () => ({
+  createFeishuWSClient: vi.fn(() => ({ start: vi.fn() })),
+  createEventDispatcher: vi.fn(() => ({ register: vi.fn() })),
+}));
+
+import { monitorFeishuProvider, stopFeishuMonitor } from "./monitor.js";
+
+function buildMultiAccountWebsocketConfig(accountIds: string[]): ClawdbotConfig {
+  return {
+    channels: {
+      feishu: {
+        enabled: true,
+        accounts: Object.fromEntries(
+          accountIds.map((accountId) => [
+            accountId,
+            {
+              enabled: true,
+              appId: `cli_${accountId}`,
+              appSecret: `secret_${accountId}`,
+              connectionMode: "websocket",
+            },
+          ]),
+        ),
+      },
+    },
+  } as ClawdbotConfig;
+}
+
+afterEach(() => {
+  stopFeishuMonitor();
+});
+
+describe("Feishu monitor startup preflight", () => {
+  it("starts account probes sequentially to avoid startup bursts", async () => {
+    let inFlight = 0;
+    let maxInFlight = 0;
+    const started: string[] = [];
+    let releaseProbes!: () => void;
+    const probesReleased = new Promise<void>((resolve) => {
+      releaseProbes = () => resolve();
+    });
+    probeFeishuMock.mockImplementation(async (account: { accountId: string }) => {
+      started.push(account.accountId);
+      inFlight += 1;
+      maxInFlight = Math.max(maxInFlight, inFlight);
+      await probesReleased;
+      inFlight -= 1;
+      return { ok: true, botOpenId: `bot_${account.accountId}` };
+    });
+
+    const abortController = new AbortController();
+    const monitorPromise = monitorFeishuProvider({
+      config: buildMultiAccountWebsocketConfig(["alpha", "beta", "gamma"]),
+      abortSignal: abortController.signal,
+    });
+
+    try {
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(started).toEqual(["alpha"]);
+      expect(maxInFlight).toBe(1);
+    } finally {
+      releaseProbes();
+      abortController.abort();
+      await monitorPromise;
+    }
+  });
+
+  it("does not refetch bot info after a failed sequential preflight", async () => {
+    const started: string[] = [];
+    let releaseBetaProbe!: () => void;
+    const betaProbeReleased = new Promise<void>((resolve) => {
+      releaseBetaProbe = () => resolve();
+    });
+
+    probeFeishuMock.mockImplementation(async (account: { accountId: string }) => {
+      started.push(account.accountId);
+      if (account.accountId === "alpha") {
+        return { ok: false };
+      }
+      await betaProbeReleased;
+      return { ok: true, botOpenId: `bot_${account.accountId}` };
+    });
+
+    const abortController = new AbortController();
+    const monitorPromise = monitorFeishuProvider({
+      config: buildMultiAccountWebsocketConfig(["alpha", "beta"]),
+      abortSignal: abortController.signal,
+    });
+
+    try {
+      for (let i = 0; i < 10 && !started.includes("beta"); i += 1) {
+        await Promise.resolve();
+      }
+
+      expect(started).toEqual(["alpha", "beta"]);
+      expect(started.filter((accountId) => accountId === "alpha")).toHaveLength(1);
+    } finally {
+      releaseBetaProbe();
+      abortController.abort();
+      await monitorPromise;
+    }
+  });
+
+  it("continues startup when probe layer reports timeout", async () => {
+    const started: string[] = [];
+    let releaseBetaProbe!: () => void;
+    const betaProbeReleased = new Promise<void>((resolve) => {
+      releaseBetaProbe = () => resolve();
+    });
+
+    probeFeishuMock.mockImplementation((account: { accountId: string }) => {
+      started.push(account.accountId);
+      if (account.accountId === "alpha") {
+        return Promise.resolve({ ok: false, error: "probe timed out after 10000ms" });
+      }
+      return betaProbeReleased.then(() => ({ ok: true, botOpenId: `bot_${account.accountId}` }));
+    });
+
+    const abortController = new AbortController();
+    const runtime = { log: vi.fn(), error: vi.fn(), exit: vi.fn() };
+    const monitorPromise = monitorFeishuProvider({
+      config: buildMultiAccountWebsocketConfig(["alpha", "beta"]),
+      runtime,
+      abortSignal: abortController.signal,
+    });
+
+    try {
+      for (let i = 0; i < 10 && !started.includes("beta"); i += 1) {
+        await Promise.resolve();
+      }
+
+      expect(started).toEqual(["alpha", "beta"]);
+      expect(runtime.error).toHaveBeenCalledWith(
+        expect.stringContaining("bot info probe timed out"),
+      );
+    } finally {
+      releaseBetaProbe();
+      abortController.abort();
+      await monitorPromise;
+    }
+  });
+
+  it("stops sequential preflight when aborted during probe", async () => {
+    const started: string[] = [];
+    probeFeishuMock.mockImplementation(
+      (account: { accountId: string }, options: { abortSignal?: AbortSignal }) => {
+        started.push(account.accountId);
+        return new Promise((resolve) => {
+          options.abortSignal?.addEventListener(
+            "abort",
+            () => resolve({ ok: false, error: "probe aborted" }),
+            { once: true },
+          );
+        });
+      },
+    );
+
+    const abortController = new AbortController();
+    const monitorPromise = monitorFeishuProvider({
+      config: buildMultiAccountWebsocketConfig(["alpha", "beta"]),
+      abortSignal: abortController.signal,
+    });
+
+    try {
+      await Promise.resolve();
+      expect(started).toEqual(["alpha"]);
+
+      abortController.abort();
+      await monitorPromise;
+
+      expect(started).toEqual(["alpha"]);
+    } finally {
+      abortController.abort();
+    }
+  });
+});

package/src/monitor.startup.ts

@@ -0,0 +1,51 @@
+import type { RuntimeEnv } from "openclaw/plugin-sdk";
+import { probeFeishu } from "./probe.js";
+import type { ResolvedFeishuAccount } from "./types.js";
+
+export const FEISHU_STARTUP_BOT_INFO_TIMEOUT_MS = 10_000;
+
+type FetchBotOpenIdOptions = {
+  runtime?: RuntimeEnv;
+  abortSignal?: AbortSignal;
+  timeoutMs?: number;
+};
+
+function isTimeoutErrorMessage(message: string | undefined): boolean {
+  return message?.toLowerCase().includes("timeout") || message?.toLowerCase().includes("timed out")
+    ? true
+    : false;
+}
+
+function isAbortErrorMessage(message: string | undefined): boolean {
+  return message?.toLowerCase().includes("aborted") ?? false;
+}
+
+export async function fetchBotOpenIdForMonitor(
+  account: ResolvedFeishuAccount,
+  options: FetchBotOpenIdOptions = {},
+): Promise<string | undefined> {
+  if (options.abortSignal?.aborted) {
+    return undefined;
+  }
+
+  const timeoutMs = options.timeoutMs ?? FEISHU_STARTUP_BOT_INFO_TIMEOUT_MS;
+  const result = await probeFeishu(account, {
+    timeoutMs,
+    abortSignal: options.abortSignal,
+  });
+  if (result.ok) {
+    return result.botOpenId;
+  }
+
+  if (options.abortSignal?.aborted || isAbortErrorMessage(result.error)) {
+    return undefined;
+  }
+
+  if (isTimeoutErrorMessage(result.error)) {
+    const error = options.runtime?.error ?? console.error;
+    error(
+      `feishu[${account.accountId}]: bot info probe timed out after ${timeoutMs}ms; continuing startup`,
+    );
+  }
+  return undefined;
+}

package/src/monitor.state.ts

@@ -0,0 +1,76 @@
+import * as http from "http";
+import * as Lark from "@larksuiteoapi/node-sdk";
+import {
+  createFixedWindowRateLimiter,
+  createWebhookAnomalyTracker,
+  type RuntimeEnv,
+  WEBHOOK_ANOMALY_COUNTER_DEFAULTS,
+  WEBHOOK_RATE_LIMIT_DEFAULTS,
+} from "openclaw/plugin-sdk";
+
+export const wsClients = new Map<string, Lark.WSClient>();
+export const httpServers = new Map<string, http.Server>();
+export const botOpenIds = new Map<string, string>();
+
+export const FEISHU_WEBHOOK_MAX_BODY_BYTES = 1024 * 1024;
+export const FEISHU_WEBHOOK_BODY_TIMEOUT_MS = 30_000;
+
+export const feishuWebhookRateLimiter = createFixedWindowRateLimiter({
+  windowMs: WEBHOOK_RATE_LIMIT_DEFAULTS.windowMs,
+  maxRequests: WEBHOOK_RATE_LIMIT_DEFAULTS.maxRequests,
+  maxTrackedKeys: WEBHOOK_RATE_LIMIT_DEFAULTS.maxTrackedKeys,
+});
+
+const feishuWebhookAnomalyTracker = createWebhookAnomalyTracker({
+  maxTrackedKeys: WEBHOOK_ANOMALY_COUNTER_DEFAULTS.maxTrackedKeys,
+  ttlMs: WEBHOOK_ANOMALY_COUNTER_DEFAULTS.ttlMs,
+  logEvery: WEBHOOK_ANOMALY_COUNTER_DEFAULTS.logEvery,
+});
+
+export function clearFeishuWebhookRateLimitStateForTest(): void {
+  feishuWebhookRateLimiter.clear();
+  feishuWebhookAnomalyTracker.clear();
+}
+
+export function getFeishuWebhookRateLimitStateSizeForTest(): number {
+  return feishuWebhookRateLimiter.size();
+}
+
+export function isWebhookRateLimitedForTest(key: string, nowMs: number): boolean {
+  return feishuWebhookRateLimiter.isRateLimited(key, nowMs);
+}
+
+export function recordWebhookStatus(
+  runtime: RuntimeEnv | undefined,
+  accountId: string,
+  path: string,
+  statusCode: number,
+): void {
+  feishuWebhookAnomalyTracker.record({
+    key: `${accountId}:${path}:${statusCode}`,
+    statusCode,
+    log: runtime?.log ?? console.log,
+    message: (count) =>
+      `feishu[${accountId}]: webhook anomaly path=${path} status=${statusCode} count=${count}`,
+  });
+}
+
+export function stopFeishuMonitorState(accountId?: string): void {
+  if (accountId) {
+    wsClients.delete(accountId);
+    const server = httpServers.get(accountId);
+    if (server) {
+      server.close();
+      httpServers.delete(accountId);
+    }
+    botOpenIds.delete(accountId);
+    return;
+  }
+
+  wsClients.clear();
+  for (const server of httpServers.values()) {
+    server.close();
+  }
+  httpServers.clear();
+  botOpenIds.clear();
+}

package/src/monitor.transport.ts

@@ -0,0 +1,163 @@
+import * as http from "http";
+import * as Lark from "@larksuiteoapi/node-sdk";
+import {
+  applyBasicWebhookRequestGuards,
+  type RuntimeEnv,
+  installRequestBodyLimitGuard,
+} from "openclaw/plugin-sdk";
+import { createFeishuWSClient } from "./client.js";
+import {
+  botOpenIds,
+  FEISHU_WEBHOOK_BODY_TIMEOUT_MS,
+  FEISHU_WEBHOOK_MAX_BODY_BYTES,
+  feishuWebhookRateLimiter,
+  httpServers,
+  recordWebhookStatus,
+  wsClients,
+} from "./monitor.state.js";
+import type { ResolvedFeishuAccount } from "./types.js";
+
+export type MonitorTransportParams = {
+  account: ResolvedFeishuAccount;
+  accountId: string;
+  runtime?: RuntimeEnv;
+  abortSignal?: AbortSignal;
+  eventDispatcher: Lark.EventDispatcher;
+};
+
+export async function monitorWebSocket({
+  account,
+  accountId,
+  runtime,
+  abortSignal,
+  eventDispatcher,
+}: MonitorTransportParams): Promise<void> {
+  const log = runtime?.log ?? console.log;
+  log(`feishu[${accountId}]: starting WebSocket connection...`);
+
+  const wsClient = createFeishuWSClient(account);
+  wsClients.set(accountId, wsClient);
+
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      wsClients.delete(accountId);
+      botOpenIds.delete(accountId);
+    };
+
+    const handleAbort = () => {
+      log(`feishu[${accountId}]: abort signal received, stopping`);
+      cleanup();
+      resolve();
+    };
+
+    if (abortSignal?.aborted) {
+      cleanup();
+      resolve();
+      return;
+    }
+
+    abortSignal?.addEventListener("abort", handleAbort, { once: true });
+
+    try {
+      wsClient.start({ eventDispatcher });
+      log(`feishu[${accountId}]: WebSocket client started`);
+    } catch (err) {
+      cleanup();
+      abortSignal?.removeEventListener("abort", handleAbort);
+      reject(err);
+    }
+  });
+}
+
+export async function monitorWebhook({
+  account,
+  accountId,
+  runtime,
+  abortSignal,
+  eventDispatcher,
+}: MonitorTransportParams): Promise<void> {
+  const log = runtime?.log ?? console.log;
+  const error = runtime?.error ?? console.error;
+
+  const port = account.config.webhookPort ?? 3000;
+  const path = account.config.webhookPath ?? "/feishu/events";
+  const host = account.config.webhookHost ?? "127.0.0.1";
+
+  log(`feishu[${accountId}]: starting Webhook server on ${host}:${port}, path ${path}...`);
+
+  const server = http.createServer();
+  const webhookHandler = Lark.adaptDefault(path, eventDispatcher, { autoChallenge: true });
+
+  server.on("request", (req, res) => {
+    res.on("finish", () => {
+      recordWebhookStatus(runtime, accountId, path, res.statusCode);
+    });
+
+    const rateLimitKey = `${accountId}:${path}:${req.socket.remoteAddress ?? "unknown"}`;
+    if (
+      !applyBasicWebhookRequestGuards({
+        req,
+        res,
+        rateLimiter: feishuWebhookRateLimiter,
+        rateLimitKey,
+        nowMs: Date.now(),
+        requireJsonContentType: true,
+      })
+    ) {
+      return;
+    }
+
+    const guard = installRequestBodyLimitGuard(req, res, {
+      maxBytes: FEISHU_WEBHOOK_MAX_BODY_BYTES,
+      timeoutMs: FEISHU_WEBHOOK_BODY_TIMEOUT_MS,
+      responseFormat: "text",
+    });
+    if (guard.isTripped()) {
+      return;
+    }
+
+    void Promise.resolve(webhookHandler(req, res))
+      .catch((err) => {
+        if (!guard.isTripped()) {
+          error(`feishu[${accountId}]: webhook handler error: ${String(err)}`);
+        }
+      })
+      .finally(() => {
+        guard.dispose();
+      });
+  });
+
+  httpServers.set(accountId, server);
+
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      server.close();
+      httpServers.delete(accountId);
+      botOpenIds.delete(accountId);
+    };
+
+    const handleAbort = () => {
+      log(`feishu[${accountId}]: abort signal received, stopping Webhook server`);
+      cleanup();
+      resolve();
+    };
+
+    if (abortSignal?.aborted) {
+      cleanup();
+      resolve();
+      return;
+    }
+
+    abortSignal?.addEventListener("abort", handleAbort, { once: true });
+
+    server.listen(port, host, () => {
+      log(`feishu[${accountId}]: Webhook server listening on ${host}:${port}`);
+    });
+
+    server.on("error", (err) => {
+      error(`feishu[${accountId}]: Webhook server error: ${err}`);
+      abortSignal?.removeEventListener("abort", handleAbort);
+      reject(err);
+    });
+  });
+}