@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/core/uat-client.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * UAT (User Access Token) API call wrapper.
+ *
+ * Provides a safe, auto-refreshing interface for making Feishu API calls on
+ * behalf of a user.  Tokens are read from the OS Keychain, refreshed
+ * transparently, and **never** exposed to the AI layer.
+ */
+import type { LarkBrand } from './types';
+import { NeedAuthorizationError } from './auth-errors';
+export { NeedAuthorizationError };
+export interface UATCallOptions {
+    userOpenId: string;
+    appId: string;
+    appSecret: string;
+    domain: LarkBrand;
+}
+export interface UATStatus {
+    authorized: boolean;
+    userOpenId: string;
+    scope?: string;
+    expiresAt?: number;
+    refreshExpiresAt?: number;
+    grantedAt?: number;
+    tokenStatus?: 'valid' | 'needs_refresh' | 'expired';
+}
+/**
+ * Obtain a valid access_token for the given user.
+ *
+ * - Reads from Keychain.
+ * - Refreshes proactively if the token is about to expire.
+ * - Throws when no token exists or refresh fails irrecoverably.
+ *
+ * **The returned token must never be exposed to the AI layer.**
+ */
+export declare function getValidAccessToken(opts: UATCallOptions): Promise<string>;
+/**
+ * Execute an API call with a valid UAT, retrying once on token-expiry errors.
+ */
+export declare function callWithUAT<T>(opts: UATCallOptions, apiCall: (accessToken: string) => Promise<T>): Promise<T>;
+/**
+ * Revoke a user's UAT by removing it from the Keychain.
+ */
+export declare function revokeUAT(appId: string, userOpenId: string): Promise<void>;

package/src/core/uat-client.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * UAT (User Access Token) API call wrapper.
+ *
+ * Provides a safe, auto-refreshing interface for making Feishu API calls on
+ * behalf of a user.  Tokens are read from the OS Keychain, refreshed
+ * transparently, and **never** exposed to the AI layer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NeedAuthorizationError = void 0;
+exports.getValidAccessToken = getValidAccessToken;
+exports.callWithUAT = callWithUAT;
+exports.revokeUAT = revokeUAT;
+const token_store_1 = require("./token-store.js");
+const device_flow_1 = require("./device-flow.js");
+const lark_logger_1 = require("./lark-logger.js");
+const log = (0, lark_logger_1.larkLogger)('core/uat-client');
+const feishu_fetch_1 = require("./feishu-fetch.js");
+const auth_errors_1 = require("./auth-errors.js");
+Object.defineProperty(exports, "NeedAuthorizationError", { enumerable: true, get: function () { return auth_errors_1.NeedAuthorizationError; } });
+// ---------------------------------------------------------------------------
+// Per-user refresh lock
+// ---------------------------------------------------------------------------
+/**
+ * Guards against concurrent refresh operations for the same user.
+ *
+ * refresh_token is single-use: if two requests trigger a refresh
+ * simultaneously, the second one would use an already-consumed token and
+ * fail.  The lock ensures only one refresh runs at a time per user.
+ */
+const refreshLocks = new Map();
+// ---------------------------------------------------------------------------
+// Refresh implementation
+// ---------------------------------------------------------------------------
+async function doRefreshToken(opts, stored) {
+    // refresh_token already expired → can't refresh, need re-auth.
+    if (Date.now() >= stored.refreshExpiresAt) {
+        log.info(`refresh_token expired for ${opts.userOpenId}, clearing`);
+        await (0, token_store_1.removeStoredToken)(opts.appId, opts.userOpenId);
+        return null;
+    }
+    const endpoints = (0, device_flow_1.resolveOAuthEndpoints)(opts.domain);
+    const requestBody = new URLSearchParams({
+        grant_type: 'refresh_token',
+        refresh_token: stored.refreshToken,
+        client_id: opts.appId,
+        client_secret: opts.appSecret,
+    }).toString();
+    const callEndpoint = async () => {
+        const resp = await (0, feishu_fetch_1.feishuFetch)(endpoints.token, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: requestBody,
+        });
+        return (await resp.json());
+    };
+    let data = await callEndpoint();
+    // Feishu v2 token endpoint returns `code: 0` on success.
+    // Some responses use `error` field instead (standard OAuth).
+    const code = data.code;
+    const error = data.error;
+    if ((code !== undefined && code !== 0) || error) {
+        const errCode = code ?? error;
+        // Transient server error: retry once, then clear.
+        if (auth_errors_1.REFRESH_TOKEN_RETRYABLE.has(code)) {
+            log.warn(`refresh transient error (code=${errCode}) for ${opts.userOpenId}, retrying once`);
+            data = await callEndpoint();
+            const retryCode = data.code;
+            const retryError = data.error;
+            if ((retryCode !== undefined && retryCode !== 0) || retryError) {
+                const retryErrCode = retryCode ?? retryError;
+                log.warn(`refresh failed after retry (code=${retryErrCode}), clearing token for ${opts.userOpenId}`);
+                await (0, token_store_1.removeStoredToken)(opts.appId, opts.userOpenId);
+                return null;
+            }
+        }
+        else {
+            // Any other error (invalid/expired/revoked token, or unknown): clear and force re-auth.
+            log.warn(`refresh failed (code=${errCode}), clearing token for ${opts.userOpenId}`);
+            await (0, token_store_1.removeStoredToken)(opts.appId, opts.userOpenId);
+            return null;
+        }
+    }
+    if (!data.access_token) {
+        throw new Error('Token refresh returned no access_token');
+    }
+    const now = Date.now();
+    const updated = {
+        userOpenId: stored.userOpenId,
+        appId: opts.appId,
+        accessToken: data.access_token,
+        // refresh_token is rotated – always use the new one.
+        refreshToken: data.refresh_token ?? stored.refreshToken,
+        expiresAt: now + (data.expires_in ?? 7200) * 1000,
+        refreshExpiresAt: data.refresh_token_expires_in
+            ? now + data.refresh_token_expires_in * 1000
+            : stored.refreshExpiresAt,
+        scope: data.scope ?? stored.scope,
+        grantedAt: stored.grantedAt,
+    };
+    await (0, token_store_1.setStoredToken)(updated);
+    log.info(`refreshed UAT for ${opts.userOpenId} (at:${(0, token_store_1.maskToken)(updated.accessToken)})`);
+    return updated;
+}
+/**
+ * Refresh with per-user locking.
+ */
+async function refreshWithLock(opts, stored) {
+    const key = `${opts.appId}:${opts.userOpenId}`;
+    // Another refresh is already in-flight – wait for it and re-read.
+    const existing = refreshLocks.get(key);
+    if (existing) {
+        await existing;
+        return (0, token_store_1.getStoredToken)(opts.appId, opts.userOpenId);
+    }
+    const promise = doRefreshToken(opts, stored);
+    refreshLocks.set(key, promise);
+    try {
+        return await promise;
+    }
+    finally {
+        refreshLocks.delete(key);
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Obtain a valid access_token for the given user.
+ *
+ * - Reads from Keychain.
+ * - Refreshes proactively if the token is about to expire.
+ * - Throws when no token exists or refresh fails irrecoverably.
+ *
+ * **The returned token must never be exposed to the AI layer.**
+ */
+async function getValidAccessToken(opts) {
+    // Owner 检查已迁移到 owner-policy.ts（由 tool-client.ts 的 invokeAsUser 调用）
+    const stored = await (0, token_store_1.getStoredToken)(opts.appId, opts.userOpenId);
+    if (!stored) {
+        throw new auth_errors_1.NeedAuthorizationError(opts.userOpenId);
+    }
+    const status = (0, token_store_1.tokenStatus)(stored);
+    if (status === 'valid') {
+        return stored.accessToken;
+    }
+    if (status === 'needs_refresh') {
+        const refreshed = await refreshWithLock(opts, stored);
+        if (!refreshed) {
+            throw new auth_errors_1.NeedAuthorizationError(opts.userOpenId);
+        }
+        return refreshed.accessToken;
+    }
+    // expired
+    await (0, token_store_1.removeStoredToken)(opts.appId, opts.userOpenId);
+    throw new auth_errors_1.NeedAuthorizationError(opts.userOpenId);
+}
+/**
+ * Execute an API call with a valid UAT, retrying once on token-expiry errors.
+ */
+async function callWithUAT(opts, apiCall) {
+    const accessToken = await getValidAccessToken(opts);
+    try {
+        return await apiCall(accessToken);
+    }
+    catch (err) {
+        // Retry once if the server reports token invalid/expired.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const code = err?.code ?? err?.response?.data?.code;
+        if (auth_errors_1.TOKEN_RETRY_CODES.has(code)) {
+            log.warn(`API call failed (code=${code}), refreshing and retrying`);
+            const stored = await (0, token_store_1.getStoredToken)(opts.appId, opts.userOpenId);
+            if (!stored)
+                throw new auth_errors_1.NeedAuthorizationError(opts.userOpenId);
+            const refreshed = await refreshWithLock(opts, stored);
+            if (!refreshed)
+                throw new auth_errors_1.NeedAuthorizationError(opts.userOpenId);
+            return await apiCall(refreshed.accessToken);
+        }
+        throw err;
+    }
+}
+/**
+ * Revoke a user's UAT by removing it from the Keychain.
+ */
+async function revokeUAT(appId, userOpenId) {
+    await (0, token_store_1.removeStoredToken)(appId, userOpenId);
+    log.info(`revoked UAT for ${userOpenId}`);
+}

package/src/core/version.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * 插件版本号管理
+ *
+ * 从 package.json 读取版本号并生成 User-Agent 字符串。
+ */
+/**
+ * 获取插件版本号（从 package.json 读取）
+ *
+ * @returns 版本号字符串，如 "2026.2.28.5"；读取失败返回 "unknown"
+ */
+export declare function getPluginVersion(): string;
+/**
+ * 获取当前运行平台名称
+ *
+ * @returns `mac` | `linux` | `windows`
+ */
+export declare function getPlatform(): string;
+/**
+ * 生成 User-Agent 字符串
+ *
+ * @returns User-Agent 字符串，格式：`openclaw-lark/{version}/{platform}`
+ *
+ * @example
+ * ```typescript
+ * getUserAgent() // => "openclaw-lark/2026.2.28.5/mac"
+ * ```
+ */
+export declare function getUserAgent(): string;

package/src/core/version.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * 插件版本号管理
+ *
+ * 从 package.json 读取版本号并生成 User-Agent 字符串。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPluginVersion = getPluginVersion;
+exports.getPlatform = getPlatform;
+exports.getUserAgent = getUserAgent;
+const node_url_1 = require("node:url");
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+/** 缓存的版本号 */
+let cachedVersion;
+/**
+ * 获取插件版本号（从 package.json 读取）
+ *
+ * @returns 版本号字符串，如 "2026.2.28.5"；读取失败返回 "unknown"
+ */
+function getPluginVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    try {
+        // 当前文件: src/core/version.ts → 向上两级到达项目根目录
+        const __filename = (0, node_url_1.fileURLToPath)(import.meta.url);
+        const __dirname = (0, node_path_1.dirname)(__filename);
+        const packageJsonPath = (0, node_path_1.join)(__dirname, '..', '..', 'package.json');
+        const raw = (0, node_fs_1.readFileSync)(packageJsonPath, 'utf8');
+        const pkg = JSON.parse(raw);
+        cachedVersion = pkg.version ?? 'unknown';
+        return cachedVersion;
+    }
+    catch {
+        cachedVersion = 'unknown';
+        return cachedVersion;
+    }
+}
+/**
+ * 获取当前运行平台名称
+ *
+ * @returns `mac` | `linux` | `windows`
+ */
+function getPlatform() {
+    switch (process.platform) {
+        case 'darwin':
+            return 'mac';
+        case 'win32':
+            return 'windows';
+        default:
+            return 'linux';
+    }
+}
+/**
+ * 生成 User-Agent 字符串
+ *
+ * @returns User-Agent 字符串，格式：`openclaw-lark/{version}/{platform}`
+ *
+ * @example
+ * ```typescript
+ * getUserAgent() // => "openclaw-lark/2026.2.28.5/mac"
+ * ```
+ */
+function getUserAgent() {
+    return `openclaw-lark/${getPluginVersion()}/${getPlatform()}`;
+}

package/src/messaging/converters/audio.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "audio" message type.
+ */
+import type { ContentConverterFn } from './types';
+export declare const convertAudio: ContentConverterFn;

package/src/messaging/converters/audio.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "audio" message type.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertAudio = void 0;
+const utils_1 = require("./utils.js");
+const convertAudio = (raw) => {
+    const parsed = (0, utils_1.safeParse)(raw);
+    const fileKey = parsed?.file_key;
+    if (!fileKey) {
+        return { content: '[audio]', resources: [] };
+    }
+    const duration = parsed?.duration;
+    const durationAttr = duration != null ? ` duration="${(0, utils_1.formatDuration)(duration)}"` : '';
+    return {
+        content: `<audio key="${fileKey}"${durationAttr}/>`,
+        resources: [{ type: 'audio', fileKey, duration: duration ?? undefined }],
+    };
+};
+exports.convertAudio = convertAudio;

package/src/messaging/converters/calendar.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converters for calendar-related message types:
+ * - share_calendar_event
+ * - calendar
+ * - general_calendar
+ */
+import type { ContentConverterFn } from './types';
+export declare const convertShareCalendarEvent: ContentConverterFn;
+export declare const convertCalendar: ContentConverterFn;
+export declare const convertGeneralCalendar: ContentConverterFn;

package/src/messaging/converters/calendar.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converters for calendar-related message types:
+ * - share_calendar_event
+ * - calendar
+ * - general_calendar
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertGeneralCalendar = exports.convertCalendar = exports.convertShareCalendarEvent = void 0;
+const utils_1 = require("./utils.js");
+function formatCalendarContent(parsed) {
+    const summary = parsed?.summary ?? '';
+    const parts = [];
+    if (summary) {
+        parts.push(`📅 ${summary}`);
+    }
+    const start = parsed?.start_time ? (0, utils_1.millisToDatetime)(parsed.start_time) : '';
+    const end = parsed?.end_time ? (0, utils_1.millisToDatetime)(parsed.end_time) : '';
+    if (start && end) {
+        parts.push(`🕙 ${start} ~ ${end}`);
+    }
+    else if (start) {
+        parts.push(`🕙 ${start}`);
+    }
+    return parts.join('\n') || '[calendar event]';
+}
+const convertShareCalendarEvent = (raw) => {
+    const parsed = (0, utils_1.safeParse)(raw);
+    const inner = formatCalendarContent(parsed);
+    return {
+        content: `<calendar_share>${inner}</calendar_share>`,
+        resources: [],
+    };
+};
+exports.convertShareCalendarEvent = convertShareCalendarEvent;
+const convertCalendar = (raw) => {
+    const parsed = (0, utils_1.safeParse)(raw);
+    const inner = formatCalendarContent(parsed);
+    return {
+        content: `<calendar_invite>${inner}</calendar_invite>`,
+        resources: [],
+    };
+};
+exports.convertCalendar = convertCalendar;
+const convertGeneralCalendar = (raw) => {
+    const parsed = (0, utils_1.safeParse)(raw);
+    const inner = formatCalendarContent(parsed);
+    return {
+        content: `<calendar>${inner}</calendar>`,
+        resources: [],
+    };
+};
+exports.convertGeneralCalendar = convertGeneralCalendar;

package/src/messaging/converters/content-converter-helpers.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared helper functions for Feishu content converters.
+ */
+import type { ApiMessageItem, ConvertContext } from './types';
+/** 从 mention 的 id 字段提取 open_id（兼容事件推送的对象格式和 API 响应的字符串格式） */
+export declare function extractMentionOpenId(id: unknown): string;
+/**
+ * Build a {@link ConvertContext} from a raw Feishu API message item.
+ *
+ * Extracts the `mentions` array that the IM API returns on each message
+ * item and maps it into the key→MentionInfo / openId→MentionInfo
+ * structures the converter system expects.
+ */
+export declare function buildConvertContextFromItem(item: ApiMessageItem, fallbackMessageId: string, accountId?: string): ConvertContext;
+/**
+ * Resolve mention placeholders in text.
+ *
+ * - Bot self-mention + stripBotMentions: leading-only strip. When the
+ *   self-mention sits at the very start of the message, drop it (the
+ *   `WasMentioned` envelope field already tells the agent "this message
+ *   was addressed to you", so the anchor is redundant). When it appears
+ *   mid-text, render it as plain `@Name` so the surrounding context still
+ *   reads naturally without leaving an inline anchor the LLM might echo
+ *   back into its reply.
+ * - Non-bot mentions: replace the placeholder key with readable `@name`.
+ */
+export declare function resolveMentions(text: string, ctx: ConvertContext): string;

package/src/messaging/converters/content-converter-helpers.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared helper functions for Feishu content converters.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractMentionOpenId = extractMentionOpenId;
+exports.buildConvertContextFromItem = buildConvertContextFromItem;
+exports.resolveMentions = resolveMentions;
+const user_name_cache_1 = require("../inbound/user-name-cache.js");
+const utils_1 = require("./utils.js");
+/** 从 mention 的 id 字段提取 open_id（兼容事件推送的对象格式和 API 响应的字符串格式） */
+function extractMentionOpenId(id) {
+    if (typeof id === 'string')
+        return id;
+    if (id != null && typeof id === 'object' && 'open_id' in id) {
+        const openId = id.open_id;
+        return typeof openId === 'string' ? openId : '';
+    }
+    return '';
+}
+/**
+ * Build a {@link ConvertContext} from a raw Feishu API message item.
+ *
+ * Extracts the `mentions` array that the IM API returns on each message
+ * item and maps it into the key→MentionInfo / openId→MentionInfo
+ * structures the converter system expects.
+ */
+function buildConvertContextFromItem(item, fallbackMessageId, accountId) {
+    const mentions = new Map();
+    const mentionsByOpenId = new Map();
+    for (const m of item.mentions ?? []) {
+        const openId = extractMentionOpenId(m.id);
+        if (!openId)
+            continue;
+        const info = {
+            key: m.key,
+            openId,
+            name: m.name ?? '',
+            isBot: false,
+        };
+        mentions.set(m.key, info);
+        mentionsByOpenId.set(openId, info);
+    }
+    return {
+        mentions,
+        mentionsByOpenId,
+        messageId: item.message_id ?? fallbackMessageId,
+        accountId,
+        resolveUserName: accountId ? (openId) => (0, user_name_cache_1.getUserNameCache)(accountId).get(openId) : undefined,
+    };
+}
+/**
+ * Resolve mention placeholders in text.
+ *
+ * - Bot self-mention + stripBotMentions: leading-only strip. When the
+ *   self-mention sits at the very start of the message, drop it (the
+ *   `WasMentioned` envelope field already tells the agent "this message
+ *   was addressed to you", so the anchor is redundant). When it appears
+ *   mid-text, render it as plain `@Name` so the surrounding context still
+ *   reads naturally without leaving an inline anchor the LLM might echo
+ *   back into its reply.
+ * - Non-bot mentions: replace the placeholder key with readable `@name`.
+ */
+function resolveMentions(text, ctx) {
+    if (ctx.mentions.size === 0)
+        return text;
+    let result = text;
+    for (const [key, info] of ctx.mentions) {
+        if (info.isBot && ctx.stripBotMentions) {
+            result = result.replace(new RegExp((0, utils_1.escapeRegExp)(key), 'g'), `@${info.name}`);
+            const leadingPattern = new RegExp(`^\\s*@${(0, utils_1.escapeRegExp)(info.name)}[\\s,，:：]*`);
+            result = result.replace(leadingPattern, '').trimStart();
+        }
+        else {
+            result = result.replace(new RegExp((0, utils_1.escapeRegExp)(key), 'g'), `@${info.name}`);
+        }
+    }
+    return result;
+}

package/src/messaging/converters/content-converter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Content converter for Feishu messages.
+ *
+ * Each message type (text, post, image, etc.) has a dedicated converter
+ * function that parses raw JSON content into an AI-friendly text
+ * representation plus a list of resource descriptors.
+ *
+ * This module is a general-purpose message parsing utility — usable
+ * from inbound handling, outbound formatting, and skills.
+ */
+import type { ConvertContext, ConvertResult } from './types';
+export type { ApiMessageItem, ConvertContext, ConvertResult, ContentConverterFn } from './types';
+export { buildConvertContextFromItem, extractMentionOpenId, resolveMentions } from './content-converter-helpers';
+/**
+ * Convert raw message content using the converter for the given message
+ * type. Falls back to the "unknown" converter for unrecognised types.
+ *
+ * Returns a Promise because some converters (e.g. merge_forward) perform
+ * async operations. Synchronous converters are awaited transparently.
+ */
+export declare function convertMessageContent(raw: string, messageType: string, ctx: ConvertContext): Promise<ConvertResult>;

package/src/messaging/converters/content-converter.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Content converter for Feishu messages.
+ *
+ * Each message type (text, post, image, etc.) has a dedicated converter
+ * function that parses raw JSON content into an AI-friendly text
+ * representation plus a list of resource descriptors.
+ *
+ * This module is a general-purpose message parsing utility — usable
+ * from inbound handling, outbound formatting, and skills.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveMentions = exports.extractMentionOpenId = exports.buildConvertContextFromItem = void 0;
+exports.convertMessageContent = convertMessageContent;
+const index_1 = require("./index.js");
+var content_converter_helpers_1 = require("./content-converter-helpers.js");
+Object.defineProperty(exports, "buildConvertContextFromItem", { enumerable: true, get: function () { return content_converter_helpers_1.buildConvertContextFromItem; } });
+Object.defineProperty(exports, "extractMentionOpenId", { enumerable: true, get: function () { return content_converter_helpers_1.extractMentionOpenId; } });
+Object.defineProperty(exports, "resolveMentions", { enumerable: true, get: function () { return content_converter_helpers_1.resolveMentions; } });
+// ---------------------------------------------------------------------------
+// Convert
+// ---------------------------------------------------------------------------
+/**
+ * Convert raw message content using the converter for the given message
+ * type. Falls back to the "unknown" converter for unrecognised types.
+ *
+ * Returns a Promise because some converters (e.g. merge_forward) perform
+ * async operations. Synchronous converters are awaited transparently.
+ */
+async function convertMessageContent(raw, messageType, ctx) {
+    const fn = index_1.converters.get(messageType) ?? index_1.converters.get('unknown');
+    if (!fn) {
+        return { content: raw, resources: [] };
+    }
+    const nextCtx = ctx.convertMessageContent ? ctx : { ...ctx, convertMessageContent };
+    return fn(raw, nextCtx);
+}

package/src/messaging/converters/file.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "file" message type.
+ */
+import type { ContentConverterFn } from './types';
+export declare const convertFile: ContentConverterFn;

package/src/messaging/converters/file.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "file" message type.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertFile = void 0;
+const utils_1 = require("./utils.js");
+const convertFile = (raw) => {
+    const parsed = (0, utils_1.safeParse)(raw);
+    const fileKey = parsed?.file_key;
+    if (!fileKey) {
+        return { content: '[file]', resources: [] };
+    }
+    const fileName = parsed?.file_name ?? '';
+    const nameAttr = fileName ? ` name="${fileName}"` : '';
+    return {
+        content: `<file key="${fileKey}"${nameAttr}/>`,
+        resources: [{ type: 'file', fileKey, fileName: fileName || undefined }],
+    };
+};
+exports.convertFile = convertFile;

package/src/messaging/converters/folder.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "folder" message type.
+ */
+import type { ContentConverterFn } from './types';
+export declare const convertFolder: ContentConverterFn;