@feihan-im/openclaw-plugin 0.1.0

package/src/messaging/inbound.ts

@@ -0,0 +1,396 @@
+// Copyright (c) 2026 上海飞函安全科技有限公司 (Shanghai Feihan Security Technology Co., Ltd.)
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Inbound message processing pipeline for Feihan IM.
+ *
+ * Pipeline: parse -> gate -> dedup -> build context -> dispatch
+ *
+ * Codes against the FeihanClient interface contract (task 99) —
+ * the client is not imported here; this module receives parsed events.
+ */
+
+import type {
+  FeihanAccountConfig,
+  FeihanMessage,
+  FeihanMessageEvent,
+  PluginApi,
+} from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Parse — extract usable text body from incoming message
+// ---------------------------------------------------------------------------
+
+export interface ParsedInboundMessage {
+  messageId: string;
+  chatId: string;
+  chatType: "direct" | "group";
+  senderId: string;
+  body: string;
+  timestamp: number;
+  mentionUserIds: string[];
+}
+
+/**
+ * Normalize a raw Feihan message event into a structured inbound message.
+ * Returns `null` if the event cannot be parsed into a usable message.
+ *
+ * Only text messages are supported in this phase — media/card/file are
+ * follow-up work (task 08).
+ */
+export function parseMessageEvent(
+  event: FeihanMessageEvent,
+): ParsedInboundMessage | null {
+  const msg = event?.message;
+  if (!msg || !msg.messageId || !msg.chatId) return null;
+
+  const body = extractTextBody(msg);
+  if (body === null) return null;
+
+  const chatType = msg.chatType === "group" ? "group" : "direct";
+
+  const senderId =
+    msg.sender?.userId || msg.sender?.openUserId || msg.sender?.unionUserId;
+  if (!senderId) return null;
+
+  const mentionUserIds = (msg.mentionUserList ?? [])
+    .map((u) => u.userId || u.openUserId || u.unionUserId || "")
+    .filter(Boolean);
+
+  return {
+    messageId: msg.messageId,
+    chatId: msg.chatId,
+    chatType,
+    senderId,
+    body,
+    timestamp: msg.createdAt ?? Date.now(),
+    mentionUserIds,
+  };
+}
+
+/**
+ * Extract plain-text content from a Feihan message.
+ * Returns `null` for non-text or empty messages.
+ */
+function extractTextBody(msg: FeihanMessage): string | null {
+  if (msg.messageType !== "text") return null;
+
+  const content = msg.messageContent;
+  if (typeof content === "string") {
+    // Content may be JSON-encoded string (Feihan convention)
+    try {
+      const parsed = JSON.parse(content);
+      // Feihan format: { text: { content: "Hello" } }
+      if (parsed?.text && typeof parsed.text === "object" && typeof parsed.text.content === "string")
+        return parsed.text.content.trim() || null;
+      if (typeof parsed?.text === "string") return parsed.text.trim() || null;
+      if (typeof parsed?.content === "string")
+        return parsed.content.trim() || null;
+      // Fall through to raw string
+    } catch {
+      // Not JSON — use raw string
+    }
+    return content.trim() || null;
+  }
+
+  if (content && typeof content === "object") {
+    const obj = content as Record<string, unknown>;
+    // Feihan format: { text: { content: "Hello" } }
+    if (obj.text && typeof obj.text === "object") {
+      const textObj = obj.text as Record<string, unknown>;
+      if (typeof textObj.content === "string") return textObj.content.trim() || null;
+    }
+    if (typeof obj.text === "string") return obj.text.trim() || null;
+    if (typeof obj.content === "string") return obj.content.trim() || null;
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Gate — filter out messages the plugin should not process
+// ---------------------------------------------------------------------------
+
+export interface GateResult {
+  pass: boolean;
+  reason?: string;
+}
+
+/**
+ * Determine whether a parsed inbound message should be processed.
+ * Checks in order: self-message, whitelist, group mention requirement.
+ */
+export function checkMessageGate(
+  msg: ParsedInboundMessage,
+  account: FeihanAccountConfig,
+): GateResult {
+  // 1. Self-message filter: ignore messages from the bot itself
+  if (account.botUserId && msg.senderId === account.botUserId) {
+    return { pass: false, reason: "self-message" };
+  }
+
+  // 2. Whitelist filter: if whitelist is non-empty, only allow listed senders
+  if (account.inboundWhitelist.length > 0) {
+    if (!account.inboundWhitelist.includes(msg.senderId)) {
+      return { pass: false, reason: "sender-not-in-whitelist" };
+    }
+  }
+
+  // 3. Group mention filter: in group chats, require @mention if configured
+  if (
+    msg.chatType === "group" &&
+    account.requireMention &&
+    !isBotMentioned(msg, account)
+  ) {
+    return { pass: false, reason: "group-no-mention" };
+  }
+
+  return { pass: true };
+}
+
+/**
+ * Check if the bot was @mentioned in a message.
+ */
+export function isBotMentioned(
+  msg: ParsedInboundMessage,
+  account: FeihanAccountConfig,
+): boolean {
+  if (!account.botUserId) return false;
+  return msg.mentionUserIds.includes(account.botUserId);
+}
+
+// ---------------------------------------------------------------------------
+// Dedup — skip already-processed message IDs
+// ---------------------------------------------------------------------------
+
+const DEDUP_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const DEDUP_CLEANUP_INTERVAL_MS = 60 * 1000; // clean every 1 minute
+const DEDUP_MAX_SIZE = 10_000;
+
+/** In-memory set of recently processed message IDs with TTL. */
+const processedMessages = new Map<string, number>();
+let lastCleanup = Date.now();
+
+/**
+ * Returns `true` if the message has already been processed (duplicate).
+ * Records the message ID on first encounter.
+ */
+export function isDuplicate(messageId: string): boolean {
+  cleanupIfNeeded();
+
+  if (processedMessages.has(messageId)) return true;
+
+  processedMessages.set(messageId, Date.now());
+  return false;
+}
+
+function cleanupIfNeeded(): void {
+  const now = Date.now();
+  if (now - lastCleanup < DEDUP_CLEANUP_INTERVAL_MS) return;
+  lastCleanup = now;
+
+  const expiry = now - DEDUP_TTL_MS;
+  for (const [id, ts] of processedMessages) {
+    if (ts < expiry) processedMessages.delete(id);
+  }
+
+  // Hard cap to prevent unbounded growth
+  if (processedMessages.size > DEDUP_MAX_SIZE) {
+    const excess = processedMessages.size - DEDUP_MAX_SIZE;
+    const iter = processedMessages.keys();
+    for (let i = 0; i < excess; i++) {
+      const key = iter.next().value;
+      if (key !== undefined) processedMessages.delete(key);
+    }
+  }
+}
+
+/** Reset dedup state — exposed for testing only. */
+export function _resetDedup(): void {
+  processedMessages.clear();
+  lastCleanup = Date.now();
+}
+
+// ---------------------------------------------------------------------------
+// Build context & dispatch
+// ---------------------------------------------------------------------------
+
+export interface InboundContext {
+  Body: string;
+  From: string;
+  To: string;
+  SessionKey: string;
+  AccountId: string;
+  ChatType: "direct" | "group";
+  Provider: "feihan";
+  Surface: "feihan";
+  MessageSid: string;
+  Timestamp: number;
+  CommandAuthorized: boolean;
+  _feihan: {
+    accountId: string;
+    isGroup: boolean;
+    senderId: string;
+    chatId: string;
+  };
+}
+
+/**
+ * Build the OpenClaw context payload from a parsed inbound message.
+ */
+export function buildContext(
+  msg: ParsedInboundMessage,
+  account: FeihanAccountConfig,
+): InboundContext {
+  const isGroup = msg.chatType === "group";
+
+  // Session key: group chats key on chatId, DMs key on sender
+  const sessionKey = isGroup
+    ? `feihan:chat:${msg.chatId}`
+    : `feihan:user:${msg.senderId}`;
+
+  return {
+    Body: msg.body,
+    From: isGroup ? `feihan:chat:${msg.chatId}` : `feihan:user:${msg.senderId}`,
+    To: `feihan:bot:${account.botUserId ?? account.appId}`,
+    SessionKey: sessionKey,
+    AccountId: account.accountId,
+    ChatType: isGroup ? "group" : "direct",
+    Provider: "feihan",
+    Surface: "feihan",
+    MessageSid: msg.messageId,
+    Timestamp: msg.timestamp,
+    CommandAuthorized: true,
+    _feihan: {
+      accountId: account.accountId,
+      isGroup,
+      senderId: msg.senderId,
+      chatId: msg.chatId,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Top-level dispatch
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for the deliver callback wired by the caller (e.g. the service
+ * start handler in index.ts once task 06 connects the FeihanClient).
+ */
+export interface InboundDispatchOptions {
+  /** Send a reply back to the Feihan chat. */
+  deliver: (chatId: string, text: string) => Promise<void>;
+}
+
+/**
+ * Process an inbound Feihan message event end-to-end:
+ * parse -> gate -> dedup -> build context -> dispatch.
+ *
+ * Returns `true` if the message was dispatched, `false` if filtered.
+ */
+export async function processInboundMessage(
+  api: PluginApi,
+  account: FeihanAccountConfig,
+  event: FeihanMessageEvent,
+  opts: InboundDispatchOptions,
+): Promise<boolean> {
+  const logger = api.logger;
+
+  // 1. Parse
+  const parsed = parseMessageEvent(event);
+  if (!parsed) {
+    logger?.debug(
+      `[feihan] ignoring unparseable event (messageId=${event?.message?.messageId ?? "unknown"} messageType=${event?.message?.messageType ?? "undefined"})`,
+    );
+    return false;
+  }
+
+  // 2. Gate
+  const gate = checkMessageGate(parsed, account);
+  if (!gate.pass) {
+    logger?.debug(
+      `[feihan] gated message=${parsed.messageId} reason=${gate.reason} chat=${parsed.chatId}`,
+    );
+    return false;
+  }
+
+  // 3. Dedup
+  if (isDuplicate(parsed.messageId)) {
+    logger?.debug(
+      `[feihan] duplicate message=${parsed.messageId} chat=${parsed.chatId}`,
+    );
+    return false;
+  }
+
+  // 4. Build context
+  const ctx = buildContext(parsed, account);
+
+  logger?.info(
+    `[feihan] dispatching message=${parsed.messageId} chat=${parsed.chatId} sender=${parsed.senderId} type=${parsed.chatType}`,
+  );
+
+  // 5. Dispatch
+  const runtime = api.runtime;
+  if (!runtime?.channel?.reply?.dispatchReplyWithBufferedBlockDispatcher) {
+    logger?.warn("[feihan] runtime.channel.reply not available — cannot dispatch");
+    return false;
+  }
+
+  // Record session for context continuity
+  const cfgSession = (api.config as Record<string, unknown>)?.session as Record<string, unknown> | undefined;
+  const storePath =
+    runtime.channel.session?.resolveStorePath?.(
+      cfgSession?.store,
+      { agentId: "main" },
+    ) ?? "";
+
+  await runtime.channel.session?.recordInboundSession?.({
+    storePath,
+    sessionKey: ctx.SessionKey,
+    ctx,
+    updateLastRoute:
+      ctx.ChatType === "direct"
+        ? {
+            sessionKey: ctx.SessionKey,
+            channel: "feihan",
+            to: parsed.chatId,
+            accountId: account.accountId,
+          }
+        : undefined,
+  });
+
+  // Dispatch reply with buffered block dispatcher
+  logger?.debug(
+    `[feihan] dispatch starting for message=${parsed.messageId} session=${ctx.SessionKey}`,
+  );
+
+  await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx,
+    cfg: api.config,
+    dispatcherOptions: {
+      deliver: async (payload: { text?: string }) => {
+        logger?.info(
+          `[feihan] deliver callback called for message=${parsed.messageId} hasText=${!!payload.text} textLen=${payload.text?.length ?? 0}`,
+        );
+        if (payload.text) {
+          await opts.deliver(parsed.chatId, payload.text);
+          logger?.info(
+            `[feihan] deliver completed for message=${parsed.messageId} chat=${parsed.chatId}`,
+          );
+        }
+      },
+      onError: (err: unknown, info?: { kind?: string }) => {
+        logger?.error(
+          `[feihan] ${info?.kind ?? "reply"} error for message=${parsed.messageId}: ${err}`,
+        );
+      },
+    },
+  });
+
+  logger?.info(
+    `[feihan] dispatch finished for message=${parsed.messageId}`,
+  );
+
+  return true;
+}

package/src/messaging/outbound.test.ts

@@ -0,0 +1,172 @@
+// Copyright (c) 2026 上海飞函安全科技有限公司 (Shanghai Feihan Security Technology Co., Ltd.)
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// We test outbound logic by mocking the client manager.
+// Mock shape matches @feihan-im/sdk's client.Im.v1.* API surface.
+
+/** Marker class for mock auth errors. */
+class MockAuthError extends Error {
+  code = 40000006;
+  constructor() { super("鉴权失败"); }
+}
+
+vi.mock("../core/feihan-client.js", () => {
+  const mockClient = {
+    client: {
+      Im: {
+        v1: {
+          Message: {
+            sendMessage: vi.fn().mockResolvedValue({ message_id: "sent_msg_001" }),
+            readMessage: vi.fn().mockResolvedValue({}),
+          },
+          Chat: {
+            createTyping: vi.fn().mockResolvedValue({}),
+            deleteTyping: vi.fn().mockResolvedValue({}),
+          },
+        },
+      },
+      preheat: vi.fn().mockResolvedValue(undefined),
+    },
+    config: { accountId: "test-account" },
+    connectionState: "connected",
+  };
+
+  return {
+    getClient: vi.fn((accountId?: string) => {
+      if (accountId === "missing") return undefined;
+      return mockClient;
+    }),
+    isAuthError: vi.fn((err: unknown) => err instanceof MockAuthError),
+    MessageType_TEXT: "text",
+    __mockClient: mockClient,
+  };
+});
+
+import { sendText, setTyping, clearTyping, readMessage, makeDeliver } from "./outbound.js";
+import { getClient } from "../core/feihan-client.js";
+
+// Access mock internals
+const { __mockClient: mockClient } = await import("../core/feihan-client.js") as any;
+
+describe("sendText", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("sends a text message successfully", async () => {
+    const result = await sendText("chat_001", "Hello!", "test-account");
+    expect(result.ok).toBe(true);
+    expect(result.messageId).toBe("sent_msg_001");
+    expect(result.provider).toBe("feihan");
+
+    const sendCall = mockClient.client.Im.v1.Message.sendMessage.mock.calls[0][0];
+    expect(sendCall.chat_id).toBe("chat_001");
+    expect(sendCall.message_type).toBe("text");
+    expect(sendCall.message_content.text.content).toBe("Hello!");
+  });
+
+  it("returns error when no client is connected", async () => {
+    const result = await sendText("chat_001", "Hello!", "missing");
+    expect(result.ok).toBe(false);
+    expect(result.error?.message).toContain("no connected client");
+  });
+
+  it("returns error when SDK throws non-auth error", async () => {
+    mockClient.client.Im.v1.Message.sendMessage.mockRejectedValueOnce(new Error("API error"));
+    const result = await sendText("chat_001", "Hello!");
+    expect(result.ok).toBe(false);
+    expect(result.error?.message).toContain("send failed");
+    // preheat should NOT have been called for non-auth errors
+    expect(mockClient.client.preheat).not.toHaveBeenCalled();
+  });
+
+  it("retries once on auth error after preheat", async () => {
+    // First call fails with auth error, second succeeds
+    mockClient.client.Im.v1.Message.sendMessage
+      .mockRejectedValueOnce(new MockAuthError())
+      .mockResolvedValueOnce({ message_id: "retry_msg_001" });
+
+    const logWarn = vi.fn();
+    const result = await sendText("chat_001", "Hello!", "test-account", undefined, logWarn);
+    expect(result.ok).toBe(true);
+    expect(result.messageId).toBe("retry_msg_001");
+    expect(mockClient.client.preheat).toHaveBeenCalledOnce();
+    expect(logWarn).toHaveBeenCalled();
+    expect(logWarn.mock.calls[0][0]).toContain("auth error on send");
+  });
+
+  it("returns error when retry also fails after auth error", async () => {
+    // Both calls fail
+    mockClient.client.Im.v1.Message.sendMessage
+      .mockRejectedValueOnce(new MockAuthError())
+      .mockRejectedValueOnce(new Error("still broken"));
+
+    const result = await sendText("chat_001", "Hello!", "test-account");
+    expect(result.ok).toBe(false);
+    expect(result.error?.message).toContain("after auth retry");
+    expect(mockClient.client.preheat).toHaveBeenCalledOnce();
+  });
+
+  it("does not retry on non-auth SDK errors", async () => {
+    mockClient.client.Im.v1.Message.sendMessage.mockRejectedValueOnce(new Error("network timeout"));
+    const result = await sendText("chat_001", "Hello!");
+    expect(result.ok).toBe(false);
+    expect(mockClient.client.preheat).not.toHaveBeenCalled();
+    expect(mockClient.client.Im.v1.Message.sendMessage).toHaveBeenCalledOnce();
+  });
+
+  it("passes reply_message_id when provided", async () => {
+    await sendText("chat_001", "reply!", "test-account", "original_msg");
+    const sendCall = mockClient.client.Im.v1.Message.sendMessage.mock.calls[0][0];
+    expect(sendCall.reply_message_id).toBe("original_msg");
+  });
+});
+
+describe("setTyping", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("calls createTyping on the client", async () => {
+    await setTyping("chat_001");
+    expect(mockClient.client.Im.v1.Chat.createTyping).toHaveBeenCalledWith({ chat_id: "chat_001" });
+  });
+
+  it("does not throw when client is missing", async () => {
+    await expect(setTyping("chat_001", "missing")).resolves.toBeUndefined();
+  });
+});
+
+describe("clearTyping", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("calls deleteTyping on the client", async () => {
+    await clearTyping("chat_001");
+    expect(mockClient.client.Im.v1.Chat.deleteTyping).toHaveBeenCalledWith({ chat_id: "chat_001" });
+  });
+});
+
+describe("readMessage", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("calls readMessage on the client", async () => {
+    await readMessage("msg_001");
+    expect(mockClient.client.Im.v1.Message.readMessage).toHaveBeenCalledWith({ message_id: "msg_001" });
+  });
+});
+
+describe("makeDeliver", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("returns a deliver function that sends text", async () => {
+    const deliver = makeDeliver("test-account");
+    await deliver("chat_001", "AI reply");
+    expect(mockClient.client.Im.v1.Message.sendMessage).toHaveBeenCalledOnce();
+  });
+
+  it("throws when send fails", async () => {
+    mockClient.client.Im.v1.Message.sendMessage.mockRejectedValueOnce(new Error("fail"));
+    const deliver = makeDeliver("test-account");
+    await expect(deliver("chat_001", "AI reply")).rejects.toThrow();
+  });
+});