@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/core/lark-logger.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Structured logger factory for the Feishu plugin.
+ *
+ * Wraps `PluginRuntime.logging.getChildLogger()` with automatic
+ * LarkTicket injection from AsyncLocalStorage and a console fallback
+ * when the runtime is not yet initialised.
+ *
+ * Usage:
+ *   const log = larkLogger("card/streaming");
+ *   log.info("created entity", { cardId, sequence });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.larkLogger = larkLogger;
+const lark_ticket_1 = require("./lark-ticket.js");
+const runtime_store_1 = require("./runtime-store.js");
+// ---------------------------------------------------------------------------
+// Console fallback (with ANSI colors)
+// ---------------------------------------------------------------------------
+// ANSI escape codes for colored console output
+const CYAN = '\x1b[36m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const GRAY = '\x1b[90m';
+const RESET = '\x1b[0m';
+function consoleFallback(subsystem) {
+    const tag = `feishu/${subsystem}`;
+    /* eslint-disable no-console -- logger底层实现，console 是最终输出目标 */
+    return {
+        debug: (msg, meta) => console.debug(`${GRAY}[${tag}]${RESET}`, msg, ...(meta ? [meta] : [])),
+        info: (msg, meta) => console.log(`${CYAN}[${tag}]${RESET}`, msg, ...(meta ? [meta] : [])),
+        warn: (msg, meta) => console.warn(`${YELLOW}[${tag}]${RESET}`, msg, ...(meta ? [meta] : [])),
+        error: (msg, meta) => console.error(`${RED}[${tag}]${RESET}`, msg, ...(meta ? [meta] : [])),
+    };
+    /* eslint-enable no-console */
+}
+// ---------------------------------------------------------------------------
+// Lazy runtime resolution
+// ---------------------------------------------------------------------------
+function resolveRuntimeLogger(subsystem) {
+    try {
+        const runtime = (0, runtime_store_1.tryGetLarkRuntime)();
+        if (!runtime)
+            return null;
+        return runtime.logging.getChildLogger({
+            subsystem: `feishu/${subsystem}`,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// LarkTicket enrichment
+// ---------------------------------------------------------------------------
+function getTraceMeta() {
+    const ctx = (0, lark_ticket_1.getTicket)();
+    if (!ctx)
+        return null;
+    const trace = {
+        accountId: ctx.accountId,
+        messageId: ctx.messageId,
+        chatId: ctx.chatId,
+    };
+    if (ctx.senderOpenId)
+        trace.senderOpenId = ctx.senderOpenId;
+    return trace;
+}
+function enrichMeta(meta) {
+    const trace = getTraceMeta();
+    if (!trace)
+        return meta ?? {};
+    return meta ? { ...trace, ...meta } : trace;
+}
+// ---------------------------------------------------------------------------
+// Message formatting
+// ---------------------------------------------------------------------------
+/**
+ * Build a trace-aware prefix like `feishu[default][msg:om_xxx]:`.
+ *
+ * Mirrors the format used by `trace.ts` so log lines are consistent
+ * across the old and new logging systems.
+ */
+function buildTracePrefix() {
+    const ctx = (0, lark_ticket_1.getTicket)();
+    if (!ctx)
+        return 'feishu:';
+    return `feishu[${ctx.accountId}][msg:${ctx.messageId}]:`;
+}
+/**
+ * Format message with inline meta for text-based log output.
+ *
+ * RuntimeLogger implementations typically ignore the `meta` parameter in
+ * their text output (gateway.log / console).  To ensure meta is always
+ * visible, we serialize user-supplied meta into the message string and
+ * prepend the trace context prefix (accountId + messageId).
+ *
+ * Example:
+ *   formatMessage("card.create response", { code: 0, cardId: "c_xxx" })
+ *   → "feishu[default][msg:om_xxx]: card.create response (code=0, cardId=c_xxx)"
+ */
+function formatMessage(message, meta) {
+    const prefix = buildTracePrefix();
+    if (!meta || Object.keys(meta).length === 0)
+        return `${prefix} ${message}`;
+    const parts = Object.entries(meta)
+        .map(([k, v]) => {
+        if (v === undefined || v == null)
+            return null;
+        if (typeof v === 'object')
+            return `${k}=${JSON.stringify(v)}`;
+        return `${k}=${v}`;
+    })
+        .filter(Boolean);
+    return parts.length > 0 ? `${prefix} ${message} (${parts.join(', ')})` : `${prefix} ${message}`;
+}
+// ---------------------------------------------------------------------------
+// LarkLogger implementation
+// ---------------------------------------------------------------------------
+function createLarkLogger(subsystem) {
+    // RuntimeLogger is resolved lazily on first log call so that module-level
+    // `larkLogger()` calls work even before `LarkClient.setRuntime()`.
+    let cachedLogger = null;
+    let resolved = false;
+    function getLogger() {
+        if (!resolved) {
+            cachedLogger = resolveRuntimeLogger(subsystem);
+            if (cachedLogger)
+                resolved = true;
+        }
+        return cachedLogger ?? consoleFallback(subsystem);
+    }
+    return {
+        subsystem,
+        debug(message, meta) {
+            getLogger().debug?.(formatMessage(message, meta), enrichMeta(meta));
+        },
+        info(message, meta) {
+            getLogger().info(formatMessage(message, meta), enrichMeta(meta));
+        },
+        warn(message, meta) {
+            getLogger().warn(formatMessage(message, meta), enrichMeta(meta));
+        },
+        error(message, meta) {
+            getLogger().error(formatMessage(message, meta), enrichMeta(meta));
+        },
+        child(name) {
+            return createLarkLogger(`${subsystem}/${name}`);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Public factory
+// ---------------------------------------------------------------------------
+function larkLogger(subsystem) {
+    return createLarkLogger(subsystem);
+}

package/src/core/lark-ticket.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Request-level ticket for the Feishu plugin.
+ *
+ * Uses Node.js AsyncLocalStorage to propagate a ticket (message_id,
+ * chat_id, account_id) through the entire async call chain without passing
+ * parameters explicitly.  Call {@link withTicket} at the event entry point
+ * (monitor.ts) and use {@link getTicket} anywhere downstream.
+ */
+export interface LarkTicket {
+    messageId: string;
+    chatId: string;
+    accountId: string;
+    startTime: number;
+    senderOpenId?: string;
+    chatType?: 'p2p' | 'group';
+    threadId?: string;
+}
+/**
+ * Run `fn` within a ticket context.  All async operations spawned inside
+ * `fn` will inherit the context and can access it via {@link getTicket}.
+ */
+export declare function withTicket<T>(ticket: LarkTicket, fn: () => T | Promise<T>): T | Promise<T>;
+/** Return the current ticket, or `undefined` if not inside withTicket. */
+export declare function getTicket(): LarkTicket | undefined;
+/** Milliseconds elapsed since the current ticket was created, or 0. */
+export declare function ticketElapsed(): number;

package/src/core/lark-ticket.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Request-level ticket for the Feishu plugin.
+ *
+ * Uses Node.js AsyncLocalStorage to propagate a ticket (message_id,
+ * chat_id, account_id) through the entire async call chain without passing
+ * parameters explicitly.  Call {@link withTicket} at the event entry point
+ * (monitor.ts) and use {@link getTicket} anywhere downstream.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withTicket = withTicket;
+exports.getTicket = getTicket;
+exports.ticketElapsed = ticketElapsed;
+const node_async_hooks_1 = require("node:async_hooks");
+// ---------------------------------------------------------------------------
+// Storage
+// ---------------------------------------------------------------------------
+const store = new node_async_hooks_1.AsyncLocalStorage();
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Run `fn` within a ticket context.  All async operations spawned inside
+ * `fn` will inherit the context and can access it via {@link getTicket}.
+ */
+function withTicket(ticket, fn) {
+    return store.run(ticket, fn);
+}
+/** Return the current ticket, or `undefined` if not inside withTicket. */
+function getTicket() {
+    return store.getStore();
+}
+/** Milliseconds elapsed since the current ticket was created, or 0. */
+function ticketElapsed() {
+    const t = store.getStore();
+    return t ? Date.now() - t.startTime : 0;
+}

package/src/core/message-unavailable.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * 消息不可用（已撤回/已删除）状态管理。
+ *
+ * 目标：
+ * 1) 当命中飞书终止错误码（230011/231003）时，按 message_id 标记不可用；
+ * 2) 后续针对该 message_id 的 API 调用直接短路，避免持续报错刷屏。
+ */
+import type { LARK_ERROR } from './auth-errors';
+export type TerminalMessageApiCode = typeof LARK_ERROR.MESSAGE_RECALLED | typeof LARK_ERROR.MESSAGE_DELETED;
+export interface MessageUnavailableState {
+    apiCode: TerminalMessageApiCode;
+    markedAtMs: number;
+    operation?: string;
+}
+export declare function isTerminalMessageApiCode(code: unknown): code is TerminalMessageApiCode;
+export declare function markMessageUnavailable(params: {
+    messageId: string;
+    apiCode: TerminalMessageApiCode;
+    operation?: string;
+}): void;
+export declare function getMessageUnavailableState(messageId: string | undefined): MessageUnavailableState | undefined;
+export declare function isMessageUnavailable(messageId: string | undefined): boolean;
+export declare function markMessageUnavailableFromError(params: {
+    messageId: string | undefined;
+    error: unknown;
+    operation?: string;
+}): TerminalMessageApiCode | undefined;
+export declare class MessageUnavailableError extends Error {
+    readonly messageId: string;
+    readonly apiCode: TerminalMessageApiCode;
+    readonly operation?: string;
+    constructor(params: {
+        messageId: string;
+        apiCode: TerminalMessageApiCode;
+        operation?: string;
+    });
+}
+export declare function isMessageUnavailableError(error: unknown): error is MessageUnavailableError;
+export declare function assertMessageAvailable(messageId: string | undefined, operation?: string): void;
+/**
+ * 针对 message_id 的统一保护：
+ * - 调用前检查是否已标记不可用；
+ * - 调用报错后识别 230011/231003 并标记；
+ * - 命中时抛出 MessageUnavailableError 供上游快速终止流程。
+ */
+export declare function runWithMessageUnavailableGuard<T>(params: {
+    messageId: string | undefined;
+    operation: string;
+    fn: () => Promise<T>;
+}): Promise<T>;

package/src/core/message-unavailable.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * 消息不可用（已撤回/已删除）状态管理。
+ *
+ * 目标：
+ * 1) 当命中飞书终止错误码（230011/231003）时，按 message_id 标记不可用；
+ * 2) 后续针对该 message_id 的 API 调用直接短路，避免持续报错刷屏。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessageUnavailableError = void 0;
+exports.isTerminalMessageApiCode = isTerminalMessageApiCode;
+exports.markMessageUnavailable = markMessageUnavailable;
+exports.getMessageUnavailableState = getMessageUnavailableState;
+exports.isMessageUnavailable = isMessageUnavailable;
+exports.markMessageUnavailableFromError = markMessageUnavailableFromError;
+exports.isMessageUnavailableError = isMessageUnavailableError;
+exports.assertMessageAvailable = assertMessageAvailable;
+exports.runWithMessageUnavailableGuard = runWithMessageUnavailableGuard;
+const auth_errors_1 = require("./auth-errors.js");
+const api_error_1 = require("./api-error.js");
+const targets_1 = require("./targets.js");
+const UNAVAILABLE_CACHE_TTL_MS = 30 * 60 * 1000;
+const MAX_CACHE_SIZE_BEFORE_PRUNE = 512;
+const unavailableMessageCache = new Map();
+function pruneExpired(nowMs = Date.now()) {
+    for (const [messageId, state] of unavailableMessageCache) {
+        if (nowMs - state.markedAtMs > UNAVAILABLE_CACHE_TTL_MS) {
+            unavailableMessageCache.delete(messageId);
+        }
+    }
+}
+function isTerminalMessageApiCode(code) {
+    return typeof code === 'number' && auth_errors_1.MESSAGE_TERMINAL_CODES.has(code);
+}
+function markMessageUnavailable(params) {
+    const normalizedId = (0, targets_1.normalizeMessageId)(params.messageId);
+    if (!normalizedId)
+        return;
+    if (unavailableMessageCache.size >= MAX_CACHE_SIZE_BEFORE_PRUNE) {
+        pruneExpired();
+    }
+    unavailableMessageCache.set(normalizedId, {
+        apiCode: params.apiCode,
+        operation: params.operation,
+        markedAtMs: Date.now(),
+    });
+}
+function getMessageUnavailableState(messageId) {
+    const normalizedId = (0, targets_1.normalizeMessageId)(messageId);
+    if (!normalizedId)
+        return undefined;
+    const state = unavailableMessageCache.get(normalizedId);
+    if (!state)
+        return undefined;
+    if (Date.now() - state.markedAtMs > UNAVAILABLE_CACHE_TTL_MS) {
+        unavailableMessageCache.delete(normalizedId);
+        return undefined;
+    }
+    return state;
+}
+function isMessageUnavailable(messageId) {
+    return !!getMessageUnavailableState(messageId);
+}
+function markMessageUnavailableFromError(params) {
+    const normalizedId = (0, targets_1.normalizeMessageId)(params.messageId);
+    if (!normalizedId)
+        return undefined;
+    const code = (0, api_error_1.extractLarkApiCode)(params.error);
+    if (!isTerminalMessageApiCode(code))
+        return undefined;
+    markMessageUnavailable({
+        messageId: normalizedId,
+        apiCode: code,
+        operation: params.operation,
+    });
+    return code;
+}
+class MessageUnavailableError extends Error {
+    messageId;
+    apiCode;
+    operation;
+    constructor(params) {
+        const operationText = params.operation ? `, op=${params.operation}` : '';
+        super(`[feishu-message-unavailable] message ${params.messageId} unavailable (code=${params.apiCode}${operationText})`);
+        this.name = 'MessageUnavailableError';
+        this.messageId = params.messageId;
+        this.apiCode = params.apiCode;
+        this.operation = params.operation;
+    }
+}
+exports.MessageUnavailableError = MessageUnavailableError;
+function isMessageUnavailableError(error) {
+    return (error instanceof MessageUnavailableError ||
+        (typeof error === 'object' && error != null && error.name === 'MessageUnavailableError'));
+}
+function assertMessageAvailable(messageId, operation) {
+    const normalizedId = (0, targets_1.normalizeMessageId)(messageId);
+    if (!normalizedId)
+        return;
+    const state = getMessageUnavailableState(normalizedId);
+    if (!state)
+        return;
+    throw new MessageUnavailableError({
+        messageId: normalizedId,
+        apiCode: state.apiCode,
+        operation: operation ?? state.operation,
+    });
+}
+/**
+ * 针对 message_id 的统一保护：
+ * - 调用前检查是否已标记不可用；
+ * - 调用报错后识别 230011/231003 并标记；
+ * - 命中时抛出 MessageUnavailableError 供上游快速终止流程。
+ */
+async function runWithMessageUnavailableGuard(params) {
+    const normalizedId = (0, targets_1.normalizeMessageId)(params.messageId);
+    if (!normalizedId) {
+        return params.fn();
+    }
+    assertMessageAvailable(normalizedId, params.operation);
+    try {
+        return await params.fn();
+    }
+    catch (error) {
+        const code = markMessageUnavailableFromError({
+            messageId: normalizedId,
+            error,
+            operation: params.operation,
+        });
+        if (code) {
+            throw new MessageUnavailableError({
+                messageId: normalizedId,
+                apiCode: code,
+                operation: params.operation,
+            });
+        }
+        throw error;
+    }
+}

package/src/core/owner-policy.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * owner-policy.ts — 应用 Owner 访问控制策略。
+ *
+ * 从 uat-client.ts 迁移 owner 检查逻辑到独立 policy 层。
+ * 提供 fail-close 策略（安全优先：授权发起路径）。
+ */
+import type * as Lark from '@larksuiteoapi/node-sdk';
+import type { ConfiguredLarkAccount } from './types';
+/**
+ * 非应用 owner 尝试执行 owner-only 操作时抛出。
+ *
+ * 注意：`appOwnerId` 仅用于内部日志，不应序列化到用户可见的响应中，
+ * 以避免泄露 owner 的 open_id。
+ */
+export declare class OwnerAccessDeniedError extends Error {
+    readonly userOpenId: string;
+    readonly appOwnerId: string;
+    constructor(userOpenId: string, appOwnerId: string);
+}
+/**
+ * 校验用户是否为应用 owner（fail-close 版本）。
+ *
+ * - 获取 owner 失败时 → 拒绝（安全优先）
+ * - owner 不匹配时 → 拒绝
+ *
+ * 适用于：`executeAuthorize`（OAuth 授权发起）、`commands/auth.ts`（批量授权）等
+ * 赋予实质性权限的入口。
+ */
+export declare function assertOwnerAccessStrict(account: ConfiguredLarkAccount, sdk: Lark.Client, userOpenId: string): Promise<void>;

package/src/core/owner-policy.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * owner-policy.ts — 应用 Owner 访问控制策略。
+ *
+ * 从 uat-client.ts 迁移 owner 检查逻辑到独立 policy 层。
+ * 提供 fail-close 策略（安全优先：授权发起路径）。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OwnerAccessDeniedError = void 0;
+exports.assertOwnerAccessStrict = assertOwnerAccessStrict;
+const app_owner_fallback_1 = require("./app-owner-fallback.js");
+// ---------------------------------------------------------------------------
+// Error class
+// ---------------------------------------------------------------------------
+/**
+ * 非应用 owner 尝试执行 owner-only 操作时抛出。
+ *
+ * 注意：`appOwnerId` 仅用于内部日志，不应序列化到用户可见的响应中，
+ * 以避免泄露 owner 的 open_id。
+ */
+class OwnerAccessDeniedError extends Error {
+    userOpenId;
+    appOwnerId;
+    constructor(userOpenId, appOwnerId) {
+        super('Permission denied: Only the app owner is authorized to use this feature.');
+        this.name = 'OwnerAccessDeniedError';
+        this.userOpenId = userOpenId;
+        this.appOwnerId = appOwnerId;
+    }
+}
+exports.OwnerAccessDeniedError = OwnerAccessDeniedError;
+// ---------------------------------------------------------------------------
+// Policy functions
+// ---------------------------------------------------------------------------
+/**
+ * 校验用户是否为应用 owner（fail-close 版本）。
+ *
+ * - 获取 owner 失败时 → 拒绝（安全优先）
+ * - owner 不匹配时 → 拒绝
+ *
+ * 适用于：`executeAuthorize`（OAuth 授权发起）、`commands/auth.ts`（批量授权）等
+ * 赋予实质性权限的入口。
+ */
+async function assertOwnerAccessStrict(account, sdk, userOpenId) {
+    const ownerOpenId = await (0, app_owner_fallback_1.getAppOwnerFallback)(account, sdk);
+    if (!ownerOpenId) {
+        throw new OwnerAccessDeniedError(userOpenId, 'unknown');
+    }
+    if (ownerOpenId !== userOpenId) {
+        throw new OwnerAccessDeniedError(userOpenId, ownerOpenId);
+    }
+}

package/src/core/permission-url.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Permission URL extraction utilities.
+ *
+ * Shared functions for extracting and processing permission grant URLs
+ * from Feishu API error messages.
+ */
+/**
+ * Extract permission grant URL from a Feishu error message and optimize it
+ * by keeping only the highest-priority permission.
+ *
+ * @param msg - The error message containing the grant URL
+ * @returns The optimized grant URL with single permission, or empty string if not found
+ */
+export declare function extractPermissionGrantUrl(msg: string): string;
+/**
+ * Extract permission scopes from a Feishu error message.
+ * Looks for scopes in the format [scope1,scope2,...]
+ */
+export declare function extractPermissionScopes(msg: string): string;

package/src/core/permission-url.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Permission URL extraction utilities.
+ *
+ * Shared functions for extracting and processing permission grant URLs
+ * from Feishu API error messages.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractPermissionGrantUrl = extractPermissionGrantUrl;
+exports.extractPermissionScopes = extractPermissionScopes;
+// ---------------------------------------------------------------------------
+// Permission priority
+// ---------------------------------------------------------------------------
+/**
+ * Permission priority for sorting.
+ * Lower number = higher priority.
+ * - read: 1 (highest)
+ * - write: 2
+ * - other / both read+write: 3 (lowest)
+ */
+function getPermissionPriority(scope) {
+    const lowerScope = scope.toLowerCase();
+    const hasRead = lowerScope.includes('read');
+    const hasWrite = lowerScope.includes('write');
+    if (hasRead && !hasWrite)
+        return 1;
+    if (hasWrite && !hasRead)
+        return 2;
+    return 3;
+}
+/**
+ * Extract the highest-priority permission from a scope list.
+ * Returns the permission with the lowest priority number (read > write > other).
+ */
+function extractHighestPriorityScope(scopeList) {
+    return scopeList.split(',').sort((a, b) => getPermissionPriority(a) - getPermissionPriority(b))[0] ?? '';
+}
+// ---------------------------------------------------------------------------
+// Permission URL extraction
+// ---------------------------------------------------------------------------
+/**
+ * Extract permission grant URL from a Feishu error message and optimize it
+ * by keeping only the highest-priority permission.
+ *
+ * @param msg - The error message containing the grant URL
+ * @returns The optimized grant URL with single permission, or empty string if not found
+ */
+function extractPermissionGrantUrl(msg) {
+    const urlMatch = msg.match(/https:\/\/[^\s]+\/app\/[^\s]+/);
+    if (!urlMatch?.[0]) {
+        return '';
+    }
+    try {
+        const url = new URL(urlMatch[0]);
+        const scopeListParam = url.searchParams.get('q') ?? '';
+        const firstScope = extractHighestPriorityScope(scopeListParam);
+        if (firstScope) {
+            url.searchParams.set('q', firstScope);
+        }
+        return url.href;
+    }
+    catch {
+        return urlMatch[0];
+    }
+}
+/**
+ * Extract permission scopes from a Feishu error message.
+ * Looks for scopes in the format [scope1,scope2,...]
+ */
+function extractPermissionScopes(msg) {
+    const scopeMatch = msg.match(/\[([^\]]+)\]/);
+    return scopeMatch?.[1] ?? 'unknown';
+}

package/src/core/raw-request.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * raw-request.ts — 飞书 Open API 裸 HTTP 请求工具。
+ *
+ * 从 tool-client.ts 提取，提供不依赖 SDK 的直接 API 调用能力。
+ * 用于 SDK 未覆盖的 API 或需要精细控制请求的场景。
+ */
+import type { LarkBrand } from './types';
+/** 将 LarkBrand 映射为 API base URL。 */
+export declare function resolveDomainUrl(brand: LarkBrand): string;
+export interface RawLarkRequestOptions {
+    brand: LarkBrand;
+    path: string;
+    method?: string;
+    body?: unknown;
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+    accessToken?: string;
+}
+/**
+ * 发起 raw HTTP 请求到飞书 API，自动处理域名解析、header 注入和错误检测。
+ *
+ * 飞书 API 统一错误模式：返回 JSON 中 `code !== 0` 表示失败。
+ */
+export declare function rawLarkRequest<T>(options: RawLarkRequestOptions): Promise<T>;