@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/messaging/inbound/mention.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * @mention utilities for the Lark/Feishu channel plugin.
+ *
+ * All logic is based on `MentionInfo[]` from `MessageContext.mentions`.
+ * Provides:
+ * - Derive helpers: `mentionedBot()`, `nonBotMentions()`
+ * - Format helpers for outbound text and card messages.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMentionAll = isMentionAll;
+exports.mentionedBot = mentionedBot;
+exports.nonBotMentions = nonBotMentions;
+exports.extractMessageBody = extractMessageBody;
+exports.formatMentionForText = formatMentionForText;
+exports.formatMentionAllForText = formatMentionAllForText;
+exports.formatMentionForCard = formatMentionForCard;
+exports.formatMentionAllForCard = formatMentionAllForCard;
+exports.buildMentionedMessage = buildMentionedMessage;
+exports.buildMentionedCardContent = buildMentionedCardContent;
+const utils_1 = require("../converters/utils.js");
+// ---------------------------------------------------------------------------
+// Derive helpers (work on MentionInfo[])
+// ---------------------------------------------------------------------------
+/**
+ * Detect whether a raw mention entry represents @all / @所有人.
+ *
+ * Feishu @all mentions have `key: "@_all"` and empty ID fields.
+ * We match on `key` as the primary signal (most stable across locales).
+ */
+function isMentionAll(mention) {
+    return mention.key === '@_all';
+}
+/** Whether the receiving bot itself was @-mentioned. */
+function mentionedBot(ctx) {
+    return ctx.mentions.some((m) => m.isBot);
+}
+/** All mentions excluding the receiving bot itself. */
+function nonBotMentions(ctx) {
+    return ctx.mentions.filter((m) => !m.isBot);
+}
+// ---------------------------------------------------------------------------
+// extractMessageBody
+// ---------------------------------------------------------------------------
+/**
+ * Remove all @mention placeholder keys from the message text.
+ */
+function extractMessageBody(text, allMentionKeys) {
+    let result = text;
+    for (const key of allMentionKeys) {
+        result = result.replace(new RegExp((0, utils_1.escapeRegExp)(key) + '\\s*', 'g'), '');
+    }
+    return result.trim();
+}
+// ---------------------------------------------------------------------------
+// Format helpers -- text messages
+// ---------------------------------------------------------------------------
+/**
+ * Format a mention for a Feishu text / post message.
+ * @returns e.g. `<at user_id="ou_xxx">Alice</at>`
+ */
+function formatMentionForText(target) {
+    return `<at user_id="${target.openId}">${target.name}</at>`;
+}
+/** Format an @everyone mention for text / post. */
+function formatMentionAllForText() {
+    return `<at user_id="all">Everyone</at>`;
+}
+// ---------------------------------------------------------------------------
+// Format helpers -- interactive card messages
+// ---------------------------------------------------------------------------
+/**
+ * Format a mention for a Feishu Interactive Card.
+ * @returns e.g. `<at id=ou_xxx></at>`
+ */
+function formatMentionForCard(target) {
+    return `<at id=${target.openId}></at>`;
+}
+/** Format an @everyone mention for card. */
+function formatMentionAllForCard() {
+    return `<at id=all></at>`;
+}
+// ---------------------------------------------------------------------------
+// Build helpers (prepend mentions to message body)
+// ---------------------------------------------------------------------------
+/** Prepend @mention tags (text format) to a message body. */
+function buildMentionedMessage(targets, message) {
+    if (targets.length === 0)
+        return message;
+    const mentionTags = targets.map(formatMentionForText).join(' ');
+    return `${mentionTags}\n${message}`;
+}
+/** Prepend @mention tags (card format) to card markdown content. */
+function buildMentionedCardContent(targets, message) {
+    if (targets.length === 0)
+        return message;
+    const mentionTags = targets.map(formatMentionForCard).join(' ');
+    return `${mentionTags}\n${message}`;
+}

package/src/messaging/inbound/parse-io.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * I/O adapters for inbound message parsing.
+ *
+ * Contains API-calling functions that are used during the parse phase
+ * but separated from the pure parsing logic in parse.ts.
+ */
+import type { LarkClient as LarkClientType } from '../../core/lark-client';
+import type { LarkAccount } from '../../core/types';
+/** Shape of a single message item returned by the im/v1/messages API. */
+export interface ApiMessageItem {
+    message_id?: string;
+    msg_type?: string;
+    body?: {
+        content?: string;
+    };
+    sender?: {
+        id?: string;
+        sender_type?: string;
+    };
+    [key: string]: unknown;
+}
+/**
+ * 对 interactive 消息，通过 TAT 调用 API 获取完整 v2 卡片内容。
+ * 事件推送的 content 可能不包含 json_card，API 调用可返回完整的 raw_card_content。
+ * 失败时返回 undefined，调用方 fallback 到原始 content。
+ *
+ * Note: `larkClient.sdk` 的类型定义不暴露 raw `request` 方法，
+ * 因此这里使用 `as any` 断言调用。
+ */
+export declare function fetchCardContent(messageId: string, larkClient: LarkClientType): Promise<string | undefined>;
+/**
+ * Create a `fetchSubMessages` callback for use in `ConvertContext`.
+ *
+ * The returned function calls the im/v1/messages API to fetch
+ * sub-messages of a merge_forward message.
+ *
+ * Note: `larkClient.sdk` 的类型定义不暴露 raw `request` 方法，
+ * 因此这里使用 `as any` 断言调用。
+ */
+export declare function createFetchSubMessages(larkClient: LarkClientType): (msgId: string) => Promise<ApiMessageItem[]>;
+/**
+ * Create a `batchResolveNames` callback for use in `ConvertContext`.
+ *
+ * Wraps `createBatchResolveNames` from user-name-cache.ts, providing
+ * the account and log function.
+ */
+export declare function createParseResolveNames(account: LarkAccount): (openIds: string[]) => Promise<void>;

package/src/messaging/inbound/parse-io.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * I/O adapters for inbound message parsing.
+ *
+ * Contains API-calling functions that are used during the parse phase
+ * but separated from the pure parsing logic in parse.ts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchCardContent = fetchCardContent;
+exports.createFetchSubMessages = createFetchSubMessages;
+exports.createParseResolveNames = createParseResolveNames;
+const lark_logger_1 = require("../../core/lark-logger.js");
+const user_name_cache_1 = require("./user-name-cache.js");
+const log = (0, lark_logger_1.larkLogger)('inbound/parse-io');
+// ---------------------------------------------------------------------------
+// Card content fetcher
+// ---------------------------------------------------------------------------
+/**
+ * 对 interactive 消息，通过 TAT 调用 API 获取完整 v2 卡片内容。
+ * 事件推送的 content 可能不包含 json_card，API 调用可返回完整的 raw_card_content。
+ * 失败时返回 undefined，调用方 fallback 到原始 content。
+ *
+ * Note: `larkClient.sdk` 的类型定义不暴露 raw `request` 方法，
+ * 因此这里使用 `as any` 断言调用。
+ */
+async function fetchCardContent(messageId, larkClient) {
+    try {
+        // SDK 类型不暴露 raw request 方法，需要 as any
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const response = await larkClient.sdk.request({
+            method: 'GET',
+            url: `/open-apis/im/v1/messages/${messageId}`,
+            params: {
+                user_id_type: 'open_id',
+                card_msg_content_type: 'raw_card_content',
+            },
+        });
+        return response?.data?.items?.[0]?.body?.content ?? undefined;
+    }
+    catch (err) {
+        log.warn(`fetchCardContent failed for ${messageId}: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// Sub-message fetcher (for merge_forward)
+// ---------------------------------------------------------------------------
+/**
+ * Create a `fetchSubMessages` callback for use in `ConvertContext`.
+ *
+ * The returned function calls the im/v1/messages API to fetch
+ * sub-messages of a merge_forward message.
+ *
+ * Note: `larkClient.sdk` 的类型定义不暴露 raw `request` 方法，
+ * 因此这里使用 `as any` 断言调用。
+ */
+function createFetchSubMessages(larkClient) {
+    return async (msgId) => {
+        // SDK 类型不暴露 raw request 方法，需要 as any
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const response = await larkClient.sdk.request({
+            method: 'GET',
+            url: `/open-apis/im/v1/messages/${msgId}`,
+            params: { user_id_type: 'open_id', card_msg_content_type: 'raw_card_content' },
+        });
+        if (response?.code !== 0) {
+            throw new Error(`API error: code=${response?.code} msg=${response?.msg}`);
+        }
+        return response?.data?.items ?? [];
+    };
+}
+// ---------------------------------------------------------------------------
+// Batch resolve names callback factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a `batchResolveNames` callback for use in `ConvertContext`.
+ *
+ * Wraps `createBatchResolveNames` from user-name-cache.ts, providing
+ * the account and log function.
+ */
+function createParseResolveNames(account) {
+    return (0, user_name_cache_1.createBatchResolveNames)(account, (...args) => log.info(args.map(String).join(' ')));
+}

package/src/messaging/inbound/parse.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Event parsing for inbound Feishu messages.
+ *
+ * Converts a raw FeishuMessageEvent into a normalised MessageContext.
+ * All mention information is captured in `mentions: MentionInfo[]`;
+ * downstream logic derives `mentionedBot` and non-bot targets from it.
+ *
+ * When `expandCtx` is provided, `cfg` and `accountId` are passed into
+ * the converter context so that async converters (e.g. merge_forward)
+ * can make API calls during parsing.
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+import type { FeishuMessageEvent, MessageContext } from '../types';
+/**
+ * Parse a raw Feishu message event into a normalised MessageContext.
+ *
+ * @param expandCtx  When provided, cfg/accountId are used to create
+ *                   callbacks for async converters (e.g. merge_forward)
+ *                   to fetch sub-messages and resolve sender names.
+ */
+export declare function parseMessageEvent(event: FeishuMessageEvent, botOpenId?: string, expandCtx?: {
+    /** account 级别的 ClawdbotConfig（channels.feishu 已替换为 per-account 合并后的配置） */
+    cfg: ClawdbotConfig;
+    accountId?: string;
+}): Promise<MessageContext>;

package/src/messaging/inbound/parse.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Event parsing for inbound Feishu messages.
+ *
+ * Converts a raw FeishuMessageEvent into a normalised MessageContext.
+ * All mention information is captured in `mentions: MentionInfo[]`;
+ * downstream logic derives `mentionedBot` and non-bot targets from it.
+ *
+ * When `expandCtx` is provided, `cfg` and `accountId` are passed into
+ * the converter context so that async converters (e.g. merge_forward)
+ * can make API calls during parsing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseMessageEvent = parseMessageEvent;
+const content_converter_1 = require("../converters/content-converter.js");
+const accounts_1 = require("../../core/accounts.js");
+const lark_client_1 = require("../../core/lark-client.js");
+const lark_logger_1 = require("../../core/lark-logger.js");
+const mention_1 = require("./mention.js");
+const user_name_cache_1 = require("./user-name-cache.js");
+const parse_io_1 = require("./parse-io.js");
+const log = (0, lark_logger_1.larkLogger)('inbound/parse');
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Parse a raw Feishu message event into a normalised MessageContext.
+ *
+ * @param expandCtx  When provided, cfg/accountId are used to create
+ *                   callbacks for async converters (e.g. merge_forward)
+ *                   to fetch sub-messages and resolve sender names.
+ */
+async function parseMessageEvent(event, botOpenId, expandCtx) {
+    // 1. Build MentionInfo list from event mentions
+    const mentionMap = new Map();
+    const mentionList = [];
+    let mentionAll = false;
+    for (const m of event.message.mentions ?? []) {
+        // Detect @all / @所有人: add to mentionMap (for text replacement by
+        // resolveMentions) but not mentionList (not a user mention).
+        if ((0, mention_1.isMentionAll)(m)) {
+            mentionAll = true;
+            mentionMap.set(m.key, {
+                key: m.key,
+                openId: '',
+                name: m.name,
+                isBot: false,
+            });
+            continue;
+        }
+        const openId = m.id?.open_id ?? '';
+        if (!openId)
+            continue;
+        const info = {
+            key: m.key,
+            openId,
+            name: m.name,
+            isBot: Boolean(botOpenId && openId === botOpenId),
+        };
+        mentionMap.set(m.key, info);
+        mentionList.push(info);
+    }
+    // Build reverse map for O(1) openId lookup
+    const mentionsByOpenId = new Map();
+    for (const info of mentionList) {
+        mentionsByOpenId.set(info.openId, info);
+    }
+    // 2. Convert content via registered converter
+    const acctId = expandCtx?.accountId;
+    // Create larkClient once when expandCtx is available (used for merge_forward & card fetch)
+    const larkClient = expandCtx ? lark_client_1.LarkClient.fromCfg(expandCtx.cfg, acctId) : undefined;
+    // Build merge_forward callbacks when expandCtx is provided
+    let fetchSubMessages;
+    let batchResolveNames;
+    if (expandCtx) {
+        const account = (0, accounts_1.getLarkAccount)(expandCtx.cfg, acctId);
+        fetchSubMessages = (0, parse_io_1.createFetchSubMessages)(larkClient);
+        batchResolveNames = (0, parse_io_1.createParseResolveNames)(account);
+    }
+    // For interactive messages, fetch full v2 card content via API
+    let effectiveContent = event.message.content;
+    if (event.message.message_type === 'interactive' && expandCtx) {
+        const fullContent = await (0, parse_io_1.fetchCardContent)(event.message.message_id, larkClient);
+        if (fullContent) {
+            effectiveContent = fullContent;
+            log.info('replaced interactive content with full v2 card data');
+        }
+    }
+    const convertCtx = {
+        mentions: mentionMap,
+        mentionsByOpenId,
+        messageId: event.message.message_id,
+        botOpenId,
+        cfg: expandCtx?.cfg,
+        accountId: acctId,
+        resolveUserName: acctId ? (openId) => (0, user_name_cache_1.getUserNameCache)(acctId).get(openId) : undefined,
+        fetchSubMessages,
+        batchResolveNames,
+        stripBotMentions: true,
+    };
+    const { content, resources } = await (0, content_converter_1.convertMessageContent)(effectiveContent, event.message.message_type, convertCtx);
+    const createTimeStr = event.message.create_time;
+    const createTime = createTimeStr ? parseInt(createTimeStr, 10) : undefined;
+    return {
+        chatId: event.message.chat_id,
+        messageId: event.message.message_id,
+        senderId: event.sender.sender_id.open_id || '',
+        chatType: event.message.chat_type,
+        rootId: event.message.root_id || undefined,
+        parentId: event.message.parent_id || undefined,
+        threadId: event.message.thread_id || undefined,
+        content,
+        contentType: event.message.message_type,
+        resources,
+        mentions: mentionList,
+        mentionAll,
+        // Per Feishu docs, im.message.receive_v1 sets sender_type to 'user' or
+        // 'bot'. We also accept 'app' defensively for any SDK/legacy variant that
+        // surfaces the older value.
+        senderIsBot: event.sender.sender_type === 'bot' || event.sender.sender_type === 'app',
+        createTime: Number.isNaN(createTime) ? undefined : createTime,
+        rawMessage: effectiveContent !== event.message.content ? { ...event.message, content: effectiveContent } : event.message,
+        rawSender: event.sender,
+    };
+}

package/src/messaging/inbound/permission.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Permission error extraction and cooldown tracking for Feishu API calls.
+ *
+ * Extracted from bot.ts: PermissionError type, extractPermissionError,
+ * PERMISSION_ERROR_COOLDOWN_MS, permissionErrorNotifiedAt.
+ */
+export interface PermissionError {
+    code: number;
+    message: string;
+    grantUrl?: string;
+}
+export declare function extractPermissionError(err: unknown): PermissionError | null;
+export declare const PERMISSION_ERROR_COOLDOWN_MS: number;
+export declare const permissionErrorNotifiedAt: Map<string, number>;

package/src/messaging/inbound/permission.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Permission error extraction and cooldown tracking for Feishu API calls.
+ *
+ * Extracted from bot.ts: PermissionError type, extractPermissionError,
+ * PERMISSION_ERROR_COOLDOWN_MS, permissionErrorNotifiedAt.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.permissionErrorNotifiedAt = exports.PERMISSION_ERROR_COOLDOWN_MS = void 0;
+exports.extractPermissionError = extractPermissionError;
+const permission_url_1 = require("../../core/permission-url.js");
+const auth_errors_1 = require("../../core/auth-errors.js");
+// ---------------------------------------------------------------------------
+// Permission error extraction
+// ---------------------------------------------------------------------------
+function extractPermissionError(err) {
+    if (!err || typeof err !== 'object') {
+        return null;
+    }
+    const axiosErr = err;
+    const data = axiosErr.response?.data;
+    if (!data || typeof data !== 'object') {
+        return null;
+    }
+    const feishuErr = data;
+    // Feishu permission error code
+    if (feishuErr.code !== auth_errors_1.LARK_ERROR.APP_SCOPE_MISSING) {
+        return null;
+    }
+    const msg = feishuErr.msg ?? '';
+    const grantUrl = (0, permission_url_1.extractPermissionGrantUrl)(msg);
+    if (!grantUrl) {
+        return null;
+    }
+    return { code: feishuErr.code, message: msg, grantUrl };
+}
+// ---------------------------------------------------------------------------
+// Cooldown tracking
+// ---------------------------------------------------------------------------
+exports.PERMISSION_ERROR_COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
+exports.permissionErrorNotifiedAt = new Map();

package/src/messaging/inbound/policy.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Access control policies for the Lark/Feishu channel plugin.
+ *
+ * Provides allowlist matching, group configuration lookup, tool policy
+ * extraction, and group access checks.
+ */
+import type { ChannelGroupContext } from 'openclaw/plugin-sdk/channel-contract';
+import type { GroupToolPolicyConfig } from 'openclaw/plugin-sdk/channel-policy';
+import type { FeishuConfig, FeishuGroupConfig } from '../../core/types';
+export interface FeishuAllowlistMatch {
+    allowed: boolean;
+    matchKey?: string;
+    matchSource?: 'wildcard' | 'id' | 'name';
+}
+/**
+ * Check whether a sender is permitted by a given allowlist.
+ *
+ * Entries are normalised to lowercase strings before comparison.
+ * A single "*" entry acts as a wildcard that matches everyone.
+ * When the allowlist is empty the result is `{ allowed: false }`.
+ */
+export declare function resolveFeishuAllowlistMatch(params: {
+    allowFrom: Array<string | number>;
+    senderId: string;
+    senderName?: string | null;
+}): FeishuAllowlistMatch;
+/**
+ * Look up the per-group configuration by group ID.
+ *
+ * Performs a case-insensitive lookup against the keys in `cfg.groups`.
+ * Returns `undefined` when no matching group entry is found.
+ */
+export declare function resolveFeishuGroupConfig(params: {
+    cfg?: FeishuConfig;
+    groupId?: string | null;
+}): FeishuGroupConfig | undefined;
+/**
+ * Extract the tool policy configuration from the group config that
+ * corresponds to the given group context.
+ *
+ * ★ 多账号配置隔离：SDK 回调传入的 params.cfg 是顶层全局配置，
+ *   cfg.channels.feishu 不包含 per-account 的覆盖值。
+ *   这里通过 getLarkAccount() 获取当前 account 合并后的配置，
+ *   确保每个账号的 groups / tool policy 配置独立生效。
+ */
+export declare function resolveFeishuGroupToolPolicy(params: ChannelGroupContext): GroupToolPolicyConfig | undefined;
+/**
+ * Determine whether an inbound group message should be processed.
+ *
+ * - `disabled` --> always rejected
+ * - `open`     --> always allowed
+ * - `allowlist` --> allowed only when the sender matches the allowlist
+ */
+export declare function isFeishuGroupAllowed(params: {
+    groupPolicy: 'open' | 'allowlist' | 'disabled';
+    allowFrom: Array<string | number>;
+    senderId: string;
+    senderName?: string | null;
+}): boolean;
+/**
+ * Split a raw `groupAllowFrom` array into legacy chat-ID entries
+ * (`oc_xxx`) and sender-level entries.
+ *
+ * Older Feishu configs used `groupAllowFrom` with `oc_xxx` chat IDs to
+ * control which groups are allowed.  The correct semantic (aligned with
+ * Telegram) is sender IDs.  This function separates the two concerns so
+ * both layers can work independently.
+ */
+export declare function splitLegacyGroupAllowFrom(rawGroupAllowFrom: Array<string | number>): {
+    legacyChatIds: string[];
+    senderAllowFrom: string[];
+};
+/**
+ * Resolve the effective sender-level group policy and the merged
+ * `allowFrom` list for sender filtering within a group.
+ *
+ * The precedence chain for `senderPolicy` is:
+ *   per-group `groupPolicy` > default ("*") group `groupPolicy` >
+ *   global `groupPolicy` > "open" (default).
+ *
+ * The `senderAllowFrom` is the union of global (non-oc_) entries,
+ * per-group entries, and default ("*") entries (when no per-group config).
+ */
+export declare function resolveGroupSenderPolicyContext(params: {
+    groupConfig?: FeishuGroupConfig;
+    defaultConfig?: FeishuGroupConfig;
+    accountFeishuCfg?: FeishuConfig;
+    senderGroupAllowFrom: Array<string | number>;
+}): {
+    senderPolicy: 'open' | 'allowlist' | 'disabled';
+    senderAllowFrom: Array<string | number>;
+};