@openclaw/feishu 2026.2.25 → 2026.3.1

package/src/send.ts

@@ -3,21 +3,105 @@ import { resolveFeishuAccount } from "./accounts.js";
 import { createFeishuClient } from "./client.js";
 import type { MentionTarget } from "./mention.js";
 import { buildMentionedMessage, buildMentionedCardContent } from "./mention.js";
+import { parsePostContent } from "./post.js";
 import { getFeishuRuntime } from "./runtime.js";
 import { assertFeishuMessageApiSuccess, toFeishuSendResult } from "./send-result.js";
 import { resolveFeishuSendTarget } from "./send-target.js";
 import type { FeishuSendResult } from "./types.js";
 
+const WITHDRAWN_REPLY_ERROR_CODES = new Set([230011, 231003]);
+
+function shouldFallbackFromReplyTarget(response: { code?: number; msg?: string }): boolean {
+  if (response.code !== undefined && WITHDRAWN_REPLY_ERROR_CODES.has(response.code)) {
+    return true;
+  }
+  const msg = response.msg?.toLowerCase() ?? "";
+  return msg.includes("withdrawn") || msg.includes("not found");
+}
+
 export type FeishuMessageInfo = {
   messageId: string;
   chatId: string;
   senderId?: string;
   senderOpenId?: string;
+  senderType?: string;
   content: string;
   contentType: string;
   createTime?: number;
 };
 
+function parseInteractiveCardContent(parsed: unknown): string {
+  if (!parsed || typeof parsed !== "object") {
+    return "[Interactive Card]";
+  }
+
+  const candidate = parsed as { elements?: unknown };
+  if (!Array.isArray(candidate.elements)) {
+    return "[Interactive Card]";
+  }
+
+  const texts: string[] = [];
+  for (const element of candidate.elements) {
+    if (!element || typeof element !== "object") {
+      continue;
+    }
+    const item = element as {
+      tag?: string;
+      content?: string;
+      text?: { content?: string };
+    };
+    if (item.tag === "div" && typeof item.text?.content === "string") {
+      texts.push(item.text.content);
+      continue;
+    }
+    if (item.tag === "markdown" && typeof item.content === "string") {
+      texts.push(item.content);
+    }
+  }
+  return texts.join("\n").trim() || "[Interactive Card]";
+}
+
+function parseQuotedMessageContent(rawContent: string, msgType: string): string {
+  if (!rawContent) {
+    return "";
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawContent);
+  } catch {
+    return rawContent;
+  }
+
+  if (msgType === "text") {
+    const text = (parsed as { text?: unknown })?.text;
+    return typeof text === "string" ? text : "[Text message]";
+  }
+
+  if (msgType === "post") {
+    return parsePostContent(rawContent).textContent;
+  }
+
+  if (msgType === "interactive") {
+    return parseInteractiveCardContent(parsed);
+  }
+
+  if (typeof parsed === "string") {
+    return parsed;
+  }
+
+  const genericText = (parsed as { text?: unknown; title?: unknown } | null)?.text;
+  if (typeof genericText === "string" && genericText.trim()) {
+    return genericText;
+  }
+  const genericTitle = (parsed as { title?: unknown } | null)?.title;
+  if (typeof genericTitle === "string" && genericTitle.trim()) {
+    return genericTitle;
+  }
+
+  return `[${msgType || "unknown"} message]`;
+}
+
 /**
  * Get a message by its ID.
  * Useful for fetching quoted/replied message content.
@@ -54,6 +138,16 @@ export async function getMessageFeishu(params: {
           };
           create_time?: string;
         }>;
+        message_id?: string;
+        chat_id?: string;
+        msg_type?: string;
+        body?: { content?: string };
+        sender?: {
+          id?: string;
+          id_type?: string;
+          sender_type?: string;
+        };
+        create_time?: string;
       };
     };
 
@@ -61,30 +155,30 @@ export async function getMessageFeishu(params: {
       return null;
     }
 
-    const item = response.data?.items?.[0];
+    // Support both list shape (data.items[0]) and single-object shape (data as message)
+    const rawItem = response.data?.items?.[0] ?? response.data;
+    const item =
+      rawItem &&
+      (rawItem.body !== undefined || (rawItem as { message_id?: string }).message_id !== undefined)
+        ? rawItem
+        : null;
     if (!item) {
       return null;
     }
 
-    // Parse content based on message type
-    let content = item.body?.content ?? "";
-    try {
-      const parsed = JSON.parse(content);
-      if (item.msg_type === "text" && parsed.text) {
-        content = parsed.text;
-      }
-    } catch {
-      // Keep raw content if parsing fails
-    }
+    const msgType = item.msg_type ?? "text";
+    const rawContent = item.body?.content ?? "";
+    const content = parseQuotedMessageContent(rawContent, msgType);
 
     return {
       messageId: item.message_id ?? messageId,
       chatId: item.chat_id ?? "",
       senderId: item.sender?.id,
       senderOpenId: item.sender?.id_type === "open_id" ? item.sender?.id : undefined,
+      senderType: item.sender?.sender_type,
       content,
-      contentType: item.msg_type ?? "text",
-      createTime: item.create_time ? parseInt(item.create_time, 10) : undefined,
+      contentType: msgType,
+      createTime: item.create_time ? parseInt(String(item.create_time), 10) : undefined,
     };
   } catch {
     return null;
@@ -96,6 +190,8 @@ export type SendFeishuMessageParams = {
   to: string;
   text: string;
   replyToMessageId?: string;
+  /** When true, reply creates a Feishu topic thread instead of an inline reply */
+  replyInThread?: boolean;
   /** Mention target users */
   mentions?: MentionTarget[];
   /** Account ID (optional, uses default if not specified) */
@@ -127,7 +223,7 @@ function buildFeishuPostMessagePayload(params: { messageText: string }): {
 export async function sendMessageFeishu(
   params: SendFeishuMessageParams,
 ): Promise<FeishuSendResult> {
-  const { cfg, to, text, replyToMessageId, mentions, accountId } = params;
+  const { cfg, to, text, replyToMessageId, replyInThread, mentions, accountId } = params;
   const { client, receiveId, receiveIdType } = resolveFeishuSendTarget({ cfg, to, accountId });
   const tableMode = getFeishuRuntime().channel.text.resolveMarkdownTableMode({
     cfg,
@@ -149,8 +245,21 @@ export async function sendMessageFeishu(
       data: {
         content,
         msg_type: msgType,
+        ...(replyInThread ? { reply_in_thread: true } : {}),
       },
     });
+    if (shouldFallbackFromReplyTarget(response)) {
+      const fallback = await client.im.message.create({
+        params: { receive_id_type: receiveIdType },
+        data: {
+          receive_id: receiveId,
+          content,
+          msg_type: msgType,
+        },
+      });
+      assertFeishuMessageApiSuccess(fallback, "Feishu send failed");
+      return toFeishuSendResult(fallback, receiveId);
+    }
     assertFeishuMessageApiSuccess(response, "Feishu reply failed");
     return toFeishuSendResult(response, receiveId);
   }
@@ -172,11 +281,13 @@ export type SendFeishuCardParams = {
   to: string;
   card: Record<string, unknown>;
   replyToMessageId?: string;
+  /** When true, reply creates a Feishu topic thread instead of an inline reply */
+  replyInThread?: boolean;
   accountId?: string;
 };
 
 export async function sendCardFeishu(params: SendFeishuCardParams): Promise<FeishuSendResult> {
-  const { cfg, to, card, replyToMessageId, accountId } = params;
+  const { cfg, to, card, replyToMessageId, replyInThread, accountId } = params;
   const { client, receiveId, receiveIdType } = resolveFeishuSendTarget({ cfg, to, accountId });
   const content = JSON.stringify(card);
 
@@ -186,8 +297,21 @@ export async function sendCardFeishu(params: SendFeishuCardParams): Promise<Feis
       data: {
         content,
         msg_type: "interactive",
+        ...(replyInThread ? { reply_in_thread: true } : {}),
       },
     });
+    if (shouldFallbackFromReplyTarget(response)) {
+      const fallback = await client.im.message.create({
+        params: { receive_id_type: receiveIdType },
+        data: {
+          receive_id: receiveId,
+          content,
+          msg_type: "interactive",
+        },
+      });
+      assertFeishuMessageApiSuccess(fallback, "Feishu card send failed");
+      return toFeishuSendResult(fallback, receiveId);
+    }
     assertFeishuMessageApiSuccess(response, "Feishu card reply failed");
     return toFeishuSendResult(response, receiveId);
   }
@@ -260,18 +384,19 @@ export async function sendMarkdownCardFeishu(params: {
   to: string;
   text: string;
   replyToMessageId?: string;
+  /** When true, reply creates a Feishu topic thread instead of an inline reply */
+  replyInThread?: boolean;
   /** Mention target users */
   mentions?: MentionTarget[];
   accountId?: string;
 }): Promise<FeishuSendResult> {
-  const { cfg, to, text, replyToMessageId, mentions, accountId } = params;
-  // Build message content (with @mention support)
+  const { cfg, to, text, replyToMessageId, replyInThread, mentions, accountId } = params;
   let cardText = text;
   if (mentions && mentions.length > 0) {
     cardText = buildMentionedCardContent(mentions, text);
   }
   const card = buildMarkdownCard(cardText);
-  return sendCardFeishu({ cfg, to, card, replyToMessageId, accountId });
+  return sendCardFeishu({ cfg, to, card, replyToMessageId, replyInThread, accountId });
 }
 
 /**

package/src/streaming-card.ts

@@ -3,11 +3,19 @@
  */
 
 import type { Client } from "@larksuiteoapi/node-sdk";
+import { fetchWithSsrFGuard } from "openclaw/plugin-sdk";
 import type { FeishuDomain } from "./types.js";
 
 type Credentials = { appId: string; appSecret: string; domain?: FeishuDomain };
 type CardState = { cardId: string; messageId: string; sequence: number; currentText: string };
 
+/** Optional header for streaming cards (title bar with color template) */
+export type StreamingCardHeader = {
+  title: string;
+  /** Color template: blue, green, red, orange, purple, indigo, wathet, turquoise, yellow, grey, carmine, violet, lime */
+  template?: string;
+};
+
 // Token cache (keyed by domain + appId)
 const tokenCache = new Map<string, { token: string; expiresAt: number }>();
 
@@ -21,6 +29,20 @@ function resolveApiBase(domain?: FeishuDomain): string {
   return "https://open.feishu.cn/open-apis";
 }
 
+function resolveAllowedHostnames(domain?: FeishuDomain): string[] {
+  if (domain === "lark") {
+    return ["open.larksuite.com"];
+  }
+  if (domain && domain !== "feishu" && domain.startsWith("http")) {
+    try {
+      return [new URL(domain).hostname];
+    } catch {
+      return [];
+    }
+  }
+  return ["open.feishu.cn"];
+}
+
 async function getToken(creds: Credentials): Promise<string> {
   const key = `${creds.domain ?? "feishu"}|${creds.appId}`;
   const cached = tokenCache.get(key);
@@ -28,17 +50,23 @@ async function getToken(creds: Credentials): Promise<string> {
     return cached.token;
   }
 
-  const res = await fetch(`${resolveApiBase(creds.domain)}/auth/v3/tenant_access_token/internal`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ app_id: creds.appId, app_secret: creds.appSecret }),
+  const { response, release } = await fetchWithSsrFGuard({
+    url: `${resolveApiBase(creds.domain)}/auth/v3/tenant_access_token/internal`,
+    init: {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ app_id: creds.appId, app_secret: creds.appSecret }),
+    },
+    policy: { allowedHostnames: resolveAllowedHostnames(creds.domain) },
+    auditContext: "feishu.streaming-card.token",
   });
-  const data = (await res.json()) as {
+  const data = (await response.json()) as {
     code: number;
     msg: string;
     tenant_access_token?: string;
     expire?: number;
   };
+  await release();
   if (data.code !== 0 || !data.tenant_access_token) {
     throw new Error(`Token error: ${data.msg}`);
   }
@@ -78,13 +106,19 @@ export class FeishuStreamingSession {
   async start(
     receiveId: string,
     receiveIdType: "open_id" | "user_id" | "union_id" | "email" | "chat_id" = "chat_id",
+    options?: {
+      replyToMessageId?: string;
+      replyInThread?: boolean;
+      rootId?: string;
+      header?: StreamingCardHeader;
+    },
   ): Promise<void> {
     if (this.state) {
       return;
     }
 
     const apiBase = resolveApiBase(this.creds.domain);
-    const cardJson = {
+    const cardJson: Record<string, unknown> = {
       schema: "2.0",
       config: {
         streaming_mode: true,
@@ -95,35 +129,71 @@ export class FeishuStreamingSession {
         elements: [{ tag: "markdown", content: "⏳ Thinking...", element_id: "content" }],
       },
     };
+    if (options?.header) {
+      cardJson.header = {
+        title: { tag: "plain_text", content: options.header.title },
+        template: options.header.template ?? "blue",
+      };
+    }
 
     // Create card entity
-    const createRes = await fetch(`${apiBase}/cardkit/v1/cards`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${await getToken(this.creds)}`,
-        "Content-Type": "application/json",
+    const { response: createRes, release: releaseCreate } = await fetchWithSsrFGuard({
+      url: `${apiBase}/cardkit/v1/cards`,
+      init: {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${await getToken(this.creds)}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ type: "card_json", data: JSON.stringify(cardJson) }),
       },
-      body: JSON.stringify({ type: "card_json", data: JSON.stringify(cardJson) }),
+      policy: { allowedHostnames: resolveAllowedHostnames(this.creds.domain) },
+      auditContext: "feishu.streaming-card.create",
     });
     const createData = (await createRes.json()) as {
       code: number;
       msg: string;
       data?: { card_id: string };
     };
+    await releaseCreate();
     if (createData.code !== 0 || !createData.data?.card_id) {
       throw new Error(`Create card failed: ${createData.msg}`);
     }
     const cardId = createData.data.card_id;
+    const cardContent = JSON.stringify({ type: "card", data: { card_id: cardId } });
 
-    // Send card message
-    const sendRes = await this.client.im.message.create({
-      params: { receive_id_type: receiveIdType },
-      data: {
+    // Topic-group replies require root_id routing. Prefer create+root_id when available.
+    let sendRes;
+    if (options?.rootId) {
+      const createData = {
         receive_id: receiveId,
         msg_type: "interactive",
-        content: JSON.stringify({ type: "card", data: { card_id: cardId } }),
-      },
-    });
+        content: cardContent,
+        root_id: options.rootId,
+      };
+      sendRes = await this.client.im.message.create({
+        params: { receive_id_type: receiveIdType },
+        data: createData,
+      });
+    } else if (options?.replyToMessageId) {
+      sendRes = await this.client.im.message.reply({
+        path: { message_id: options.replyToMessageId },
+        data: {
+          msg_type: "interactive",
+          content: cardContent,
+          ...(options.replyInThread ? { reply_in_thread: true } : {}),
+        },
+      });
+    } else {
+      sendRes = await this.client.im.message.create({
+        params: { receive_id_type: receiveIdType },
+        data: {
+          receive_id: receiveId,
+          msg_type: "interactive",
+          content: cardContent,
+        },
+      });
+    }
     if (sendRes.code !== 0 || !sendRes.data?.message_id) {
       throw new Error(`Send card failed: ${sendRes.msg}`);
     }
@@ -138,18 +208,27 @@ export class FeishuStreamingSession {
     }
     const apiBase = resolveApiBase(this.creds.domain);
     this.state.sequence += 1;
-    await fetch(`${apiBase}/cardkit/v1/cards/${this.state.cardId}/elements/content/content`, {
-      method: "PUT",
-      headers: {
-        Authorization: `Bearer ${await getToken(this.creds)}`,
-        "Content-Type": "application/json",
+    await fetchWithSsrFGuard({
+      url: `${apiBase}/cardkit/v1/cards/${this.state.cardId}/elements/content/content`,
+      init: {
+        method: "PUT",
+        headers: {
+          Authorization: `Bearer ${await getToken(this.creds)}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          content: text,
+          sequence: this.state.sequence,
+          uuid: `s_${this.state.cardId}_${this.state.sequence}`,
+        }),
       },
-      body: JSON.stringify({
-        content: text,
-        sequence: this.state.sequence,
-        uuid: `s_${this.state.cardId}_${this.state.sequence}`,
-      }),
-    }).catch((error) => onError?.(error));
+      policy: { allowedHostnames: resolveAllowedHostnames(this.creds.domain) },
+      auditContext: "feishu.streaming-card.update",
+    })
+      .then(async ({ release }) => {
+        await release();
+      })
+      .catch((error) => onError?.(error));
   }
 
   async update(text: string): Promise<void> {
@@ -194,20 +273,29 @@ export class FeishuStreamingSession {
 
     // Close streaming mode
     this.state.sequence += 1;
-    await fetch(`${apiBase}/cardkit/v1/cards/${this.state.cardId}/settings`, {
-      method: "PATCH",
-      headers: {
-        Authorization: `Bearer ${await getToken(this.creds)}`,
-        "Content-Type": "application/json; charset=utf-8",
-      },
-      body: JSON.stringify({
-        settings: JSON.stringify({
-          config: { streaming_mode: false, summary: { content: truncateSummary(text) } },
+    await fetchWithSsrFGuard({
+      url: `${apiBase}/cardkit/v1/cards/${this.state.cardId}/settings`,
+      init: {
+        method: "PATCH",
+        headers: {
+          Authorization: `Bearer ${await getToken(this.creds)}`,
+          "Content-Type": "application/json; charset=utf-8",
+        },
+        body: JSON.stringify({
+          settings: JSON.stringify({
+            config: { streaming_mode: false, summary: { content: truncateSummary(text) } },
+          }),
+          sequence: this.state.sequence,
+          uuid: `c_${this.state.cardId}_${this.state.sequence}`,
         }),
-        sequence: this.state.sequence,
-        uuid: `c_${this.state.cardId}_${this.state.sequence}`,
-      }),
-    }).catch((e) => this.log?.(`Close failed: ${String(e)}`));
+      },
+      policy: { allowedHostnames: resolveAllowedHostnames(this.creds.domain) },
+      auditContext: "feishu.streaming-card.close",
+    })
+      .then(async ({ release }) => {
+        await release();
+      })
+      .catch((e) => this.log?.(`Close failed: ${String(e)}`));
 
     this.log?.(`Closed streaming: cardId=${this.state.cardId}`);
   }

package/src/targets.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { resolveReceiveIdType } from "./targets.js";
+import { looksLikeFeishuId, normalizeFeishuTarget, resolveReceiveIdType } from "./targets.js";
 
 describe("resolveReceiveIdType", () => {
   it("resolves chat IDs by oc_ prefix", () => {
@@ -14,3 +14,28 @@ describe("resolveReceiveIdType", () => {
     expect(resolveReceiveIdType("u_123")).toBe("user_id");
   });
 });
+
+describe("normalizeFeishuTarget", () => {
+  it("strips provider and user prefixes", () => {
+    expect(normalizeFeishuTarget("feishu:user:ou_123")).toBe("ou_123");
+    expect(normalizeFeishuTarget("lark:user:ou_123")).toBe("ou_123");
+  });
+
+  it("strips provider and chat prefixes", () => {
+    expect(normalizeFeishuTarget("feishu:chat:oc_123")).toBe("oc_123");
+  });
+
+  it("accepts provider-prefixed raw ids", () => {
+    expect(normalizeFeishuTarget("feishu:ou_123")).toBe("ou_123");
+  });
+});
+
+describe("looksLikeFeishuId", () => {
+  it("accepts provider-prefixed user targets", () => {
+    expect(looksLikeFeishuId("feishu:user:ou_123")).toBe(true);
+  });
+
+  it("accepts provider-prefixed chat targets", () => {
+    expect(looksLikeFeishuId("lark:chat:oc_123")).toBe(true);
+  });
+});

package/src/targets.ts

@@ -4,6 +4,10 @@ const CHAT_ID_PREFIX = "oc_";
 const OPEN_ID_PREFIX = "ou_";
 const USER_ID_REGEX = /^[a-zA-Z0-9_-]+$/;
 
+function stripProviderPrefix(raw: string): string {
+  return raw.replace(/^(feishu|lark):/i, "").trim();
+}
+
 export function detectIdType(id: string): FeishuIdType | null {
   const trimmed = id.trim();
   if (trimmed.startsWith(CHAT_ID_PREFIX)) {
@@ -24,18 +28,19 @@ export function normalizeFeishuTarget(raw: string): string | null {
     return null;
   }
 
-  const lowered = trimmed.toLowerCase();
+  const withoutProvider = stripProviderPrefix(trimmed);
+  const lowered = withoutProvider.toLowerCase();
   if (lowered.startsWith("chat:")) {
-    return trimmed.slice("chat:".length).trim() || null;
+    return withoutProvider.slice("chat:".length).trim() || null;
   }
   if (lowered.startsWith("user:")) {
-    return trimmed.slice("user:".length).trim() || null;
+    return withoutProvider.slice("user:".length).trim() || null;
   }
   if (lowered.startsWith("open_id:")) {
-    return trimmed.slice("open_id:".length).trim() || null;
+    return withoutProvider.slice("open_id:".length).trim() || null;
   }
 
-  return trimmed;
+  return withoutProvider;
 }
 
 export function formatFeishuTarget(id: string, type?: FeishuIdType): string {
@@ -61,7 +66,7 @@ export function resolveReceiveIdType(id: string): "chat_id" | "open_id" | "user_
 }
 
 export function looksLikeFeishuId(raw: string): boolean {
-  const trimmed = raw.trim();
+  const trimmed = stripProviderPrefix(raw.trim());
   if (!trimmed) {
     return false;
   }