@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/messaging/inbound/synthetic-message.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared helper for dispatching synthetic inbound text messages.
+ *
+ * Synthetic messages are used to resume the normal inbound pipeline after
+ * card actions or OAuth flows complete.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchSyntheticTextMessage = dispatchSyntheticTextMessage;
+const chat_queue_1 = require("../../channel/chat-queue.js");
+const lark_ticket_1 = require("../../core/lark-ticket.js");
+const handler_registry_1 = require("./handler-registry.js");
+async function dispatchSyntheticTextMessage(params) {
+    const handleFeishuMessage = (0, handler_registry_1.getInboundHandler)();
+    const { cfg, accountId, chatId, senderOpenId, text, syntheticMessageId, replyToMessageId, chatType, threadId, runtime, forceMention = true, } = params;
+    const syntheticEvent = {
+        sender: {
+            sender_id: { open_id: senderOpenId },
+        },
+        message: {
+            message_id: syntheticMessageId,
+            chat_id: chatId,
+            chat_type: chatType ?? 'p2p',
+            message_type: 'text',
+            content: JSON.stringify({ text }),
+            thread_id: threadId,
+        },
+    };
+    const { status, promise } = (0, chat_queue_1.enqueueFeishuChatTask)({
+        accountId,
+        chatId,
+        threadId,
+        task: async () => {
+            await (0, lark_ticket_1.withTicket)({
+                messageId: syntheticMessageId,
+                chatId,
+                accountId,
+                startTime: Date.now(),
+                senderOpenId,
+                chatType,
+                threadId,
+            }, () => handleFeishuMessage({
+                cfg,
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                event: syntheticEvent,
+                accountId,
+                forceMention,
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                runtime: runtime,
+                replyToMessageId,
+            }));
+        },
+    });
+    await promise;
+    return status;
+}

package/src/messaging/inbound/user-name-cache-store.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Account-scoped cache registry for Feishu user display names.
+ *
+ * Stores forward (openId → name + kind) and reverse (normalizedName → Set<openId>)
+ * indexes for mention resolution. Per-account, LRU + TTL.
+ */
+export type PrincipalKind = 'user' | 'bot';
+export interface MentionMatch {
+    openId: string;
+    name: string;
+    kind?: PrincipalKind;
+}
+export interface ChatMember {
+    openId: string;
+    name: string;
+    kind: PrincipalKind;
+}
+export interface ChatMembersEntry {
+    members: ChatMember[];
+    expireAt: number;
+}
+export declare class UserNameCache {
+    private nameByOpenId;
+    private openIdsByName;
+    private maxSize;
+    private ttlMs;
+    private chatBots;
+    private chatMembers;
+    private inFlight;
+    private maxChats;
+    constructor(maxSize?: number, ttlMs?: number, maxChats?: number);
+    has(openId: string): boolean;
+    get(openId: string): string | undefined;
+    set(openId: string, name: string): void;
+    setWithKind(openId: string, name: string, kind: PrincipalKind): void;
+    lookupByName(name: string): MentionMatch[];
+    setMany(entries: Iterable<[string, string]>): void;
+    filterMissing(openIds: string[]): string[];
+    getMany(openIds: string[]): Map<string, string>;
+    recordChatBots(chatId: string, members: Array<{
+        openId: string;
+        name: string;
+    }>): void;
+    recordChatMembers(chatId: string, members: ChatMember[]): void;
+    getChatBots(chatId: string): ChatMembersEntry | null;
+    getChatMembers(chatId: string): ChatMembersEntry | null;
+    getInflight(key: string): Promise<void> | undefined;
+    setInflight(key: string, promise: Promise<void>): void;
+    clearInflight(key: string): void;
+    clear(): void;
+    private writeEntry;
+    private writeEntryNoEvict;
+    private deleteOpenId;
+    private removeFromReverse;
+    private evictChats;
+    private evict;
+}
+export declare function getUserNameCache(accountId: string): UserNameCache;
+export declare function clearUserNameCache(accountId?: string): void;

package/src/messaging/inbound/user-name-cache-store.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Account-scoped cache registry for Feishu user display names.
+ *
+ * Stores forward (openId → name + kind) and reverse (normalizedName → Set<openId>)
+ * indexes for mention resolution. Per-account, LRU + TTL.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserNameCache = void 0;
+exports.getUserNameCache = getUserNameCache;
+exports.clearUserNameCache = clearUserNameCache;
+const DEFAULT_MAX_SIZE = 500;
+const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const DEFAULT_MAX_CHATS = 200;
+function normalizeName(name) {
+    return name.trim().toLowerCase();
+}
+class UserNameCache {
+    nameByOpenId = new Map();
+    openIdsByName = new Map();
+    maxSize;
+    ttlMs;
+    chatBots = new Map();
+    chatMembers = new Map();
+    inFlight = new Map();
+    maxChats;
+    constructor(maxSize = DEFAULT_MAX_SIZE, ttlMs = DEFAULT_TTL_MS, maxChats = DEFAULT_MAX_CHATS) {
+        this.maxSize = maxSize;
+        this.ttlMs = ttlMs;
+        this.maxChats = maxChats;
+    }
+    has(openId) {
+        const entry = this.nameByOpenId.get(openId);
+        if (!entry)
+            return false;
+        if (entry.expireAt <= Date.now()) {
+            this.deleteOpenId(openId);
+            return false;
+        }
+        return true;
+    }
+    get(openId) {
+        const entry = this.nameByOpenId.get(openId);
+        if (!entry)
+            return undefined;
+        if (entry.expireAt <= Date.now()) {
+            this.deleteOpenId(openId);
+            return undefined;
+        }
+        // LRU bump
+        this.nameByOpenId.delete(openId);
+        this.nameByOpenId.set(openId, entry);
+        return entry.name;
+    }
+    set(openId, name) {
+        this.writeEntry(openId, name, undefined);
+    }
+    setWithKind(openId, name, kind) {
+        this.writeEntry(openId, name, kind);
+    }
+    lookupByName(name) {
+        const key = normalizeName(name);
+        const ids = this.openIdsByName.get(key);
+        if (!ids || ids.size === 0)
+            return [];
+        const matches = [];
+        for (const openId of ids) {
+            const entry = this.nameByOpenId.get(openId);
+            if (!entry)
+                continue;
+            if (entry.expireAt <= Date.now()) {
+                this.deleteOpenId(openId);
+                continue;
+            }
+            matches.push({ openId, name: entry.name, kind: entry.kind });
+        }
+        return matches;
+    }
+    setMany(entries) {
+        for (const [openId, name] of entries) {
+            this.writeEntryNoEvict(openId, name, undefined);
+        }
+        this.evict();
+    }
+    filterMissing(openIds) {
+        return openIds.filter((id) => !this.has(id));
+    }
+    getMany(openIds) {
+        const result = new Map();
+        for (const id of openIds) {
+            if (this.has(id)) {
+                result.set(id, this.get(id) ?? '');
+            }
+        }
+        return result;
+    }
+    recordChatBots(chatId, members) {
+        const enriched = members.map((m) => ({ ...m, kind: 'bot' }));
+        this.chatBots.delete(chatId);
+        this.chatBots.set(chatId, { members: enriched, expireAt: Date.now() + this.ttlMs });
+        this.evictChats(this.chatBots);
+        for (const m of enriched) {
+            if (m.openId)
+                this.writeEntryNoEvict(m.openId, m.name, 'bot');
+        }
+        this.evict();
+    }
+    recordChatMembers(chatId, members) {
+        const enriched = members.slice();
+        this.chatMembers.delete(chatId);
+        this.chatMembers.set(chatId, { members: enriched, expireAt: Date.now() + this.ttlMs });
+        this.evictChats(this.chatMembers);
+        for (const m of enriched) {
+            if (m.openId)
+                this.writeEntryNoEvict(m.openId, m.name, m.kind);
+        }
+        this.evict();
+    }
+    getChatBots(chatId) {
+        const entry = this.chatBots.get(chatId);
+        if (!entry)
+            return null;
+        if (entry.expireAt <= Date.now()) {
+            this.chatBots.delete(chatId);
+            return null;
+        }
+        return entry;
+    }
+    getChatMembers(chatId) {
+        const entry = this.chatMembers.get(chatId);
+        if (!entry)
+            return null;
+        if (entry.expireAt <= Date.now()) {
+            this.chatMembers.delete(chatId);
+            return null;
+        }
+        return entry;
+    }
+    getInflight(key) {
+        return this.inFlight.get(key);
+    }
+    setInflight(key, promise) {
+        this.inFlight.set(key, promise);
+    }
+    clearInflight(key) {
+        this.inFlight.delete(key);
+    }
+    clear() {
+        this.nameByOpenId.clear();
+        this.openIdsByName.clear();
+        this.chatBots.clear();
+        this.chatMembers.clear();
+        this.inFlight.clear();
+    }
+    // ----- private helpers -----
+    writeEntry(openId, name, kind) {
+        this.writeEntryNoEvict(openId, name, kind);
+        this.evict();
+    }
+    writeEntryNoEvict(openId, name, kind) {
+        // remove from old reverse bucket if name changed
+        const old = this.nameByOpenId.get(openId);
+        if (old) {
+            const oldKey = normalizeName(old.name);
+            const newKey = normalizeName(name);
+            if (oldKey !== newKey) {
+                this.removeFromReverse(oldKey, openId);
+            }
+        }
+        this.nameByOpenId.delete(openId);
+        this.nameByOpenId.set(openId, { name, kind, expireAt: Date.now() + this.ttlMs });
+        const key = normalizeName(name);
+        let bucket = this.openIdsByName.get(key);
+        if (!bucket) {
+            bucket = new Set();
+            this.openIdsByName.set(key, bucket);
+        }
+        bucket.add(openId);
+    }
+    deleteOpenId(openId) {
+        const entry = this.nameByOpenId.get(openId);
+        if (!entry)
+            return;
+        this.nameByOpenId.delete(openId);
+        this.removeFromReverse(normalizeName(entry.name), openId);
+    }
+    removeFromReverse(key, openId) {
+        const bucket = this.openIdsByName.get(key);
+        if (!bucket)
+            return;
+        bucket.delete(openId);
+        if (bucket.size === 0) {
+            this.openIdsByName.delete(key);
+        }
+    }
+    evictChats(map) {
+        while (map.size > this.maxChats) {
+            const oldest = map.keys().next().value;
+            if (oldest === undefined)
+                break;
+            map.delete(oldest);
+        }
+    }
+    evict() {
+        while (this.nameByOpenId.size > this.maxSize) {
+            const oldest = this.nameByOpenId.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.deleteOpenId(oldest);
+        }
+    }
+}
+exports.UserNameCache = UserNameCache;
+const registry = new Map();
+function getUserNameCache(accountId) {
+    let c = registry.get(accountId);
+    if (!c) {
+        c = new UserNameCache();
+        registry.set(accountId, c);
+    }
+    return c;
+}
+function clearUserNameCache(accountId) {
+    if (accountId !== undefined) {
+        registry.get(accountId)?.clear();
+        registry.delete(accountId);
+    }
+    else {
+        for (const c of registry.values())
+            c.clear();
+        registry.clear();
+    }
+}

package/src/messaging/inbound/user-name-cache.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Account-scoped LRU cache for Feishu user display names.
+ *
+ * Provides:
+ * - `UserNameCache` — per-account LRU Map with TTL
+ * - `getUserNameCache(accountId)` — singleton registry
+ * - `batchResolveUserNames()` — batch API via `contact/v3/users/batch`
+ * - `resolveUserName()` — single-user fallback via `contact.user.get`
+ * - `clearUserNameCache()` — teardown hook (called from LarkClient.clearCache)
+ */
+import type { LarkAccount } from '../../core/types';
+import { type PermissionError } from './permission';
+export { UserNameCache, clearUserNameCache, getUserNameCache } from './user-name-cache-store';
+/**
+ * Batch-resolve user display names.
+ *
+ * 1. Check cache → collect misses
+ * 2. Deduplicate
+ * 3. Call `GET /open-apis/contact/v3/users/batch` in chunks of 50
+ * 4. Write results back to cache
+ * 5. Return full Map<openId, name> (cache hits + API results)
+ *
+ * Best-effort: API errors are logged but never thrown.
+ */
+export declare function batchResolveUserNames(params: {
+    account: LarkAccount;
+    openIds: string[];
+    log: (...args: unknown[]) => void;
+}): Promise<Map<string, string>>;
+/**
+ * Create a `batchResolveNames` callback for use in `ConvertContext`.
+ *
+ * The returned function calls `batchResolveUserNames` with the given
+ * account and log function, populating the TAT user-name cache.
+ */
+export declare function createBatchResolveNames(account: LarkAccount, log: (...args: unknown[]) => void): (openIds: string[]) => Promise<void>;
+export interface ResolveUserNameResult {
+    name?: string;
+    permissionError?: PermissionError;
+}
+/**
+ * Resolve a single bot's display name via `/open-apis/bot/v3/bots/basic_batch`.
+ *
+ * Bots are not returned by the contact API, so they have their own endpoint.
+ * Names share the same account-scoped cache (keyed by openId) since both
+ * bots and users have `ou_` prefixed openIds and a single display name.
+ */
+export declare function resolveBotName(params: {
+    account: LarkAccount;
+    openId: string;
+    log: (...args: unknown[]) => void;
+}): Promise<ResolveUserNameResult>;
+/**
+ * Fetches the bot members of a chat via
+ * `GET /open-apis/im/v1/chats/{chat_id}/members/bots` and writes them
+ * to the per-account cache.
+ */
+export declare function prefetchChatBots(account: LarkAccount, chatId: string, log: (...args: unknown[]) => void): Promise<void>;
+/**
+ * Fetches the human members of a chat via
+ * `GET /open-apis/im/v1/chats/{chat_id}/members` and writes them to
+ * the per-account cache.
+ */
+export declare function prefetchChatMembers(account: LarkAccount, chatId: string, log: (...args: unknown[]) => void): Promise<void>;
+/**
+ * Resolve a single user's display name.
+ *
+ * Checks the account-scoped cache first, then falls back to the
+ * `contact.user.get` API (same as the old `resolveFeishuSenderName`).
+ */
+export declare function resolveUserName(params: {
+    account: LarkAccount;
+    openId: string;
+    log: (...args: unknown[]) => void;
+}): Promise<ResolveUserNameResult>;