@colinlu50/openclaw-lark-stream 2026.3.17

package/src/core/api-error.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared Lark API error handling utilities.
+ *
+ * Provides unified error handling for two distinct error paths:
+ *
+ * 1. **Response-level errors** — The SDK returns a response object with a
+ *    non-zero `code`.  Handled by {@link assertLarkOk}.
+ *
+ * 2. **Thrown exceptions** — The SDK throws an Axios-style error (HTTP 4xx)
+ *    whose properties include the Feishu error `code` and `msg`.
+ *    Handled by {@link formatLarkError}.
+ *
+ * Both paths intercept well-known codes (e.g. LARK_ERROR.APP_SCOPE_MISSING (99991672) — missing API scopes)
+ * and produce user-friendly messages with actionable authorization links.
+ */
+/**
+ * 从 Lark SDK 抛错对象中提取飞书 API code。
+ *
+ * 支持三种常见结构：
+ * - `{ code }` — SDK 直接挂载
+ * - `{ data: { code } }` — 响应体嵌套
+ * - `{ response: { data: { code } } }` — Axios 风格
+ */
+export declare function extractLarkApiCode(err: unknown): number | undefined;
+/**
+ * Assert that a Lark SDK response is successful (code === 0).
+ *
+ * For permission errors (code LARK_ERROR.APP_SCOPE_MISSING (99991672)), the thrown error includes the
+ * required scope names and a direct authorization URL so the AI can
+ * present it to the end user.
+ */
+export declare function assertLarkOk(res: {
+    code?: number;
+    msg?: string;
+}): void;
+/**
+ * Extract a meaningful error message from a thrown Lark SDK / Axios error.
+ *
+ * The Lark SDK throws Axios errors whose object carries Feishu-specific
+ * fields (`code`, `msg`) alongside the standard `message`.  For permission
+ * errors (LARK_ERROR.APP_SCOPE_MISSING (99991672)) we format a user-friendly string with scopes + auth URL.
+ * For all other errors we try `err.msg` first (the Feishu detail) and fall
+ * back to `err.message` (the generic Axios text).
+ */
+export declare function formatLarkError(err: unknown): string;

package/src/core/api-error.js

@@ -0,0 +1,112 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared Lark API error handling utilities.
+ *
+ * Provides unified error handling for two distinct error paths:
+ *
+ * 1. **Response-level errors** — The SDK returns a response object with a
+ *    non-zero `code`.  Handled by {@link assertLarkOk}.
+ *
+ * 2. **Thrown exceptions** — The SDK throws an Axios-style error (HTTP 4xx)
+ *    whose properties include the Feishu error `code` and `msg`.
+ *    Handled by {@link formatLarkError}.
+ *
+ * Both paths intercept well-known codes (e.g. LARK_ERROR.APP_SCOPE_MISSING (99991672) — missing API scopes)
+ * and produce user-friendly messages with actionable authorization links.
+ */
+import { extractPermissionGrantUrl, extractPermissionScopes } from './permission-url';
+import { LARK_ERROR } from './auth-errors';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Given a Feishu error code and msg, format a user-friendly permission
+ * error string if the code is LARK_ERROR.APP_SCOPE_MISSING (99991672).  Returns `null` for other codes.
+ */
+function formatPermissionError(code, msg) {
+    if (code !== LARK_ERROR.APP_SCOPE_MISSING)
+        return null;
+    const authUrl = extractPermissionGrantUrl(msg);
+    const scopes = extractPermissionScopes(msg);
+    return `权限不足：应用缺少 [${scopes}] 权限。\n` + `请管理员点击以下链接申请并开通权限：\n${authUrl}`;
+}
+// ---------------------------------------------------------------------------
+// Code extraction
+// ---------------------------------------------------------------------------
+function coerceCode(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+/**
+ * 从 Lark SDK 抛错对象中提取飞书 API code。
+ *
+ * 支持三种常见结构：
+ * - `{ code }` — SDK 直接挂载
+ * - `{ data: { code } }` — 响应体嵌套
+ * - `{ response: { data: { code } } }` — Axios 风格
+ */
+export function extractLarkApiCode(err) {
+    if (!err || typeof err !== 'object')
+        return undefined;
+    const e = err;
+    return coerceCode(e.code) ?? coerceCode(e.data?.code) ?? coerceCode(e.response?.data?.code);
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Assert that a Lark SDK response is successful (code === 0).
+ *
+ * For permission errors (code LARK_ERROR.APP_SCOPE_MISSING (99991672)), the thrown error includes the
+ * required scope names and a direct authorization URL so the AI can
+ * present it to the end user.
+ */
+export function assertLarkOk(res) {
+    if (!res.code || res.code === 0)
+        return;
+    const permMsg = formatPermissionError(res.code, res.msg ?? '');
+    if (permMsg)
+        throw new Error(permMsg);
+    throw new Error(res.msg ?? `Feishu API error (code: ${res.code})`);
+}
+/**
+ * Extract a meaningful error message from a thrown Lark SDK / Axios error.
+ *
+ * The Lark SDK throws Axios errors whose object carries Feishu-specific
+ * fields (`code`, `msg`) alongside the standard `message`.  For permission
+ * errors (LARK_ERROR.APP_SCOPE_MISSING (99991672)) we format a user-friendly string with scopes + auth URL.
+ * For all other errors we try `err.msg` first (the Feishu detail) and fall
+ * back to `err.message` (the generic Axios text).
+ */
+export function formatLarkError(err) {
+    if (!err || typeof err !== 'object') {
+        return String(err);
+    }
+    const e = err;
+    // Path 1: Lark SDK merges Feishu fields onto the thrown error object.
+    if (typeof e.code === 'number' && e.msg) {
+        const permMsg = formatPermissionError(e.code, e.msg);
+        if (permMsg)
+            return permMsg;
+        return e.msg;
+    }
+    // Path 2: Standard Axios error — dig into response.data.
+    const data = e.response?.data;
+    if (data && typeof data.code === 'number' && data.msg) {
+        const permMsg = formatPermissionError(data.code, data.msg);
+        if (permMsg)
+            return permMsg;
+        return data.msg;
+    }
+    // Fallback.
+    return e.message ?? String(err);
+}

package/src/core/app-owner-fallback.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * 应用所有者查询 — 复用 app-scope-checker 的 API 调用和统一 owner 定义。
+ *
+ * 所有 owner 判定统一使用 {@link getAppInfo} 返回的 `effectiveOwnerOpenId`。
+ * 不维护独立缓存，完全依赖 app-scope-checker 的 30s 缓存。
+ */
+import type { ConfiguredLarkAccount } from './types';
+/**
+ * 获取应用的 effectiveOwnerOpenId。
+ *
+ * 复用 app-scope-checker 的 API 调用、缓存和统一 owner 定义（effectiveOwnerOpenId）。
+ * 查询失败时返回 undefined（fail-open）。
+ *
+ * @param account - 已配置的飞书账号信息
+ * @param sdk - 飞书 SDK 实例（必须已初始化 TAT）
+ * @returns 应用所有者的 open_id，如果查询失败则返回 undefined
+ */
+export declare function getAppOwnerFallback(account: ConfiguredLarkAccount, sdk: any): Promise<string | undefined>;

package/src/core/app-owner-fallback.js

@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * 应用所有者查询 — 复用 app-scope-checker 的 API 调用和统一 owner 定义。
+ *
+ * 所有 owner 判定统一使用 {@link getAppInfo} 返回的 `effectiveOwnerOpenId`。
+ * 不维护独立缓存，完全依赖 app-scope-checker 的 30s 缓存。
+ */
+import { getAppInfo } from './app-scope-checker';
+import { larkLogger } from './lark-logger';
+const log = larkLogger('core/app-owner-fallback');
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * 获取应用的 effectiveOwnerOpenId。
+ *
+ * 复用 app-scope-checker 的 API 调用、缓存和统一 owner 定义（effectiveOwnerOpenId）。
+ * 查询失败时返回 undefined（fail-open）。
+ *
+ * @param account - 已配置的飞书账号信息
+ * @param sdk - 飞书 SDK 实例（必须已初始化 TAT）
+ * @returns 应用所有者的 open_id，如果查询失败则返回 undefined
+ */
+export async function getAppOwnerFallback(account, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+sdk) {
+    const { appId } = account;
+    try {
+        const appInfo = await getAppInfo(sdk, appId);
+        return appInfo.effectiveOwnerOpenId;
+    }
+    catch (err) {
+        log.warn(`failed to get owner for ${appId}: ${err instanceof Error ? err.message : err}`);
+        return undefined; // fail-open: 获取失败不阻塞业务
+    }
+}

package/src/core/app-scope-checker.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * App Scope Checker — 查询应用已开通的 scope 列表。
+ *
+ * 通过 `GET /open-apis/application/v6/applications/:app_id` (TAT) 获取
+ * 应用信息，从 `app.scopes` 中提取已开通的 scope 字符串列表。
+ *
+ * 结果带 30 秒内存缓存，避免每次 invoke() 都调远程 API。
+ * scope 检查失败后可调 {@link invalidateAppScopeCache} 清缓存重查。
+ */
+import type * as Lark from '@larksuiteoapi/node-sdk';
+export interface AppInfo {
+    appId: string;
+    creatorId?: string;
+    ownerOpenId?: string;
+    ownerType?: number;
+    /**
+     * 统一的 owner 判定结果。所有需要判定"谁是应用 owner"的场景都应使用此字段。
+     *
+     * 规则：owner_type=2（企业内成员）时取 owner_id，否则回退 creator_id。
+     * 兼容 owner.owner_type 和 owner.type 两种字段名。
+     */
+    effectiveOwnerOpenId?: string;
+    scopes: Array<{
+        scope: string;
+        token_types?: string[];
+    }>;
+}
+/** 清除指定 appId 的缓存。 */
+export declare function invalidateAppScopeCache(appId: string): void;
+/**
+ * 获取应用已开通的 scope 列表。
+ *
+ * 需要应用自身有 `application:application:self_manage` 权限。
+ * `appId` 可传 `"me"` 查自己。
+ *
+ * @param sdk - Lark SDK 实例
+ * @param appId - 应用 ID
+ * @param tokenType - token 类型，用于过滤只支持特定 token 类型的 scope
+ * @returns scope 字符串数组，如 `["calendar:calendar", "task:task:write"]`
+ */
+export declare function getAppGrantedScopes(sdk: Lark.Client, appId: string, tokenType?: 'user' | 'tenant'): Promise<string[]>;
+/**
+ * 获取应用信息，包括 owner 信息。
+ *
+ * 复用 getAppGrantedScopes 的 API 调用和缓存。
+ * 如果缓存中已有数据且未过期，直接从缓存提取。
+ *
+ * @param sdk - Lark SDK 实例
+ * @param appId - 应用 ID（可传 "me"）
+ */
+export declare function getAppInfo(sdk: Lark.Client, appId: string): Promise<AppInfo>;
+/**
+ * 计算 APP 已有 ∩ OAPI 需要 的交集。
+ *
+ * 用于传给 OAuth 的 scope 参数 — 只请求 APP 已开通且 API 需要的 scope。
+ *
+ * @param appGranted - 应用已开通的 scope 列表
+ * @param apiRequired - OAPI 要求的 scope 列表
+ * @returns 交集 scope 列表
+ */
+export declare function intersectScopes(appGranted: string[], apiRequired: string[]): string[];
+/**
+ * 计算 OAPI 需要但 APP 未开通的 scope（差集）。
+ *
+ * 用于 AppScopeMissingError 的 missingScopes。
+ *
+ * @param appGranted - 应用已开通的 scope 列表
+ * @param apiRequired - OAPI 要求的 scope 列表
+ * @returns 缺失的 scope 列表
+ */
+export declare function missingScopes(appGranted: string[], apiRequired: string[]): string[];
+/**
+ * 校验应用已开通的 scope 是否满足要求。
+ *
+ * 与 tool-client.ts invoke() 的 scope 校验逻辑完全一致，作为唯一真值来源：
+ *   - `scopeNeedType === "all"`: appScopes 必须包含 requiredScopes 的全部项
+ *   - 其他（默认 "one"）:        appScopes 与 requiredScopes 的交集非空即可
+ *   - appScopes 为空:            视为满足（API 查询失败，退回服务端判断）
+ *
+ * @param appScopes      - 应用已开通的 scope 列表（由 getAppGrantedScopes 返回）
+ * @param requiredScopes - 需要的 scope 列表
+ * @param scopeNeedType  - "all" 表示全部必须，undefined/"one" 表示任一即可
+ */
+export declare function isAppScopeSatisfied(appScopes: string[], requiredScopes: string[], scopeNeedType?: 'one' | 'all'): boolean;

package/src/core/app-scope-checker.js

@@ -0,0 +1,190 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * App Scope Checker — 查询应用已开通的 scope 列表。
+ *
+ * 通过 `GET /open-apis/application/v6/applications/:app_id` (TAT) 获取
+ * 应用信息，从 `app.scopes` 中提取已开通的 scope 字符串列表。
+ *
+ * 结果带 30 秒内存缓存，避免每次 invoke() 都调远程 API。
+ * scope 检查失败后可调 {@link invalidateAppScopeCache} 清缓存重查。
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { larkLogger } from './lark-logger';
+const log = larkLogger('core/app-scope-checker');
+import { AppScopeCheckFailedError } from './auth-errors';
+// ---------------------------------------------------------------------------
+// Cache
+// ---------------------------------------------------------------------------
+const cache = new Map();
+const CACHE_TTL_MS = 30 * 1000; // 30 秒
+/** 清除指定 appId 的缓存。 */
+export function invalidateAppScopeCache(appId) {
+    cache.delete(appId);
+}
+// ---------------------------------------------------------------------------
+// Fetch
+// ---------------------------------------------------------------------------
+/**
+ * 获取应用已开通的 scope 列表。
+ *
+ * 需要应用自身有 `application:application:self_manage` 权限。
+ * `appId` 可传 `"me"` 查自己。
+ *
+ * @param sdk - Lark SDK 实例
+ * @param appId - 应用 ID
+ * @param tokenType - token 类型，用于过滤只支持特定 token 类型的 scope
+ * @returns scope 字符串数组，如 `["calendar:calendar", "task:task:write"]`
+ */
+export async function getAppGrantedScopes(sdk, appId, tokenType) {
+    // 1. 检查缓存
+    const cached = cache.get(appId);
+    if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
+        // 从缓存中过滤出支持当前 token 类型的 scope
+        return cached.rawScopes
+            .filter((s) => {
+            if (tokenType && s.token_types && Array.isArray(s.token_types)) {
+                return s.token_types.includes(tokenType);
+            }
+            return true;
+        })
+            .map((s) => s.scope);
+    }
+    // 2. 调用 API
+    try {
+        const res = await sdk.request({
+            method: 'GET',
+            url: `/open-apis/application/v6/applications/${appId}`,
+            params: { lang: 'zh_cn' },
+        });
+        if (res.code !== 0) {
+            // 任何 API 错误都认为是应用缺少 application:application:self_manage 权限
+            throw new AppScopeCheckFailedError(appId);
+        }
+        // 响应结构: res.data.app.scopes → [{ scope: "xxx", description, level, token_types?: string[] }]
+        // 或者从 app_version 中获取 scopes
+        const app = res.data?.app ?? res.app ?? res.data;
+        const rawScopes = app?.scopes ?? app?.online_version?.scopes ?? [];
+        // 提取并验证 scope 字符串
+        const validScopes = rawScopes
+            .filter((s) => typeof s.scope === 'string' && s.scope.length > 0)
+            .map((s) => ({ scope: s.scope, token_types: s.token_types }));
+        // 3. 写缓存（缓存完整数据，包含 token_types 和原始 app 对象）
+        cache.set(appId, { rawScopes: validScopes, rawApp: app, fetchedAt: Date.now() });
+        log.info(`fetched ${validScopes.length} scopes for app ${appId}`);
+        // 4. 根据 tokenType 过滤
+        const scopes = validScopes
+            .filter((s) => {
+            if (tokenType && s.token_types && Array.isArray(s.token_types)) {
+                return s.token_types.includes(tokenType);
+            }
+            return true;
+        })
+            .map((s) => s.scope);
+        log.info(`returning ${scopes.length} scopes${tokenType ? ` for ${tokenType} token` : ''}`);
+        return scopes;
+    }
+    catch (err) {
+        // 如果是 AppScopeCheckFailedError，重新抛出（不吞掉）
+        if (err instanceof AppScopeCheckFailedError) {
+            throw err;
+        }
+        // 检查是否是权限相关的 HTTP 错误（400/403）
+        // axios/SDK 异常对象通常包含 response.status 或 status 字段
+        const statusCode = err?.response?.status || err?.status || err?.statusCode;
+        const isPermissionError = statusCode === 400 ||
+            statusCode === 403 ||
+            (err instanceof Error && (err.message.includes('status code 400') || err.message.includes('status code 403')));
+        if (isPermissionError) {
+            throw new AppScopeCheckFailedError(appId);
+        }
+        log.warn(`failed to fetch scopes for ${appId}: ${err instanceof Error ? err.message : err}`);
+        // 其他查询失败不阻塞调用，返回空数组（后续 API 调用如果缺 scope 会被服务端拒绝）
+        return [];
+    }
+}
+// ---------------------------------------------------------------------------
+// App info
+// ---------------------------------------------------------------------------
+/**
+ * 获取应用信息，包括 owner 信息。
+ *
+ * 复用 getAppGrantedScopes 的 API 调用和缓存。
+ * 如果缓存中已有数据且未过期，直接从缓存提取。
+ *
+ * @param sdk - Lark SDK 实例
+ * @param appId - 应用 ID（可传 "me"）
+ */
+export async function getAppInfo(sdk, appId) {
+    // 先确保缓存已填充（调一次 getAppGrantedScopes 来触发 API + 缓存）
+    await getAppGrantedScopes(sdk, appId);
+    const cached = cache.get(appId);
+    const rawApp = cached?.rawApp;
+    // 提取 owner 信息
+    const owner = rawApp?.owner;
+    const creatorId = rawApp?.creator_id;
+    // 统一 owner 定义：type=2（企业内成员）用 owner_id，否则回退 creator_id
+    // 兼容两种字段名（owner_type 和 type）
+    const ownerTypeValue = owner?.owner_type ?? owner?.type;
+    const effectiveOwnerOpenId = ownerTypeValue === 2 && owner?.owner_id ? owner.owner_id : (creatorId ?? owner?.owner_id);
+    return {
+        appId,
+        creatorId,
+        ownerOpenId: owner?.owner_id,
+        ownerType: owner?.owner_type,
+        effectiveOwnerOpenId,
+        scopes: cached?.rawScopes ?? [],
+    };
+}
+// ---------------------------------------------------------------------------
+// Scope intersection
+// ---------------------------------------------------------------------------
+/**
+ * 计算 APP 已有 ∩ OAPI 需要 的交集。
+ *
+ * 用于传给 OAuth 的 scope 参数 — 只请求 APP 已开通且 API 需要的 scope。
+ *
+ * @param appGranted - 应用已开通的 scope 列表
+ * @param apiRequired - OAPI 要求的 scope 列表
+ * @returns 交集 scope 列表
+ */
+export function intersectScopes(appGranted, apiRequired) {
+    const grantedSet = new Set(appGranted);
+    return apiRequired.filter((s) => grantedSet.has(s));
+}
+/**
+ * 计算 OAPI 需要但 APP 未开通的 scope（差集）。
+ *
+ * 用于 AppScopeMissingError 的 missingScopes。
+ *
+ * @param appGranted - 应用已开通的 scope 列表
+ * @param apiRequired - OAPI 要求的 scope 列表
+ * @returns 缺失的 scope 列表
+ */
+export function missingScopes(appGranted, apiRequired) {
+    const grantedSet = new Set(appGranted);
+    return apiRequired.filter((s) => !grantedSet.has(s));
+}
+/**
+ * 校验应用已开通的 scope 是否满足要求。
+ *
+ * 与 tool-client.ts invoke() 的 scope 校验逻辑完全一致，作为唯一真值来源：
+ *   - `scopeNeedType === "all"`: appScopes 必须包含 requiredScopes 的全部项
+ *   - 其他（默认 "one"）:        appScopes 与 requiredScopes 的交集非空即可
+ *   - appScopes 为空:            视为满足（API 查询失败，退回服务端判断）
+ *
+ * @param appScopes      - 应用已开通的 scope 列表（由 getAppGrantedScopes 返回）
+ * @param requiredScopes - 需要的 scope 列表
+ * @param scopeNeedType  - "all" 表示全部必须，undefined/"one" 表示任一即可
+ */
+export function isAppScopeSatisfied(appScopes, requiredScopes, scopeNeedType) {
+    if (appScopes.length === 0)
+        return true; // API 查询失败 → 退回服务端判断
+    if (requiredScopes.length === 0)
+        return true;
+    if (scopeNeedType === 'all') {
+        return missingScopes(appScopes, requiredScopes).length === 0;
+    }
+    return intersectScopes(appScopes, requiredScopes).length > 0;
+}

package/src/core/auth-errors.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * auth-errors.ts — 统一错误类型定义。
+ *
+ * 所有与认证/授权/scope 相关的错误类型集中在此文件，
+ * 解除 tool-client ↔ app-scope-checker 循环依赖。
+ *
+ * 其他模块应直接 import 此文件，或通过 tool-client / uat-client 的 re-export 使用。
+ */
+/** 飞书 OAPI 错误码常量，替代各处硬编码的 magic number。 */
+export declare const LARK_ERROR: {
+    /** 应用 scope 不足（租户维度） */
+    readonly APP_SCOPE_MISSING: 99991672;
+    /** 用户 token scope 不足 */
+    readonly USER_SCOPE_INSUFFICIENT: 99991679;
+    /** access_token 无效 */
+    readonly TOKEN_INVALID: 99991668;
+    /** access_token 已过期 */
+    readonly TOKEN_EXPIRED: 99991677;
+    /** refresh_token 本身无效（格式非法或来自 v1 API） */
+    readonly REFRESH_TOKEN_INVALID: 20026;
+    /** refresh_token 已过期（超过 365 天） */
+    readonly REFRESH_TOKEN_EXPIRED: 20037;
+    /** refresh_token 已被吊销 */
+    readonly REFRESH_TOKEN_REVOKED: 20064;
+    /** refresh_token 已被使用（单次消费，rotation 场景） */
+    readonly REFRESH_TOKEN_ALREADY_USED: 20073;
+    /** refresh token 端点服务端内部错误，可重试 */
+    readonly REFRESH_SERVER_ERROR: 20050;
+    /** 消息已被撤回 */
+    readonly MESSAGE_RECALLED: 230011;
+    /** 消息已被删除 */
+    readonly MESSAGE_DELETED: 231003;
+};
+/** refresh token 端点可重试的错误码集合（服务端瞬时故障）。遇到后重试一次，仍失败则清 token。 */
+export declare const REFRESH_TOKEN_RETRYABLE: ReadonlySet<number>;
+/** 消息终止错误码集合（撤回/删除），遇到后应停止对该消息的后续操作。 */
+export declare const MESSAGE_TERMINAL_CODES: ReadonlySet<number>;
+/** access_token 失效相关的错误码集合，遇到后可尝试刷新重试。 */
+export declare const TOKEN_RETRY_CODES: ReadonlySet<number>;
+/** invoke() 错误共享的 scope 信息。 */
+export interface ScopeErrorInfo {
+    apiName: string;
+    scopes: string[];
+    /** 应用 scope 是否已验证通过。false 表示 app scope 检查失败，scope 信息可能不准确。 */
+    appScopeVerified?: boolean;
+    /** 应用 ID，用于生成开放平台权限管理链接。 */
+    appId?: string;
+}
+/** OAuth 授权提示信息，与 handleInvokeError 返回的结构一致。 */
+export interface AuthHint {
+    error: string;
+    api: string;
+    required_scope: string;
+    user_open_id: string;
+    message: string;
+    next_tool_call: {
+        tool: 'feishu_oauth';
+        params: {
+            action: 'authorize';
+            scope: string;
+        };
+    };
+}
+/** tryInvoke 返回值的判别联合体。 */
+export type TryInvokeResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+    authHint: AuthHint;
+} | {
+    ok: false;
+    error: string;
+    authHint?: undefined;
+};
+/**
+ * Thrown when no valid UAT exists and the user needs to (re-)authorise.
+ * Callers should catch this and trigger the OAuth flow.
+ */
+export declare class NeedAuthorizationError extends Error {
+    readonly userOpenId: string;
+    constructor(userOpenId: string);
+}
+/**
+ * 应用缺少 application:application:self_manage 权限，无法查询应用权限配置。
+ *
+ * 需要管理员在飞书开放平台开通 application:application:self_manage 权限。
+ */
+export declare class AppScopeCheckFailedError extends Error {
+    /** 应用 ID，用于生成开放平台权限管理链接。 */
+    readonly appId?: string;
+    constructor(appId?: string);
+}
+/**
+ * 应用未开通 OAPI 所需 scope。
+ *
+ * 需要管理员在飞书开放平台开通权限。
+ */
+export declare class AppScopeMissingError extends Error {
+    readonly apiName: string;
+    /** OAPI 需要但 APP 未开通的 scope 列表。 */
+    readonly missingScopes: string[];
+    /** 工具的全部所需 scope（含已开通的），用于应用权限完成后一次性发起用户授权。 */
+    readonly allRequiredScopes?: string[];
+    /** 应用 ID，用于生成开放平台权限管理链接。 */
+    readonly appId?: string;
+    readonly scopeNeedType?: 'one' | 'all';
+    /** 触发此错误时使用的 token 类型，用于保持 card action 二次校验一致。 */
+    readonly tokenType?: 'user' | 'tenant';
+    constructor(info: ScopeErrorInfo, scopeNeedType?: 'one' | 'all', tokenType?: 'user' | 'tenant', allRequiredScopes?: string[]);
+}
+/**
+ * 用户未授权或 scope 不足，需要发起 OAuth 授权。
+ *
+ * `requiredScopes` 为 APP∩OAPI 的有效 scope，可直接传给
+ * `feishu_oauth authorize --scope`。
+ */
+export declare class UserAuthRequiredError extends Error {
+    readonly userOpenId: string;
+    readonly apiName: string;
+    /** APP∩OAPI 交集 scope，传给 OAuth authorize。 */
+    readonly requiredScopes: string[];
+    /** 应用 scope 是否已验证通过。false 时 requiredScopes 可能不准确。 */
+    readonly appScopeVerified: boolean;
+    /** 应用 ID，用于生成开放平台权限管理链接。 */
+    readonly appId?: string;
+    constructor(userOpenId: string, info: ScopeErrorInfo);
+}
+/**
+ * 服务端报 99991679 — 用户 token 的 scope 不足。
+ *
+ * 需要增量授权：用缺失的 scope 发起新 Device Flow。
+ */
+export declare class UserScopeInsufficientError extends Error {
+    readonly userOpenId: string;
+    readonly apiName: string;
+    /** 缺失的 scope 列表。 */
+    readonly missingScopes: string[];
+    constructor(userOpenId: string, info: ScopeErrorInfo);
+}