@m1heng-clawd/feishu 0.1.13 → 0.1.15

package/src/drive-tools/actions.ts

@@ -5,6 +5,30 @@ import type { FeishuDriveParams } from "./schemas.js";
 type DriveMoveType = "doc" | "docx" | "sheet" | "bitable" | "folder" | "file" | "mindnote" | "slides";
 type DriveDeleteType = DriveMoveType | "shortcut";
 
+async function getFileType(client: DriveClient, fileToken: string): Promise<string> {
+  let pageToken: string | undefined;
+  
+  do {
+    const listRes = await runDriveApiCall("drive.file.list", () =>
+      client.drive.file.list({
+        params: pageToken ? { page_token: pageToken } : {},
+      }),
+    );
+
+    const file = listRes.data?.files?.find((f: any) => f.token === fileToken);
+    if (file) {
+      if (!file.type) {
+        throw new Error(`File found but no type for ${fileToken}. Please provide the 'type' parameter explicitly.`);
+      }
+      return file.type;
+    }
+    
+    pageToken = listRes.data?.next_page_token;
+  } while (pageToken);
+
+  throw new Error(`File not found: ${fileToken}. Please provide the 'type' parameter explicitly.`);
+}
+
 async function getRootFolderToken(client: DriveClient): Promise<string> {
   // Use generic HTTP client to call the root folder meta API
   // as it's not directly exposed in the SDK.
@@ -46,27 +70,32 @@ async function listFolder(client: DriveClient, folderToken?: string) {
 }
 
 async function getFileInfo(client: DriveClient, fileToken: string, folderToken?: string) {
-  // Use list with folder_token to find file info.
-  const res = await runDriveApiCall("drive.file.list", () =>
-    client.drive.file.list({
-      params: folderToken ? { folder_token: folderToken } : {},
-    }),
-  );
+  let pageToken: string | undefined;
+
+  do {
+    const res = await runDriveApiCall("drive.file.list", () =>
+      client.drive.file.list({
+        params: folderToken ? { folder_token: folderToken, page_token: pageToken } : { page_token: pageToken },
+      }),
+    );
+
+    const file = res.data?.files?.find((f: any) => f.token === fileToken);
+    if (file) {
+      return {
+        token: file.token,
+        name: file.name,
+        type: file.type,
+        url: file.url,
+        created_time: file.created_time,
+        modified_time: file.modified_time,
+        owner_id: file.owner_id,
+      };
+    }
 
-  const file = res.data?.files?.find((f) => f.token === fileToken);
-  if (!file) {
-    throw new Error(`File not found: ${fileToken}`);
-  }
+    pageToken = res.data?.next_page_token;
+  } while (pageToken);
 
-  return {
-    token: file.token,
-    name: file.name,
-    type: file.type,
-    url: file.url,
-    created_time: file.created_time,
-    modified_time: file.modified_time,
-    owner_id: file.owner_id,
-  };
+  throw new Error(`File not found: ${fileToken}`);
 }
 
 async function createFolder(client: DriveClient, name: string, folderToken?: string) {
@@ -119,12 +148,18 @@ async function moveFile(
   };
 }
 
-async function deleteFile(client: DriveClient, fileToken: string, type: string) {
+async function deleteFile(client: DriveClient, fileToken: string, type?: string) {
+  let effectiveType = type;
+
+  if (!effectiveType) {
+    effectiveType = await getFileType(client, fileToken);
+  }
+
   const res = await runDriveApiCall("drive.file.delete", () =>
     client.drive.file.delete({
       path: { file_token: fileToken },
       params: {
-        type: type as DriveDeleteType,
+        type: effectiveType as DriveDeleteType,
       },
     }),
   );
@@ -132,6 +167,7 @@ async function deleteFile(client: DriveClient, fileToken: string, type: string)
   return {
     success: true,
     task_id: res.data?.task_id,
+    type_used: effectiveType,
   };
 }
 

package/src/drive-tools/schemas.ts

@@ -26,7 +26,7 @@ export const FeishuDriveSchema = Type.Union([
   Type.Object({
     action: Type.Literal("info"),
     file_token: Type.String({ description: "File or folder token" }),
-    type: FileType,
+    type: Type.Optional(FileType),
   }),
   Type.Object({
     action: Type.Literal("create_folder"),
@@ -44,7 +44,7 @@ export const FeishuDriveSchema = Type.Union([
   Type.Object({
     action: Type.Literal("delete"),
     file_token: Type.String({ description: "File token to delete" }),
-    type: FileType,
+    type: Type.Optional(FileType),
   }),
   Type.Object({
     action: Type.Literal("import_document"),

package/src/media-duration.ts

@@ -0,0 +1,190 @@
+/**
+ * Media duration parsers for Feishu file upload.
+ *
+ * Feishu's im.file.create API requires a `duration` (in ms) for audio and video
+ * so that the player shows the correct length and enables seeking.
+ *
+ * Supported containers:
+ *   - OGG  (Opus / Vorbis)  — used by Feishu voice messages and most AI TTS output
+ *   - MP4  (ISO base media) — MP4, MOV, QuickTime, M4A, M4V, 3GP share this format
+ *   - WAV  (RIFF PCM)       — uncompressed audio
+ *
+ * Formats intentionally skipped (complex frame-level parsing, rare in practice):
+ *   - MP3 (VBR makes byte-count estimation unreliable without scanning all frames)
+ *   - Raw AAC / ADTS
+ */
+
+/**
+ * Parse duration from an OGG container (Opus or Vorbis).
+ * Reads the granule position from the last OGG page and divides by sample rate.
+ * Returns duration in milliseconds, or undefined if not OGG or parsing fails.
+ */
+export function parseOggDurationMs(buffer: Buffer): number | undefined {
+  if (buffer.length < 27) return undefined;
+  // Verify OGG capture pattern "OggS"
+  if (buffer[0] !== 0x4f || buffer[1] !== 0x67 || buffer[2] !== 0x67 || buffer[3] !== 0x53) {
+    return undefined;
+  }
+
+  // Detect codec and sample rate from identification header (scan first 4 KB)
+  let sampleRate = 0;
+  const searchLen = Math.min(buffer.length, 4096);
+  for (let i = 0; i < searchLen - 8; i++) {
+    // "OpusHead" — Opus always uses 48000 Hz for granule positions
+    if (
+      buffer[i] === 0x4f && buffer[i + 1] === 0x70 && buffer[i + 2] === 0x75 &&
+      buffer[i + 3] === 0x73 && buffer[i + 4] === 0x48 && buffer[i + 5] === 0x65 &&
+      buffer[i + 6] === 0x61 && buffer[i + 7] === 0x64
+    ) {
+      sampleRate = 48000;
+      break;
+    }
+    // "\x01vorbis" — sample rate is uint32LE at +12 from start of tag
+    if (
+      buffer[i] === 0x01 && buffer[i + 1] === 0x76 && buffer[i + 2] === 0x6f &&
+      buffer[i + 3] === 0x72 && buffer[i + 4] === 0x62 && buffer[i + 5] === 0x69 &&
+      buffer[i + 6] === 0x73
+    ) {
+      if (i + 16 <= buffer.length) sampleRate = buffer.readUInt32LE(i + 12);
+      break;
+    }
+  }
+  if (sampleRate === 0) return undefined;
+
+  // Scan all OGG pages to find the highest valid granule position
+  let lastGranule = 0;
+  let offset = 0;
+  while (offset + 27 <= buffer.length) {
+    if (
+      buffer[offset] !== 0x4f || buffer[offset + 1] !== 0x67 ||
+      buffer[offset + 2] !== 0x67 || buffer[offset + 3] !== 0x53
+    ) break;
+    // Granule position: 8 bytes LE at offset+6; 0xFFFFFFFFFFFFFFFF means "no position"
+    const lo = buffer.readUInt32LE(offset + 6);
+    const hi = buffer.readUInt32LE(offset + 10);
+    if (lo !== 0xffffffff || hi !== 0xffffffff) {
+      const granule = hi * 0x100000000 + lo;
+      if (granule > lastGranule) lastGranule = granule;
+    }
+    const numSegments = buffer.readUInt8(offset + 26);
+    if (offset + 27 + numSegments > buffer.length) break;
+    let pageDataSize = 0;
+    for (let i = 0; i < numSegments; i++) pageDataSize += buffer.readUInt8(offset + 27 + i);
+    offset += 27 + numSegments + pageDataSize;
+  }
+
+  if (lastGranule <= 0) return undefined;
+  return Math.round((lastGranule / sampleRate) * 1000);
+}
+
+/**
+ * Parse duration from an ISO base media file format container (MP4 / MOV / M4A / QuickTime / 3GP).
+ * Reads the `mvhd` (movie header) box inside `moov`.
+ * Returns duration in milliseconds, or undefined if the box is not found.
+ */
+export function parseMp4DurationMs(buffer: Buffer): number | undefined {
+  // Find 'moov' box at the top level
+  let offset = 0;
+  let moovStart = -1;
+  let moovEnd = -1;
+  while (offset + 8 <= buffer.length) {
+    const boxSize = buffer.readUInt32BE(offset);
+    if (boxSize < 8) break;
+    if (buffer.toString("ascii", offset + 4, offset + 8) === "moov") {
+      moovStart = offset;
+      moovEnd = Math.min(offset + boxSize, buffer.length);
+      break;
+    }
+    offset += boxSize;
+  }
+  if (moovStart < 0) return undefined;
+
+  // Find 'mvhd' inside 'moov'
+  let inner = moovStart + 8;
+  while (inner + 8 <= moovEnd) {
+    const boxSize = buffer.readUInt32BE(inner);
+    if (boxSize < 8) break;
+    if (buffer.toString("ascii", inner + 4, inner + 8) === "mvhd") {
+      const version = buffer.readUInt8(inner + 8);
+      if (version === 0) {
+        // creation(4) + modification(4) + timescale(4) + duration(4)
+        if (inner + 28 > buffer.length) return undefined;
+        const timeScale = buffer.readUInt32BE(inner + 20);
+        const duration = buffer.readUInt32BE(inner + 24);
+        if (timeScale === 0) return undefined;
+        return Math.round((duration / timeScale) * 1000);
+      } else if (version === 1) {
+        // creation(8) + modification(8) + timescale(4) + duration(8)
+        if (inner + 40 > buffer.length) return undefined;
+        const timeScale = buffer.readUInt32BE(inner + 28);
+        const durationHi = buffer.readUInt32BE(inner + 32);
+        const durationLo = buffer.readUInt32BE(inner + 36);
+        const duration = durationHi * 0x100000000 + durationLo;
+        if (timeScale === 0) return undefined;
+        return Math.round((duration / timeScale) * 1000);
+      }
+      return undefined;
+    }
+    inner += boxSize;
+  }
+  return undefined;
+}
+
+/**
+ * Parse duration from a WAV (RIFF PCM) file.
+ * Computes duration from the `data` chunk size and the byte rate in the `fmt ` chunk.
+ * Returns duration in milliseconds, or undefined if not WAV or parsing fails.
+ */
+export function parseWavDurationMs(buffer: Buffer): number | undefined {
+  if (buffer.length < 44) return undefined;
+  if (buffer.toString("ascii", 0, 4) !== "RIFF") return undefined;
+  if (buffer.toString("ascii", 8, 12) !== "WAVE") return undefined;
+
+  let offset = 12;
+  let byteRate = 0;
+  let dataSize = 0;
+
+  while (offset + 8 <= buffer.length) {
+    const chunkId = buffer.toString("ascii", offset, offset + 4);
+    const chunkSize = buffer.readUInt32LE(offset + 4);
+    if (chunkId === "fmt ") {
+      // fmt chunk layout (from chunk start):
+      //   +0  chunk id "fmt " (4)
+      //   +4  chunk size (4)
+      //   +8  audio format (2)
+      //   +10 num channels (2)
+      //   +12 sample rate (4)
+      //   +16 byte rate (4)  ← what we need
+      if (offset + 20 > buffer.length) return undefined;
+      byteRate = buffer.readUInt32LE(offset + 16);
+    } else if (chunkId === "data") {
+      dataSize = chunkSize;
+      break;
+    }
+    // Advance to next chunk; RIFF chunks are aligned to even byte boundaries
+    offset += 8 + chunkSize + (chunkSize % 2);
+  }
+
+  if (byteRate === 0 || dataSize === 0) return undefined;
+  return Math.round((dataSize / byteRate) * 1000);
+}
+
+/**
+ * Parse duration from a media buffer for Feishu upload.
+ *
+ * Routes to the appropriate parser based on Feishu's file type:
+ *   - "mp4"  → MP4/MOV/QuickTime container parser
+ *   - "opus" → OGG parser, then MP4 container (covers M4A), then WAV
+ *
+ * Returns duration in milliseconds, or undefined if not determinable.
+ */
+export function parseFeishuMediaDurationMs(
+  buffer: Buffer,
+  fileType: "opus" | "mp4",
+): number | undefined {
+  if (fileType === "mp4") {
+    return parseMp4DurationMs(buffer);
+  }
+  // fileType === "opus": try each container format in likelihood order
+  return parseOggDurationMs(buffer) ?? parseMp4DurationMs(buffer) ?? parseWavDurationMs(buffer);
+}

package/src/media.ts

@@ -3,6 +3,7 @@ import { createFeishuClient } from "./client.js";
 import { resolveFeishuAccount } from "./accounts.js";
 import { getFeishuRuntime } from "./runtime.js";
 import { resolveReceiveIdType, normalizeFeishuTarget } from "./targets.js";
+import { parseFeishuMediaDurationMs } from "./media-duration.js";
 import fs from "fs";
 import path from "path";
 import os from "os";
@@ -236,6 +237,24 @@ export async function uploadImageFeishu(params: {
   return { imageKey };
 }
 
+/**
+ * Encode a filename for safe use in Feishu multipart/form-data uploads.
+ * Non-ASCII characters (Chinese, em-dash, full-width brackets, etc.) cause
+ * the upload to silently fail when passed raw through the SDK's form-data
+ * serialization. RFC 5987 percent-encoding keeps headers 7-bit clean while
+ * Feishu's server decodes and preserves the original display name.
+ */
+export function sanitizeFileNameForUpload(fileName: string): string {
+  const ASCII_ONLY = /^[\x20-\x7E]+$/;
+  if (ASCII_ONLY.test(fileName)) {
+    return fileName;
+  }
+  return encodeURIComponent(fileName)
+    .replace(/'/g, "%27")
+    .replace(/\(/g, "%28")
+    .replace(/\)/g, "%29");
+}
+
 /**
  * Upload a file to Feishu and get a file_key for sending.
  * Max file size: 30MB
@@ -261,10 +280,12 @@ export async function uploadFileFeishu(params: {
   const fileStream =
     typeof file === "string" ? fs.createReadStream(file) : Readable.from(file);
 
+  const safeFileName = sanitizeFileNameForUpload(fileName);
+
   const response = await client.im.file.create({
     data: {
       file_type: fileType,
-      file_name: fileName,
+      file_name: safeFileName,
       file: fileStream as any,
       ...(duration !== undefined && { duration }),
     },
@@ -356,10 +377,12 @@ export async function sendFileFeishu(params: {
   fileKey: string;
   /** Use "audio" for audio, "media" for video, "file" for documents */
   msgType?: "file" | "audio" | "media";
+  /** Optional cover image key for video (msg_type "media") messages */
+  imageKey?: string;
   replyToMessageId?: string;
   accountId?: string;
 }): Promise<SendMediaResult> {
-  const { cfg, to, fileKey, replyToMessageId, accountId } = params;
+  const { cfg, to, fileKey, imageKey, replyToMessageId, accountId } = params;
   const msgType = params.msgType ?? "file";
   const account = resolveFeishuAccount({ cfg, accountId });
   if (!account.configured) {
@@ -373,7 +396,10 @@ export async function sendFileFeishu(params: {
   }
 
   const receiveIdType = resolveReceiveIdType(receiveId);
-  const content = JSON.stringify({ file_key: fileKey });
+  const content = JSON.stringify({
+    file_key: fileKey,
+    ...(imageKey && { image_key: imageKey }),
+  });
 
   if (replyToMessageId) {
     const response = await client.im.message.reply({
@@ -421,12 +447,27 @@ export function detectFileType(
 ): "opus" | "mp4" | "pdf" | "doc" | "xls" | "ppt" | "stream" {
   const ext = path.extname(fileName).toLowerCase();
   switch (ext) {
+    // Audio formats → Feishu "opus" category
     case ".opus":
     case ".ogg":
+    case ".mp3":
+    case ".m4a":
+    case ".aac":
+    case ".wav":
+    case ".flac":
+    case ".wma":
+    case ".amr":
       return "opus";
+    // Video formats → Feishu "mp4" category
     case ".mp4":
     case ".mov":
     case ".avi":
+    case ".mkv":
+    case ".webm":
+    case ".flv":
+    case ".wmv":
+    case ".m4v":
+    case ".3gp":
       return "mp4";
     case ".pdf":
       return "pdf";
@@ -444,6 +485,7 @@ export function detectFileType(
   }
 }
 
+
 /**
  * Upload and send media (image or file) from URL, local path, or buffer
  */
@@ -465,6 +507,7 @@ export async function sendMediaFeishu(params: {
 
   let buffer: Buffer;
   let name: string;
+  let contentType: string | undefined;
 
   if (mediaBuffer) {
     buffer = mediaBuffer;
@@ -496,6 +539,7 @@ export async function sendMediaFeishu(params: {
     })();
     buffer = loaded.buffer;
     name = fileName ?? loaded.fileName ?? "file";
+    contentType = loaded.contentType;
   } else {
     throw new Error("Either mediaUrl or mediaBuffer must be provided");
   }
@@ -508,16 +552,27 @@ export async function sendMediaFeishu(params: {
     const { imageKey } = await uploadImageFeishu({ cfg, image: buffer, accountId });
     return sendImageFeishu({ cfg, to, imageKey, replyToMessageId, accountId });
   } else {
-    const fileType = detectFileType(name);
+    // Determine file type from extension; fall back to MIME type for files without
+    // a recognized extension (e.g. URLs with no filename, or buffers without fileName).
+    let fileType = detectFileType(name);
+    if (fileType === "stream" && contentType) {
+      if (contentType.startsWith("video/")) fileType = "mp4";
+      else if (contentType.startsWith("audio/")) fileType = "opus";
+    }
+    const msgType = fileType === "opus" ? "audio" : fileType === "mp4" ? "media" : "file";
+    const duration =
+      fileType === "opus" || fileType === "mp4"
+        ? parseFeishuMediaDurationMs(buffer, fileType)
+        : undefined;
     const { fileKey } = await uploadFileFeishu({
       cfg,
       file: buffer,
       fileName: name,
       fileType,
+      duration,
       accountId,
     });
     // Feishu requires msg_type "audio" for audio, "media" for video, "file" for documents
-    const msgType = fileType === "opus" ? "audio" : fileType === "mp4" ? "media" : "file";
     return sendFileFeishu({
       cfg,
       to,

package/src/mention.ts

@@ -45,7 +45,7 @@ export function isMentionForwardRequest(
   const mentions = event.message.mentions ?? [];
   if (mentions.length === 0) return false;
 
-  const isDirectMessage = event.message.chat_type === "p2p";
+  const isDirectMessage = event.message.chat_type !== "group";
   const hasOtherMention = mentions.some((m) => m.id.open_id !== botOpenId);
 
   if (isDirectMessage) {

package/src/monitor.ts

@@ -37,6 +37,26 @@ async function fetchBotOpenId(
   }
 }
 
+/**
+ * Per-chat serial queue that ensures messages from the same chat are processed
+ * in arrival order while allowing different chats to run concurrently.
+ * Uses .then(task, task) so a failure in one message never blocks the next.
+ */
+function createChatQueue() {
+  const queues = new Map<string, Promise<void>>();
+  return (chatId: string, task: () => Promise<void>): Promise<void> => {
+    const prev = queues.get(chatId) ?? Promise.resolve();
+    const next = prev.then(task, task);
+    queues.set(chatId, next);
+    void next.finally(() => {
+      if (queues.get(chatId) === next) {
+        queues.delete(chatId);
+      }
+    });
+    return next;
+  };
+}
+
 /**
  * Register common event handlers on an EventDispatcher.
  * When fireAndForget is true (webhook mode), message handling is not awaited
@@ -55,19 +75,23 @@ function registerEventHandlers(
   const { cfg, accountId, runtime, chatHistories, fireAndForget } = context;
   const log = runtime?.log ?? console.log;
   const error = runtime?.error ?? console.error;
+  const enqueue = createChatQueue();
 
   eventDispatcher.register({
     "im.message.receive_v1": async (data) => {
       try {
         const event = data as unknown as FeishuMessageEvent;
-        const promise = handleFeishuMessage({
-          cfg,
-          event,
-          botOpenId: botOpenIds.get(accountId),
-          runtime,
-          chatHistories,
-          accountId,
-        });
+        const chatId = event.message.chat_id?.trim() || "unknown";
+        const task = () =>
+          handleFeishuMessage({
+            cfg,
+            event,
+            botOpenId: botOpenIds.get(accountId),
+            runtime,
+            chatHistories,
+            accountId,
+          });
+        const promise = enqueue(chatId, task);
         if (fireAndForget) {
           promise.catch((err) => {
             error(`feishu[${accountId}]: error handling message: ${String(err)}`);

package/src/policy.ts

@@ -82,15 +82,19 @@ export function resolveFeishuReplyPolicy(params: {
   isDirectMessage: boolean;
   globalConfig?: FeishuConfig;
   groupConfig?: FeishuGroupConfig;
-}): { requireMention: boolean } {
+}): { requireMention: boolean; allowMentionlessInMultiBotGroup: boolean } {
   if (params.isDirectMessage) {
-    return { requireMention: false };
+    return { requireMention: false, allowMentionlessInMultiBotGroup: false };
   }
 
   const requireMention =
     params.groupConfig?.requireMention ?? params.globalConfig?.requireMention ?? true;
+  const allowMentionlessInMultiBotGroup =
+    params.groupConfig?.allowMentionlessInMultiBotGroup ??
+    params.globalConfig?.allowMentionlessInMultiBotGroup ??
+    false;
 
-  return { requireMention };
+  return { requireMention, allowMentionlessInMultiBotGroup };
 }
 
 export function resolveFeishuGroupCommandMentionBypass(params: {