@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/channel/chat-queue.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Process-level chat task queue.
+ *
+ * Although located in channel/, this module is intentionally shared
+ * across channel, messaging, tools, and card layers as a process-level
+ * singleton. Consumers: monitor.ts, dispatch.ts, oauth.ts, auto-auth.ts.
+ *
+ * Ensures tasks targeting the same account+chat are executed serially.
+ * Used by both websocket inbound messages and synthetic message paths.
+ */
+type QueueStatus = 'queued' | 'immediate';
+export interface ActiveDispatcherEntry {
+    abortCard: () => Promise<void>;
+    abortController?: AbortController;
+}
+/**
+ * Append `:thread:{threadId}` suffix when threadId is present.
+ * Consistent with the SDK's `:thread:` separator convention.
+ */
+export declare function threadScopedKey(base: string, threadId?: string): string;
+export declare function buildQueueKey(accountId: string, chatId: string, threadId?: string): string;
+export declare function registerActiveDispatcher(key: string, entry: ActiveDispatcherEntry): void;
+export declare function unregisterActiveDispatcher(key: string): void;
+export declare function getActiveDispatcher(key: string): ActiveDispatcherEntry | undefined;
+/** Check whether the queue has an active task for the given key. */
+export declare function hasActiveTask(key: string): boolean;
+export declare function enqueueFeishuChatTask(params: {
+    accountId: string;
+    chatId: string;
+    threadId?: string;
+    task: () => Promise<void>;
+}): {
+    status: QueueStatus;
+    promise: Promise<void>;
+};
+/** @internal Test-only: reset all queue and dispatcher state. */
+export declare function _resetChatQueueState(): void;
+export {};

package/src/channel/chat-queue.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Process-level chat task queue.
+ *
+ * Although located in channel/, this module is intentionally shared
+ * across channel, messaging, tools, and card layers as a process-level
+ * singleton. Consumers: monitor.ts, dispatch.ts, oauth.ts, auto-auth.ts.
+ *
+ * Ensures tasks targeting the same account+chat are executed serially.
+ * Used by both websocket inbound messages and synthetic message paths.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.threadScopedKey = threadScopedKey;
+exports.buildQueueKey = buildQueueKey;
+exports.registerActiveDispatcher = registerActiveDispatcher;
+exports.unregisterActiveDispatcher = unregisterActiveDispatcher;
+exports.getActiveDispatcher = getActiveDispatcher;
+exports.hasActiveTask = hasActiveTask;
+exports.enqueueFeishuChatTask = enqueueFeishuChatTask;
+exports._resetChatQueueState = _resetChatQueueState;
+const chatQueues = new Map();
+const activeDispatchers = new Map();
+/**
+ * Append `:thread:{threadId}` suffix when threadId is present.
+ * Consistent with the SDK's `:thread:` separator convention.
+ */
+function threadScopedKey(base, threadId) {
+    return threadId ? `${base}:thread:${threadId}` : base;
+}
+function buildQueueKey(accountId, chatId, threadId) {
+    return threadScopedKey(`${accountId}:${chatId}`, threadId);
+}
+function registerActiveDispatcher(key, entry) {
+    activeDispatchers.set(key, entry);
+}
+function unregisterActiveDispatcher(key) {
+    activeDispatchers.delete(key);
+}
+function getActiveDispatcher(key) {
+    return activeDispatchers.get(key);
+}
+/** Check whether the queue has an active task for the given key. */
+function hasActiveTask(key) {
+    return chatQueues.has(key);
+}
+function enqueueFeishuChatTask(params) {
+    const { accountId, chatId, threadId, task } = params;
+    const key = buildQueueKey(accountId, chatId, threadId);
+    const prev = chatQueues.get(key) ?? Promise.resolve();
+    const status = chatQueues.has(key) ? 'queued' : 'immediate';
+    const taskPromise = prev.then(task, task);
+    chatQueues.set(key, taskPromise);
+    const cleanup = () => {
+        if (chatQueues.get(key) === taskPromise) {
+            chatQueues.delete(key);
+        }
+    };
+    taskPromise.then(cleanup, cleanup);
+    return { status, promise: taskPromise };
+}
+/** @internal Test-only: reset all queue and dispatcher state. */
+function _resetChatQueueState() {
+    chatQueues.clear();
+    activeDispatchers.clear();
+}

package/src/channel/config-adapter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Configuration merge helpers for Feishu account management.
+ *
+ * Centralises the pattern of merging a partial configuration patch
+ * into the Feishu section of the top-level ClawdbotConfig, handling
+ * both the default account (top-level fields) and named accounts
+ * (nested under `accounts`).
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+/** Set the `enabled` flag on a Feishu account. */
+export declare function setAccountEnabled(cfg: ClawdbotConfig, accountId: string, enabled: boolean): ClawdbotConfig;
+/** Apply an arbitrary config patch to a Feishu account. */
+export declare function applyAccountConfig(cfg: ClawdbotConfig, accountId: string, patch: Record<string, unknown>): ClawdbotConfig;
+/** Delete a Feishu account entry from the config. */
+export declare function deleteAccount(cfg: ClawdbotConfig, accountId: string): ClawdbotConfig;
+/** Collect security warnings for a Feishu account. */
+export declare function collectFeishuSecurityWarnings(params: {
+    cfg: ClawdbotConfig;
+    accountId: string;
+}): string[];

package/src/channel/config-adapter.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Configuration merge helpers for Feishu account management.
+ *
+ * Centralises the pattern of merging a partial configuration patch
+ * into the Feishu section of the top-level ClawdbotConfig, handling
+ * both the default account (top-level fields) and named accounts
+ * (nested under `accounts`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setAccountEnabled = setAccountEnabled;
+exports.applyAccountConfig = applyAccountConfig;
+exports.deleteAccount = deleteAccount;
+exports.collectFeishuSecurityWarnings = collectFeishuSecurityWarnings;
+const account_id_1 = require("openclaw/plugin-sdk/account-id");
+const accounts_1 = require("../core/accounts.js");
+const security_check_1 = require("../core/security-check.js");
+/** Generic Feishu account config merge. */
+function mergeFeishuAccountConfig(cfg, accountId, patch) {
+    const isDefault = !accountId || accountId === account_id_1.DEFAULT_ACCOUNT_ID;
+    if (isDefault) {
+        return {
+            ...cfg,
+            channels: {
+                ...cfg.channels,
+                feishu: { ...cfg.channels?.feishu, ...patch },
+            },
+        };
+    }
+    const feishuCfg = cfg.channels?.feishu;
+    return {
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            feishu: {
+                ...feishuCfg,
+                accounts: {
+                    ...feishuCfg?.accounts,
+                    [accountId]: { ...feishuCfg?.accounts?.[accountId], ...patch },
+                },
+            },
+        },
+    };
+}
+/** Set the `enabled` flag on a Feishu account. */
+function setAccountEnabled(cfg, accountId, enabled) {
+    return mergeFeishuAccountConfig(cfg, accountId, { enabled });
+}
+/** Apply an arbitrary config patch to a Feishu account. */
+function applyAccountConfig(cfg, accountId, patch) {
+    return mergeFeishuAccountConfig(cfg, accountId, patch);
+}
+/** Delete a Feishu account entry from the config. */
+function deleteAccount(cfg, accountId) {
+    const isDefault = !accountId || accountId === account_id_1.DEFAULT_ACCOUNT_ID;
+    if (isDefault) {
+        // Delete entire feishu config
+        const next = { ...cfg };
+        const nextChannels = { ...cfg.channels };
+        delete nextChannels.feishu;
+        if (Object.keys(nextChannels).length > 0) {
+            next.channels = nextChannels;
+        }
+        else {
+            delete next.channels;
+        }
+        return next;
+    }
+    // Delete specific account from accounts
+    const feishuCfg = cfg.channels?.feishu;
+    const accounts = { ...feishuCfg?.accounts };
+    delete accounts[accountId];
+    return {
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            feishu: {
+                ...feishuCfg,
+                accounts: Object.keys(accounts).length > 0 ? accounts : undefined,
+            },
+        },
+    };
+}
+/** Collect security warnings for a Feishu account. */
+function collectFeishuSecurityWarnings(params) {
+    const { cfg, accountId } = params;
+    const warnings = [];
+    const account = (0, accounts_1.getLarkAccount)(cfg, accountId);
+    const feishuCfg = account.config;
+    // cfg.channels.defaults is a cross-channel defaults object (not formally typed)
+    const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
+    const groupPolicy = feishuCfg?.groupPolicy ?? defaultGroupPolicy ?? 'allowlist';
+    if (groupPolicy === 'open') {
+        warnings.push(`- Feishu[${account.accountId}] groups: groupPolicy="open" allows any group to interact (mention-gated). To restrict which groups are allowed, set groupPolicy="allowlist" and list group IDs in channels.feishu.groups. To restrict which senders can trigger the bot, set channels.feishu.groupAllowFrom with user open_ids (ou_xxx).`);
+    }
+    // Multi-account cross-tenant isolation check (only on first account to avoid duplicates)
+    const allIds = (0, accounts_1.getLarkAccountIds)(cfg);
+    if (allIds.length === 0 || accountId === allIds[0]) {
+        for (const w of (0, security_check_1.collectIsolationWarnings)(cfg)) {
+            warnings.push(w);
+        }
+    }
+    return warnings;
+}

package/src/channel/directory.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Directory listing for Feishu peers (users) and groups.
+ *
+ * Provides both config-based (offline) and live API directory
+ * lookups so the outbound subsystem and UI can resolve targets.
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+import type { FeishuDirectoryGroup, FeishuDirectoryPeer } from './types';
+export type { FeishuDirectoryPeer, FeishuDirectoryGroup } from './types';
+/**
+ * List users known from the channel config (allowFrom + dms fields).
+ *
+ * Does not make any API calls -- useful when the bot is not yet
+ * connected or when credentials are unavailable.
+ */
+export declare function listFeishuDirectoryPeers(params: {
+    cfg: ClawdbotConfig;
+    query?: string;
+    limit?: number;
+    accountId?: string;
+}): Promise<FeishuDirectoryPeer[]>;
+/**
+ * List groups known from the channel config (groups + groupAllowFrom).
+ */
+export declare function listFeishuDirectoryGroups(params: {
+    cfg: ClawdbotConfig;
+    query?: string;
+    limit?: number;
+    accountId?: string;
+}): Promise<FeishuDirectoryGroup[]>;
+/**
+ * List users via the Feishu contact/v3/users API.
+ *
+ * Falls back to config-based listing when credentials are missing or
+ * the API call fails.
+ */
+export declare function listFeishuDirectoryPeersLive(params: {
+    cfg: ClawdbotConfig;
+    query?: string;
+    limit?: number;
+    accountId?: string;
+}): Promise<FeishuDirectoryPeer[]>;
+/**
+ * List groups via the Feishu im/v1/chats API.
+ *
+ * Falls back to config-based listing when credentials are missing or
+ * the API call fails.
+ */
+export declare function listFeishuDirectoryGroupsLive(params: {
+    cfg: ClawdbotConfig;
+    query?: string;
+    limit?: number;
+    accountId?: string;
+}): Promise<FeishuDirectoryGroup[]>;

package/src/channel/directory.js

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Directory listing for Feishu peers (users) and groups.
+ *
+ * Provides both config-based (offline) and live API directory
+ * lookups so the outbound subsystem and UI can resolve targets.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listFeishuDirectoryPeers = listFeishuDirectoryPeers;
+exports.listFeishuDirectoryGroups = listFeishuDirectoryGroups;
+exports.listFeishuDirectoryPeersLive = listFeishuDirectoryPeersLive;
+exports.listFeishuDirectoryGroupsLive = listFeishuDirectoryGroupsLive;
+const accounts_1 = require("../core/accounts.js");
+const lark_client_1 = require("../core/lark-client.js");
+const targets_1 = require("../core/targets.js");
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+/** Case-insensitive substring match on id and optional name. */
+function matchesQuery(id, name, query) {
+    if (!query)
+        return true;
+    return id.toLowerCase().includes(query) || (name?.toLowerCase().includes(query) ?? false);
+}
+/** Filter items and apply optional limit. */
+function applyLimitSlice(items, limit) {
+    return limit && limit > 0 ? items.slice(0, limit) : items;
+}
+// ---------------------------------------------------------------------------
+// Config-based (offline) directory
+// ---------------------------------------------------------------------------
+/**
+ * List users known from the channel config (allowFrom + dms fields).
+ *
+ * Does not make any API calls -- useful when the bot is not yet
+ * connected or when credentials are unavailable.
+ */
+async function listFeishuDirectoryPeers(params) {
+    const account = (0, accounts_1.getLarkAccount)(params.cfg, params.accountId);
+    const feishuCfg = account.config;
+    const q = params.query?.trim().toLowerCase() || '';
+    const ids = new Set();
+    // Collect from allowFrom entries.
+    for (const entry of feishuCfg?.allowFrom ?? []) {
+        const trimmed = String(entry).trim();
+        if (trimmed && trimmed !== '*') {
+            ids.add(trimmed);
+        }
+    }
+    // Collect from per-user DM config keys.
+    for (const userId of Object.keys(feishuCfg?.dms ?? {})) {
+        const trimmed = userId.trim();
+        if (trimmed) {
+            ids.add(trimmed);
+        }
+    }
+    const peers = Array.from(ids)
+        .map((raw) => raw.trim())
+        .filter(Boolean)
+        .map((raw) => (0, targets_1.normalizeFeishuTarget)(raw) ?? raw)
+        .filter((id) => matchesQuery(id, undefined, q))
+        .map((id) => ({ kind: 'user', id }));
+    return applyLimitSlice(peers, params.limit);
+}
+/**
+ * List groups known from the channel config (groups + groupAllowFrom).
+ */
+async function listFeishuDirectoryGroups(params) {
+    const account = (0, accounts_1.getLarkAccount)(params.cfg, params.accountId);
+    const feishuCfg = account.config;
+    const q = params.query?.trim().toLowerCase() || '';
+    const ids = new Set();
+    // Collect from per-group config keys.
+    for (const groupId of Object.keys(feishuCfg?.groups ?? {})) {
+        const trimmed = groupId.trim();
+        if (trimmed && trimmed !== '*') {
+            ids.add(trimmed);
+        }
+    }
+    // Collect from groupAllowFrom entries.
+    for (const entry of feishuCfg?.groupAllowFrom ?? []) {
+        const trimmed = String(entry).trim();
+        if (trimmed && trimmed !== '*') {
+            ids.add(trimmed);
+        }
+    }
+    const groups = Array.from(ids)
+        .map((raw) => raw.trim())
+        .filter(Boolean)
+        .filter((id) => matchesQuery(id, undefined, q))
+        .map((id) => ({ kind: 'group', id }));
+    return applyLimitSlice(groups, params.limit);
+}
+// ---------------------------------------------------------------------------
+// Live API directory
+// ---------------------------------------------------------------------------
+/**
+ * List users via the Feishu contact/v3/users API.
+ *
+ * Falls back to config-based listing when credentials are missing or
+ * the API call fails.
+ */
+async function listFeishuDirectoryPeersLive(params) {
+    const account = (0, accounts_1.getLarkAccount)(params.cfg, params.accountId);
+    if (!account.configured) {
+        return listFeishuDirectoryPeers(params);
+    }
+    try {
+        const client = lark_client_1.LarkClient.fromAccount(account).sdk;
+        const peers = [];
+        const limit = params.limit ?? 50;
+        if (limit <= 0)
+            return [];
+        const q = params.query?.trim().toLowerCase() || '';
+        let pageToken;
+        do {
+            const remaining = limit - peers.length;
+            const response = await client.contact.user.list({
+                params: {
+                    page_size: Math.min(remaining, 50),
+                    page_token: pageToken,
+                },
+            });
+            if (response.code !== 0 || !response.data?.items)
+                break;
+            for (const user of response.data.items) {
+                if (user.open_id && matchesQuery(user.open_id, user.name, q)) {
+                    peers.push({
+                        kind: 'user',
+                        id: user.open_id,
+                        name: user.name || undefined,
+                    });
+                }
+                if (peers.length >= limit)
+                    break;
+            }
+            pageToken = response.data?.page_token;
+        } while (pageToken && peers.length < limit);
+        return peers;
+    }
+    catch {
+        // Fallback to config-based listing on API failure.
+        return listFeishuDirectoryPeers(params);
+    }
+}
+/**
+ * List groups via the Feishu im/v1/chats API.
+ *
+ * Falls back to config-based listing when credentials are missing or
+ * the API call fails.
+ */
+async function listFeishuDirectoryGroupsLive(params) {
+    const account = (0, accounts_1.getLarkAccount)(params.cfg, params.accountId);
+    if (!account.configured) {
+        return listFeishuDirectoryGroups(params);
+    }
+    try {
+        const client = lark_client_1.LarkClient.fromAccount(account).sdk;
+        const groups = [];
+        const limit = params.limit ?? 50;
+        if (limit <= 0)
+            return [];
+        const q = params.query?.trim().toLowerCase() || '';
+        let pageToken;
+        do {
+            const remaining = limit - groups.length;
+            const response = await client.im.chat.list({
+                params: {
+                    page_size: Math.min(remaining, 100),
+                    page_token: pageToken,
+                },
+            });
+            if (response.code !== 0 || !response.data?.items)
+                break;
+            for (const chat of response.data.items) {
+                if (chat.chat_id && matchesQuery(chat.chat_id, chat.name, q)) {
+                    groups.push({
+                        kind: 'group',
+                        id: chat.chat_id,
+                        name: chat.name || undefined,
+                    });
+                }
+                if (groups.length >= limit)
+                    break;
+            }
+            pageToken = response.data?.page_token;
+        } while (pageToken && groups.length < limit);
+        return groups;
+    }
+    catch {
+        // Fallback to config-based listing on API failure.
+        return listFeishuDirectoryGroups(params);
+    }
+}

package/src/channel/event-handlers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Event handlers for the Feishu WebSocket monitor.
+ *
+ * Extracted from monitor.ts to improve testability and reduce
+ * function size. Each handler receives a MonitorContext with all
+ * dependencies needed to process the event.
+ */
+import type { MonitorContext } from './types';
+export declare function handleMessageEvent(ctx: MonitorContext, data: unknown): Promise<void>;
+export declare function handleReactionEvent(ctx: MonitorContext, data: unknown): Promise<void>;
+export declare function handleBotMembershipEvent(ctx: MonitorContext, data: unknown, action: 'added' | 'removed'): Promise<void>;
+export declare function handleVcMeetingInvitedEvent(ctx: MonitorContext, data: unknown): Promise<void>;
+export declare function handleCommentEvent(ctx: MonitorContext, data: unknown): Promise<void>;
+export declare function handleCardActionEvent(ctx: MonitorContext, data: unknown): Promise<unknown>;