@openclaw-china/shared 0.1.18 → 0.1.19

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@openclaw-china/shared",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
   },
   "scripts": {
     "build": "tsc",
-    "dev": "tsc --watch"
+    "dev": "tsc --watch",
+    "test": "vitest --run"
   },
   "devDependencies": {
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
   },
   "private": false
 }

package/src/file/file-utils.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Unit Tests for File Utilities
+ * 
+ * Feature: dingtalk-media-receive
+ * Validates: Requirements 5.1-5.8, 6.1-6.6
+ */
+
+import { describe, it, expect } from "vitest";
+import { resolveFileCategory, resolveExtension } from "./file-utils.js";
+
+describe("resolveFileCategory", () => {
+  // Image categorization (Requirement 5.1)
+  it("should categorize image MIME types", () => {
+    expect(resolveFileCategory("image/jpeg")).toBe("image");
+    expect(resolveFileCategory("image/png")).toBe("image");
+    expect(resolveFileCategory("image/gif")).toBe("image");
+    expect(resolveFileCategory("image/webp")).toBe("image");
+    expect(resolveFileCategory("image/bmp")).toBe("image");
+  });
+
+  // Audio categorization (Requirement 5.2)
+  it("should categorize audio MIME types", () => {
+    expect(resolveFileCategory("audio/mpeg")).toBe("audio");
+    expect(resolveFileCategory("audio/wav")).toBe("audio");
+    expect(resolveFileCategory("audio/ogg")).toBe("audio");
+    expect(resolveFileCategory("audio/amr")).toBe("audio");
+  });
+
+  // Video categorization (Requirement 5.3)
+  it("should categorize video MIME types", () => {
+    expect(resolveFileCategory("video/mp4")).toBe("video");
+    expect(resolveFileCategory("video/quicktime")).toBe("video");
+    expect(resolveFileCategory("video/webm")).toBe("video");
+  });
+
+  // Document categorization (Requirement 5.4)
+  it("should categorize document MIME types", () => {
+    expect(resolveFileCategory("application/pdf")).toBe("document");
+    expect(resolveFileCategory("application/msword")).toBe("document");
+    expect(resolveFileCategory("text/plain")).toBe("document");
+    expect(resolveFileCategory("text/markdown")).toBe("document");
+  });
+
+  // Archive categorization (Requirement 5.5)
+  it("should categorize archive MIME types", () => {
+    expect(resolveFileCategory("application/zip")).toBe("archive");
+    expect(resolveFileCategory("application/x-rar-compressed")).toBe("archive");
+    expect(resolveFileCategory("application/x-7z-compressed")).toBe("archive");
+  });
+
+  // Code categorization (Requirement 5.6)
+  it("should categorize code MIME types", () => {
+    expect(resolveFileCategory("application/json")).toBe("code");
+    expect(resolveFileCategory("text/html")).toBe("code");
+    expect(resolveFileCategory("text/css")).toBe("code");
+    expect(resolveFileCategory("text/javascript")).toBe("code");
+  });
+
+  // Extension fallback (Requirement 5.8)
+  it("should use extension fallback when MIME type is unknown", () => {
+    expect(resolveFileCategory("application/octet-stream", "photo.jpg")).toBe("image");
+    expect(resolveFileCategory("application/octet-stream", "song.mp3")).toBe("audio");
+    expect(resolveFileCategory("application/octet-stream", "movie.mp4")).toBe("video");
+    expect(resolveFileCategory("application/octet-stream", "doc.pdf")).toBe("document");
+    expect(resolveFileCategory("application/octet-stream", "archive.zip")).toBe("archive");
+    expect(resolveFileCategory("application/octet-stream", "script.py")).toBe("code");
+  });
+
+  // Other category (Requirement 5.7)
+  it("should return 'other' for unknown types", () => {
+    expect(resolveFileCategory("application/octet-stream")).toBe("other");
+    expect(resolveFileCategory("application/unknown")).toBe("other");
+    expect(resolveFileCategory("application/octet-stream", "file.xyz")).toBe("other");
+  });
+
+  // MIME type normalization
+  it("should handle MIME types with parameters", () => {
+    expect(resolveFileCategory("image/jpeg; charset=utf-8")).toBe("image");
+    expect(resolveFileCategory("text/plain; charset=utf-8")).toBe("document");
+  });
+});
+
+describe("resolveExtension", () => {
+  // Image extensions (Requirement 6.1)
+  it("should resolve image MIME types to extensions", () => {
+    expect(resolveExtension("image/jpeg")).toBe(".jpg");
+    expect(resolveExtension("image/png")).toBe(".png");
+    expect(resolveExtension("image/gif")).toBe(".gif");
+    expect(resolveExtension("image/webp")).toBe(".webp");
+    expect(resolveExtension("image/bmp")).toBe(".bmp");
+  });
+
+  // Audio extensions (Requirement 6.2)
+  it("should resolve audio MIME types to extensions", () => {
+    expect(resolveExtension("audio/mpeg")).toBe(".mp3");
+    expect(resolveExtension("audio/wav")).toBe(".wav");
+    expect(resolveExtension("audio/ogg")).toBe(".ogg");
+    expect(resolveExtension("audio/amr")).toBe(".amr");
+    expect(resolveExtension("audio/x-m4a")).toBe(".m4a");
+  });
+
+  // Video extensions (Requirement 6.3)
+  it("should resolve video MIME types to extensions", () => {
+    expect(resolveExtension("video/mp4")).toBe(".mp4");
+    expect(resolveExtension("video/quicktime")).toBe(".mov");
+    expect(resolveExtension("video/x-msvideo")).toBe(".avi");
+    expect(resolveExtension("video/webm")).toBe(".webm");
+  });
+
+  // Document extensions (Requirement 6.4)
+  it("should resolve document MIME types to extensions", () => {
+    expect(resolveExtension("application/pdf")).toBe(".pdf");
+    expect(resolveExtension("application/msword")).toBe(".doc");
+    expect(resolveExtension("application/vnd.openxmlformats-officedocument.wordprocessingml.document")).toBe(".docx");
+  });
+
+  // Default extension (Requirement 6.5)
+  it("should return .bin for unknown MIME types", () => {
+    expect(resolveExtension("application/unknown")).toBe(".bin");
+    expect(resolveExtension("application/octet-stream")).toBe(".bin");
+  });
+
+  // fileName precedence (Requirement 6.6)
+  it("should use fileName extension when provided", () => {
+    expect(resolveExtension("application/octet-stream", "photo.jpg")).toBe(".jpg");
+    expect(resolveExtension("image/png", "custom.jpeg")).toBe(".jpeg");
+    expect(resolveExtension("application/unknown", "document.pdf")).toBe(".pdf");
+  });
+
+  // MIME type normalization
+  it("should handle MIME types with parameters", () => {
+    expect(resolveExtension("image/jpeg; charset=utf-8")).toBe(".jpg");
+    expect(resolveExtension("audio/mpeg; bitrate=320")).toBe(".mp3");
+  });
+
+  // Edge cases
+  it("should handle fileName without extension", () => {
+    expect(resolveExtension("image/jpeg", "photo")).toBe(".jpg");
+    expect(resolveExtension("application/unknown", "noext")).toBe(".bin");
+  });
+});

package/src/file/file-utils.ts

@@ -0,0 +1,284 @@
+/**
+ * File utilities for categorizing and resolving file extensions
+ * @module @openclaw-china/shared/file
+ */
+
+/**
+ * File category for processing strategy
+ */
+export type FileCategory =
+  | "image"
+  | "audio"
+  | "video"
+  | "document"
+  | "archive"
+  | "code"
+  | "other";
+
+/**
+ * MIME type to extension mapping
+ */
+const MIME_TO_EXTENSION: Record<string, string> = {
+  // Images
+  "image/jpeg": ".jpg",
+  "image/png": ".png",
+  "image/gif": ".gif",
+  "image/webp": ".webp",
+  "image/bmp": ".bmp",
+
+  // Audio
+  "audio/mpeg": ".mp3",
+  "audio/wav": ".wav",
+  "audio/ogg": ".ogg",
+  "audio/amr": ".amr",
+  "audio/x-m4a": ".m4a",
+
+  // Video
+  "video/mp4": ".mp4",
+  "video/quicktime": ".mov",
+  "video/x-msvideo": ".avi",
+  "video/webm": ".webm",
+
+  // Documents
+  "application/pdf": ".pdf",
+  "application/msword": ".doc",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document":
+    ".docx",
+  "application/vnd.ms-excel": ".xls",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+  "application/vnd.ms-powerpoint": ".ppt",
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation":
+    ".pptx",
+  "application/rtf": ".rtf",
+  "application/vnd.oasis.opendocument.text": ".odt",
+  "application/vnd.oasis.opendocument.spreadsheet": ".ods",
+  "text/plain": ".txt",
+  "text/markdown": ".md",
+  "text/csv": ".csv",
+
+  // Archives
+  "application/zip": ".zip",
+  "application/x-rar-compressed": ".rar",
+  "application/vnd.rar": ".rar",
+  "application/x-7z-compressed": ".7z",
+  "application/x-tar": ".tar",
+  "application/gzip": ".gz",
+  "application/x-gzip": ".gz",
+  "application/x-bzip2": ".bz2",
+
+  // Code
+  "application/json": ".json",
+  "application/xml": ".xml",
+  "text/xml": ".xml",
+  "text/html": ".html",
+  "text/css": ".css",
+  "text/javascript": ".js",
+  "application/javascript": ".js",
+  "text/x-python": ".py",
+  "text/x-java-source": ".java",
+  "text/x-c": ".c",
+  "text/x-yaml": ".yaml",
+  "application/x-yaml": ".yaml",
+};
+
+/**
+ * MIME type to category mapping for non-prefix-based types
+ */
+const CATEGORY_BY_MIME: Record<string, FileCategory> = {
+  // Documents
+  "application/pdf": "document",
+  "application/msword": "document",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document":
+    "document",
+  "application/vnd.ms-excel": "document",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":
+    "document",
+  "application/vnd.ms-powerpoint": "document",
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation":
+    "document",
+  "application/rtf": "document",
+  "application/vnd.oasis.opendocument.text": "document",
+  "application/vnd.oasis.opendocument.spreadsheet": "document",
+  "text/plain": "document",
+  "text/markdown": "document",
+  "text/csv": "document",
+  // Archives
+  "application/zip": "archive",
+  "application/x-rar-compressed": "archive",
+  "application/vnd.rar": "archive",
+  "application/x-7z-compressed": "archive",
+  "application/x-tar": "archive",
+  "application/gzip": "archive",
+  "application/x-gzip": "archive",
+  "application/x-bzip2": "archive",
+  // Code
+  "application/json": "code",
+  "application/xml": "code",
+  "text/xml": "code",
+  "text/html": "code",
+  "text/css": "code",
+  "text/javascript": "code",
+  "application/javascript": "code",
+  "text/x-python": "code",
+  "text/x-java-source": "code",
+  "text/x-c": "code",
+  "text/x-yaml": "code",
+  "application/x-yaml": "code",
+};
+
+/**
+ * Extension to category mapping
+ */
+const CATEGORY_BY_EXTENSION: Record<string, FileCategory> = {
+  // Images
+  ".jpg": "image",
+  ".jpeg": "image",
+  ".png": "image",
+  ".gif": "image",
+  ".webp": "image",
+  ".bmp": "image",
+  // Audio
+  ".mp3": "audio",
+  ".wav": "audio",
+  ".ogg": "audio",
+  ".m4a": "audio",
+  ".amr": "audio",
+  // Video
+  ".mp4": "video",
+  ".mov": "video",
+  ".avi": "video",
+  ".mkv": "video",
+  ".webm": "video",
+  // Documents
+  ".pdf": "document",
+  ".doc": "document",
+  ".docx": "document",
+  ".txt": "document",
+  ".md": "document",
+  ".rtf": "document",
+  ".odt": "document",
+  ".xls": "document",
+  ".xlsx": "document",
+  ".csv": "document",
+  ".ods": "document",
+  ".ppt": "document",
+  ".pptx": "document",
+  // Archives
+  ".zip": "archive",
+  ".rar": "archive",
+  ".7z": "archive",
+  ".tar": "archive",
+  ".gz": "archive",
+  ".bz2": "archive",
+  // Code
+  ".py": "code",
+  ".js": "code",
+  ".ts": "code",
+  ".jsx": "code",
+  ".tsx": "code",
+  ".java": "code",
+  ".cpp": "code",
+  ".c": "code",
+  ".go": "code",
+  ".rs": "code",
+  ".json": "code",
+  ".xml": "code",
+  ".yaml": "code",
+  ".yml": "code",
+  ".html": "code",
+  ".css": "code",
+};
+
+/**
+ * Extract file extension from a file name
+ * @param fileName - The file name to extract extension from
+ * @returns The extension with leading dot (e.g., ".jpg") or empty string if none
+ */
+function extractExtension(fileName: string): string {
+  const lastDot = fileName.lastIndexOf(".");
+  if (lastDot === -1 || lastDot === fileName.length - 1) {
+    return "";
+  }
+  return fileName.slice(lastDot).toLowerCase();
+}
+
+/**
+ * Categorize a file based on MIME type and extension
+ *
+ * Priority:
+ * 1. Check MIME type prefix (image/, audio/, video/)
+ * 2. Check exact MIME type mapping (document, archive, code)
+ * 3. Check file extension from fileName
+ * 4. Return 'other' if no match
+ *
+ * @param contentType - MIME type string
+ * @param fileName - Optional file name for extension-based fallback
+ * @returns File category
+ */
+export function resolveFileCategory(
+  contentType: string,
+  fileName?: string
+): FileCategory {
+  // Normalize content type (remove parameters like charset)
+  const mimeType = contentType.split(";")[0].trim().toLowerCase();
+
+  // Check MIME type prefix first (image/, audio/, video/)
+  if (mimeType.startsWith("image/")) {
+    return "image";
+  }
+  if (mimeType.startsWith("audio/")) {
+    return "audio";
+  }
+  if (mimeType.startsWith("video/")) {
+    return "video";
+  }
+
+  // Check exact MIME type mapping (document, archive, code)
+  if (mimeType in CATEGORY_BY_MIME) {
+    return CATEGORY_BY_MIME[mimeType];
+  }
+
+  // Check file extension if fileName is provided
+  if (fileName) {
+    const ext = extractExtension(fileName);
+    if (ext && ext in CATEGORY_BY_EXTENSION) {
+      return CATEGORY_BY_EXTENSION[ext];
+    }
+  }
+
+  return "other";
+}
+
+/**
+ * Resolve file extension from MIME type or fileName
+ *
+ * Priority:
+ * 1. fileName extension (if provided and has extension)
+ * 2. MIME type mapping
+ * 3. ".bin" default
+ *
+ * @param contentType - MIME type string
+ * @param fileName - Optional file name to extract extension from (takes precedence)
+ * @returns Extension with leading dot (e.g., ".jpg") or ".bin" if unknown
+ */
+export function resolveExtension(
+  contentType: string,
+  fileName?: string
+): string {
+  // Priority 1: fileName extension
+  if (fileName) {
+    const ext = extractExtension(fileName);
+    if (ext) {
+      return ext;
+    }
+  }
+
+  // Priority 2: MIME type mapping
+  const mimeType = contentType.split(";")[0].trim().toLowerCase();
+  if (mimeType in MIME_TO_EXTENSION) {
+    return MIME_TO_EXTENSION[mimeType];
+  }
+
+  // Priority 3: Default
+  return ".bin";
+}

package/src/file/index.ts

@@ -0,0 +1,10 @@
+/**
+ * File utilities module
+ * @module @openclaw-china/shared/file
+ */
+
+export {
+  type FileCategory,
+  resolveFileCategory,
+  resolveExtension,
+} from "./file-utils.js";

package/src/index.ts

@@ -5,3 +5,4 @@ export * from "./logger/index.js";
 export * from "./policy/index.js";
 export * from "./http/index.js";
 export * from "./types/common.js";
+export * from "./file/index.js";

package/src/logger/index.ts

@@ -1 +1 @@
-export * from "./logger.js";
+export * from "./logger.js";

package/src/logger/logger.ts

@@ -1,51 +1,51 @@
-/**
- * 通用日志工具
- *
- * 提供分级日志功能:
- * - info: 关键业务日志（默认显示）
- * - debug: 调试日志（带 [DEBUG] 标记）
- * - error: 错误日志
- * - warn: 警告日志
- */
-
-export type LogLevel = "debug" | "info" | "warn" | "error";
-
-export interface Logger {
-  debug: (msg: string) => void;
-  info: (msg: string) => void;
-  warn: (msg: string) => void;
-  error: (msg: string) => void;
-}
-
-export interface LoggerOptions {
-  log?: (msg: string) => void;
-  error?: (msg: string) => void;
-}
-
-/**
- * 创建带前缀的日志器
- *
- * @param prefix 日志前缀（如 "dingtalk", "feishu"）
- * @param opts 可选的日志输出函数
- * @returns Logger 实例
- *
- * @example
- * ```ts
- * const logger = createLogger("dingtalk");
- * logger.debug("connecting..."); // [dingtalk] [DEBUG] connecting...
- * logger.info("connected");      // [dingtalk] connected
- * logger.warn("slow response");  // [dingtalk] [WARN] slow response
- * logger.error("failed");        // [dingtalk] [ERROR] failed
- * ```
- */
-export function createLogger(prefix: string, opts?: LoggerOptions): Logger {
-  const logFn = opts?.log ?? console.log;
-  const errorFn = opts?.error ?? console.error;
-
-  return {
-    debug: (msg: string) => logFn(`[${prefix}] [DEBUG] ${msg}`),
-    info: (msg: string) => logFn(`[${prefix}] ${msg}`),
-    warn: (msg: string) => logFn(`[${prefix}] [WARN] ${msg}`),
-    error: (msg: string) => errorFn(`[${prefix}] [ERROR] ${msg}`),
-  };
-}
+/**
+ * 通用日志工具
+ *
+ * 提供分级日志功能:
+ * - info: 关键业务日志（默认显示）
+ * - debug: 调试日志（带 [DEBUG] 标记）
+ * - error: 错误日志
+ * - warn: 警告日志
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface Logger {
+  debug: (msg: string) => void;
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+}
+
+export interface LoggerOptions {
+  log?: (msg: string) => void;
+  error?: (msg: string) => void;
+}
+
+/**
+ * 创建带前缀的日志器
+ *
+ * @param prefix 日志前缀（如 "dingtalk", "feishu"）
+ * @param opts 可选的日志输出函数
+ * @returns Logger 实例
+ *
+ * @example
+ * ```ts
+ * const logger = createLogger("dingtalk");
+ * logger.debug("connecting..."); // [dingtalk] [DEBUG] connecting...
+ * logger.info("connected");      // [dingtalk] connected
+ * logger.warn("slow response");  // [dingtalk] [WARN] slow response
+ * logger.error("failed");        // [dingtalk] [ERROR] failed
+ * ```
+ */
+export function createLogger(prefix: string, opts?: LoggerOptions): Logger {
+  const logFn = opts?.log ?? console.log;
+  const errorFn = opts?.error ?? console.error;
+
+  return {
+    debug: (msg: string) => logFn(`[${prefix}] [DEBUG] ${msg}`),
+    info: (msg: string) => logFn(`[${prefix}] ${msg}`),
+    warn: (msg: string) => logFn(`[${prefix}] [WARN] ${msg}`),
+    error: (msg: string) => errorFn(`[${prefix}] [ERROR] ${msg}`),
+  };
+}

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.ts"],
+    globals: false,
+  },
+});