/**
 * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
 * SPDX-License-Identifier: MIT
 *
  * 飞书工具开发的通用辅助函数
 *
  * 提供所有工具通用的模式，减少重复代码。
 */
import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
import type { ClawdbotConfig } from "openclaw/plugin-sdk";
import type { Client as LarkSdkClient } from "@larksuiteoapi/node-sdk";
import type { LarkAccount } from "../core/types.js";
import { ToolClient } from "../core/tool-client.js";
/**
 * 工具返回值的标准格式
 */
export interface ToolResult {
    content: Array<{
        type: "text";
        text: string;
    }>;
    details: unknown;
}
/**
 * 客户端获取器函数类型
 */
export type ClientGetter = () => LarkSdkClient;
/**
 * 工具上下文对象，包含所有常用的辅助工具
 */
export interface ToolContext {
    /** @deprecated 使用 `toolClient().sdk` 代替 */
    getClient: ClientGetter;
    /** 获取当前请求对应的 {@link ToolClient} 实例 */
    toolClient: () => ToolClient;
    /** 工具日志记录器 */
    log: ReturnType<typeof createToolLogger>;
}
/**
 * 获取飞书客户端的标准模式
 *
 * 这是所有工具通用的逻辑：
 * 1. 优先使用 TraceContext 中的 accountId 动态解析账号
 * 2. 如果没有 TraceContext，回退到 accountIndex 指定的账号
 * 3. 返回创建好的客户端实例
 *
 * @param config - OpenClaw 配置对象
 * @param accountIndex - 使用第几个账号（默认 0，即第一个），仅在无 TraceContext 时使用
 * @returns 飞书 SDK 客户端实例
 * @throws 如果没有启用的账号
 *
 * @example
 * ```typescript
 * export function registerMyTool(api: OpenClawPluginApi) {
 *   const getClient = createClientGetter(api.config);
 *
 *   api.registerTool({
 *     name: "my_tool",
 *     async execute(_toolCallId, params) {
 *       const client = getClient();
 *       const res = await client.im.message.create({ ... });
 *       return formatToolResult(res.data);
 *     }
 *   });
 * }
 * ```
 */
export declare function createClientGetter(config: ClawdbotConfig, accountIndex?: number): ClientGetter;
/**
 * 获取当前请求对应的飞书账号信息
 *
 * 优先使用 TraceContext 中的 accountId，回退到第一个启用的账号。
 *
 * @param config - OpenClaw 配置对象
 * @returns 解析后的账号信息
 * @throws 如果没有启用的账号
 *
 * @example
 * ```typescript
 * const account = getFirstAccount(api.config);
 * const client = LarkClient.fromAccount(account);
 * ```
 */
export declare function getFirstAccount(config: ClawdbotConfig): LarkAccount;
/**
 * 创建工具上下文，一次性返回所有常用的辅助工具
 *
 * 这是推荐的模式，避免在每个工具中重复调用 createClientGetter 和 createToolLogger。
 *
 * @param api - OpenClaw 插件 API
 * @param toolName - 工具名称
 * @param options - 可选配置
 * @returns 工具上下文对象
 *
 * @example
 * ```typescript
 * export function registerMyTool(api: OpenClawPluginApi) {
 *   if (!api.config) return;
 *
 *   const { toolClient, log } = createToolContext(api, "my_tool");
 *
 *   api.registerTool({
 *     name: "my_tool",
 *     async execute(_toolCallId, params) {
 *       const client = getClient();
 *       log.info(`Processing action: ${params.action}`);
 *       const res = await client.im.message.create({ ... });
 *       return formatToolResult(res.data);
 *     }
 *   });
 * }
 * ```
 */
export declare function createToolContext(api: OpenClawPluginApi, toolName: string, options?: {
    /** 使用第几个账号（默认 0，即第一个） */
    accountIndex?: number;
}): ToolContext;
/**
 * 格式化工具返回值为 OpenClaw 期望的格式
 *
 * @param data - 要返回的数据（会被序列化为 JSON）
 * @param options - 可选配置
 * @returns OpenClaw 工具返回值格式
 *
 * @example
 * ```typescript
 * // 简单使用
 * return formatToolResult({ success: true, user_id: "ou_xxx" });
 *
 * // 自定义 JSON 格式化
 * return formatToolResult(data, { indent: 4 });
 * ```
 */
export declare function formatToolResult(data: unknown, options?: {
    /** JSON 缩进空格数，默认 2 */
    indent?: number;
}): ToolResult;
/**
 * 格式化错误为工具返回值
 *
 * @param error - 错误对象或字符串
 * @param context - 错误上下文信息（可选）
 * @returns 包含错误信息的工具返回值
 *
 * @example
 * ```typescript
 * try {
 *   const res = await client.im.message.create({ ... });
 *   return formatToolResult(res.data);
 * } catch (err) {
 *   return formatToolError(err, { action: "send_message", user_id: "ou_xxx" });
 * }
 * ```
 */
export declare function formatToolError(error: unknown, context?: Record<string, unknown>): ToolResult;
/**
 * 创建带工具名前缀的日志函数
 *
 * @param api - OpenClaw 插件 API
 * @param toolName - 工具名称
 * @returns 日志函数对象
 *
 * @example
 * ```typescript
 * export function registerMyTool(api: OpenClawPluginApi) {
 *   const log = createToolLogger(api, "my_tool");
 *
 *   log.info("Tool started");
 *   log.warn("Missing optional param: user_id");
 *   log.error("API call failed");
 *   log.debug("Intermediate state", { count: 5 });
 * }
 * ```
 */
export declare function createToolLogger(api: OpenClawPluginApi, toolName: string): {
    info: (msg: string) => void;
    warn: (msg: string) => void;
    error: (msg: string) => void;
    debug: (msg: string) => void;
};
/**
 * 校验必填参数
 *
 * @param params - 参数对象
 * @param requiredFields - 必填字段列表
 * @returns 校验结果，如果有缺失字段则返回错误信息
 *
 * @example
 * ```typescript
 * async execute(_toolCallId, params) {
 *   const error = validateRequiredParams(params, ["action", "user_id"]);
 *   if (error) return formatToolResult(error);
 *
 *   // 继续处理...
 * }
 * ```
 */
export declare function validateRequiredParams(params: Record<string, unknown>, requiredFields: string[]): {
    error: string;
    missing: string[];
} | null;
/**
 * 校验枚举值
 *
 * @param value - 要校验的值
 * @param allowedValues - 允许的值列表
 * @param fieldName - 字段名（用于错误提示）
 * @returns 校验结果，如果值不在允许列表中则返回错误信息
 *
 * @example
 * ```typescript
 * const error = validateEnum(params.action, ["create", "list", "delete"], "action");
 * if (error) return formatToolResult(error);
 * ```
 */
export declare function validateEnum(value: unknown, allowedValues: unknown[], fieldName: string): {
    error: string;
    allowed: unknown[];
} | null;
//# sourceMappingURL=helpers.d.ts.map