@nextclaw/channel-plugin-feishu 0.2.13 → 0.2.15

package/src/media.ts

@@ -0,0 +1,484 @@
+import fs from "fs";
+import path from "path";
+import { Readable } from "stream";
+import { withTempDownloadPath, type ClawdbotConfig } from "./nextclaw-sdk/feishu.js";
+import { resolveFeishuAccount } from "./accounts.js";
+import { createFeishuClient } from "./client.js";
+import { normalizeFeishuExternalKey } from "./external-keys.js";
+import { getFeishuRuntime } from "./runtime.js";
+import { assertFeishuMessageApiSuccess, toFeishuSendResult } from "./send-result.js";
+import { resolveFeishuSendTarget } from "./send-target.js";
+
+const FEISHU_MEDIA_HTTP_TIMEOUT_MS = 120_000;
+
+export type DownloadImageResult = {
+  buffer: Buffer;
+  contentType?: string;
+};
+
+export type DownloadMessageResourceResult = {
+  buffer: Buffer;
+  contentType?: string;
+  fileName?: string;
+};
+
+function createConfiguredFeishuMediaClient(params: { cfg: ClawdbotConfig; accountId?: string }): {
+  account: ReturnType<typeof resolveFeishuAccount>;
+  client: ReturnType<typeof createFeishuClient>;
+} {
+  const account = resolveFeishuAccount({ cfg: params.cfg, accountId: params.accountId });
+  if (!account.configured) {
+    throw new Error(`Feishu account "${account.accountId}" not configured`);
+  }
+
+  return {
+    account,
+    client: createFeishuClient({
+      ...account,
+      httpTimeoutMs: FEISHU_MEDIA_HTTP_TIMEOUT_MS,
+    }),
+  };
+}
+
+function extractFeishuUploadKey(
+  response: unknown,
+  params: {
+    key: "image_key" | "file_key";
+    errorPrefix: string;
+  },
+): string {
+  // SDK v1.30+ returns data directly without code wrapper on success.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK response type
+  const responseAny = response as any;
+  if (responseAny.code !== undefined && responseAny.code !== 0) {
+    throw new Error(`${params.errorPrefix}: ${responseAny.msg || `code ${responseAny.code}`}`);
+  }
+
+  const key = responseAny[params.key] ?? responseAny.data?.[params.key];
+  if (!key) {
+    throw new Error(`${params.errorPrefix}: no ${params.key} returned`);
+  }
+  return key;
+}
+
+async function readFeishuResponseBuffer(params: {
+  response: unknown;
+  tmpDirPrefix: string;
+  errorPrefix: string;
+}): Promise<Buffer> {
+  const { response } = params;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK response type
+  const responseAny = response as any;
+  if (responseAny.code !== undefined && responseAny.code !== 0) {
+    throw new Error(`${params.errorPrefix}: ${responseAny.msg || `code ${responseAny.code}`}`);
+  }
+
+  if (Buffer.isBuffer(response)) {
+    return response;
+  }
+  if (response instanceof ArrayBuffer) {
+    return Buffer.from(response);
+  }
+  if (responseAny.data && Buffer.isBuffer(responseAny.data)) {
+    return responseAny.data;
+  }
+  if (responseAny.data instanceof ArrayBuffer) {
+    return Buffer.from(responseAny.data);
+  }
+  if (typeof responseAny.getReadableStream === "function") {
+    const stream = responseAny.getReadableStream();
+    const chunks: Buffer[] = [];
+    for await (const chunk of stream) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+  }
+  if (typeof responseAny.writeFile === "function") {
+    return await withTempDownloadPath({ prefix: params.tmpDirPrefix }, async (tmpPath) => {
+      await responseAny.writeFile(tmpPath);
+      return await fs.promises.readFile(tmpPath);
+    });
+  }
+  if (typeof responseAny[Symbol.asyncIterator] === "function") {
+    const chunks: Buffer[] = [];
+    for await (const chunk of responseAny) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+  }
+  if (typeof responseAny.read === "function") {
+    const chunks: Buffer[] = [];
+    for await (const chunk of responseAny as Readable) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+  }
+
+  const keys = Object.keys(responseAny);
+  const types = keys.map((k) => `${k}: ${typeof responseAny[k]}`).join(", ");
+  throw new Error(`${params.errorPrefix}: unexpected response format. Keys: [${types}]`);
+}
+
+/**
+ * Download an image from Feishu using image_key.
+ * Used for downloading images sent in messages.
+ */
+export async function downloadImageFeishu(params: {
+  cfg: ClawdbotConfig;
+  imageKey: string;
+  accountId?: string;
+}): Promise<DownloadImageResult> {
+  const { cfg, imageKey, accountId } = params;
+  const normalizedImageKey = normalizeFeishuExternalKey(imageKey);
+  if (!normalizedImageKey) {
+    throw new Error("Feishu image download failed: invalid image_key");
+  }
+  const { client } = createConfiguredFeishuMediaClient({ cfg, accountId });
+
+  const response = await client.im.image.get({
+    path: { image_key: normalizedImageKey },
+  });
+
+  const buffer = await readFeishuResponseBuffer({
+    response,
+    tmpDirPrefix: "openclaw-feishu-img-",
+    errorPrefix: "Feishu image download failed",
+  });
+  return { buffer };
+}
+
+/**
+ * Download a message resource (file/image/audio/video) from Feishu.
+ * Used for downloading files, audio, and video from messages.
+ */
+export async function downloadMessageResourceFeishu(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+  fileKey: string;
+  type: "image" | "file";
+  accountId?: string;
+}): Promise<DownloadMessageResourceResult> {
+  const { cfg, messageId, fileKey, type, accountId } = params;
+  const normalizedFileKey = normalizeFeishuExternalKey(fileKey);
+  if (!normalizedFileKey) {
+    throw new Error("Feishu message resource download failed: invalid file_key");
+  }
+  const { client } = createConfiguredFeishuMediaClient({ cfg, accountId });
+
+  const response = await client.im.messageResource.get({
+    path: { message_id: messageId, file_key: normalizedFileKey },
+    params: { type },
+  });
+
+  const buffer = await readFeishuResponseBuffer({
+    response,
+    tmpDirPrefix: "openclaw-feishu-resource-",
+    errorPrefix: "Feishu message resource download failed",
+  });
+  return { buffer };
+}
+
+export type UploadImageResult = {
+  imageKey: string;
+};
+
+export type UploadFileResult = {
+  fileKey: string;
+};
+
+export type SendMediaResult = {
+  messageId: string;
+  chatId: string;
+};
+
+/**
+ * Upload an image to Feishu and get an image_key for sending.
+ * Supports: JPEG, PNG, WEBP, GIF, TIFF, BMP, ICO
+ */
+export async function uploadImageFeishu(params: {
+  cfg: ClawdbotConfig;
+  image: Buffer | string; // Buffer or file path
+  imageType?: "message" | "avatar";
+  accountId?: string;
+}): Promise<UploadImageResult> {
+  const { cfg, image, imageType = "message", accountId } = params;
+  const { client } = createConfiguredFeishuMediaClient({ cfg, accountId });
+
+  // SDK accepts Buffer directly or fs.ReadStream for file paths
+  // Using Readable.from(buffer) causes issues with form-data library
+  // See: https://github.com/larksuite/node-sdk/issues/121
+  const imageData = typeof image === "string" ? fs.createReadStream(image) : image;
+
+  const response = await client.im.image.create({
+    data: {
+      image_type: imageType,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK accepts Buffer or ReadStream
+      image: imageData as any,
+    },
+  });
+
+  return {
+    imageKey: extractFeishuUploadKey(response, {
+      key: "image_key",
+      errorPrefix: "Feishu image upload failed",
+    }),
+  };
+}
+
+/**
+ * Sanitize a filename for safe use in Feishu multipart/form-data uploads.
+ * Strips control characters and multipart-injection vectors (CWE-93) while
+ * preserving the original UTF-8 display name (Chinese, emoji, etc.).
+ *
+ * Previous versions percent-encoded non-ASCII characters, but the Feishu
+ * `im.file.create` API uses `file_name` as a literal display name — it does
+ * NOT decode percent-encoding — so encoded filenames appeared as garbled text
+ * in chat (regression in v2026.3.2).
+ */
+export function sanitizeFileNameForUpload(fileName: string): string {
+  return fileName.replace(/[\x00-\x1F\x7F\r\n"\\]/g, "_");
+}
+
+/**
+ * Upload a file to Feishu and get a file_key for sending.
+ * Max file size: 30MB
+ */
+export async function uploadFileFeishu(params: {
+  cfg: ClawdbotConfig;
+  file: Buffer | string; // Buffer or file path
+  fileName: string;
+  fileType: "opus" | "mp4" | "pdf" | "doc" | "xls" | "ppt" | "stream";
+  duration?: number; // Required for audio/video files, in milliseconds
+  accountId?: string;
+}): Promise<UploadFileResult> {
+  const { cfg, file, fileName, fileType, duration, accountId } = params;
+  const { client } = createConfiguredFeishuMediaClient({ cfg, accountId });
+
+  // SDK accepts Buffer directly or fs.ReadStream for file paths
+  // Using Readable.from(buffer) causes issues with form-data library
+  // See: https://github.com/larksuite/node-sdk/issues/121
+  const fileData = typeof file === "string" ? fs.createReadStream(file) : file;
+
+  const safeFileName = sanitizeFileNameForUpload(fileName);
+
+  const response = await client.im.file.create({
+    data: {
+      file_type: fileType,
+      file_name: safeFileName,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK accepts Buffer or ReadStream
+      file: fileData as any,
+      ...(duration !== undefined && { duration }),
+    },
+  });
+
+  return {
+    fileKey: extractFeishuUploadKey(response, {
+      key: "file_key",
+      errorPrefix: "Feishu file upload failed",
+    }),
+  };
+}
+
+/**
+ * Send an image message using an image_key
+ */
+export async function sendImageFeishu(params: {
+  cfg: ClawdbotConfig;
+  to: string;
+  imageKey: string;
+  replyToMessageId?: string;
+  replyInThread?: boolean;
+  accountId?: string;
+}): Promise<SendMediaResult> {
+  const { cfg, to, imageKey, replyToMessageId, replyInThread, accountId } = params;
+  const { client, receiveId, receiveIdType } = resolveFeishuSendTarget({
+    cfg,
+    to,
+    accountId,
+  });
+  const content = JSON.stringify({ image_key: imageKey });
+
+  if (replyToMessageId) {
+    const response = await client.im.message.reply({
+      path: { message_id: replyToMessageId },
+      data: {
+        content,
+        msg_type: "image",
+        ...(replyInThread ? { reply_in_thread: true } : {}),
+      },
+    });
+    assertFeishuMessageApiSuccess(response, "Feishu image reply failed");
+    return toFeishuSendResult(response, receiveId);
+  }
+
+  const response = await client.im.message.create({
+    params: { receive_id_type: receiveIdType },
+    data: {
+      receive_id: receiveId,
+      content,
+      msg_type: "image",
+    },
+  });
+  assertFeishuMessageApiSuccess(response, "Feishu image send failed");
+  return toFeishuSendResult(response, receiveId);
+}
+
+/**
+ * Send a file message using a file_key
+ */
+export async function sendFileFeishu(params: {
+  cfg: ClawdbotConfig;
+  to: string;
+  fileKey: string;
+  /** Use "audio" for audio, "media" for video (mp4), "file" for documents */
+  msgType?: "file" | "audio" | "media";
+  replyToMessageId?: string;
+  replyInThread?: boolean;
+  accountId?: string;
+}): Promise<SendMediaResult> {
+  const { cfg, to, fileKey, replyToMessageId, replyInThread, accountId } = params;
+  const msgType = params.msgType ?? "file";
+  const { client, receiveId, receiveIdType } = resolveFeishuSendTarget({
+    cfg,
+    to,
+    accountId,
+  });
+  const content = JSON.stringify({ file_key: fileKey });
+
+  if (replyToMessageId) {
+    const response = await client.im.message.reply({
+      path: { message_id: replyToMessageId },
+      data: {
+        content,
+        msg_type: msgType,
+        ...(replyInThread ? { reply_in_thread: true } : {}),
+      },
+    });
+    assertFeishuMessageApiSuccess(response, "Feishu file reply failed");
+    return toFeishuSendResult(response, receiveId);
+  }
+
+  const response = await client.im.message.create({
+    params: { receive_id_type: receiveIdType },
+    data: {
+      receive_id: receiveId,
+      content,
+      msg_type: msgType,
+    },
+  });
+  assertFeishuMessageApiSuccess(response, "Feishu file send failed");
+  return toFeishuSendResult(response, receiveId);
+}
+
+/**
+ * Helper to detect file type from extension
+ */
+export function detectFileType(
+  fileName: string,
+): "opus" | "mp4" | "pdf" | "doc" | "xls" | "ppt" | "stream" {
+  const ext = path.extname(fileName).toLowerCase();
+  switch (ext) {
+    case ".opus":
+    case ".ogg":
+      return "opus";
+    case ".mp4":
+    case ".mov":
+    case ".avi":
+      return "mp4";
+    case ".pdf":
+      return "pdf";
+    case ".doc":
+    case ".docx":
+      return "doc";
+    case ".xls":
+    case ".xlsx":
+      return "xls";
+    case ".ppt":
+    case ".pptx":
+      return "ppt";
+    default:
+      return "stream";
+  }
+}
+
+/**
+ * Upload and send media (image or file) from URL, local path, or buffer.
+ * When mediaUrl is a local path, mediaLocalRoots (from core outbound context)
+ * must be passed so loadWebMedia allows the path (post CVE-2026-26321).
+ */
+export async function sendMediaFeishu(params: {
+  cfg: ClawdbotConfig;
+  to: string;
+  mediaUrl?: string;
+  mediaBuffer?: Buffer;
+  fileName?: string;
+  replyToMessageId?: string;
+  replyInThread?: boolean;
+  accountId?: string;
+  /** Allowed roots for local path reads; required for local filePath to work. */
+  mediaLocalRoots?: readonly string[];
+}): Promise<SendMediaResult> {
+  const {
+    cfg,
+    to,
+    mediaUrl,
+    mediaBuffer,
+    fileName,
+    replyToMessageId,
+    replyInThread,
+    accountId,
+    mediaLocalRoots,
+  } = params;
+  const account = resolveFeishuAccount({ cfg, accountId });
+  if (!account.configured) {
+    throw new Error(`Feishu account "${account.accountId}" not configured`);
+  }
+  const mediaMaxBytes = (account.config?.mediaMaxMb ?? 30) * 1024 * 1024;
+
+  let buffer: Buffer;
+  let name: string;
+
+  if (mediaBuffer) {
+    buffer = mediaBuffer;
+    name = fileName ?? "file";
+  } else if (mediaUrl) {
+    const loaded = await getFeishuRuntime().media.loadWebMedia(mediaUrl, {
+      maxBytes: mediaMaxBytes,
+      optimizeImages: false,
+      localRoots: mediaLocalRoots?.length ? mediaLocalRoots : undefined,
+    });
+    buffer = loaded.buffer;
+    name = fileName ?? loaded.fileName ?? "file";
+  } else {
+    throw new Error("Either mediaUrl or mediaBuffer must be provided");
+  }
+
+  // Determine if it's an image based on extension
+  const ext = path.extname(name).toLowerCase();
+  const isImage = [".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp", ".ico", ".tiff"].includes(ext);
+
+  if (isImage) {
+    const { imageKey } = await uploadImageFeishu({ cfg, image: buffer, accountId });
+    return sendImageFeishu({ cfg, to, imageKey, replyToMessageId, replyInThread, accountId });
+  } else {
+    const fileType = detectFileType(name);
+    const { fileKey } = await uploadFileFeishu({
+      cfg,
+      file: buffer,
+      fileName: name,
+      fileType,
+      accountId,
+    });
+    // Feishu API: opus -> "audio", mp4/video -> "media" (playable), others -> "file"
+    const msgType = fileType === "opus" ? "audio" : fileType === "mp4" ? "media" : "file";
+    return sendFileFeishu({
+      cfg,
+      to,
+      fileKey,
+      msgType,
+      replyToMessageId,
+      replyInThread,
+      accountId,
+    });
+  }
+}

package/src/mention.ts

@@ -0,0 +1,133 @@
+import type { FeishuMessageEvent } from "./bot.js";
+
+/**
+ * Escape regex metacharacters so user-controlled mention fields are treated literally.
+ */
+export function escapeRegExp(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Mention target user info
+ */
+export type MentionTarget = {
+  openId: string;
+  name: string;
+  key: string; // Placeholder in original message, e.g. @_user_1
+};
+
+/**
+ * Extract mention targets from message event (excluding the bot itself)
+ */
+export function extractMentionTargets(
+  event: FeishuMessageEvent,
+  botOpenId?: string,
+): MentionTarget[] {
+  const mentions = event.message.mentions ?? [];
+
+  return mentions
+    .filter((m) => {
+      // Exclude the bot itself
+      if (botOpenId && m.id.open_id === botOpenId) {
+        return false;
+      }
+      // Must have open_id
+      return !!m.id.open_id;
+    })
+    .map((m) => ({
+      openId: m.id.open_id!,
+      name: m.name,
+      key: m.key,
+    }));
+}
+
+/**
+ * Check if message is a mention forward request
+ * Rules:
+ * - Group: message mentions bot + at least one other user
+ * - DM: message mentions any user (no need to mention bot)
+ */
+export function isMentionForwardRequest(event: FeishuMessageEvent, botOpenId?: string): boolean {
+  const mentions = event.message.mentions ?? [];
+  if (mentions.length === 0) {
+    return false;
+  }
+
+  const isDirectMessage = event.message.chat_type !== "group";
+  const hasOtherMention = mentions.some((m) => m.id.open_id !== botOpenId);
+
+  if (isDirectMessage) {
+    // DM: trigger if any non-bot user is mentioned
+    return hasOtherMention;
+  } else {
+    // Group: need to mention both bot and other users
+    const hasBotMention = mentions.some((m) => m.id.open_id === botOpenId);
+    return hasBotMention && hasOtherMention;
+  }
+}
+
+/**
+ * Extract message body from text (remove @ placeholders)
+ */
+export function extractMessageBody(text: string, allMentionKeys: string[]): string {
+  let result = text;
+
+  // Remove all @ placeholders
+  for (const key of allMentionKeys) {
+    result = result.replace(new RegExp(escapeRegExp(key), "g"), "");
+  }
+
+  return result.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Format @mention for text message
+ */
+export function formatMentionForText(target: MentionTarget): string {
+  return `<at user_id="${target.openId}">${target.name}</at>`;
+}
+
+/**
+ * Format @everyone for text message
+ */
+export function formatMentionAllForText(): string {
+  return `<at user_id="all">Everyone</at>`;
+}
+
+/**
+ * Format @mention for card message (lark_md)
+ */
+export function formatMentionForCard(target: MentionTarget): string {
+  return `<at id=${target.openId}></at>`;
+}
+
+/**
+ * Format @everyone for card message
+ */
+export function formatMentionAllForCard(): string {
+  return `<at id=all></at>`;
+}
+
+/**
+ * Build complete message with @mentions (text format)
+ */
+export function buildMentionedMessage(targets: MentionTarget[], message: string): string {
+  if (targets.length === 0) {
+    return message;
+  }
+
+  const mentionParts = targets.map((t) => formatMentionForText(t));
+  return `${mentionParts.join(" ")} ${message}`;
+}
+
+/**
+ * Build card content with @mentions (Markdown format)
+ */
+export function buildMentionedCardContent(targets: MentionTarget[], message: string): string {
+  if (targets.length === 0) {
+    return message;
+  }
+
+  const mentionParts = targets.map((t) => formatMentionForCard(t));
+  return `${mentionParts.join(" ")} ${message}`;
+}