@milerliu/feishu 0.1.5

package/src/send.ts

@@ -0,0 +1,475 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+import type { FeishuConfig, FeishuSendResult } from "./types.js";
+import type { MentionTarget } from "./mention.js";
+import { buildMentionedMessage, buildMentionedCardContent } from "./mention.js";
+import { createFeishuClient } from "./client.js";
+import { resolveReceiveIdType, normalizeFeishuTarget } from "./targets.js";
+import { getFeishuRuntime } from "./runtime.js";
+
+export type FeishuMessageInfo = {
+  messageId: string;
+  chatId: string;
+  senderId?: string;
+  senderOpenId?: string;
+  content: string;
+  contentType: string;
+  createTime?: number;
+};
+
+/**
+ * Send text with streaming effect using Feishu streaming update card.
+ * This creates an initial card and then streams updates to it.
+ * Uses the official Feishu streaming update card API.
+ */
+export async function sendStreamingMessageFeishu(params: {
+  cfg: ClawdbotConfig;
+  to: string;
+  text: string;
+  /** Mention target users */
+  mentions?: MentionTarget[];
+}): Promise<FeishuSendResult> {
+  const { cfg, to, text, mentions } = params;
+  const feishuCfg = cfg.channels?.feishu as FeishuConfig | undefined;
+  if (!feishuCfg) {
+    throw new Error("Feishu channel not configured");
+  }
+
+  const client = createFeishuClient(feishuCfg);
+  const receiveId = normalizeFeishuTarget(to);
+  if (!receiveId) {
+    throw new Error(`Invalid Feishu target: ${to}`);
+  }
+
+  const receiveIdType = resolveReceiveIdType(receiveId);
+  const tableMode = getFeishuRuntime().channel.text.resolveMarkdownTableMode({
+    cfg,
+    channel: "feishu",
+  });
+
+  // Build message content (with @mention support)
+  let rawText = text ?? "";
+  if (mentions && mentions.length > 0) {
+    rawText = buildMentionedCardContent(mentions, rawText);
+  }
+  const messageText = getFeishuRuntime().channel.text.convertMarkdownTables(rawText, tableMode);
+
+  // Build initial card with streaming_update header for proper streaming behavior
+  const initialCard = {
+    header: {
+      title: {
+        tag: "plain_text",
+        content: "AI 回复",
+      },
+    },
+    config: {
+      wide_screen_mode: true,
+      streaming_update: true, // Enable streaming update mode
+    },
+    elements: [
+      {
+        tag: "markdown",
+        content: "",
+      },
+    ],
+  };
+
+  const content = JSON.stringify(initialCard);
+
+  // Create initial card with empty content
+  const response = await client.im.message.create({
+    params: { receive_id_type: receiveIdType },
+    data: {
+      receive_id: receiveId,
+      content,
+      msg_type: "interactive",
+    },
+  });
+
+  if (response.code !== 0) {
+    throw new Error(`Feishu streaming card creation failed: ${response.msg || `code ${response.code}`}`);
+  }
+
+  const messageId = response.data?.message_id ?? "unknown";
+
+  // Extract card_id from response if available
+  const cardData = response.data as Record<string, unknown> | undefined;
+  const cardId = cardData?.card_id as string | undefined;
+
+  if (!cardId) {
+    console.warn('No card_id returned, falling back to regular card send');
+    // Fallback: send as regular card if no card_id
+    const fallbackCard = buildMarkdownCard(messageText);
+    return sendCardFeishu({ cfg, to, card: fallbackCard });
+  }
+
+  // Stream the content updates using card_id
+  // Split content into chunks for streaming effect
+  const chunkSize = 300; // Smaller chunks for smoother streaming
+  const chunks: string[] = [];
+
+  for (let i = 0; i < messageText.length; i += chunkSize) {
+    chunks.push(messageText.slice(i, i + chunkSize));
+  }
+
+  // Send updates with small delay between each using the correct API
+  for (let i = 0; i < chunks.length; i++) {
+    const partialContent = chunks.slice(0, i + 1).join("");
+
+    const updateCard = {
+      header: {
+        title: {
+          tag: "plain_text",
+          content: "AI 回复",
+        },
+      },
+      config: {
+        wide_screen_mode: true,
+        streaming_update: true,
+      },
+      elements: [
+        {
+          tag: "markdown",
+          content: partialContent,
+        },
+      ],
+    };
+
+    const updateContent = JSON.stringify(updateCard);
+
+    // Use PATCH /im/message/:message_id with card_id for streaming update
+    // Note: This is the official streaming update method
+    try {
+      const updateResponse = await (client.im.message as Record<string, unknown>).patch?.({
+        path: { message_id: messageId },
+        data: {
+          msg_type: "interactive",
+          content: updateContent,
+        },
+      }) ?? { code: -1, msg: "API not available" };
+
+      if ((updateResponse as Record<string, unknown>).code !== 0) {
+        console.error(`Feishu streaming update failed: ${(updateResponse as Record<string, unknown>).msg}`);
+      }
+    } catch (err) {
+      console.error(`Feishu streaming update error: ${err}`);
+    }
+
+    // Add small delay between updates for streaming effect
+    if (i < chunks.length - 1) {
+      await new Promise((resolve) => setTimeout(resolve, 150));
+    }
+  }
+
+  return {
+    messageId,
+    chatId: receiveId,
+  };
+}
+
+/**
+ * Get a message by its ID.
+ * Useful for fetching quoted/replied message content.
+ */
+export async function getMessageFeishu(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+}): Promise<FeishuMessageInfo | null> {
+  const { cfg, messageId } = params;
+  const feishuCfg = cfg.channels?.feishu as FeishuConfig | undefined;
+  if (!feishuCfg) {
+    throw new Error("Feishu channel not configured");
+  }
+
+  const client = createFeishuClient(feishuCfg);
+
+  try {
+    const response = (await client.im.message.get({
+      path: { message_id: messageId },
+    })) as {
+      code?: number;
+      msg?: string;
+      data?: {
+        items?: Array<{
+          message_id?: string;
+          chat_id?: string;
+          msg_type?: string;
+          body?: { content?: string };
+          sender?: {
+            id?: string;
+            id_type?: string;
+            sender_type?: string;
+          };
+          create_time?: string;
+        }>;
+      };
+    };
+
+    if (response.code !== 0) {
+      return null;
+    }
+
+    const item = response.data?.items?.[0];
+    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
+    }
+
+    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,
+      content,
+      contentType: item.msg_type ?? "text",
+      createTime: item.create_time ? parseInt(item.create_time, 10) : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export type SendFeishuMessageParams = {
+  cfg: ClawdbotConfig;
+  to: string;
+  text: string;
+  replyToMessageId?: string;
+  /** Mention target users */
+  mentions?: MentionTarget[];
+};
+
+export async function sendMessageFeishu(params: SendFeishuMessageParams): Promise<FeishuSendResult> {
+  const { cfg, to, text, replyToMessageId, mentions } = params;
+  const feishuCfg = cfg.channels?.feishu as FeishuConfig | undefined;
+  if (!feishuCfg) {
+    throw new Error("Feishu channel not configured");
+  }
+
+  const client = createFeishuClient(feishuCfg);
+  const receiveId = normalizeFeishuTarget(to);
+  if (!receiveId) {
+    throw new Error(`Invalid Feishu target: ${to}`);
+  }
+
+  const receiveIdType = resolveReceiveIdType(receiveId);
+  const tableMode = getFeishuRuntime().channel.text.resolveMarkdownTableMode({
+    cfg,
+    channel: "feishu",
+  });
+
+  // Build message content (with @mention support)
+  let rawText = text ?? "";
+  if (mentions && mentions.length > 0) {
+    rawText = buildMentionedMessage(mentions, rawText);
+  }
+  const messageText = getFeishuRuntime().channel.text.convertMarkdownTables(rawText, tableMode);
+
+  const content = JSON.stringify({ text: messageText });
+
+  if (replyToMessageId) {
+    const response = await client.im.message.reply({
+      path: { message_id: replyToMessageId },
+      data: {
+        content,
+        msg_type: "text",
+      },
+    });
+
+    if (response.code !== 0) {
+      throw new Error(`Feishu reply failed: ${response.msg || `code ${response.code}`}`);
+    }
+
+    return {
+      messageId: response.data?.message_id ?? "unknown",
+      chatId: receiveId,
+    };
+  }
+
+  const response = await client.im.message.create({
+    params: { receive_id_type: receiveIdType },
+    data: {
+      receive_id: receiveId,
+      content,
+      msg_type: "text",
+    },
+  });
+
+  if (response.code !== 0) {
+    throw new Error(`Feishu send failed: ${response.msg || `code ${response.code}`}`);
+  }
+
+  return {
+    messageId: response.data?.message_id ?? "unknown",
+    chatId: receiveId,
+  };
+}
+
+export type SendFeishuCardParams = {
+  cfg: ClawdbotConfig;
+  to: string;
+  card: Record<string, unknown>;
+  replyToMessageId?: string;
+};
+
+export async function sendCardFeishu(params: SendFeishuCardParams): Promise<FeishuSendResult> {
+  const { cfg, to, card, replyToMessageId } = params;
+  const feishuCfg = cfg.channels?.feishu as FeishuConfig | undefined;
+  if (!feishuCfg) {
+    throw new Error("Feishu channel not configured");
+  }
+
+  const client = createFeishuClient(feishuCfg);
+  const receiveId = normalizeFeishuTarget(to);
+  if (!receiveId) {
+    throw new Error(`Invalid Feishu target: ${to}`);
+  }
+
+  const receiveIdType = resolveReceiveIdType(receiveId);
+  const content = JSON.stringify(card);
+
+  if (replyToMessageId) {
+    const response = await client.im.message.reply({
+      path: { message_id: replyToMessageId },
+      data: {
+        content,
+        msg_type: "interactive",
+      },
+    });
+
+    if (response.code !== 0) {
+      throw new Error(`Feishu card reply failed: ${response.msg || `code ${response.code}`}`);
+    }
+
+    return {
+      messageId: response.data?.message_id ?? "unknown",
+      chatId: receiveId,
+    };
+  }
+
+  const response = await client.im.message.create({
+    params: { receive_id_type: receiveIdType },
+    data: {
+      receive_id: receiveId,
+      content,
+      msg_type: "interactive",
+    },
+  });
+
+  if (response.code !== 0) {
+    throw new Error(`Feishu card send failed: ${response.msg || `code ${response.code}`}`);
+  }
+
+  return {
+    messageId: response.data?.message_id ?? "unknown",
+    chatId: receiveId,
+  };
+}
+
+export async function updateCardFeishu(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+  card: Record<string, unknown>;
+}): Promise<void> {
+  const { cfg, messageId, card } = params;
+  const feishuCfg = cfg.channels?.feishu as FeishuConfig | undefined;
+  if (!feishuCfg) {
+    throw new Error("Feishu channel not configured");
+  }
+
+  const client = createFeishuClient(feishuCfg);
+  const content = JSON.stringify(card);
+
+  const response = await client.im.message.patch({
+    path: { message_id: messageId },
+    data: { content },
+  });
+
+  if (response.code !== 0) {
+    throw new Error(`Feishu card update failed: ${response.msg || `code ${response.code}`}`);
+  }
+}
+
+/**
+ * Build a Feishu interactive card with markdown content.
+ * Cards render markdown properly (code blocks, tables, links, etc.)
+ */
+export function buildMarkdownCard(text: string): Record<string, unknown> {
+  return {
+    config: {
+      wide_screen_mode: true,
+    },
+    elements: [
+      {
+        tag: "markdown",
+        content: text,
+      },
+    ],
+  };
+}
+
+/**
+ * Send a message as a markdown card (interactive message).
+ * This renders markdown properly in Feishu (code blocks, tables, bold/italic, etc.)
+ */
+export async function sendMarkdownCardFeishu(params: {
+  cfg: ClawdbotConfig;
+  to: string;
+  text: string;
+  replyToMessageId?: string;
+  /** Mention target users */
+  mentions?: MentionTarget[];
+}): Promise<FeishuSendResult> {
+  const { cfg, to, text, replyToMessageId, mentions } = params;
+  // Build message content (with @mention support)
+  let cardText = text;
+  if (mentions && mentions.length > 0) {
+    cardText = buildMentionedCardContent(mentions, text);
+  }
+  const card = buildMarkdownCard(cardText);
+  return sendCardFeishu({ cfg, to, card, replyToMessageId });
+}
+
+/**
+ * Edit an existing text message.
+ * Note: Feishu only allows editing messages within 24 hours.
+ */
+export async function editMessageFeishu(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+  text: string;
+}): Promise<void> {
+  const { cfg, messageId, text } = params;
+  const feishuCfg = cfg.channels?.feishu as FeishuConfig | undefined;
+  if (!feishuCfg) {
+    throw new Error("Feishu channel not configured");
+  }
+
+  const client = createFeishuClient(feishuCfg);
+  const tableMode = getFeishuRuntime().channel.text.resolveMarkdownTableMode({
+    cfg,
+    channel: "feishu",
+  });
+  const messageText = getFeishuRuntime().channel.text.convertMarkdownTables(text ?? "", tableMode);
+  const content = JSON.stringify({ text: messageText });
+
+  const response = await client.im.message.update({
+    path: { message_id: messageId },
+    data: {
+      msg_type: "text",
+      content,
+    },
+  });
+
+  if (response.code !== 0) {
+    throw new Error(`Feishu message edit failed: ${response.msg || `code ${response.code}`}`);
+  }
+}

package/src/targets.ts

@@ -0,0 +1,58 @@
+import type { FeishuIdType } from "./types.js";
+
+const CHAT_ID_PREFIX = "oc_";
+const OPEN_ID_PREFIX = "ou_";
+const USER_ID_REGEX = /^[a-zA-Z0-9_-]+$/;
+
+export function detectIdType(id: string): FeishuIdType | null {
+  const trimmed = id.trim();
+  if (trimmed.startsWith(CHAT_ID_PREFIX)) return "chat_id";
+  if (trimmed.startsWith(OPEN_ID_PREFIX)) return "open_id";
+  if (USER_ID_REGEX.test(trimmed)) return "user_id";
+  return null;
+}
+
+export function normalizeFeishuTarget(raw: string): string | null {
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+
+  const lowered = trimmed.toLowerCase();
+  if (lowered.startsWith("chat:")) {
+    return trimmed.slice("chat:".length).trim() || null;
+  }
+  if (lowered.startsWith("user:")) {
+    return trimmed.slice("user:".length).trim() || null;
+  }
+  if (lowered.startsWith("open_id:")) {
+    return trimmed.slice("open_id:".length).trim() || null;
+  }
+
+  return trimmed;
+}
+
+export function formatFeishuTarget(id: string, type?: FeishuIdType): string {
+  const trimmed = id.trim();
+  if (type === "chat_id" || trimmed.startsWith(CHAT_ID_PREFIX)) {
+    return `chat:${trimmed}`;
+  }
+  if (type === "open_id" || trimmed.startsWith(OPEN_ID_PREFIX)) {
+    return `user:${trimmed}`;
+  }
+  return trimmed;
+}
+
+export function resolveReceiveIdType(id: string): "chat_id" | "open_id" | "user_id" {
+  const trimmed = id.trim();
+  if (trimmed.startsWith(CHAT_ID_PREFIX)) return "chat_id";
+  if (trimmed.startsWith(OPEN_ID_PREFIX)) return "open_id";
+  return "open_id";
+}
+
+export function looksLikeFeishuId(raw: string): boolean {
+  const trimmed = raw.trim();
+  if (!trimmed) return false;
+  if (/^(chat|user|open_id):/i.test(trimmed)) return true;
+  if (trimmed.startsWith(CHAT_ID_PREFIX)) return true;
+  if (trimmed.startsWith(OPEN_ID_PREFIX)) return true;
+  return false;
+}

package/src/types.ts

@@ -0,0 +1,55 @@
+import type { FeishuConfigSchema, FeishuGroupSchema, z } from "./config-schema.js";
+import type { MentionTarget } from "./mention.js";
+
+export type FeishuConfig = z.infer<typeof FeishuConfigSchema>;
+export type FeishuGroupConfig = z.infer<typeof FeishuGroupSchema>;
+
+export type FeishuDomain = "feishu" | "lark";
+export type FeishuConnectionMode = "websocket" | "webhook";
+
+export type ResolvedFeishuAccount = {
+  accountId: string;
+  enabled: boolean;
+  configured: boolean;
+  appId?: string;
+  domain: FeishuDomain;
+};
+
+export type FeishuIdType = "open_id" | "user_id" | "union_id" | "chat_id";
+
+export type FeishuMessageContext = {
+  chatId: string;
+  messageId: string;
+  senderId: string;
+  senderOpenId: string;
+  senderName?: string;
+  chatType: "p2p" | "group";
+  mentionedBot: boolean;
+  rootId?: string;
+  parentId?: string;
+  content: string;
+  contentType: string;
+  /** Mention forward targets (excluding the bot itself) */
+  mentionTargets?: MentionTarget[];
+  /** Extracted message body (after removing @ placeholders) */
+  mentionMessageBody?: string;
+};
+
+export type FeishuSendResult = {
+  messageId: string;
+  chatId: string;
+};
+
+export type FeishuProbeResult = {
+  ok: boolean;
+  error?: string;
+  appId?: string;
+  botName?: string;
+  botOpenId?: string;
+};
+
+export type FeishuMediaInfo = {
+  path: string;
+  contentType?: string;
+  placeholder: string;
+};

package/src/typing.ts

@@ -0,0 +1,73 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+import type { FeishuConfig } from "./types.js";
+import { createFeishuClient } from "./client.js";
+
+// Feishu emoji types for typing indicator
+// See: https://open.feishu.cn/document/server-docs/im-v1/message-reaction/emojis-introduce
+// Full list: https://github.com/go-lark/lark/blob/main/emoji.go
+const TYPING_EMOJI = "Typing"; // Typing indicator emoji
+
+export type TypingIndicatorState = {
+  messageId: string;
+  reactionId: string | null;
+};
+
+/**
+ * Add a typing indicator (reaction) to a message
+ */
+export async function addTypingIndicator(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+}): Promise<TypingIndicatorState> {
+  const { cfg, messageId } = params;
+  const feishuCfg = cfg.channels?.feishu as FeishuConfig | undefined;
+  if (!feishuCfg) {
+    return { messageId, reactionId: null };
+  }
+
+  const client = createFeishuClient(feishuCfg);
+
+  try {
+    const response = await client.im.messageReaction.create({
+      path: { message_id: messageId },
+      data: {
+        reaction_type: { emoji_type: TYPING_EMOJI },
+      },
+    });
+
+    const reactionId = (response as any)?.data?.reaction_id ?? null;
+    return { messageId, reactionId };
+  } catch (err) {
+    // Silently fail - typing indicator is not critical
+    console.log(`[feishu] failed to add typing indicator: ${err}`);
+    return { messageId, reactionId: null };
+  }
+}
+
+/**
+ * Remove a typing indicator (reaction) from a message
+ */
+export async function removeTypingIndicator(params: {
+  cfg: ClawdbotConfig;
+  state: TypingIndicatorState;
+}): Promise<void> {
+  const { cfg, state } = params;
+  if (!state.reactionId) return;
+
+  const feishuCfg = cfg.channels?.feishu as FeishuConfig | undefined;
+  if (!feishuCfg) return;
+
+  const client = createFeishuClient(feishuCfg);
+
+  try {
+    await client.im.messageReaction.delete({
+      path: {
+        message_id: state.messageId,
+        reaction_id: state.reactionId,
+      },
+    });
+  } catch (err) {
+    // Silently fail - cleanup is not critical
+    console.log(`[feishu] failed to remove typing indicator: ${err}`);
+  }
+}