@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/core/config-schema.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Zod-based configuration schema for the OpenClaw Lark/Feishu channel plugin.
+ *
+ * Provides runtime validation, sensible defaults, and cross-field refinements
+ * so that every consuming module can rely on well-typed configuration objects.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FEISHU_CONFIG_JSON_SCHEMA = exports.FeishuConfigSchema = exports.FeishuAccountConfigSchema = exports.FeishuGroupSchema = exports.UATConfigSchema = exports.z = void 0;
+const zod_1 = require("zod");
+Object.defineProperty(exports, "z", { enumerable: true, get: function () { return zod_1.z; } });
+// ---------------------------------------------------------------------------
+// Shared micro-schemas
+// ---------------------------------------------------------------------------
+const DmPolicyEnum = zod_1.z.enum(['open', 'pairing', 'allowlist', 'disabled']);
+const GroupPolicyEnum = zod_1.z.enum(['open', 'allowlist', 'disabled']);
+const ConnectionModeEnum = zod_1.z.enum(['websocket', 'webhook']);
+const ReplyModeValue = zod_1.z.enum(['auto', 'static', 'streaming']);
+const ReplyModeSchema = zod_1.z
+    .union([
+    ReplyModeValue,
+    zod_1.z.object({
+        default: ReplyModeValue.optional(),
+        group: ReplyModeValue.optional(),
+        direct: ReplyModeValue.optional(),
+    }),
+])
+    .optional();
+const ChunkModeEnum = zod_1.z.enum(['newline', 'paragraph', 'none']);
+const DomainSchema = zod_1.z.union([zod_1.z.literal('feishu'), zod_1.z.literal('lark'), zod_1.z.string().regex(/^https:\/\//)]).optional();
+const AllowFromSchema = zod_1.z
+    .union([zod_1.z.string(), zod_1.z.array(zod_1.z.string())])
+    .optional()
+    .transform((v) => {
+    if (v === undefined || v == null)
+        return undefined;
+    return Array.isArray(v) ? v : [v];
+});
+const ToolPolicySchema = zod_1.z
+    .object({
+    allow: zod_1.z.array(zod_1.z.string()).optional(),
+    deny: zod_1.z.array(zod_1.z.string()).optional(),
+})
+    .optional();
+const FeishuToolsFlagSchema = zod_1.z
+    .object({
+    doc: zod_1.z.boolean().optional(),
+    wiki: zod_1.z.boolean().optional(),
+    drive: zod_1.z.boolean().optional(),
+    perm: zod_1.z.boolean().optional(),
+    scopes: zod_1.z.boolean().optional(),
+})
+    .optional();
+const FeishuFooterSchema = zod_1.z
+    .object({
+    status: zod_1.z.boolean().optional(),
+    elapsed: zod_1.z.boolean().optional(),
+    tokens: zod_1.z.boolean().optional(),
+    cache: zod_1.z.boolean().optional(),
+    context: zod_1.z.boolean().optional(),
+    model: zod_1.z.boolean().optional(),
+})
+    .optional();
+const BlockStreamingCoalesceSchema = zod_1.z
+    .object({
+    minChars: zod_1.z.number().optional(),
+    maxChars: zod_1.z.number().optional(),
+    idleMs: zod_1.z.number().optional(),
+})
+    .optional();
+const MarkdownConfigSchema = zod_1.z
+    .object({
+    tables: zod_1.z.enum(['off', 'bullets', 'code']).optional(),
+})
+    .optional();
+const HeartbeatSchema = zod_1.z
+    .object({
+    every: zod_1.z.string().optional(),
+    activeHours: zod_1.z
+        .object({
+        start: zod_1.z.string().optional(),
+        end: zod_1.z.string().optional(),
+        timezone: zod_1.z.string().optional(),
+    })
+        .optional(),
+    target: zod_1.z.string().optional(),
+    to: zod_1.z.string().optional(),
+    prompt: zod_1.z.string().optional(),
+    accountId: zod_1.z.string().optional(),
+})
+    .optional();
+const CapabilitiesSchema = zod_1.z
+    .object({
+    image: zod_1.z.boolean().optional(),
+    audio: zod_1.z.boolean().optional(),
+    video: zod_1.z.boolean().optional(),
+})
+    .optional();
+const DedupSchema = zod_1.z
+    .object({
+    ttlMs: zod_1.z.number().optional(), // default 43200000 (12h)
+    maxEntries: zod_1.z.number().optional(), // default 5000
+})
+    .optional();
+const AllowBotsSchema = zod_1.z.union([zod_1.z.boolean(), zod_1.z.literal('mentions')]).optional();
+const ReactionNotificationModeSchema = zod_1.z.enum(['off', 'own', 'all']).optional();
+exports.UATConfigSchema = zod_1.z
+    .object({
+    enabled: zod_1.z.boolean().optional(),
+    allowedScopes: zod_1.z.array(zod_1.z.string()).optional(),
+    blockedScopes: zod_1.z.array(zod_1.z.string()).optional(),
+})
+    .optional();
+const DmConfigSchema = zod_1.z
+    .object({
+    historyLimit: zod_1.z.number().optional(),
+})
+    .optional();
+// ---------------------------------------------------------------------------
+// Group schema
+// ---------------------------------------------------------------------------
+exports.FeishuGroupSchema = zod_1.z.object({
+    groupPolicy: GroupPolicyEnum.optional(),
+    requireMention: zod_1.z.boolean().optional(),
+    respondToMentionAll: zod_1.z.boolean().optional(),
+    tools: ToolPolicySchema,
+    skills: zod_1.z.array(zod_1.z.string()).optional(),
+    enabled: zod_1.z.boolean().optional(),
+    allowFrom: AllowFromSchema,
+    systemPrompt: zod_1.z.string().optional(),
+    allowBots: AllowBotsSchema,
+    // When true, bot-to-bot replies are allowed to stay inside a thread/topic
+    // instead of being forced to the main chat (relaxes the #32980 guard).
+    replyInThread: zod_1.z.boolean().optional(),
+});
+// ---------------------------------------------------------------------------
+// Account config schema (same shape as top-level minus `accounts`)
+// ---------------------------------------------------------------------------
+exports.FeishuAccountConfigSchema = zod_1.z.object({
+    appId: zod_1.z.string().optional(),
+    appSecret: zod_1.z.string().optional(),
+    encryptKey: zod_1.z.string().optional(),
+    verificationToken: zod_1.z.string().optional(),
+    name: zod_1.z.string().optional(),
+    enabled: zod_1.z.boolean().optional(),
+    domain: DomainSchema,
+    connectionMode: ConnectionModeEnum.optional(),
+    webhookPath: zod_1.z.string().optional(),
+    webhookPort: zod_1.z.number().optional(),
+    dmPolicy: DmPolicyEnum.optional(),
+    allowFrom: AllowFromSchema,
+    groupPolicy: GroupPolicyEnum.optional(),
+    groupAllowFrom: AllowFromSchema,
+    requireMention: zod_1.z.boolean().optional(),
+    respondToMentionAll: zod_1.z.boolean().optional(),
+    groups: zod_1.z.record(zod_1.z.string(), exports.FeishuGroupSchema).optional(),
+    historyLimit: zod_1.z.number().optional(),
+    dmHistoryLimit: zod_1.z.number().optional(),
+    dms: DmConfigSchema,
+    textChunkLimit: zod_1.z.number().optional(),
+    chunkMode: ChunkModeEnum.optional(),
+    blockStreamingCoalesce: BlockStreamingCoalesceSchema,
+    mediaMaxMb: zod_1.z.number().optional(),
+    heartbeat: HeartbeatSchema,
+    replyMode: ReplyModeSchema,
+    streaming: zod_1.z.boolean().optional(),
+    blockStreaming: zod_1.z.boolean().optional(),
+    toolUseDisplay: zod_1.z
+        .object({
+        showFullPaths: zod_1.z.boolean().optional(),
+    })
+        .optional(),
+    tools: FeishuToolsFlagSchema,
+    footer: FeishuFooterSchema,
+    markdown: MarkdownConfigSchema,
+    configWrites: zod_1.z.boolean().optional(),
+    capabilities: CapabilitiesSchema,
+    dedup: DedupSchema,
+    reactionNotifications: ReactionNotificationModeSchema,
+    threadSession: zod_1.z.boolean().optional(),
+    allowBots: AllowBotsSchema,
+    // Account-level default for letting bot-to-bot replies stay in a thread
+    // (per-group `replyInThread` overrides this).
+    replyInThread: zod_1.z.boolean().optional(),
+    uat: exports.UATConfigSchema,
+});
+// ---------------------------------------------------------------------------
+// Top-level Feishu config schema
+// ---------------------------------------------------------------------------
+exports.FeishuConfigSchema = exports.FeishuAccountConfigSchema.extend({
+    accounts: zod_1.z.record(zod_1.z.string(), exports.FeishuAccountConfigSchema).optional(),
+}).superRefine((data, ctx) => {
+    // When dmPolicy is "open", allowFrom must contain the wildcard "*".
+    if (data.dmPolicy === 'open') {
+        const list = data.allowFrom;
+        const hasWildcard = Array.isArray(list) && list.includes('*');
+        if (!hasWildcard) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                path: ['allowFrom'],
+                message: 'When dmPolicy is "open", allowFrom must include "*" to permit all senders.',
+            });
+        }
+    }
+});
+// ---------------------------------------------------------------------------
+// Auto-generated JSON Schema (single source of truth)
+// ---------------------------------------------------------------------------
+/**
+ * JSON Schema derived from FeishuConfigSchema.
+ *
+ * - `io: "input"` exposes the input type for `.transform()` schemas (e.g. AllowFromSchema).
+ * - `unrepresentable: "any"` degrades `.superRefine()` constraints to `{}`.
+ * - `target: "draft-07"` matches the plugin system's expected JSON Schema version.
+ */
+exports.FEISHU_CONFIG_JSON_SCHEMA = (0, zod_1.toJSONSchema)(exports.FeishuConfigSchema, {
+    target: 'draft-07',
+    io: 'input',
+    unrepresentable: 'any',
+});

package/src/core/device-flow.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * OAuth 2.0 Device Authorization Grant (RFC 8628) for Lark/Feishu.
+ *
+ * Two-step flow:
+ *   1. `requestDeviceAuthorization` – obtains device_code + user_code.
+ *   2. `pollDeviceToken` – polls the token endpoint until the user authorises,
+ *      rejects, or the code expires.
+ *
+ * All HTTP calls use the built-in `fetch` (Node 18+). The Lark SDK is not
+ * used here because these OAuth endpoints are outside the SDK's scope.
+ */
+import type { LarkBrand } from './types';
+export interface DeviceAuthResponse {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    expiresIn: number;
+    interval: number;
+}
+export interface DeviceFlowTokenData {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+    refreshExpiresIn: number;
+    scope: string;
+}
+export type DeviceFlowResult = {
+    ok: true;
+    token: DeviceFlowTokenData;
+} | {
+    ok: false;
+    error: DeviceFlowError;
+    message: string;
+};
+export type DeviceFlowError = 'authorization_pending' | 'slow_down' | 'access_denied' | 'expired_token';
+/**
+ * Resolve the two OAuth endpoint URLs based on the configured brand.
+ */
+export declare function resolveOAuthEndpoints(brand: LarkBrand): {
+    deviceAuthorization: string;
+    token: string;
+};
+/**
+ * Request a device authorisation code from the Feishu OAuth server.
+ *
+ * Uses Confidential Client authentication (HTTP Basic with appId:appSecret).
+ * The `offline_access` scope is automatically appended so that the token
+ * response includes a refresh_token.
+ */
+export declare function requestDeviceAuthorization(params: {
+    appId: string;
+    appSecret: string;
+    brand: LarkBrand;
+    scope?: string;
+}): Promise<DeviceAuthResponse>;
+/**
+ * Poll the token endpoint until the user authorises, rejects, or the code
+ * expires.
+ *
+ * Handles `authorization_pending` (keep polling), `slow_down` (back off by
+ * +5 s), `access_denied` and `expired_token` (terminal errors).
+ *
+ * Pass an `AbortSignal` to cancel polling from the outside.
+ */
+export declare function pollDeviceToken(params: {
+    appId: string;
+    appSecret: string;
+    brand: LarkBrand;
+    deviceCode: string;
+    interval: number;
+    expiresIn: number;
+    signal?: AbortSignal;
+}): Promise<DeviceFlowResult>;

package/src/core/device-flow.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * OAuth 2.0 Device Authorization Grant (RFC 8628) for Lark/Feishu.
+ *
+ * Two-step flow:
+ *   1. `requestDeviceAuthorization` – obtains device_code + user_code.
+ *   2. `pollDeviceToken` – polls the token endpoint until the user authorises,
+ *      rejects, or the code expires.
+ *
+ * All HTTP calls use the built-in `fetch` (Node 18+). The Lark SDK is not
+ * used here because these OAuth endpoints are outside the SDK's scope.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveOAuthEndpoints = resolveOAuthEndpoints;
+exports.requestDeviceAuthorization = requestDeviceAuthorization;
+exports.pollDeviceToken = pollDeviceToken;
+const lark_logger_1 = require("./lark-logger.js");
+const log = (0, lark_logger_1.larkLogger)('core/device-flow');
+const feishu_fetch_1 = require("./feishu-fetch.js");
+// ---------------------------------------------------------------------------
+// Endpoint resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the two OAuth endpoint URLs based on the configured brand.
+ */
+function resolveOAuthEndpoints(brand) {
+    if (!brand || brand === 'feishu') {
+        return {
+            deviceAuthorization: 'https://accounts.feishu.cn/oauth/v1/device_authorization',
+            token: 'https://open.feishu.cn/open-apis/authen/v2/oauth/token',
+        };
+    }
+    if (brand === 'lark') {
+        return {
+            deviceAuthorization: 'https://accounts.larksuite.com/oauth/v1/device_authorization',
+            token: 'https://open.larksuite.com/open-apis/authen/v2/oauth/token',
+        };
+    }
+    // Custom domain – derive paths by convention.
+    // Smart derivation: open.X → accounts.X for the device authorization endpoint.
+    const base = brand.replace(/\/+$/, '');
+    let accountsBase = base;
+    try {
+        const parsed = new URL(base);
+        if (parsed.hostname.startsWith('open.')) {
+            accountsBase = `${parsed.protocol}//${parsed.hostname.replace(/^open\./, 'accounts.')}`;
+        }
+    }
+    catch {
+        /* fallback to base */
+    }
+    return {
+        deviceAuthorization: `${accountsBase}/oauth/v1/device_authorization`,
+        token: `${base}/open-apis/authen/v2/oauth/token`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Step 1 – Device Authorization Request
+// ---------------------------------------------------------------------------
+/**
+ * Request a device authorisation code from the Feishu OAuth server.
+ *
+ * Uses Confidential Client authentication (HTTP Basic with appId:appSecret).
+ * The `offline_access` scope is automatically appended so that the token
+ * response includes a refresh_token.
+ */
+async function requestDeviceAuthorization(params) {
+    const { appId, appSecret, brand } = params;
+    const endpoints = resolveOAuthEndpoints(brand);
+    // Ensure offline_access is always requested.
+    let scope = params.scope ?? '';
+    if (!scope.includes('offline_access')) {
+        scope = scope ? `${scope} offline_access` : 'offline_access';
+    }
+    const basicAuth = Buffer.from(`${appId}:${appSecret}`).toString('base64');
+    const body = new URLSearchParams();
+    body.set('client_id', appId);
+    body.set('scope', scope);
+    log.info(`requesting device authorization (scope="${scope}") url=${endpoints.deviceAuthorization} token_url=${endpoints.token}`);
+    const resp = await (0, feishu_fetch_1.feishuFetch)(endpoints.deviceAuthorization, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Authorization: `Basic ${basicAuth}`,
+        },
+        body: body.toString(),
+    });
+    const text = await resp.text();
+    log.info(`response status=${resp.status} body=${text.slice(0, 500)}`);
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`Device authorization failed: HTTP ${resp.status} – ${text.slice(0, 200)}`);
+    }
+    if (!resp.ok || data.error) {
+        const msg = data.error_description ?? data.error ?? 'Unknown error';
+        throw new Error(`Device authorization failed: ${msg}`);
+    }
+    const expiresIn = data.expires_in ?? 240;
+    const interval = data.interval ?? 5;
+    log.info(`device_code obtained, expires_in=${expiresIn}s (${Math.round(expiresIn / 60)}min), interval=${interval}s`);
+    return {
+        deviceCode: data.device_code,
+        userCode: data.user_code,
+        verificationUri: data.verification_uri,
+        verificationUriComplete: data.verification_uri_complete ?? data.verification_uri,
+        expiresIn,
+        interval,
+    };
+}
+// ---------------------------------------------------------------------------
+// Step 2 – Poll Token Endpoint
+// ---------------------------------------------------------------------------
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(new DOMException('Aborted', 'AbortError'));
+        }, { once: true });
+    });
+}
+/**
+ * Poll the token endpoint until the user authorises, rejects, or the code
+ * expires.
+ *
+ * Handles `authorization_pending` (keep polling), `slow_down` (back off by
+ * +5 s), `access_denied` and `expired_token` (terminal errors).
+ *
+ * Pass an `AbortSignal` to cancel polling from the outside.
+ */
+async function pollDeviceToken(params) {
+    const MAX_POLL_INTERVAL = 60; // slow_down 最大间隔 60 秒
+    const MAX_POLL_ATTEMPTS = 200; // 安全上限（远超设备码有效期）
+    const { appId, appSecret, brand, deviceCode, expiresIn, signal } = params;
+    let interval = params.interval;
+    const endpoints = resolveOAuthEndpoints(brand);
+    const deadline = Date.now() + expiresIn * 1000;
+    let attempts = 0;
+    while (Date.now() < deadline && attempts < MAX_POLL_ATTEMPTS) {
+        attempts++;
+        if (signal?.aborted) {
+            return { ok: false, error: 'expired_token', message: 'Polling was cancelled' };
+        }
+        await sleep(interval * 1000, signal);
+        let data;
+        try {
+            const resp = await (0, feishu_fetch_1.feishuFetch)(endpoints.token, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                body: new URLSearchParams({
+                    grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+                    device_code: deviceCode,
+                    client_id: appId,
+                    client_secret: appSecret,
+                }).toString(),
+            });
+            data = (await resp.json());
+        }
+        catch (err) {
+            log.warn(`poll network error: ${err}`);
+            interval = Math.min(interval + 1, MAX_POLL_INTERVAL);
+            continue;
+        }
+        const error = data.error;
+        if (!error && data.access_token) {
+            log.info('token obtained successfully');
+            const refreshToken = data.refresh_token ?? '';
+            const expiresIn = data.expires_in ?? 7200;
+            let refreshExpiresIn = data.refresh_token_expires_in ?? 604800;
+            if (!refreshToken) {
+                log.warn('no refresh_token in response, token will not be refreshable');
+                refreshExpiresIn = expiresIn;
+            }
+            return {
+                ok: true,
+                token: {
+                    accessToken: data.access_token,
+                    refreshToken,
+                    expiresIn,
+                    refreshExpiresIn,
+                    scope: data.scope ?? '',
+                },
+            };
+        }
+        if (error === 'authorization_pending') {
+            log.debug('authorization_pending, retrying...');
+            continue;
+        }
+        if (error === 'slow_down') {
+            interval = Math.min(interval + 5, MAX_POLL_INTERVAL);
+            log.info(`slow_down, interval increased to ${interval}s`);
+            continue;
+        }
+        if (error === 'access_denied') {
+            log.info('user denied authorization');
+            return { ok: false, error: 'access_denied', message: '用户拒绝了授权' };
+        }
+        if (error === 'expired_token' || error === 'invalid_grant') {
+            log.info(`device code expired/invalid (error=${error})`);
+            return { ok: false, error: 'expired_token', message: '授权码已过期，请重新发起' };
+        }
+        // Unknown error – treat as terminal.
+        const desc = data.error_description ?? error ?? 'Unknown error';
+        log.warn(`unexpected error: error=${error}, desc=${desc}`);
+        return { ok: false, error: 'expired_token', message: desc };
+    }
+    if (attempts >= MAX_POLL_ATTEMPTS) {
+        log.warn(`max poll attempts (${MAX_POLL_ATTEMPTS}) reached`);
+    }
+    return { ok: false, error: 'expired_token', message: '授权超时，请重新发起' };
+}

package/src/core/domains.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Centralized domain helpers for Feishu / Lark brand-aware URL generation.
+ *
+ * All runtime code that needs to construct platform URLs should use these
+ * helpers instead of hardcoding domain strings.
+ */
+import type { LarkBrand } from './types';
+/** 开放平台域名 (API & 权限管理页面) */
+export declare function openPlatformDomain(brand?: LarkBrand): string;
+/** Applink 域名 */
+export declare function applinkDomain(brand?: LarkBrand): string;
+/** 主站域名 (文档、表格等用户可见链接) */
+export declare function wwwDomain(brand?: LarkBrand): string;
+/** MCP 服务域名 */
+export declare function mcpDomain(brand?: LarkBrand): string;

package/src/core/domains.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Centralized domain helpers for Feishu / Lark brand-aware URL generation.
+ *
+ * All runtime code that needs to construct platform URLs should use these
+ * helpers instead of hardcoding domain strings.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openPlatformDomain = openPlatformDomain;
+exports.applinkDomain = applinkDomain;
+exports.wwwDomain = wwwDomain;
+exports.mcpDomain = mcpDomain;
+// ---------------------------------------------------------------------------
+// Domain helpers
+// ---------------------------------------------------------------------------
+/** 开放平台域名 (API & 权限管理页面) */
+function openPlatformDomain(brand) {
+    return brand === 'lark' ? 'https://open.larksuite.com' : 'https://open.feishu.cn';
+}
+/** Applink 域名 */
+function applinkDomain(brand) {
+    return brand === 'lark' ? 'https://applink.larksuite.com' : 'https://applink.feishu.cn';
+}
+/** 主站域名 (文档、表格等用户可见链接) */
+function wwwDomain(brand) {
+    return brand === 'lark' ? 'https://www.larksuite.com' : 'https://www.feishu.cn';
+}
+/** MCP 服务域名 */
+function mcpDomain(brand) {
+    return brand === 'lark' ? 'https://mcp.larksuite.com' : 'https://mcp.feishu.cn';
+}

package/src/core/feishu-fetch.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Header-aware fetch for Feishu API calls.
+ *
+ * Drop-in replacement for `fetch()` that automatically injects
+ * the User-Agent header.
+ */
+/**
+ * Drop-in replacement for `fetch()` that automatically injects
+ * the User-Agent header.
+ *
+ * Used by `device-flow.ts` and `uat-client.ts` so that the custom
+ * User-Agent is transparently applied without changing every
+ * call-site's signature.
+ */
+export declare function feishuFetch(url: string | URL | Request, init?: RequestInit): Promise<Response>;

package/src/core/feishu-fetch.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Header-aware fetch for Feishu API calls.
+ *
+ * Drop-in replacement for `fetch()` that automatically injects
+ * the User-Agent header.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.feishuFetch = feishuFetch;
+const version_1 = require("./version.js");
+/**
+ * Drop-in replacement for `fetch()` that automatically injects
+ * the User-Agent header.
+ *
+ * Used by `device-flow.ts` and `uat-client.ts` so that the custom
+ * User-Agent is transparently applied without changing every
+ * call-site's signature.
+ */
+function feishuFetch(url, init) {
+    const headers = {
+        ...init?.headers,
+        'User-Agent': (0, version_1.getUserAgent)(),
+    };
+    return fetch(url, { ...init, headers });
+}

package/src/core/footer-config.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Default values and resolution logic for the Feishu card footer configuration.
+ *
+ * Each boolean flag controls whether a particular metadata item is displayed
+ * in the card footer (e.g. elapsed time, model name).
+ */
+import type { FeishuFooterConfig } from './types';
+/**
+ * The default footer configuration.
+ *
+ * By default all metadata items are hidden — neither status text
+ * ("已完成" / "出错" / "已停止") nor elapsed time are shown.
+ */
+export declare const DEFAULT_FOOTER_CONFIG: Required<FeishuFooterConfig>;
+/**
+ * Merge a partial footer configuration with `DEFAULT_FOOTER_CONFIG`.
+ *
+ * Fields present in the input take precedence; anything absent falls back
+ * to the default value.
+ */
+export declare function resolveFooterConfig(cfg?: FeishuFooterConfig): Required<FeishuFooterConfig>;