@colinlu50/openclaw-lark-stream 2026.3.17

package/src/messaging/shared/message-lookup.js

@@ -0,0 +1,117 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Message fetching for the Lark/Feishu channel plugin.
+ *
+ * Shared between inbound (reaction handler, enrich) and outbound modules.
+ * Extracted from `outbound/fetch.ts` to eliminate inbound→outbound
+ * dependency inversion.
+ */
+import { convertMessageContent, buildConvertContextFromItem } from '../converters/content-converter';
+import { LarkClient } from '../../core/lark-client';
+import { larkLogger } from '../../core/lark-logger';
+const log = larkLogger('shared/message-lookup');
+import { getUserNameCache, createBatchResolveNames } from '../inbound/user-name-cache';
+import { getLarkAccount } from '../../core/accounts';
+// ---------------------------------------------------------------------------
+// getMessageFeishu
+// ---------------------------------------------------------------------------
+/**
+ * Retrieve a single message by its ID from the Feishu IM API.
+ *
+ * Returns a normalised {@link FeishuMessageInfo} object, or `null` if the
+ * message cannot be found or the API returns an error.
+ *
+ * @param params.cfg       - Plugin configuration with Feishu credentials.
+ * @param params.messageId - The message ID to fetch.
+ * @param params.accountId - Optional account identifier for multi-account setups.
+ */
+export async function getMessageFeishu(params) {
+    const { cfg, messageId, accountId, expandForward } = params;
+    const larkClient = LarkClient.fromCfg(cfg, accountId);
+    const sdk = larkClient.sdk;
+    try {
+        const requestOpts = {
+            method: 'GET',
+            url: `/open-apis/im/v1/messages/mget`,
+            params: {
+                message_ids: messageId,
+                user_id_type: 'open_id',
+                card_msg_content_type: 'raw_card_content',
+            },
+        };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const response = await sdk.request(requestOpts);
+        const items = response?.data?.items;
+        if (!items || items.length === 0) {
+            log.info(`getMessageFeishu: no items returned for ${messageId}`);
+            return null;
+        }
+        const expandCtx = expandForward
+            ? {
+                cfg,
+                accountId,
+                fetchSubMessages: async (msgId) => {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const res = 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 (res?.code !== 0) {
+                        throw new Error(`API error: code=${res?.code} msg=${res?.msg}`);
+                    }
+                    return res?.data?.items ?? [];
+                },
+                batchResolveNames: createBatchResolveNames(getLarkAccount(cfg, accountId), (...args) => log.info(args.map(String).join(' '))),
+            }
+            : undefined;
+        return await parseMessageItem(items[0], messageId, expandCtx);
+    }
+    catch (error) {
+        log.error(`get message failed (${messageId}): ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Parse a single message item from the Feishu IM API response into a
+ * normalised {@link FeishuMessageInfo}.
+ *
+ * Content parsing is delegated to the shared converter system so that
+ * every message-type mapping is defined in exactly one place.
+ */
+async function parseMessageItem(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+msg, fallbackMessageId, expandCtx) {
+    const msgType = msg.msg_type ?? 'text';
+    const rawContent = msg.body?.content ?? '{}';
+    const messageId = msg.message_id ?? fallbackMessageId;
+    const acctId = expandCtx?.accountId;
+    const ctx = {
+        ...buildConvertContextFromItem(msg, fallbackMessageId, acctId),
+        cfg: expandCtx?.cfg,
+        accountId: acctId,
+        fetchSubMessages: expandCtx?.fetchSubMessages,
+        batchResolveNames: expandCtx?.batchResolveNames,
+    };
+    const { content } = await convertMessageContent(rawContent, msgType, ctx);
+    const senderId = msg.sender?.id ?? undefined;
+    const senderType = msg.sender?.sender_type ?? undefined;
+    const senderName = senderId && acctId ? getUserNameCache(acctId).get(senderId) : undefined;
+    return {
+        messageId,
+        chatId: msg.chat_id ?? '',
+        chatType: msg.chat_type ?? undefined,
+        senderId,
+        senderName,
+        senderType,
+        content,
+        contentType: msgType,
+        createTime: msg.create_time ? parseInt(String(msg.create_time), 10) : undefined,
+        threadId: msg.thread_id || undefined,
+    };
+}

package/src/messaging/types.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Messaging type definitions for the Lark/Feishu channel plugin.
+ *
+ * Pure shape types for inbound message events, normalised message context,
+ * mention targets, and media metadata.
+ */
+export interface FeishuMessageEvent {
+    sender: {
+        sender_id: {
+            open_id?: string;
+            user_id?: string;
+            union_id?: string;
+        };
+        sender_type?: string;
+        tenant_key?: string;
+    };
+    message: {
+        message_id: string;
+        root_id?: string;
+        parent_id?: string;
+        create_time?: string;
+        update_time?: string;
+        chat_id: string;
+        thread_id?: string;
+        chat_type: 'p2p' | 'group';
+        message_type: string;
+        content: string;
+        mentions?: Array<{
+            key: string;
+            id: {
+                open_id?: string;
+                user_id?: string;
+                union_id?: string;
+            };
+            name: string;
+            tenant_key?: string;
+        }>;
+        user_agent?: string;
+    };
+}
+export interface FeishuReactionCreatedEvent {
+    message_id: string;
+    chat_id?: string;
+    chat_type?: 'p2p' | 'group' | 'private';
+    reaction_type?: {
+        emoji_type?: string;
+    };
+    operator_type?: string;
+    user_id?: {
+        open_id?: string;
+        user_id?: string;
+        union_id?: string;
+    };
+    action_time?: string;
+}
+export interface FeishuBotAddedEvent {
+    chat_id: string;
+    operator_id: {
+        open_id?: string;
+        user_id?: string;
+        union_id?: string;
+    };
+    external: boolean;
+    operator_tenant_key?: string;
+    name?: string;
+    i18n_names?: {
+        zh_cn?: string;
+        en_us?: string;
+        ja_jp?: string;
+    };
+}
+/** Metadata describing a media resource in a message (no binary data). */
+export interface ResourceDescriptor {
+    type: 'image' | 'file' | 'audio' | 'video' | 'sticker';
+    /** image_key or file_key from the raw message content. */
+    fileKey: string;
+    /** Original file name (file/video messages). */
+    fileName?: string;
+    /** Duration in milliseconds (audio/video messages). */
+    duration?: number;
+    /** Video cover image key. */
+    coverImageKey?: string;
+}
+/** Structured @mention information from a message. */
+export interface MentionInfo {
+    /** Placeholder key in raw content (e.g. "@_user_1"). */
+    key: string;
+    /** Feishu Open ID of the mentioned user. */
+    openId: string;
+    /** Display name. */
+    name: string;
+    /** Whether this mention targets the bot itself. */
+    isBot: boolean;
+}
+/** Raw message body, directly mapped from FeishuMessageEvent.message. */
+export interface RawMessage {
+    message_id: string;
+    root_id?: string;
+    parent_id?: string;
+    create_time?: string;
+    update_time?: string;
+    chat_id: string;
+    thread_id?: string;
+    chat_type: 'p2p' | 'group';
+    message_type: string;
+    content: string;
+    mentions?: Array<{
+        key: string;
+        id: {
+            open_id?: string;
+            user_id?: string;
+            union_id?: string;
+        };
+        name: string;
+        tenant_key?: string;
+    }>;
+    user_agent?: string;
+}
+/** Raw sender data, directly mapped from FeishuMessageEvent.sender. */
+export interface RawSender {
+    sender_id: {
+        open_id?: string;
+        user_id?: string;
+        union_id?: string;
+    };
+    sender_type?: string;
+    tenant_key?: string;
+}
+/** Normalised representation of an inbound Feishu message. */
+export interface MessageContext {
+    chatId: string;
+    messageId: string;
+    senderId: string;
+    senderName?: string;
+    chatType: 'p2p' | 'group';
+    content: string;
+    contentType: string;
+    /** Media resource descriptors extracted during parsing. */
+    resources: ResourceDescriptor[];
+    /** All @mentions in the message (including bot). */
+    mentions: MentionInfo[];
+    rootId?: string;
+    parentId?: string;
+    threadId?: string;
+    createTime?: number;
+    rawMessage: RawMessage;
+    rawSender: RawSender;
+}
+/** @deprecated Use {@link MessageContext} instead. */
+export type FeishuMessageContext = MessageContext;
+/** Metadata about a media attachment received in or sent through Feishu. */
+export interface FeishuMediaInfo {
+    path: string;
+    contentType?: string;
+    placeholder: string;
+    /** Original Feishu file_key / image_key that was downloaded. */
+    fileKey: string;
+    /** Resource type from the original descriptor. */
+    resourceType: ResourceDescriptor['type'];
+}
+/** Result of sending a message via the Feishu API. */
+export interface FeishuSendResult {
+    messageId: string;
+    chatId: string;
+    /**
+     * Human-readable warning when the send succeeded but with degradation
+     * (e.g. media upload failed, fell back to a text link).
+     *
+     * Populated so upstream callers (and the AI) can detect that the
+     * delivery was not fully as intended and take corrective action.
+     */
+    warning?: string;
+}

package/src/messaging/types.js

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Messaging type definitions for the Lark/Feishu channel plugin.
+ *
+ * Pure shape types for inbound message events, normalised message context,
+ * mention targets, and media metadata.
+ */
+export {};

package/src/tools/auto-auth.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * auto-auth.ts — 工具层自动授权处理。
+ *
+ * 当 OAPI 工具遇到授权问题时，直接在工具层处理，不再让 AI 判断：
+ *
+ * - UserAuthRequiredError (appScopeVerified=true)
+ *   → 直接调用 executeAuthorize 发起 OAuth Device Flow 卡片
+ *
+ * - UserScopeInsufficientError
+ *   → 直接调用 executeAuthorize（使用 missingScopes）
+ *
+ * - AppScopeMissingError
+ *   → 发送应用权限引导卡片；用户点击"我已完成"后：
+ *     1. 更新卡片为处理中状态
+ *     2. invalidateAppScopeCache
+ *     3. 发送中间合成消息告知 AI（"应用权限已确认，正在发起用户授权..."）
+ *     4. 调用 executeAuthorize 发起 OAuth Device Flow
+ *
+ * - 其他情况（AppScopeCheckFailedError、appScopeVerified=false 等）
+ *   → 回退到原 handleInvokeError（不触发自动授权）
+ *
+ * 降级策略（保守）：以下情况均回退到 handleInvokeError：
+ * - 无 LarkTicket（非消息场景）
+ * - 无 senderOpenId（无法确定授权对象）
+ * - 账号未配置（!acct.configured）
+ * - 任何步骤抛出异常
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+/**
+ * 处理 card.action.trigger 回调事件（由 monitor.ts 调用）。
+ *
+ * 当用户点击应用权限引导卡片的"我已完成，继续授权"按钮时：
+ * 1. 更新卡片为"处理中"状态
+ * 2. 清除应用 scope 缓存
+ * 3. 发送中间合成消息告知 AI
+ * 4. 发起 OAuth Device Flow
+ *
+ * 注意：函数体内的主要逻辑通过 setImmediate + fire-and-forget 异步执行，
+ * 确保 Feishu card.action.trigger 回调在 3 秒内返回。
+ */
+export declare function handleCardAction(data: unknown, cfg: ClawdbotConfig, accountId: string): Promise<unknown>;
+/**
+ * 统一处理 `client.invoke()` 抛出的错误，支持自动发起 OAuth 授权。
+ *
+ * 替代 `handleInvokeError`，在工具层直接处理授权问题：
+ * - 用户授权类错误 → 直接 executeAuthorize（发 Device Flow 卡片）
+ * - 应用权限缺失 → 发送引导卡片，用户确认后自动接力 OAuth
+ * - 其他错误 → 回退到 handleInvokeError 的标准处理
+ *
+ * @param err - invoke() 或其他逻辑抛出的错误
+ * @param cfg - OpenClaw 配置对象（从工具注册函数的闭包中获取）
+ */
+export declare function handleInvokeErrorWithAutoAuth(err: unknown, cfg: ClawdbotConfig): Promise<import("./helpers").ToolResult>;