/** * Feishu lark client + long-connection event dispatcher. * * Handles: ws event receiving (im.message.receive_v1 + card.action.trigger), * message sending, streaming patch via interactive cards, emoji * reactions, file download/upload, and the card action callback. */ import * as lark from "@larksuiteoapi/node-sdk"; import { readFile, writeFile, mkdir } from "node:fs/promises"; import { dirname } from "node:path"; import type { FastifyBaseLogger } from "fastify"; export interface FeishuConfig { readonly appId: string; readonly appSecret: string; readonly botOpenId: string; } export interface FeishuRuntime { readonly client: lark.Client; readonly logger: FastifyBaseLogger; } export interface OutboundPayload { readonly msgType: string; readonly content: string; } /** Raw `im.message.receive_v1` event payload. */ export interface MessageReceiveEvent { /** Feishu's SDK dispatcher flattens v2 headers onto the top-level payload. */ readonly event_id?: string; readonly event_type?: string; readonly header?: { readonly event_id?: string; readonly event_type?: string }; readonly message: { readonly message_id: string; readonly root_id?: string; readonly parent_id?: string; readonly thread_id?: string; readonly create_time?: string; readonly update_time?: string; readonly chat_id: string; readonly chat_type: string; readonly message_type: string; readonly content: string; readonly mentions?: ReadonlyArray<{ readonly key: string; readonly id: { readonly open_id?: string }; readonly name: string; }>; }; readonly sender: { readonly sender_id: { readonly open_id?: string }; readonly sender_type: string; }; } /** Card action trigger event (button clicks, select changes). */ export interface CardActionEvent { readonly operator: { readonly open_id?: string }; readonly action: { readonly value?: unknown; readonly tag?: string; readonly option?: string; }; readonly context?: { readonly open_message_id?: string; readonly open_chat_id?: string }; readonly token?: string; } // --- Message helpers --- export function buildOutboundPayload(content: string): OutboundPayload { if (containsMarkdownTable(content)) { return { msgType: "text", content: JSON.stringify({ text: content }) }; } if (containsMarkdownSyntax(content)) { return { msgType: "post", content: JSON.stringify({ zh_cn: { content: _buildMarkdownPostRows(content) } }), }; } return { msgType: "text", content: JSON.stringify({ text: content }) }; } export function _buildMarkdownPostRows(content: string): unknown[][] { if (!content.includes("```")) { return [[{ tag: "md", text: content }]]; } const rows: unknown[][] = []; const codeBlockPattern = /```[\s\S]*?```/g; let cursor = 0; let match: RegExpExecArray | null; while ((match = codeBlockPattern.exec(content)) !== null) { if (match.index > cursor) { rows.push([{ tag: "md", text: content.slice(cursor, match.index) }]); } rows.push([{ tag: "md", text: match[0] }]); cursor = match.index + match[0].length; } if (rows.length === 0) { return [[{ tag: "md", text: content }]]; } if (cursor < content.length) { rows.push([{ tag: "md", text: content.slice(cursor) }]); } return rows; } export function _stripMarkdownToPlainText(text: string): string { return text .replace(/```[^\n`]*\n?([\s\S]*?)```/g, "$1") .replace(/`([^`\n]+)`/g, "$1") .replace(/!\[([^\]\n]*)\]\([^)]+\)/g, "$1") .replace(/\[([^\]\n]+)\]\([^)]+\)/g, "$1") .replace(/^ {0,3}#{1,6}\s+/gm, "") .replace(/^ {0,3}>\s?/gm, "") .replace(/^(\s*)[-*+]\s+/gm, "$1") .replace(/^(\s*)\d+[.)]\s+/gm, "$1") .replace(/\*\*([^*\n]+)\*\*/g, "$1") .replace(/__([^_\n]+)__/g, "$1") .replace(/~~([^~\n]+)~~/g, "$1") .replace(/(^|[^*])\*([^*\n]+)\*/g, "$1$2") .replace(/(^|[^_])_([^_\n]+)_/g, "$1$2"); } /** Send a text message using the best Feishu message type for the content. */ export async function sendTextMessage(rt: FeishuRuntime, chatId: string, text: string): Promise { const payload = buildOutboundPayload(text); const client = rt.client as unknown as { im: { v1: { message: { create: (p: unknown) => Promise } } }; }; try { const res = await client.im.v1.message.create({ params: { receive_id_type: "chat_id" }, data: { receive_id: chatId, msg_type: payload.msgType, content: payload.content }, }); return messageIdFromResponse(res); } catch (e) { if (payload.msgType === "post" && isPostContentFormatError(e)) { try { const res = await client.im.v1.message.create({ params: { receive_id_type: "chat_id" }, data: { receive_id: chatId, msg_type: "text", content: JSON.stringify({ text: _stripMarkdownToPlainText(text) }), }, }); return messageIdFromResponse(res); } catch { return null; } } return null; } } /** Send a plain text message (fire-and-forget). */ export async function sendText(rt: FeishuRuntime, chatId: string, text: string): Promise { await sendTextMessage(rt, chatId, text); } /** Patch a text-as-card message in-place (streaming updates). */ export async function patchTextMessage(rt: FeishuRuntime, messageId: string, text: string): Promise { const payload = buildOutboundPayload(text); const card = buildInteractiveCardFromOutboundPayload(payload); const client = rt.client as unknown as { im: { v1: { message: { patch: (p: unknown) => Promise } } }; }; try { await client.im.v1.message.patch({ path: { message_id: messageId }, params: { msg_type: "interactive" }, data: { content: JSON.stringify(card) }, }); } catch (e) { rt.logger.warn({ messageId, err: e instanceof Error ? e.message : String(e) }, "patchTextMessage failed"); } } /** Send an approval card with buttons. Returns message_id on success. */ export async function sendApprovalCard( rt: FeishuRuntime, chatId: string, title: string, body: string, buttons: ReadonlyArray<{ label: string; value: string; style?: "primary" | "default" | "danger" }>, ): Promise { const card = { config: { wide_screen_mode: true }, header: { title: { content: title, tag: "plain_text" }, template: "orange" }, elements: [ { tag: "markdown", content: body }, { tag: "action", actions: buttons.map((button) => ({ tag: "button", text: { tag: "plain_text", content: button.label }, type: button.style ?? "default", value: { approval_action: button.value }, })), }, ], }; const client = rt.client as unknown as { im: { v1: { message: { create: (p: unknown) => Promise } } }; }; try { const res = await client.im.v1.message.create({ params: { receive_id_type: "chat_id" }, data: { receive_id: chatId, msg_type: "interactive", content: JSON.stringify(card) }, }); return messageIdFromResponse(res); } catch (e) { rt.logger.warn({ chatId, err: e instanceof Error ? e.message : String(e) }, "sendApprovalCard failed"); return null; } } /** Update a card to show it has been resolved. */ export async function resolveCard( rt: FeishuRuntime, messageId: string, icon: string, label: string, template: "green" | "red", resolvedBy: string, ): Promise { const card = { config: { wide_screen_mode: true }, header: { title: { content: `${icon} ${label}`, tag: "plain_text" }, template }, elements: [{ tag: "markdown", content: `${icon} **${label}** by ${resolvedBy}` }], }; const client = rt.client as unknown as { im: { v1: { message: { patch: (p: unknown) => Promise } } }; }; try { await client.im.v1.message.patch({ path: { message_id: messageId }, params: { msg_type: "interactive" }, data: { content: JSON.stringify(card) }, }); } catch (e) { rt.logger.warn({ messageId, err: e instanceof Error ? e.message : String(e) }, "resolveCard failed"); } } /** React to a message with an emoji. */ export async function reactToMessage(rt: FeishuRuntime, messageId: string, emoji: string): Promise { try { await rt.client.request({ method: "POST", url: `/open-apis/im/v1/messages/${messageId}/reactions`, data: { reaction_type: { emoji_type: emoji } }, }); } catch (e) { rt.logger.warn({ messageId, err: e instanceof Error ? e.message : String(e) }, "reactToMessage failed"); } } /** Add a reaction to a message, returning the reaction_id (needed for later removal). */ export async function addReaction(rt: FeishuRuntime, messageId: string, emojiType: string): Promise { try { const res = await rt.client.request({ method: "POST", url: `/open-apis/im/v1/messages/${messageId}/reactions`, data: { reaction_type: { emoji_type: emojiType } }, }) as ReactionCreateResponse; const reactionId = reactionIdFromResponse(res); if (reactionId === null) { rt.logger.warn({ messageId, emojiType }, "addReaction failed: response missing reaction_id"); } return reactionId; } catch (e) { rt.logger.warn({ messageId, emojiType, err: e instanceof Error ? e.message : String(e) }, "addReaction failed"); return null; } } /** Remove a previously added reaction by its reaction_id. */ export async function removeReaction(rt: FeishuRuntime, messageId: string, reactionId: string): Promise { try { await rt.client.request({ method: "DELETE", url: `/open-apis/im/v1/messages/${messageId}/reactions/${reactionId}`, }); return true; } catch (e) { rt.logger.warn({ messageId, reactionId, err: e instanceof Error ? e.message : String(e) }, "removeReaction failed"); return false; } } // --- File helpers --- /** Download a file/image from a Feishu message to a local path. */ export async function downloadMessageFile( rt: FeishuRuntime, messageId: string, fileKey: string, savePath: string, ): Promise { await mkdir(dirname(savePath), { recursive: true }); try { const res = await rt.client.request({ method: "GET", url: `/open-apis/im/v1/messages/${messageId}/resources/${fileKey}`, params: { type: "file" }, responseType: "arraybuffer", }) as { data: Buffer }; await writeFile(savePath, res.data); } catch (e) { rt.logger.warn({ messageId, fileKey, err: e instanceof Error ? e.message : String(e) }, "downloadMessageFile failed"); } } /** Upload and send a file to a chat. */ export async function sendFile(rt: FeishuRuntime, chatId: string, filePath: string, fileName: string): Promise { const client = rt.client as unknown as { im: { v1: { file: { create: (p: unknown) => Promise } message: { create: (p: unknown) => Promise } } }; }; try { const buf = await readFile(filePath); const ext = fileName.split(".").pop() ?? ""; const fileType = ext === "pdf" ? "pdf" : ext === "doc" ? "doc" : ext === "xls" ? "xls" : ext === "ppt" ? "ppt" : "stream"; const uploadRes = await client.im.v1.file.create({ data: { file_type: fileType, file_name: fileName, file: buf } }); const fileKey = fileKeyFromResponse(uploadRes); if (fileKey === undefined) { rt.logger.warn({ chatId, filePath }, "sendFile failed: upload response missing file_key"); return null; } const msgRes = await client.im.v1.message.create({ params: { receive_id_type: "chat_id" }, data: { receive_id: chatId, msg_type: "file", content: JSON.stringify({ file_key: fileKey }) }, }); const messageId = messageIdFromResponse(msgRes); if (messageId === null) { rt.logger.warn({ chatId, filePath }, "sendFile failed: message response missing message_id"); } return messageId; } catch (e) { rt.logger.warn({ chatId, filePath, err: e instanceof Error ? e.message : String(e) }, "sendFile failed"); return null; } } type MessageCreateResponse = { readonly message_id?: string | undefined; readonly data?: { readonly message_id?: string | undefined } | undefined; } | null; type FileCreateResponse = { readonly file_key?: string | undefined; readonly data?: { readonly file_key?: string | undefined } | undefined; } | null; type ReactionCreateResponse = { readonly reaction_id?: string | undefined; readonly data?: { readonly reaction_id?: string | undefined } | undefined; } | null; function messageIdFromResponse(res: MessageCreateResponse): string | null { return res?.data?.message_id ?? res?.message_id ?? null; } function fileKeyFromResponse(res: FileCreateResponse): string | undefined { return res?.file_key ?? res?.data?.file_key; } function reactionIdFromResponse(res: ReactionCreateResponse): string | null { return res?.data?.reaction_id ?? res?.reaction_id ?? null; } function containsMarkdownSyntax(content: string): boolean { const patterns = [ /^ {0,3}#{1,6}\s+\S/m, /^ {0,3}>\s+\S/m, /^ {0,3}(?:[-*+]\s+\S|\d+[.)]\s+\S)/m, /```/, /`[^`\n]+`/, /\*\*[^*\n]+\*\*/, /__[^_\n]+__/, /~~[^~\n]+~~/, /(^|[^*])\*[^*\s][^*\n]*\*(?!\*)/, /(^|[^_])_[^_\s][^_\n]*_(?!_)/, /\[[^\]\n]+\]\([^)]+\)/, ]; return patterns.some((pattern) => pattern.test(content)); } function containsMarkdownTable(content: string): boolean { const lines = content.split(/\r?\n/); for (let i = 0; i < lines.length - 1; i += 1) { const current = lines[i]; const next = lines[i + 1]; if (current !== undefined && next !== undefined && isTableHeaderLine(current) && isTableSeparatorLine(next)) { return true; } } return false; } function isTableHeaderLine(line: string): boolean { const trimmed = line.trim(); return trimmed.startsWith("|") && trimmed.includes("|", 1); } function isTableSeparatorLine(line: string): boolean { const trimmed = line.trim(); if (!trimmed.startsWith("|")) return false; const cells = trimmed.replace(/^\|/, "").replace(/\|$/, "").split("|"); return cells.length > 0 && cells.every((cell) => /^:?-{3,}:?$/.test(cell.trim())); } function buildInteractiveCardFromOutboundPayload(payload: OutboundPayload): { elements: Array<{ tag: "div"; text: { tag: "lark_md"; content: string } }> } { return { elements: rowsFromOutboundPayload(payload).map((row) => ({ tag: "div", text: { tag: "lark_md", content: row.map(markdownTextFromPostElement).join("") }, })), }; } function rowsFromOutboundPayload(payload: OutboundPayload): unknown[][] { if (payload.msgType !== "post") { return [[{ tag: "md", text: textFromTextPayload(payload.content) }]]; } try { const parsed = JSON.parse(payload.content) as { zh_cn?: { content?: unknown } }; return Array.isArray(parsed.zh_cn?.content) ? parsed.zh_cn.content as unknown[][] : [[{ tag: "md", text: "" }]]; } catch { return [[{ tag: "md", text: "" }]]; } } function textFromTextPayload(content: string): string { try { const parsed = JSON.parse(content) as { text?: unknown }; return typeof parsed.text === "string" ? parsed.text : content; } catch { return content; } } function markdownTextFromPostElement(element: unknown): string { if (typeof element !== "object" || element === null) return ""; const text = (element as { text?: unknown }).text; return typeof text === "string" ? text : ""; } function isPostContentFormatError(error: unknown): boolean { return errorText(error).includes("content format of the post type is incorrect"); } function errorText(error: unknown): string { if (error instanceof Error) { return `${error.message} ${errorText((error as { response?: unknown }).response)}`; } if (typeof error === "string") return error; if (typeof error === "object" && error !== null) { try { return JSON.stringify(error); } catch { return String(error); } } return String(error); } // --- Lark client + ws listener --- export function createLarkClient(config: FeishuConfig): lark.Client { return new lark.Client({ appId: config.appId, appSecret: config.appSecret, appType: lark.AppType.SelfBuild, }); } export function startFeishuListenerWithClient( config: FeishuConfig, client: lark.Client, logger: FastifyBaseLogger, onMessage: (event: MessageReceiveEvent, rt: FeishuRuntime) => Promise, onCardAction?: (event: CardActionEvent, rt: FeishuRuntime) => Promise, ): FeishuRuntime { const wsClient = new lark.WSClient({ appId: config.appId, appSecret: config.appSecret, domain: lark.Domain.Feishu, loggerLevel: lark.LoggerLevel.info, }); const rt: FeishuRuntime = { client, logger }; const handlers: Record Promise> = { "im.message.receive_v1": async (data) => { try { await onMessage(data as MessageReceiveEvent, rt); } catch (e) { logger.error({ err: e }, "feishu message handler threw"); } }, }; if (onCardAction !== undefined) { handlers["card.action.trigger"] = async (data) => { try { await onCardAction(data as CardActionEvent, rt); } catch (e) { logger.error({ err: e }, "feishu card action handler threw"); } }; } void wsClient.start({ eventDispatcher: new lark.EventDispatcher({}).register(handlers) }); return rt; } export function startFeishuListener( config: FeishuConfig, logger: FastifyBaseLogger, onMessage: (event: MessageReceiveEvent, rt: FeishuRuntime) => Promise, onCardAction?: (event: CardActionEvent, rt: FeishuRuntime) => Promise, ): FeishuRuntime { return startFeishuListenerWithClient(config, createLarkClient(config), logger, onMessage, onCardAction); }