@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/tools/onboarding-auth.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Onboarding 预授权模块。
+ *
+ * 配对后自动发起 OAuth Device Flow，引导应用 owner 完成用户授权。
+ * 仅当配对用户 === 应用 owner 时触发。
+ *
+ * 飞书限制：单次 OAuth 最多 50 个 scope。
+ * 超过 50 个时自动分批处理，每批授权完成后自动发起下一批（链式触发）。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.triggerOnboarding = triggerOnboarding;
+const accounts_1 = require("../core/accounts.js");
+const lark_client_1 = require("../core/lark-client.js");
+const app_scope_checker_1 = require("../core/app-scope-checker.js");
+const app_owner_fallback_1 = require("../core/app-owner-fallback.js");
+const lark_logger_1 = require("../core/lark-logger.js");
+const tool_scopes_1 = require("../core/tool-scopes.js");
+const oauth_1 = require("./oauth.js");
+const log = (0, lark_logger_1.larkLogger)('tools/onboarding-auth');
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const MAX_SCOPES_PER_BATCH = 100;
+// ---------------------------------------------------------------------------
+// Trigger onboarding
+// ---------------------------------------------------------------------------
+/**
+ * 配对后触发 onboarding OAuth 授权。
+ *
+ * 流程：
+ *   1. 检查 userOpenId === 应用 owner，不匹配则静默跳过
+ *   2. 读取 onboarding-scopes.json 中的 user scope 列表
+ *   3. 分批处理（每批最多 50 个），第一批直接发起 OAuth Device Flow
+ *   4. 每批授权完成后通过 onAuthComplete 回调自动发起下一批
+ */
+async function triggerOnboarding(params) {
+    const { cfg, userOpenId, accountId } = params;
+    const acct = (0, accounts_1.getLarkAccount)(cfg, accountId);
+    if (!acct.configured) {
+        log.warn(`account ${accountId} not configured, skipping`);
+        return;
+    }
+    const sdk = lark_client_1.LarkClient.fromAccount(acct).sdk;
+    const { appId } = acct;
+    // 1. 检查 userOpenId === 应用 owner（统一走 getAppOwnerFallback）
+    const ownerOpenId = await (0, app_owner_fallback_1.getAppOwnerFallback)(acct, sdk);
+    if (!ownerOpenId) {
+        log.info(`app ${appId} has no owner info, skipping`);
+        return;
+    }
+    if (userOpenId !== ownerOpenId) {
+        log.info(`user ${userOpenId} is not app owner (${ownerOpenId}), skipping`);
+        return;
+    }
+    log.info(`user ${userOpenId} is app owner, starting OAuth`);
+    // 3. 动态获取应用已开通的 user scope 列表
+    let allUserScopes;
+    try {
+        allUserScopes = await (0, app_scope_checker_1.getAppGrantedScopes)(sdk, appId, 'user');
+    }
+    catch (err) {
+        log.warn(`failed to get app granted scopes: ${err}`);
+        return;
+    }
+    // 过滤掉敏感 scope
+    allUserScopes = (0, tool_scopes_1.filterSensitiveScopes)(allUserScopes);
+    if (allUserScopes.length === 0) {
+        log.info('no user scopes configured, skipping');
+        return;
+    }
+    // 4. 分批
+    const batches = [];
+    for (let i = 0; i < allUserScopes.length; i += MAX_SCOPES_PER_BATCH) {
+        batches.push(allUserScopes.slice(i, i + MAX_SCOPES_PER_BATCH));
+    }
+    log.info(`${allUserScopes.length} user scopes, ${batches.length} batch(es)`);
+    // 5. 链式发起授权（第一批同步发起，后续批次由 onAuthComplete 回调触发）
+    const startBatch = async (batchIndex) => {
+        if (batchIndex >= batches.length) {
+            log.info('all batches completed');
+            return;
+        }
+        const batch = batches[batchIndex];
+        const scope = batch.join(' ');
+        let batchInfo = '';
+        if (batches.length > 1) {
+            batchInfo =
+                `\n\n📋 授权进度：第 ${batchIndex + 1}/${batches.length} 批` +
+                    `（本批 ${batch.length} 个权限，共 ${allUserScopes.length} 个）`;
+            if (batchIndex < batches.length - 1) {
+                batchInfo += `\n授权完成后将自动发起下一批。`;
+            }
+            else {
+                batchInfo += `\n这是最后一批，授权完成后即可使用所有功能。`;
+            }
+        }
+        const ticket = {
+            messageId: `onboarding:${Date.now()}`,
+            chatId: userOpenId,
+            accountId,
+            startTime: Date.now(),
+            senderOpenId: userOpenId,
+            chatType: 'p2p',
+        };
+        log.info(`starting batch ${batchIndex + 1}/${batches.length}, scopes=${batch.length}`);
+        try {
+            await (0, oauth_1.executeAuthorize)({
+                account: acct,
+                senderOpenId: userOpenId,
+                scope,
+                isBatchAuth: true,
+                totalAppScopes: allUserScopes.length,
+                alreadyGranted: batchIndex * MAX_SCOPES_PER_BATCH,
+                batchInfo,
+                skipSyntheticMessage: true,
+                cfg,
+                ticket,
+                onAuthComplete: async () => {
+                    log.info(`batch ${batchIndex + 1}/${batches.length} auth completed`);
+                    await startBatch(batchIndex + 1);
+                },
+            });
+        }
+        catch (err) {
+            log.error(`batch ${batchIndex + 1} failed: ${err}`);
+        }
+    };
+    await startBatch(0);
+}

package/src/tools/tat/im/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * IM 工具集
+ * 统一导出所有即时通讯相关工具的注册函数
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+/**
+ * 注册所有 IM 工具
+ *
+ * Note: feishu_im_message_reaction 和 feishu_im_message_recall 已移除，
+ * 其功能由 ChannelMessageActionAdapter (actions.ts) 的 react/delete action 统一覆盖。
+ */
+export declare function registerFeishuImTools(api: OpenClawPluginApi): void;

package/src/tools/tat/im/index.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * IM 工具集
+ * 统一导出所有即时通讯相关工具的注册函数
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFeishuImTools = registerFeishuImTools;
+const resource_1 = require("./resource.js");
+/**
+ * 注册所有 IM 工具
+ *
+ * Note: feishu_im_message_reaction 和 feishu_im_message_recall 已移除，
+ * 其功能由 ChannelMessageActionAdapter (actions.ts) 的 react/delete action 统一覆盖。
+ */
+function registerFeishuImTools(api) {
+    if ((0, resource_1.registerFeishuImBotImageTool)(api)) {
+        api.logger.debug?.('feishu_im: Registered feishu_im_bot_image');
+    }
+}

package/src/tools/tat/im/resource.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_im_bot_image 工具
+ *
+ * 以机器人身份下载飞书 IM 消息中的图片/文件资源到本地。
+ *
+ * 飞书 API:
+ *   - 下载资源: GET  /open-apis/im/v1/messages/:message_id/resources/:file_key
+ * 权限: im:resource
+ * 凭证: tenant_access_token
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+export declare function registerFeishuImBotImageTool(api: OpenClawPluginApi): boolean;

package/src/tools/tat/im/resource.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_im_bot_image 工具
+ *
+ * 以机器人身份下载飞书 IM 消息中的图片/文件资源到本地。
+ *
+ * 飞书 API:
+ *   - 下载资源: GET  /open-apis/im/v1/messages/:message_id/resources/:file_key
+ * 权限: im:resource
+ * 凭证: tenant_access_token
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFeishuImBotImageTool = registerFeishuImBotImageTool;
+const fsPromises = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const temp_path_1 = require("openclaw/plugin-sdk/temp-path");
+const typebox_1 = require("@sinclair/typebox");
+const helpers_1 = require("../../oapi/helpers.js");
+// ===========================================================================
+// Shared constants
+// ===========================================================================
+/** MIME type → 文件扩展名（下载时使用） */
+const MIME_TO_EXT = {
+    'image/png': '.png',
+    'image/jpeg': '.jpg',
+    'image/jpg': '.jpg',
+    'image/gif': '.gif',
+    'image/webp': '.webp',
+    'image/svg+xml': '.svg',
+    'image/bmp': '.bmp',
+    'image/tiff': '.tiff',
+    'video/mp4': '.mp4',
+    'video/mpeg': '.mpeg',
+    'video/quicktime': '.mov',
+    'video/x-msvideo': '.avi',
+    'video/webm': '.webm',
+    'audio/mpeg': '.mp3',
+    'audio/wav': '.wav',
+    'audio/ogg': '.ogg',
+    'audio/mp4': '.m4a',
+    'application/pdf': '.pdf',
+    'application/msword': '.doc',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document': '.docx',
+    'application/vnd.ms-excel': '.xls',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': '.xlsx',
+    'application/vnd.ms-powerpoint': '.ppt',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation': '.pptx',
+    'application/zip': '.zip',
+    'application/x-rar-compressed': '.rar',
+    'text/plain': '.txt',
+    'application/json': '.json',
+};
+// ===========================================================================
+// Shared helpers
+// ===========================================================================
+/**
+ * 从二进制响应中提取 Buffer、Content-Type。
+ * SDK 的二进制响应可能有 getReadableStream()，也可能直接是 Buffer 等格式。
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function extractBuffer(res) {
+    let chunks;
+    if (typeof res.getReadableStream === 'function') {
+        const stream = res.getReadableStream();
+        chunks = [];
+        for await (const chunk of stream) {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+    }
+    else if (Buffer.isBuffer(res)) {
+        chunks = [res];
+    }
+    else if (Buffer.isBuffer(res?.data)) {
+        chunks = [res.data];
+    }
+    else {
+        throw new Error('无法从响应中提取二进制数据');
+    }
+    const buffer = Buffer.concat(chunks);
+    const contentType = res.headers?.['content-type'] ?? '';
+    return { buffer, contentType };
+}
+/**
+ * 将 buffer 保存到临时文件，返回路径。
+ */
+async function saveToTempFile(buffer, contentType, prefix) {
+    const mimeType = contentType ? contentType.split(';')[0].trim() : '';
+    const mimeExt = mimeType ? MIME_TO_EXT[mimeType] : undefined;
+    const filePath = (0, temp_path_1.buildRandomTempFilePath)({
+        prefix,
+        extension: mimeExt,
+    });
+    await fsPromises.mkdir(path.dirname(filePath), { recursive: true });
+    await fsPromises.writeFile(filePath, buffer);
+    return filePath;
+}
+// ===========================================================================
+// Download tool — feishu_im_bot_image
+// ===========================================================================
+const FeishuImBotImageSchema = typebox_1.Type.Object({
+    message_id: typebox_1.Type.String({
+        description: '消息 ID（om_xxx 格式），引用消息可从上下文中的 [message_id=om_xxx] 提取',
+    }),
+    file_key: typebox_1.Type.String({
+        description: '资源 Key，图片消息的 image_key（img_xxx）或文件消息的 file_key（file_xxx）',
+    }),
+    type: (0, helpers_1.StringEnum)(['image', 'file'], {
+        description: '资源类型：image（图片消息中的图片）、file（文件/音频/视频消息中的文件）',
+    }),
+});
+function registerFeishuImBotImageTool(api) {
+    if (!api.config)
+        return false;
+    const { getClient, log } = (0, helpers_1.createToolContext)(api, 'feishu_im_bot_image');
+    return (0, helpers_1.registerTool)(api, {
+        name: 'feishu_im_bot_image',
+        label: 'Feishu: IM Bot Image Download',
+        description: '【以机器人身份】下载飞书 IM 消息中的图片或文件资源到本地。' +
+            '\n\n适用场景：用户直接发送给机器人的消息、用户引用的消息、机器人收到的群聊消息中的图片/文件。' +
+            '即当前对话上下文中出现的 message_id 和 image_key/file_key，应使用本工具下载。' +
+            '\n引用消息的 message_id 可从上下文中的 [message_id=om_xxx] 提取，无需向用户询问。' +
+            '\n\n文件自动保存到 /tmp/openclaw/ 下，返回值中的 saved_path 为实际保存路径。',
+        parameters: FeishuImBotImageSchema,
+        async execute(_toolCallId, params) {
+            const p = params;
+            try {
+                const client = getClient();
+                log.info(`download: message_id="${p.message_id}", file_key="${p.file_key}", type="${p.type}"`);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const res = await client.im.messageResource.get({
+                    path: {
+                        message_id: p.message_id,
+                        file_key: p.file_key,
+                    },
+                    params: { type: p.type },
+                });
+                const { buffer, contentType } = await extractBuffer(res);
+                log.info(`download: ${buffer.length} bytes, content-type=${contentType}`);
+                const savedPath = await saveToTempFile(buffer, contentType, 'bot-resource');
+                log.info(`download: saved to ${savedPath}`);
+                return (0, helpers_1.json)({
+                    message_id: p.message_id,
+                    file_key: p.file_key,
+                    type: p.type,
+                    size_bytes: buffer.length,
+                    content_type: contentType,
+                    saved_path: savedPath,
+                });
+            }
+            catch (err) {
+                log.error(`Error: ${(0, helpers_1.formatLarkError)(err)}`);
+                return (0, helpers_1.json)({ error: (0, helpers_1.formatLarkError)(err) });
+            }
+        },
+    }, { name: 'feishu_im_bot_image' });
+}

package/tsdown.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("tsdown/types-D2Jnze_i").d;
+export default _default;

package/tsdown.config.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tsdown_1 = require("tsdown");
+exports.default = (0, tsdown_1.defineConfig)({
+    entry: {
+        index: 'index.ts',
+        'secret-contract-api': 'secret-contract-api.ts',
+    },
+    format: 'esm',
+    target: 'node22',
+    platform: 'node',
+    clean: true,
+    outDir: 'dist',
+    dts: true,
+    deps: {
+        neverBundle: [
+            /^openclaw(\/.*)?$/,
+            /^@larksuiteoapi\//,
+            /^@sinclair\//,
+            'image-size',
+            'zod',
+            /^node:/,
+        ],
+    },
+});

package/vitest.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: UserConfig;
+export default _default;

package/vitest.config.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_1 = require("vitest/config");
+exports.default = (0, config_1.defineConfig)({
+    test: {
+        include: ['tests/**/*.test.ts'],
+        exclude: [
+            '**/node_modules/**',
+            '**/dist/**',
+        ],
+    },
+});