@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/core/auth-errors.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * auth-errors.ts — 统一错误类型定义。
+ *
+ * 所有与认证/授权/scope 相关的错误类型集中在此文件，
+ * 解除 tool-client ↔ app-scope-checker 循环依赖。
+ *
+ * 其他模块应直接 import 此文件，或通过 tool-client / uat-client 的 re-export 使用。
+ */
+/** 飞书 OAPI 错误码常量，替代各处硬编码的 magic number。 */
+export declare const LARK_ERROR: {
+    /** 应用 scope 不足（租户维度） */
+    readonly APP_SCOPE_MISSING: 99991672;
+    /** 用户 token scope 不足 */
+    readonly USER_SCOPE_INSUFFICIENT: 99991679;
+    /** access_token 无效 */
+    readonly TOKEN_INVALID: 99991668;
+    /** access_token 已过期 */
+    readonly TOKEN_EXPIRED: 99991677;
+    /** refresh_token 本身无效（格式非法或来自 v1 API） */
+    readonly REFRESH_TOKEN_INVALID: 20026;
+    /** refresh_token 已过期（超过 365 天） */
+    readonly REFRESH_TOKEN_EXPIRED: 20037;
+    /** refresh_token 已被吊销 */
+    readonly REFRESH_TOKEN_REVOKED: 20064;
+    /** refresh_token 已被使用（单次消费，rotation 场景） */
+    readonly REFRESH_TOKEN_ALREADY_USED: 20073;
+    /** refresh token 端点服务端内部错误，可重试 */
+    readonly REFRESH_SERVER_ERROR: 20050;
+    /** 消息已被撤回 */
+    readonly MESSAGE_RECALLED: 230011;
+    /** 消息已被删除 */
+    readonly MESSAGE_DELETED: 231003;
+};
+/** refresh token 端点可重试的错误码集合（服务端瞬时故障）。遇到后重试一次，仍失败则清 token。 */
+export declare const REFRESH_TOKEN_RETRYABLE: ReadonlySet<number>;
+/** 消息终止错误码集合（撤回/删除），遇到后应停止对该消息的后续操作。 */
+export declare const MESSAGE_TERMINAL_CODES: ReadonlySet<number>;
+/** access_token 失效相关的错误码集合，遇到后可尝试刷新重试。 */
+export declare const TOKEN_RETRY_CODES: ReadonlySet<number>;
+/** invoke() 错误共享的 scope 信息。 */
+export interface ScopeErrorInfo {
+    apiName: string;
+    scopes: string[];
+    /** 应用 scope 是否已验证通过。false 表示 app scope 检查失败，scope 信息可能不准确。 */
+    appScopeVerified?: boolean;
+    /** 应用 ID，用于生成开放平台权限管理链接。 */
+    appId?: string;
+}
+/** OAuth 授权提示信息，与 handleInvokeError 返回的结构一致。 */
+export interface AuthHint {
+    error: string;
+    api: string;
+    required_scope: string;
+    user_open_id: string;
+    message: string;
+    next_tool_call: {
+        tool: 'feishu_oauth';
+        params: {
+            action: 'authorize';
+            scope: string;
+        };
+    };
+}
+/** tryInvoke 返回值的判别联合体。 */
+export type TryInvokeResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+    authHint: AuthHint;
+} | {
+    ok: false;
+    error: string;
+    authHint?: undefined;
+};
+/**
+ * Thrown when no valid UAT exists and the user needs to (re-)authorise.
+ * Callers should catch this and trigger the OAuth flow.
+ */
+export declare class NeedAuthorizationError extends Error {
+    readonly userOpenId: string;
+    constructor(userOpenId: string);
+}
+/**
+ * 应用缺少 application:application:self_manage 权限，无法查询应用权限配置。
+ *
+ * 需要管理员在飞书开放平台开通 application:application:self_manage 权限。
+ */
+export declare class AppScopeCheckFailedError extends Error {
+    /** 应用 ID，用于生成开放平台权限管理链接。 */
+    readonly appId?: string;
+    constructor(appId?: string);
+}
+/**
+ * 应用未开通 OAPI 所需 scope。
+ *
+ * 需要管理员在飞书开放平台开通权限。
+ */
+export declare class AppScopeMissingError extends Error {
+    readonly apiName: string;
+    /** OAPI 需要但 APP 未开通的 scope 列表。 */
+    readonly missingScopes: string[];
+    /** 工具的全部所需 scope（含已开通的），用于应用权限完成后一次性发起用户授权。 */
+    readonly allRequiredScopes?: string[];
+    /** 应用 ID，用于生成开放平台权限管理链接。 */
+    readonly appId?: string;
+    readonly scopeNeedType?: 'one' | 'all';
+    /** 触发此错误时使用的 token 类型，用于保持 card action 二次校验一致。 */
+    readonly tokenType?: 'user' | 'tenant';
+    constructor(info: ScopeErrorInfo, scopeNeedType?: 'one' | 'all', tokenType?: 'user' | 'tenant', allRequiredScopes?: string[]);
+}
+/**
+ * 用户未授权或 scope 不足，需要发起 OAuth 授权。
+ *
+ * `requiredScopes` 为 APP∩OAPI 的有效 scope，可直接传给
+ * `feishu_oauth authorize --scope`。
+ */
+export declare class UserAuthRequiredError extends Error {
+    readonly userOpenId: string;
+    readonly apiName: string;
+    /** APP∩OAPI 交集 scope，传给 OAuth authorize。 */
+    readonly requiredScopes: string[];
+    /** 应用 scope 是否已验证通过。false 时 requiredScopes 可能不准确。 */
+    readonly appScopeVerified: boolean;
+    /** 应用 ID，用于生成开放平台权限管理链接。 */
+    readonly appId?: string;
+    constructor(userOpenId: string, info: ScopeErrorInfo);
+}
+/**
+ * 服务端报 99991679 — 用户 token 的 scope 不足。
+ *
+ * 需要增量授权：用缺失的 scope 发起新 Device Flow。
+ */
+export declare class UserScopeInsufficientError extends Error {
+    readonly userOpenId: string;
+    readonly apiName: string;
+    /** 缺失的 scope 列表。 */
+    readonly missingScopes: string[];
+    constructor(userOpenId: string, info: ScopeErrorInfo);
+}

package/src/core/auth-errors.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * auth-errors.ts — 统一错误类型定义。
+ *
+ * 所有与认证/授权/scope 相关的错误类型集中在此文件，
+ * 解除 tool-client ↔ app-scope-checker 循环依赖。
+ *
+ * 其他模块应直接 import 此文件，或通过 tool-client / uat-client 的 re-export 使用。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserScopeInsufficientError = exports.UserAuthRequiredError = exports.AppScopeMissingError = exports.AppScopeCheckFailedError = exports.NeedAuthorizationError = exports.TOKEN_RETRY_CODES = exports.MESSAGE_TERMINAL_CODES = exports.REFRESH_TOKEN_RETRYABLE = exports.LARK_ERROR = void 0;
+// ---------------------------------------------------------------------------
+// Feishu error code constants
+// ---------------------------------------------------------------------------
+/** 飞书 OAPI 错误码常量，替代各处硬编码的 magic number。 */
+exports.LARK_ERROR = {
+    /** 应用 scope 不足（租户维度） */
+    APP_SCOPE_MISSING: 99991672,
+    /** 用户 token scope 不足 */
+    USER_SCOPE_INSUFFICIENT: 99991679,
+    /** access_token 无效 */
+    TOKEN_INVALID: 99991668,
+    /** access_token 已过期 */
+    TOKEN_EXPIRED: 99991677,
+    /** refresh_token 本身无效（格式非法或来自 v1 API） */
+    REFRESH_TOKEN_INVALID: 20026,
+    /** refresh_token 已过期（超过 365 天） */
+    REFRESH_TOKEN_EXPIRED: 20037,
+    /** refresh_token 已被吊销 */
+    REFRESH_TOKEN_REVOKED: 20064,
+    /** refresh_token 已被使用（单次消费，rotation 场景） */
+    REFRESH_TOKEN_ALREADY_USED: 20073,
+    /** refresh token 端点服务端内部错误，可重试 */
+    REFRESH_SERVER_ERROR: 20050,
+    /** 消息已被撤回 */
+    MESSAGE_RECALLED: 230011,
+    /** 消息已被删除 */
+    MESSAGE_DELETED: 231003,
+};
+/** refresh token 端点可重试的错误码集合（服务端瞬时故障）。遇到后重试一次，仍失败则清 token。 */
+exports.REFRESH_TOKEN_RETRYABLE = new Set([exports.LARK_ERROR.REFRESH_SERVER_ERROR]);
+/** 消息终止错误码集合（撤回/删除），遇到后应停止对该消息的后续操作。 */
+exports.MESSAGE_TERMINAL_CODES = new Set([
+    exports.LARK_ERROR.MESSAGE_RECALLED,
+    exports.LARK_ERROR.MESSAGE_DELETED,
+]);
+/** access_token 失效相关的错误码集合，遇到后可尝试刷新重试。 */
+exports.TOKEN_RETRY_CODES = new Set([exports.LARK_ERROR.TOKEN_INVALID, exports.LARK_ERROR.TOKEN_EXPIRED]);
+// ---------------------------------------------------------------------------
+// Error classes
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when no valid UAT exists and the user needs to (re-)authorise.
+ * Callers should catch this and trigger the OAuth flow.
+ */
+class NeedAuthorizationError extends Error {
+    userOpenId;
+    constructor(userOpenId) {
+        super('need_user_authorization');
+        this.name = 'NeedAuthorizationError';
+        this.userOpenId = userOpenId;
+    }
+}
+exports.NeedAuthorizationError = NeedAuthorizationError;
+/**
+ * 应用缺少 application:application:self_manage 权限，无法查询应用权限配置。
+ *
+ * 需要管理员在飞书开放平台开通 application:application:self_manage 权限。
+ */
+class AppScopeCheckFailedError extends Error {
+    /** 应用 ID，用于生成开放平台权限管理链接。 */
+    appId;
+    constructor(appId) {
+        super('应用缺少 application:application:self_manage 权限，无法查询应用权限配置。请管理员在开放平台开通该权限。');
+        this.name = 'AppScopeCheckFailedError';
+        this.appId = appId;
+    }
+}
+exports.AppScopeCheckFailedError = AppScopeCheckFailedError;
+/**
+ * 应用未开通 OAPI 所需 scope。
+ *
+ * 需要管理员在飞书开放平台开通权限。
+ */
+class AppScopeMissingError extends Error {
+    apiName;
+    /** OAPI 需要但 APP 未开通的 scope 列表。 */
+    missingScopes;
+    /** 工具的全部所需 scope（含已开通的），用于应用权限完成后一次性发起用户授权。 */
+    allRequiredScopes;
+    /** 应用 ID，用于生成开放平台权限管理链接。 */
+    appId;
+    scopeNeedType;
+    /** 触发此错误时使用的 token 类型，用于保持 card action 二次校验一致。 */
+    tokenType;
+    constructor(info, scopeNeedType, tokenType, allRequiredScopes) {
+        if (scopeNeedType === 'one') {
+            super(`应用缺少权限 [${info.scopes.join(', ')}](开启任一权限即可)，请管理员在开放平台开通。`);
+        }
+        else {
+            super(`应用缺少权限 [${info.scopes.join(', ')}]，请管理员在开放平台开通。`);
+        }
+        this.name = 'AppScopeMissingError';
+        this.apiName = info.apiName;
+        this.missingScopes = info.scopes;
+        this.allRequiredScopes = allRequiredScopes;
+        this.appId = info.appId;
+        this.scopeNeedType = scopeNeedType;
+        this.tokenType = tokenType;
+    }
+}
+exports.AppScopeMissingError = AppScopeMissingError;
+/**
+ * 用户未授权或 scope 不足，需要发起 OAuth 授权。
+ *
+ * `requiredScopes` 为 APP∩OAPI 的有效 scope，可直接传给
+ * `feishu_oauth authorize --scope`。
+ */
+class UserAuthRequiredError extends Error {
+    userOpenId;
+    apiName;
+    /** APP∩OAPI 交集 scope，传给 OAuth authorize。 */
+    requiredScopes;
+    /** 应用 scope 是否已验证通过。false 时 requiredScopes 可能不准确。 */
+    appScopeVerified;
+    /** 应用 ID，用于生成开放平台权限管理链接。 */
+    appId;
+    constructor(userOpenId, info) {
+        super('need_user_authorization');
+        this.name = 'UserAuthRequiredError';
+        this.userOpenId = userOpenId;
+        this.apiName = info.apiName;
+        this.requiredScopes = info.scopes;
+        this.appId = info.appId;
+        this.appScopeVerified = info.appScopeVerified ?? true;
+    }
+}
+exports.UserAuthRequiredError = UserAuthRequiredError;
+/**
+ * 服务端报 99991679 — 用户 token 的 scope 不足。
+ *
+ * 需要增量授权：用缺失的 scope 发起新 Device Flow。
+ */
+class UserScopeInsufficientError extends Error {
+    userOpenId;
+    apiName;
+    /** 缺失的 scope 列表。 */
+    missingScopes;
+    constructor(userOpenId, info) {
+        super('user_scope_insufficient');
+        this.name = 'UserScopeInsufficientError';
+        this.userOpenId = userOpenId;
+        this.apiName = info.apiName;
+        this.missingScopes = info.scopes;
+    }
+}
+exports.UserScopeInsufficientError = UserScopeInsufficientError;

package/src/core/card-action-operator.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Card callback operator identity extraction.
+ *
+ * Feishu Schema 2 card callbacks may carry the operator identity under
+ * either `operator.open_id` (Schema 1 / default) or `operator.user_id`
+ * (Schema 2 when the user has no open_id in the app's tenant).
+ *
+ * This helper provides a single, consistent extraction point so that
+ * every card callback handler resolves the operator identity the same
+ * way.  See openclaw/openclaw#71670 for the upstream Schema 2 change.
+ */
+/**
+ * Minimal shape of the `operator` object in a Feishu card callback event.
+ * Both fields are optional because Schema 2 may omit `open_id` entirely.
+ */
+export interface CardCallbackOperator {
+    open_id?: string;
+    user_id?: string;
+}
+/**
+ * Extract the operator's identity from a Feishu card callback event.
+ *
+ * Prefers `open_id` (the stable per-app user identifier) and falls back
+ * to `user_id` when `open_id` is absent or empty — this is the Schema 2 path.
+ *
+ * @param operator - The `operator` field from the card callback payload.
+ * @returns The resolved operator identifier, or `undefined` when neither
+ *   field is present.
+ */
+export declare function resolveCardCallbackOperatorId(operator: CardCallbackOperator | undefined): string | undefined;

package/src/core/card-action-operator.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Card callback operator identity extraction.
+ *
+ * Feishu Schema 2 card callbacks may carry the operator identity under
+ * either `operator.open_id` (Schema 1 / default) or `operator.user_id`
+ * (Schema 2 when the user has no open_id in the app's tenant).
+ *
+ * This helper provides a single, consistent extraction point so that
+ * every card callback handler resolves the operator identity the same
+ * way.  See openclaw/openclaw#71670 for the upstream Schema 2 change.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCardCallbackOperatorId = resolveCardCallbackOperatorId;
+/**
+ * Extract the operator's identity from a Feishu card callback event.
+ *
+ * Prefers `open_id` (the stable per-app user identifier) and falls back
+ * to `user_id` when `open_id` is absent or empty — this is the Schema 2 path.
+ *
+ * @param operator - The `operator` field from the card callback payload.
+ * @returns The resolved operator identifier, or `undefined` when neither
+ *   field is present.
+ */
+function resolveCardCallbackOperatorId(operator) {
+    return operator?.open_id || operator?.user_id;
+}

package/src/core/chat-info-cache.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Account-scoped LRU cache for Feishu group/chat metadata.
+ *
+ * Caches the result of `im.chat.get` (chat_mode, group_message_type, etc.)
+ * to avoid repeated OAPI calls for every inbound message.
+ *
+ * Key fields cached:
+ * - `chat_mode`: "group" | "topic" | "p2p"
+ * - `group_message_type`: "chat" | "thread" (only for chat_mode=group)
+ */
+import type * as Lark from '@larksuiteoapi/node-sdk';
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+/** Minimal structural type for LarkClient class (avoids circular import). */
+interface LarkClientStatic {
+    fromCfg(cfg: ClawdbotConfig, accountId?: string): {
+        sdk: Lark.Client;
+    };
+}
+/** @internal Called by lark-client.ts at module init time. */
+export declare function injectLarkClient(cls: LarkClientStatic): void;
+export interface ChatInfo {
+    chatMode: 'group' | 'topic' | 'p2p';
+    groupMessageType?: 'chat' | 'thread';
+}
+/** Clear chat-info caches (called from LarkClient.clearCache). */
+export declare function clearChatInfoCache(accountId?: string): void;
+/**
+ * Determine whether a group supports thread sessions.
+ *
+ * Returns `true` when the group is a topic group (`chat_mode=topic`) or
+ * a normal group with thread message mode (`group_message_type=thread`).
+ *
+ * Results are cached per-account with a 1-hour TTL to minimise OAPI calls.
+ */
+export declare function isThreadCapableGroup(params: {
+    cfg: ClawdbotConfig;
+    chatId: string;
+    accountId?: string;
+}): Promise<boolean>;
+/**
+ * Fetch (or read from cache) the chat metadata for a given chat ID.
+ *
+ * Returns `undefined` when the API call fails (best-effort).
+ */
+export declare function getChatInfo(params: {
+    cfg: ClawdbotConfig;
+    chatId: string;
+    accountId?: string;
+}): Promise<ChatInfo | undefined>;
+/**
+ * Determine the chat type (p2p or group) for a given chat ID.
+ *
+ * Delegates to the shared {@link getChatInfo} cache (account-scoped LRU with
+ * 1-hour TTL) so that chat metadata is fetched at most once across all
+ * call-sites (dispatch, reaction handler, etc.).
+ *
+ * Falls back to "p2p" if the API call fails.
+ */
+export declare function getChatTypeFeishu(params: {
+    cfg: ClawdbotConfig;
+    chatId: string;
+    accountId?: string;
+}): Promise<'p2p' | 'group'>;
+export {};

package/src/core/chat-info-cache.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Account-scoped LRU cache for Feishu group/chat metadata.
+ *
+ * Caches the result of `im.chat.get` (chat_mode, group_message_type, etc.)
+ * to avoid repeated OAPI calls for every inbound message.
+ *
+ * Key fields cached:
+ * - `chat_mode`: "group" | "topic" | "p2p"
+ * - `group_message_type`: "chat" | "thread" (only for chat_mode=group)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.injectLarkClient = injectLarkClient;
+exports.clearChatInfoCache = clearChatInfoCache;
+exports.isThreadCapableGroup = isThreadCapableGroup;
+exports.getChatInfo = getChatInfo;
+exports.getChatTypeFeishu = getChatTypeFeishu;
+const lark_logger_1 = require("./lark-logger.js");
+let _LarkClient = null;
+/** @internal Called by lark-client.ts at module init time. */
+function injectLarkClient(cls) {
+    _LarkClient = cls;
+}
+const log = (0, lark_logger_1.larkLogger)('core/chat-info-cache');
+// ---------------------------------------------------------------------------
+// Cache implementation
+// ---------------------------------------------------------------------------
+const DEFAULT_MAX_SIZE = 500;
+const DEFAULT_TTL_MS = 60 * 60 * 1000; // 1 hour
+class ChatInfoCache {
+    map = new Map();
+    maxSize;
+    ttlMs;
+    constructor(maxSize = DEFAULT_MAX_SIZE, ttlMs = DEFAULT_TTL_MS) {
+        this.maxSize = maxSize;
+        this.ttlMs = ttlMs;
+    }
+    get(chatId) {
+        const entry = this.map.get(chatId);
+        if (!entry)
+            return undefined;
+        if (entry.expireAt <= Date.now()) {
+            this.map.delete(chatId);
+            return undefined;
+        }
+        // LRU refresh
+        this.map.delete(chatId);
+        this.map.set(chatId, entry);
+        return entry.info;
+    }
+    set(chatId, info) {
+        this.map.delete(chatId);
+        this.map.set(chatId, { info, expireAt: Date.now() + this.ttlMs });
+        this.evict();
+    }
+    clear() {
+        this.map.clear();
+    }
+    evict() {
+        while (this.map.size > this.maxSize) {
+            const oldest = this.map.keys().next().value;
+            if (oldest !== undefined)
+                this.map.delete(oldest);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Account-scoped singleton registry
+// ---------------------------------------------------------------------------
+const registry = new Map();
+function getChatInfoCache(accountId) {
+    let c = registry.get(accountId);
+    if (!c) {
+        c = new ChatInfoCache();
+        registry.set(accountId, c);
+    }
+    return c;
+}
+/** Clear chat-info caches (called from LarkClient.clearCache). */
+function clearChatInfoCache(accountId) {
+    if (accountId !== undefined) {
+        registry.get(accountId)?.clear();
+        registry.delete(accountId);
+    }
+    else {
+        for (const c of registry.values())
+            c.clear();
+        registry.clear();
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Determine whether a group supports thread sessions.
+ *
+ * Returns `true` when the group is a topic group (`chat_mode=topic`) or
+ * a normal group with thread message mode (`group_message_type=thread`).
+ *
+ * Results are cached per-account with a 1-hour TTL to minimise OAPI calls.
+ */
+async function isThreadCapableGroup(params) {
+    const { cfg, chatId, accountId } = params;
+    const info = await getChatInfo({ cfg, chatId, accountId });
+    if (!info)
+        return false;
+    return info.chatMode === 'topic' || info.groupMessageType === 'thread';
+}
+/**
+ * Fetch (or read from cache) the chat metadata for a given chat ID.
+ *
+ * Returns `undefined` when the API call fails (best-effort).
+ */
+async function getChatInfo(params) {
+    const { cfg, chatId, accountId } = params;
+    const effectiveAccountId = accountId ?? 'default';
+    const cache = getChatInfoCache(effectiveAccountId);
+    const cached = cache.get(chatId);
+    if (cached)
+        return cached;
+    try {
+        if (!_LarkClient)
+            throw new Error('LarkClient not injected — circular dependency broken?');
+        const sdk = _LarkClient.fromCfg(cfg, accountId).sdk;
+        const response = await sdk.im.chat.get({
+            path: { chat_id: chatId },
+        });
+        const data = response?.data;
+        const chatMode = data?.chat_mode ?? 'group';
+        const groupMessageType = data?.group_message_type;
+        const info = {
+            chatMode: chatMode,
+            groupMessageType: groupMessageType,
+        };
+        cache.set(chatId, info);
+        log.info(`resolved ${chatId} → chat_mode=${chatMode}, group_message_type=${groupMessageType ?? 'N/A'}`);
+        return info;
+    }
+    catch (err) {
+        log.error(`failed to get chat info for ${chatId}: ${String(err)}`);
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// getChatTypeFeishu
+// ---------------------------------------------------------------------------
+/**
+ * Determine the chat type (p2p or group) for a given chat ID.
+ *
+ * Delegates to the shared {@link getChatInfo} cache (account-scoped LRU with
+ * 1-hour TTL) so that chat metadata is fetched at most once across all
+ * call-sites (dispatch, reaction handler, etc.).
+ *
+ * Falls back to "p2p" if the API call fails.
+ */
+async function getChatTypeFeishu(params) {
+    const { cfg, chatId, accountId } = params;
+    const info = await getChatInfo({ cfg, chatId, accountId });
+    if (!info)
+        return 'p2p';
+    return info.chatMode === 'group' || info.chatMode === 'topic' ? 'group' : 'p2p';
+}

package/src/core/comment-target.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Feishu Drive comment target ID parsing and formatting utilities.
+ *
+ * Comment targets use one of these formats:
+ * - `comment:<fileType>:<fileToken>:<commentId>` (legacy/default reply mode)
+ * - `comment:<deliveryMode>:<fileType>:<fileToken>:<commentId>`
+ *
+ * This enables the outbound routing layer to distinguish comment-thread
+ * replies from normal IM messages and route them through the Drive
+ * comment API instead.
+ */
+/** Document types that support Drive comments. */
+export type CommentFileType = 'doc' | 'docx' | 'file' | 'sheet' | 'slides';
+/** Delivery mode for a comment target. */
+export type CommentDeliveryMode = 'reply' | 'create_whole';
+/** Parsed comment target components. */
+export interface CommentTarget {
+    deliveryMode: CommentDeliveryMode;
+    fileType: CommentFileType;
+    fileToken: string;
+    commentId: string;
+}
+/**
+ * Construct a comment target string from its components.
+ *
+ * @example
+ * ```ts
+ * buildFeishuCommentTarget({ fileType: 'docx', fileToken: 'abc123', commentId: '789' })
+ * // => 'comment:docx:abc123:789'
+ *
+ * buildFeishuCommentTarget({ deliveryMode: 'create_whole', fileType: 'docx', fileToken: 'abc123', commentId: '789' })
+ * // => 'comment:create_whole:docx:abc123:789'
+ * ```
+ */
+export declare function buildFeishuCommentTarget(params: {
+    deliveryMode?: CommentDeliveryMode;
+    fileType: CommentFileType;
+    fileToken: string;
+    commentId: string;
+}): string;
+/**
+ * Parse a comment target string into its components.
+ *
+ * Returns `null` when the string is not a valid comment target.
+ *
+ * @example
+ * ```ts
+ * parseFeishuCommentTarget('comment:docx:abc123:789')
+ * // => { deliveryMode: 'reply', fileType: 'docx', fileToken: 'abc123', commentId: '789' }
+ *
+ * parseFeishuCommentTarget('comment:create_whole:docx:abc123:789')
+ * // => { deliveryMode: 'create_whole', fileType: 'docx', fileToken: 'abc123', commentId: '789' }
+ *
+ * parseFeishuCommentTarget('oc_xxx')
+ * // => null
+ * ```
+ */
+export declare function parseFeishuCommentTarget(target: string): CommentTarget | null;
+/**
+ * Return `true` when a target string looks like a comment target.
+ */
+export declare function isCommentTarget(target: string): boolean;