@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/messaging/converters/interactive/card-utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Utility functions for card content conversion.
+ */
+export declare function escapeAttr(s: string): string;
+export declare function formatMillisecondsToISO8601(milliseconds: string): string;
+export declare function normalizeTimeFormat(input: string): string;

package/src/messaging/converters/interactive/card-utils.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Utility functions for card content conversion.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeAttr = escapeAttr;
+exports.formatMillisecondsToISO8601 = formatMillisecondsToISO8601;
+exports.normalizeTimeFormat = normalizeTimeFormat;
+function escapeAttr(s) {
+    return s.replace(/"/g, '\\"').replace(/\n/g, '\\n');
+}
+function formatMillisecondsToISO8601(milliseconds) {
+    const ms = parseInt(milliseconds, 10);
+    if (isNaN(ms))
+        return '';
+    return new Date(ms).toISOString();
+}
+function normalizeTimeFormat(input) {
+    if (!input)
+        return '';
+    const num = parseInt(input, 10);
+    if (!isNaN(num) && String(num) === input.trim()) {
+        if (input.length >= 13) {
+            return new Date(num).toISOString();
+        }
+        else if (input.length >= 10) {
+            return new Date(num * 1000).toISOString();
+        }
+    }
+    if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(input)) {
+        return input;
+    }
+    const dtMatch = /^(\d{4}-\d{2}-\d{2})\s+(\d{2}:\d{2}(?::\d{2})?)$/.exec(input);
+    if (dtMatch) {
+        const d = new Date(`${dtMatch[1]}T${dtMatch[2]}`);
+        if (!isNaN(d.getTime()))
+            return d.toISOString();
+    }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(input))
+        return input;
+    if (/^\d{2}:\d{2}(:\d{2})?$/.test(input))
+        return input;
+    return input;
+}

package/src/messaging/converters/interactive/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Entry point for the interactive (card) message converter.
+ */
+import type { ContentConverterFn } from '../types';
+export declare const convertInteractive: ContentConverterFn;

package/src/messaging/converters/interactive/index.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Entry point for the interactive (card) message converter.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertInteractive = void 0;
+const utils_1 = require("../utils.js");
+const card_converter_1 = require("./card-converter.js");
+const legacy_1 = require("./legacy.js");
+const convertInteractive = (raw) => {
+    const parsed = (0, utils_1.safeParse)(raw);
+    if (!parsed) {
+        return { content: '[interactive card]', resources: [] };
+    }
+    if (typeof parsed.json_card === 'string') {
+        const converter = new card_converter_1.CardConverter(card_converter_1.MODE.Concise);
+        const result = converter.convert(parsed);
+        return { content: result.content || '[interactive card]', resources: [] };
+    }
+    return (0, legacy_1.convertLegacyCard)(parsed);
+};
+exports.convertInteractive = convertInteractive;

package/src/messaging/converters/interactive/legacy.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Legacy card converter for non-raw_card_content format.
+ */
+import type { Obj } from './types';
+export declare function convertLegacyCard(parsed: Obj): {
+    content: string;
+    resources: never[];
+};

package/src/messaging/converters/interactive/legacy.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Legacy card converter for non-raw_card_content format.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertLegacyCard = convertLegacyCard;
+function convertLegacyCard(parsed) {
+    const texts = [];
+    const header = parsed.header;
+    if (header) {
+        const title = header.title;
+        if (title && typeof title.content === 'string') {
+            texts.push(`**${title.content}**`);
+        }
+    }
+    const body = parsed.body;
+    const elements = (parsed.elements ?? body?.elements ?? []);
+    extractTexts(elements, texts);
+    const content = texts.length > 0 ? texts.join('\n') : '[interactive card]';
+    return { content, resources: [] };
+}
+function extractTexts(elements, out) {
+    if (!Array.isArray(elements))
+        return;
+    for (const el of elements) {
+        if (typeof el !== 'object' || el == null)
+            continue;
+        const elem = el;
+        if (elem.tag === 'markdown' && typeof elem.content === 'string') {
+            out.push(elem.content);
+            continue;
+        }
+        if (elem.tag === 'div' || elem.tag === 'plain_text' || elem.tag === 'lark_md') {
+            const text = elem.text;
+            if (text?.content && typeof text.content === 'string') {
+                out.push(text.content);
+            }
+            if (typeof elem.content === 'string') {
+                out.push(elem.content);
+            }
+        }
+        if (elem.tag === 'column_set') {
+            const columns = elem.columns;
+            if (columns) {
+                for (const col of columns) {
+                    const colObj = col;
+                    if (colObj.elements) {
+                        extractTexts(colObj.elements, out);
+                    }
+                }
+            }
+        }
+        if (elem.elements) {
+            extractTexts(elem.elements, out);
+        }
+    }
+}

package/src/messaging/converters/interactive/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Types and constants for the interactive (card) converter.
+ */
+export type Obj = Record<string, unknown>;
+export interface RawCardContent {
+    json_card: string;
+    json_attachment?: string;
+    card_schema?: number;
+}
+export interface ConvertCardResult {
+    content: string;
+    schema: number;
+}
+export interface TextStyle {
+    bold: boolean;
+    italic: boolean;
+    strikethrough: boolean;
+}
+export declare const EMOJI_MAP: Record<string, string>;
+export declare const CHART_TYPE_NAMES: Record<string, string>;

package/src/messaging/converters/interactive/types.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Types and constants for the interactive (card) converter.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHART_TYPE_NAMES = exports.EMOJI_MAP = void 0;
+exports.EMOJI_MAP = {
+    OK: '👌',
+    THUMBSUP: '👍',
+    SMILE: '😊',
+    HEART: '❤️',
+    CLAP: '👏',
+    FIRE: '🔥',
+    PARTY: '🎉',
+    THINK: '🤔',
+};
+exports.CHART_TYPE_NAMES = {
+    bar: '柱状图',
+    line: '折线图',
+    pie: '饼图',
+    area: '面积图',
+    radar: '雷达图',
+    scatter: '散点图',
+};

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

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

package/src/messaging/converters/location.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "location" message type.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertLocation = void 0;
+const utils_1 = require("./utils.js");
+const convertLocation = (raw) => {
+    const parsed = (0, utils_1.safeParse)(raw);
+    const name = parsed?.name ?? '';
+    const lat = parsed?.latitude ?? '';
+    const lng = parsed?.longitude ?? '';
+    const nameAttr = name ? ` name="${name}"` : '';
+    const coordsAttr = lat && lng ? ` coords="lat:${lat},lng:${lng}"` : '';
+    return {
+        content: `<location${nameAttr}${coordsAttr}/>`,
+        resources: [],
+    };
+};
+exports.convertLocation = convertLocation;

package/src/messaging/converters/merge-forward.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "merge_forward" message type.
+ *
+ * Unlike other converters this is async — it fetches sub-messages via
+ * the Feishu IM API and recursively expands nested merge_forward messages.
+ *
+ * The API returns ALL nested sub-messages in a single flat `items`
+ * array with `upper_message_id` pointing to the parent container.
+ * We build a tree from this flat list and recursively format it —
+ * only one API call is needed regardless of nesting depth.
+ *
+ * This module is a pure "data → format" converter: all API capabilities
+ * (`fetchSubMessages`, `batchResolveNames`, `resolveUserName`) are
+ * injected via callbacks in `ConvertContext`. Callers are responsible
+ * for creating the appropriate callbacks (UAT / TAT / event push).
+ */
+import type { ContentConverterFn } from './types';
+/**
+ * Recursively expand a merge_forward message.
+ *
+ * Output format aligns with the Go reference implementation:
+ * ```
+ * <forwarded_messages>
+ * [RFC3339] sender_id:
+ *     message content
+ * </forwarded_messages>
+ * ```
+ */
+export declare const convertMergeForward: ContentConverterFn;

package/src/messaging/converters/merge-forward.js

@@ -0,0 +1,235 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "merge_forward" message type.
+ *
+ * Unlike other converters this is async — it fetches sub-messages via
+ * the Feishu IM API and recursively expands nested merge_forward messages.
+ *
+ * The API returns ALL nested sub-messages in a single flat `items`
+ * array with `upper_message_id` pointing to the parent container.
+ * We build a tree from this flat list and recursively format it —
+ * only one API call is needed regardless of nesting depth.
+ *
+ * This module is a pure "data → format" converter: all API capabilities
+ * (`fetchSubMessages`, `batchResolveNames`, `resolveUserName`) are
+ * injected via callbacks in `ConvertContext`. Callers are responsible
+ * for creating the appropriate callbacks (UAT / TAT / event push).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertMergeForward = void 0;
+const lark_logger_1 = require("../../core/lark-logger.js");
+const content_converter_helpers_1 = require("./content-converter-helpers.js");
+const log = (0, lark_logger_1.larkLogger)('converters/merge-forward');
+/**
+ * Recursively expand a merge_forward message.
+ *
+ * Output format aligns with the Go reference implementation:
+ * ```
+ * <forwarded_messages>
+ * [RFC3339] sender_id:
+ *     message content
+ * </forwarded_messages>
+ * ```
+ */
+const convertMergeForward = async (_raw, ctx) => {
+    const { accountId, messageId, resolveUserName, batchResolveNames, fetchSubMessages, convertMessageContent } = ctx;
+    if (!fetchSubMessages) {
+        return { content: '<forwarded_messages/>', resources: [] };
+    }
+    const content = await expand(accountId, messageId, resolveUserName, batchResolveNames, fetchSubMessages, convertMessageContent);
+    return { content, resources: [] };
+};
+exports.convertMergeForward = convertMergeForward;
+// ---------------------------------------------------------------------------
+// Single-API-call expansion with tree building
+// ---------------------------------------------------------------------------
+async function expand(accountId, messageId, resolveUserName, batchResolveNames, fetchSubMessages, convertContent) {
+    // --- Phase 1: Fetch (single API call via callback) ---
+    let items;
+    try {
+        items = await fetchSubMessages(messageId);
+    }
+    catch (error) {
+        log.error('fetch sub-messages failed', {
+            messageId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return '<forwarded_messages/>';
+    }
+    if (items.length === 0) {
+        return '<forwarded_messages/>';
+    }
+    // --- Phase 2: Build children map ---
+    const childrenMap = buildChildrenMap(items, messageId);
+    // --- Phase 2.5: Batch resolve sender names (via callback) ---
+    const senderIds = collectSenderIds(items, messageId);
+    if (senderIds.length > 0 && batchResolveNames) {
+        try {
+            await batchResolveNames(senderIds);
+        }
+        catch (err) {
+            log.debug('batchResolveNames failed (best-effort)', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    // --- Phase 3: Format tree recursively ---
+    return formatSubTree(messageId, childrenMap, accountId, resolveUserName, convertContent);
+}
+// ---------------------------------------------------------------------------
+// Tree building
+// ---------------------------------------------------------------------------
+/**
+ * Build a map from parent message ID → ordered child items.
+ *
+ * The API returns a flat `items` array where each item may carry an
+ * `upper_message_id` pointing to its parent container. Items without
+ * `upper_message_id` are direct children of the root container.
+ *
+ * The root container message itself (matching `rootMessageId`) is skipped.
+ */
+function buildChildrenMap(items, rootMessageId) {
+    const map = new Map();
+    for (const item of items) {
+        // Skip the root container message itself
+        if (item.message_id === rootMessageId && !item.upper_message_id) {
+            continue;
+        }
+        const parentId = item.upper_message_id ?? rootMessageId;
+        let children = map.get(parentId);
+        if (!children) {
+            children = [];
+            map.set(parentId, children);
+        }
+        children.push(item);
+    }
+    // Sort each group by create_time ascending
+    for (const children of map.values()) {
+        children.sort((a, b) => {
+            const ta = parseInt(String(a.create_time ?? '0'), 10);
+            const tb = parseInt(String(b.create_time ?? '0'), 10);
+            return ta - tb;
+        });
+    }
+    return map;
+}
+// ---------------------------------------------------------------------------
+// Sender ID collection
+// ---------------------------------------------------------------------------
+/**
+ * Collect all unique sender IDs from non-root items for batch name resolution.
+ */
+function collectSenderIds(items, rootMessageId) {
+    const ids = new Set();
+    for (const item of items) {
+        // Skip the root container
+        if (item.message_id === rootMessageId && !item.upper_message_id) {
+            continue;
+        }
+        if (item.sender?.sender_type === 'user') {
+            const senderId = item.sender.id;
+            if (senderId) {
+                ids.add(senderId);
+            }
+        }
+    }
+    return [...ids];
+}
+// ---------------------------------------------------------------------------
+// Recursive tree formatting
+// ---------------------------------------------------------------------------
+/**
+ * Recursively format a sub-tree of messages rooted at `parentId`.
+ *
+ * For `merge_forward` children this recurses into `formatSubTree`
+ * directly (no additional API calls). For other message types it
+ * delegates to `convertMessageContent`.
+ */
+async function formatSubTree(parentId, childrenMap, accountId, resolveUserName, convertContent) {
+    const children = childrenMap.get(parentId);
+    if (!children || children.length === 0) {
+        return '<forwarded_messages/>';
+    }
+    const parts = [];
+    for (const item of children) {
+        try {
+            const msgType = item.msg_type ?? 'text';
+            const senderId = item.sender?.id ?? 'unknown';
+            const createTime = item.create_time ? parseInt(String(item.create_time), 10) : undefined;
+            const timestamp = createTime ? formatTimestamp(createTime) : 'unknown';
+            const rawContent = item.body?.content ?? '{}';
+            let content;
+            if (msgType === 'merge_forward') {
+                // Recurse into nested merge_forward via the tree — no API call
+                const nestedId = item.message_id;
+                if (nestedId) {
+                    content = await formatSubTree(nestedId, childrenMap, accountId, resolveUserName, convertContent);
+                }
+                else {
+                    content = '<forwarded_messages/>';
+                }
+            }
+            else {
+                // Delegate to the unified converter system.
+                // Do NOT pass cfg/account here — sub-converters for non-merge_forward
+                // types don't need it, and passing it would cause nested
+                // merge_forward to re-enter expand() via convertMessageContent.
+                const subCtx = {
+                    ...(0, content_converter_helpers_1.buildConvertContextFromItem)(item, parentId, accountId),
+                    accountId,
+                    resolveUserName,
+                    convertMessageContent: convertContent,
+                };
+                if (!convertContent) {
+                    content = rawContent;
+                }
+                else {
+                    content = (await convertContent(rawContent, msgType, subCtx)).content;
+                }
+            }
+            const displayName = resolveUserName?.(senderId) ?? senderId;
+            const indented = indentLines(content, '    ');
+            parts.push(`[${timestamp}] ${displayName}:\n${indented}`);
+        }
+        catch (err) {
+            log.warn('failed to convert sub-message', {
+                messageId: item.message_id,
+                msgType: item.msg_type ?? 'unknown',
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    if (parts.length === 0) {
+        return '<forwarded_messages/>';
+    }
+    return `<forwarded_messages>\n${parts.join('\n')}\n</forwarded_messages>`;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Convert a millisecond timestamp to RFC 3339 format with +08:00 offset
+ * (Beijing time).
+ */
+function formatTimestamp(ms) {
+    const date = new Date(ms);
+    const utcMs = date.getTime() + date.getTimezoneOffset() * 60_000;
+    const bjDate = new Date(utcMs + 8 * 3600_000);
+    const y = bjDate.getFullYear();
+    const mo = String(bjDate.getMonth() + 1).padStart(2, '0');
+    const d = String(bjDate.getDate()).padStart(2, '0');
+    const h = String(bjDate.getHours()).padStart(2, '0');
+    const mi = String(bjDate.getMinutes()).padStart(2, '0');
+    const s = String(bjDate.getSeconds()).padStart(2, '0');
+    return `${y}-${mo}-${d}T${h}:${mi}:${s}+08:00`;
+}
+/** Add a prefix indent to every line of text. */
+function indentLines(text, indent) {
+    return text
+        .split('\n')
+        .map((line) => `${indent}${line}`)
+        .join('\n');
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "post" (rich text) message type.
+ *
+ * Preserves structure as Markdown: links as `[text](href)`,
+ * images as `![image](key)`, code blocks, and mention resolution.
+ */
+import type { ContentConverterFn } from './types';
+export declare const convertPost: ContentConverterFn;