@botcord/daemon 0.2.59 → 0.2.60

package/dist/gateway/channels/feishu.js

@@ -0,0 +1,459 @@
+import * as Lark from "@larksuiteoapi/node-sdk";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { sanitizeUntrustedContent } from "./sanitize.js";
+import { loadGatewaySecret } from "./secret-store.js";
+import { GatewayStateStore } from "./state-store.js";
+import { splitText } from "./text-split.js";
+const FEISHU_PROVIDER = "feishu";
+const DEFAULT_SPLIT_AT = 4000;
+const MAX_SEEN_MESSAGES = 2048;
+function sdkDomain(domain) {
+    const sdk = Lark;
+    return domain === "lark" ? sdk.Domain?.Lark : sdk.Domain?.Feishu;
+}
+function parseMessageContent(content) {
+    if (!content)
+        return null;
+    try {
+        const parsed = JSON.parse(content);
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return { text: content };
+    }
+}
+function parseInboundText(message) {
+    const parsed = parseMessageContent(message.content);
+    if (!parsed)
+        return null;
+    if (typeof parsed.text === "string")
+        return parsed.text;
+    if (message.message_type === "image" && typeof parsed.image_key === "string") {
+        return `[image: ${parsed.image_key}]`;
+    }
+    if (message.message_type === "file" && typeof parsed.file_key === "string") {
+        const name = typeof parsed.file_name === "string" ? ` ${parsed.file_name}` : "";
+        return `[file${name}: ${parsed.file_key}]`;
+    }
+    if (message.message_type === "audio" && typeof parsed.file_key === "string") {
+        return `[audio: ${parsed.file_key}]`;
+    }
+    if (message.message_type === "media" && typeof parsed.file_key === "string") {
+        return `[video: ${parsed.file_key}]`;
+    }
+    if (message.message_type)
+        return `[${message.message_type} message]`;
+    return null;
+}
+function senderLabel(event) {
+    const mentions = event.message?.mentions ?? [];
+    const senderOpenId = event.sender?.sender_id?.open_id;
+    const hit = mentions.find((m) => m.id?.open_id && m.id.open_id === senderOpenId);
+    return typeof hit?.name === "string" && hit.name ? hit.name : undefined;
+}
+export function createFeishuChannel(opts) {
+    const splitAt = opts.splitAt && opts.splitAt > 0 ? opts.splitAt : DEFAULT_SPLIT_AT;
+    const allowedSenderIds = new Set((opts.allowedSenderIds ?? []).map(String));
+    const allowedChatIds = new Set((opts.allowedChatIds ?? []).map(String));
+    let appSecret = opts.appSecret;
+    let wsClient = null;
+    let client = null;
+    let stateStore = null;
+    let botOpenId;
+    let botName;
+    let liveSetStatus = null;
+    let statusSnapshot = {
+        channel: opts.id,
+        accountId: opts.accountId,
+        running: false,
+        connected: false,
+        reconnectAttempts: 0,
+        lastError: null,
+        provider: FEISHU_PROVIDER,
+        authorized: false,
+    };
+    function ensureState() {
+        if (!stateStore) {
+            stateStore = new GatewayStateStore(opts.id, {
+                override: opts.stateFile,
+                debounceMs: opts.stateDebounceMs,
+            });
+        }
+        return stateStore;
+    }
+    function readProviderState() {
+        return (ensureState().getProviderState() ?? {});
+    }
+    function hasSeenMessage(messageId) {
+        const seen = readProviderState().seenMessageIds ?? {};
+        return Object.prototype.hasOwnProperty.call(seen, messageId);
+    }
+    function rememberMessage(messageId) {
+        const providerState = readProviderState();
+        const seen = { ...(providerState.seenMessageIds ?? {}), [messageId]: Date.now() };
+        const entries = Object.entries(seen).sort((a, b) => a[1] - b[1]);
+        while (entries.length > MAX_SEEN_MESSAGES)
+            entries.shift();
+        ensureState().update({
+            providerState: {
+                ...providerState,
+                seenMessageIds: Object.fromEntries(entries),
+            },
+        });
+    }
+    function loadSecretIfNeeded() {
+        if (appSecret)
+            return appSecret;
+        const secret = loadGatewaySecret(opts.id, opts.secretFile);
+        if (typeof secret?.appSecret === "string" && secret.appSecret.length > 0) {
+            appSecret = secret.appSecret;
+        }
+        return appSecret;
+    }
+    function ensureClient() {
+        if (client)
+            return client;
+        if (!opts.appId || !loadSecretIfNeeded()) {
+            throw new Error("feishu appId/appSecret not loaded");
+        }
+        const sdk = Lark;
+        client = new sdk.Client({
+            appId: opts.appId,
+            appSecret,
+            appType: sdk.AppType?.SelfBuild,
+            domain: sdkDomain(opts.domain),
+        });
+        return client;
+    }
+    function markStatus(patch, setStatus) {
+        statusSnapshot = { ...statusSnapshot, ...patch };
+        (setStatus ?? liveSetStatus)?.(patch);
+    }
+    async function probe() {
+        const res = (await ensureClient().request({
+            method: "POST",
+            url: "/open-apis/bot/v1/openclaw_bot/ping",
+            data: { needBotInfo: true },
+        }));
+        if (res.code !== 0) {
+            throw new Error(res.msg || `feishu bot ping failed: code=${res.code}`);
+        }
+        botOpenId = res.data?.pingBotInfo?.botID;
+        botName = res.data?.pingBotInfo?.botName;
+    }
+    function normalizeMessage(event) {
+        const message = event.message;
+        const sender = event.sender;
+        if (!message || !sender)
+            return null;
+        const chatId = message.chat_id;
+        const messageId = message.message_id;
+        const senderOpenId = sender.sender_id?.open_id;
+        if (!chatId || !messageId || !senderOpenId)
+            return null;
+        if (botOpenId && senderOpenId === botOpenId)
+            return null;
+        if (hasSeenMessage(messageId))
+            return null;
+        if (allowedChatIds.size > 0 && !allowedChatIds.has(chatId))
+            return null;
+        if (!allowedSenderIds.has(senderOpenId))
+            return null;
+        const text = parseInboundText(message);
+        if (text === null)
+            return null;
+        rememberMessage(messageId);
+        const chatType = message.chat_type ?? "";
+        const conversationKind = chatType === "p2p" ? "direct" : "group";
+        const conversationId = conversationKind === "direct" ? `feishu:user:${chatId}` : `feishu:chat:${chatId}`;
+        const receivedAt = Number(message.create_time) || Date.now();
+        return {
+            id: `feishu:${messageId}`,
+            channel: opts.id,
+            accountId: opts.accountId,
+            conversation: {
+                id: conversationId,
+                kind: conversationKind,
+                threadId: message.root_id || message.parent_id || null,
+            },
+            sender: {
+                id: `feishu:user:${senderOpenId}`,
+                ...(senderLabel(event) ? { name: senderLabel(event) } : {}),
+                kind: "user",
+            },
+            text: sanitizeUntrustedContent(text),
+            raw: event,
+            replyTo: messageId,
+            mentioned: true,
+            receivedAt,
+            trace: { id: `feishu:${messageId}`, streamable: true },
+        };
+    }
+    async function start(ctx) {
+        liveSetStatus = ctx.setStatus;
+        try {
+            if (!opts.appId || !loadSecretIfNeeded()) {
+                markStatus({
+                    running: false,
+                    connected: false,
+                    authorized: false,
+                    lastError: "feishu appId/appSecret not loaded",
+                }, ctx.setStatus);
+                return;
+            }
+            await probe();
+            const sdk = Lark;
+            const dispatcher = new sdk.EventDispatcher({});
+            dispatcher.register({
+                "im.message.receive_v1": async (data) => {
+                    const normalized = normalizeMessage(data);
+                    if (!normalized)
+                        return;
+                    markStatus({ lastInboundAt: Date.now(), connected: true, authorized: true });
+                    await ctx.emit({ message: normalized });
+                },
+            });
+            wsClient = new sdk.WSClient({
+                appId: opts.appId,
+                appSecret,
+                domain: sdkDomain(opts.domain),
+                loggerLevel: sdk.LoggerLevel?.info,
+            });
+            markStatus({
+                running: true,
+                connected: true,
+                authorized: true,
+                lastError: null,
+            }, ctx.setStatus);
+            Promise.resolve(wsClient.start({ eventDispatcher: dispatcher })).catch((err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                markStatus({
+                    running: false,
+                    connected: false,
+                    authorized: false,
+                    lastError: message,
+                    reconnectAttempts: (statusSnapshot.reconnectAttempts ?? 0) + 1,
+                });
+                ctx.log.warn("feishu ws client failed", { err: message });
+            });
+            await new Promise((resolve) => {
+                if (ctx.abortSignal.aborted)
+                    return resolve();
+                ctx.abortSignal.addEventListener("abort", () => resolve(), { once: true });
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            markStatus({
+                running: false,
+                connected: false,
+                authorized: false,
+                lastError: message,
+            }, ctx.setStatus);
+            throw err;
+        }
+        finally {
+            try {
+                wsClient?.close({ force: true });
+            }
+            catch {
+                // best effort
+            }
+            wsClient = null;
+            markStatus({ running: false, connected: false }, ctx.setStatus);
+            try {
+                stateStore?.flush();
+            }
+            catch (err) {
+                ctx.log.warn("feishu state flush failed", {
+                    err: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+    function chatIdFromConversation(conversationId) {
+        if (conversationId.startsWith("feishu:user:")) {
+            return conversationId.slice("feishu:user:".length);
+        }
+        if (conversationId.startsWith("feishu:chat:")) {
+            return conversationId.slice("feishu:chat:".length);
+        }
+        return null;
+    }
+    async function callFeishu(args) {
+        const res = (await ensureClient().request(args));
+        if (res.code !== undefined && res.code !== 0) {
+            throw new Error(res.msg || `feishu api failed: code=${res.code}`);
+        }
+        return res;
+    }
+    function resultMessageId(res) {
+        return ((typeof res.data?.message_id === "string" ? res.data.message_id : undefined) ??
+            (typeof res.message_id === "string" ? res.message_id : undefined));
+    }
+    function resultResourceKey(res, key) {
+        const direct = res[key];
+        if (typeof direct === "string")
+            return direct;
+        const nested = res.data?.[key];
+        if (typeof nested === "string")
+            return nested;
+        throw new Error(`feishu upload failed: ${key} missing`);
+    }
+    function attachmentBytes(attachment) {
+        if (attachment.data)
+            return Buffer.from(attachment.data);
+        if (attachment.filePath)
+            return readFileSync(attachment.filePath);
+        throw new Error("feishu attachment requires filePath or data");
+    }
+    function fileNameForAttachment(attachment) {
+        if (attachment.filename)
+            return attachment.filename;
+        if (attachment.filePath)
+            return path.basename(attachment.filePath);
+        return "attachment";
+    }
+    function isImageAttachment(attachment) {
+        if (attachment.kind === "image")
+            return true;
+        if (attachment.contentType?.startsWith("image/"))
+            return true;
+        return /\.(png|jpe?g|gif|webp|bmp|tiff?|ico)$/i.test(fileNameForAttachment(attachment));
+    }
+    function feishuFileType(attachment) {
+        if (attachment.kind === "video")
+            return "mp4";
+        const name = fileNameForAttachment(attachment).toLowerCase();
+        const contentType = attachment.contentType?.toLowerCase() ?? "";
+        if (contentType.includes("pdf") || name.endsWith(".pdf"))
+            return "pdf";
+        if (contentType.includes("word") || /\.(doc|docx)$/i.test(name))
+            return "doc";
+        if (contentType.includes("spreadsheet") || /\.(xls|xlsx)$/i.test(name))
+            return "xls";
+        if (contentType.includes("presentation") || /\.(ppt|pptx)$/i.test(name))
+            return "ppt";
+        if (contentType.includes("audio/ogg") || name.endsWith(".opus"))
+            return "opus";
+        if (contentType.includes("video/mp4") || name.endsWith(".mp4"))
+            return "mp4";
+        return "stream";
+    }
+    async function uploadAttachment(attachment) {
+        const bytes = attachmentBytes(attachment);
+        if (isImageAttachment(attachment)) {
+            const res = await callFeishu({
+                method: "POST",
+                url: "/open-apis/im/v1/images",
+                data: { image_type: "message", image: bytes },
+                headers: { "Content-Type": "multipart/form-data" },
+            });
+            return { msgType: "image", content: { image_key: resultResourceKey(res, "image_key") } };
+        }
+        const fileType = feishuFileType(attachment);
+        const res = await callFeishu({
+            method: "POST",
+            url: "/open-apis/im/v1/files",
+            data: {
+                file_type: fileType,
+                file_name: fileNameForAttachment(attachment),
+                file: bytes,
+            },
+            headers: { "Content-Type": "multipart/form-data" },
+        });
+        const fileKey = resultResourceKey(res, "file_key");
+        if (fileType === "opus")
+            return { msgType: "audio", content: { file_key: fileKey } };
+        if (fileType === "mp4")
+            return { msgType: "media", content: { file_key: fileKey } };
+        return { msgType: "file", content: { file_key: fileKey } };
+    }
+    async function sendPayload(args) {
+        const data = {
+            msg_type: args.msgType,
+            content: JSON.stringify(args.content),
+        };
+        if (args.replyTo) {
+            data.reply_in_thread = args.replyInThread ?? false;
+            const res = await callFeishu({
+                method: "POST",
+                url: `/open-apis/im/v1/messages/${encodeURIComponent(args.replyTo)}/reply`,
+                data,
+            });
+            return resultMessageId(res);
+        }
+        const res = await callFeishu({
+            method: "POST",
+            url: "/open-apis/im/v1/messages",
+            params: { receive_id_type: "chat_id" },
+            data: {
+                ...data,
+                receive_id: args.chatId,
+            },
+        });
+        return resultMessageId(res);
+    }
+    async function send(ctx) {
+        const chatId = chatIdFromConversation(ctx.message.conversationId);
+        if (!chatId) {
+            throw new Error("unsupported feishu conversation id");
+        }
+        let providerMessageId;
+        const replyTo = ctx.message.replyTo ?? ctx.message.threadId ?? null;
+        const textParts = ctx.message.text.length > 0 ? splitText(ctx.message.text, splitAt) : [];
+        for (const part of textParts) {
+            providerMessageId = await sendPayload({
+                chatId,
+                msgType: "text",
+                content: { text: part },
+                replyTo,
+                replyInThread: Boolean(ctx.message.threadId),
+            }) ?? providerMessageId;
+        }
+        for (const attachment of ctx.message.attachments ?? []) {
+            const uploaded = await uploadAttachment(attachment);
+            providerMessageId = await sendPayload({
+                chatId,
+                msgType: uploaded.msgType,
+                content: uploaded.content,
+                replyTo,
+                replyInThread: Boolean(ctx.message.threadId),
+            }) ?? providerMessageId;
+        }
+        markStatus({ lastSendAt: Date.now() });
+        return { providerMessageId };
+    }
+    async function typing(ctx) {
+        ctx.log.debug("feishu typing ignored: no native bot typing API", {
+            channel: opts.id,
+            conversationId: ctx.conversationId,
+        });
+    }
+    async function stop(_ctx) {
+        try {
+            wsClient?.close({ force: true });
+        }
+        catch {
+            // best effort
+        }
+        wsClient = null;
+        try {
+            stateStore?.close();
+        }
+        catch {
+            // best effort
+        }
+        markStatus({ running: false, connected: false });
+    }
+    return {
+        id: opts.id,
+        type: FEISHU_PROVIDER,
+        start,
+        stop,
+        send,
+        typing,
+        status: () => ({ ...statusSnapshot }),
+    };
+}

package/dist/gateway/channels/index.d.ts

@@ -2,6 +2,8 @@ export { createBotCordChannel } from "./botcord.js";
 export type { BotCordChannelClient, BotCordChannelOptions, BotCordClientFactory, } from "./botcord.js";
 export { createTelegramChannel, type TelegramChannelOptions } from "./telegram.js";
 export { createWechatChannel, type WechatChannelOptions } from "./wechat.js";
+export { createFeishuChannel, type FeishuChannelOptions } from "./feishu.js";
+export { startFeishuRegistration, pollFeishuRegistration, type FeishuDomain, } from "./feishu-registration.js";
 export { getBotQrcode, getQrcodeStatus, DEFAULT_WECHAT_BASE_URL, type WechatQrcode, type WechatQrcodeStatus, type WechatLoginOptions, } from "./wechat-login.js";
 export { defaultGatewaySecretPath, loadGatewaySecret, saveGatewaySecret, deleteGatewaySecret, } from "./secret-store.js";
 export { GatewayStateStore, defaultGatewayStatePath, type GatewayStateStoreOptions, type ThirdPartyGatewayState, } from "./state-store.js";

package/dist/gateway/channels/index.js

@@ -1,6 +1,8 @@
 export { createBotCordChannel } from "./botcord.js";
 export { createTelegramChannel } from "./telegram.js";
 export { createWechatChannel } from "./wechat.js";
+export { createFeishuChannel } from "./feishu.js";
+export { startFeishuRegistration, pollFeishuRegistration, } from "./feishu-registration.js";
 export { getBotQrcode, getQrcodeStatus, DEFAULT_WECHAT_BASE_URL, } from "./wechat-login.js";
 export { defaultGatewaySecretPath, loadGatewaySecret, saveGatewaySecret, deleteGatewaySecret, } from "./secret-store.js";
 export { GatewayStateStore, defaultGatewayStatePath, } from "./state-store.js";

package/dist/gateway/channels/login-session.d.ts

@@ -8,7 +8,7 @@
  * outside the daemon process or the per-gateway secret file. A daemon
  * restart drops in-flight logins; the user just rescans.
  */
-export type LoginProvider = "wechat" | "telegram";
+export type LoginProvider = "wechat" | "telegram" | "feishu";
 export interface LoginSession {
     loginId: string;
     accountId: string;
@@ -22,6 +22,14 @@ export interface LoginSession {
     baseUrl?: string;
     /** Stored only after the user confirms the qrcode. Never returned to Hub. */
     botToken?: string;
+    /** Feishu/Lark PersonalAgent app id returned by app registration. */
+    appId?: string;
+    /** Feishu/Lark PersonalAgent app secret returned by app registration. */
+    appSecret?: string;
+    /** Feishu/Lark tenant domain selected during registration. */
+    domain?: "feishu" | "lark";
+    /** Feishu/Lark user open_id returned by app registration. */
+    userOpenId?: string;
     /** Masked preview safe for Hub/dashboard display. */
     tokenPreview?: string;
     /** Unix millis. */

package/dist/gateway/channels/login-session.js

@@ -91,7 +91,7 @@ export function maskTokenPreview(token) {
  * ids and racefully claim someone else's session.
  */
 export function mintLoginId(provider) {
-    const prefix = provider === "wechat" ? "wxl" : "tgl";
+    const prefix = provider === "wechat" ? "wxl" : provider === "feishu" ? "fsl" : "tgl";
     const ts = Date.now().toString(36);
     // 32 hex chars = 128 bits of entropy — W5 regression fix from round 2.
     const rand = randomBytes(16).toString("hex");

package/dist/gateway/dispatcher.js

@@ -1003,6 +1003,7 @@ export class Dispatcher {
             // own loop-risk accounting downstream.
             const isOwnerChat = isOwnerChatRoom(msg);
             const canDeliverRuntimeText = isOwnerChat || !isBotCordChannel(channel);
+            const canDeliverRuntimeDiagnostics = canDeliverRuntimeText || isBotCordChannel(channel);
             if (slot.timedOut) {
                 this.transcript.write({
                     ts: nowIso(),
@@ -1015,7 +1016,7 @@ export class Dispatcher {
                     error: `runtime timeout after ${this.turnTimeoutMs}ms`,
                     durationMs: Date.now() - slot.dispatchedAt,
                 });
-                if (canDeliverRuntimeText) {
+                if (canDeliverRuntimeDiagnostics) {
                     await this.sendReply(channel, {
                         channel: msg.channel,
                         accountId: msg.accountId,
@@ -1060,7 +1061,7 @@ export class Dispatcher {
                     error: errMsg,
                     durationMs: Date.now() - slot.dispatchedAt,
                 });
-                if (canDeliverRuntimeText) {
+                if (canDeliverRuntimeDiagnostics) {
                     await this.sendReply(channel, {
                         channel: msg.channel,
                         accountId: msg.accountId,
@@ -1150,7 +1151,7 @@ export class Dispatcher {
                         runtime: route.runtime,
                         error: result.error,
                     });
-                    if (canDeliverRuntimeText) {
+                    if (canDeliverRuntimeDiagnostics) {
                         const sendResult = await this.sendReply(channel, {
                             channel: msg.channel,
                             accountId: msg.accountId,

package/dist/gateway/policy-resolver.d.ts

@@ -22,25 +22,29 @@
  * the agent is revoked or the cache must rebuild from scratch.
  */
 import type { AttentionPolicy } from "@botcord/protocol-core";
+export type DaemonAttentionPolicy = Omit<AttentionPolicy, "mode"> & {
+    mode: AttentionPolicy["mode"] | "allowed_senders";
+    allowedSenderIds?: string[];
+};
 /** Public surface — kept narrow so the dispatcher can mock easily in tests. */
 export interface PolicyResolverLike {
-    resolve(agentId: string, roomId: string | null): Promise<AttentionPolicy>;
+    resolve(agentId: string, roomId: string | null): Promise<DaemonAttentionPolicy>;
     invalidate(agentId: string, roomId?: string): void;
     /**
      * Install (or replace) the cached policy entry for an agent / room. Used
      * by the `policy_updated` control-frame handler to apply embedded policy
      * payloads without forcing a refetch.
      */
-    put(agentId: string, roomId: string | null, policy: AttentionPolicy): void;
+    put(agentId: string, roomId: string | null, policy: DaemonAttentionPolicy): void;
 }
 export interface PolicyResolverOptions {
     /** Fetcher for the per-agent default. Returning `undefined` means "no policy known"; the resolver falls back to `mode=always`. */
-    fetchGlobal: (agentId: string) => Promise<AttentionPolicy | undefined>;
+    fetchGlobal: (agentId: string) => Promise<DaemonAttentionPolicy | undefined>;
     /**
      * Optional per-room fetcher. PR2 supplies this; PR3 leaves it
      * unimplemented and the resolver collapses to the global policy.
      */
-    fetchEffective?: (agentId: string, roomId: string) => Promise<AttentionPolicy | undefined>;
+    fetchEffective?: (agentId: string, roomId: string) => Promise<DaemonAttentionPolicy | undefined>;
     /** Cache TTL in milliseconds. Defaults to 5 minutes. */
     ttlMs?: number;
 }
@@ -50,8 +54,8 @@ export declare class PolicyResolver implements PolicyResolverLike {
     private readonly ttlMs;
     private readonly cache;
     constructor(opts: PolicyResolverOptions);
-    resolve(agentId: string, roomId: string | null): Promise<AttentionPolicy>;
+    resolve(agentId: string, roomId: string | null): Promise<DaemonAttentionPolicy>;
     private safeFetch;
     invalidate(agentId: string, roomId?: string): void;
-    put(agentId: string, roomId: string | null, policy: AttentionPolicy): void;
+    put(agentId: string, roomId: string | null, policy: DaemonAttentionPolicy): void;
 }

package/dist/gateway/types.d.ts

@@ -171,7 +171,7 @@ export interface ChannelStatusSnapshot {
     lastStopAt?: number;
     lastError?: string | null;
     /** Third-party provider id when this channel is not the built-in BotCord. */
-    provider?: "wechat" | "telegram";
+    provider?: "wechat" | "telegram" | "feishu";
     /** Last time the adapter polled the upstream provider (ms epoch). */
     lastPollAt?: number;
     /** Last time the adapter accepted an inbound message (ms epoch). */

package/dist/gateway-control.d.ts

@@ -13,9 +13,10 @@ import type { Gateway } from "./gateway/index.js";
 import { type DaemonConfig } from "./config.js";
 import { LoginSessionStore } from "./gateway/channels/login-session.js";
 import { getBotQrcode, getQrcodeStatus } from "./gateway/channels/wechat-login.js";
+import { pollFeishuRegistration, startFeishuRegistration } from "./gateway/channels/feishu-registration.js";
 import type { FetchLike } from "./gateway/channels/http-types.js";
 type AckBody = Omit<ControlAck, "id">;
-type GatewayProvider = "telegram" | "wechat";
+type GatewayProvider = "telegram" | "wechat" | "feishu";
 interface UpsertGatewayParams {
     id: string;
     type: GatewayProvider;
@@ -28,6 +29,7 @@ interface UpsertGatewayParams {
     };
     settings?: {
         baseUrl?: string;
+        domain?: "feishu" | "lark";
         allowedSenderIds?: string[];
         allowedChatIds?: string[];
         splitAt?: number;
@@ -45,6 +47,7 @@ interface GatewayLoginStartParams {
     accountId: string;
     gatewayId?: string;
     baseUrl?: string;
+    domain?: "feishu" | "lark";
 }
 interface GatewayLoginStatusParams {
     provider: GatewayProvider;
@@ -75,6 +78,10 @@ export interface GatewayControlContext {
         getBotQrcode: typeof getBotQrcode;
         getQrcodeStatus: typeof getQrcodeStatus;
     };
+    feishuLoginClient?: {
+        startFeishuRegistration: typeof startFeishuRegistration;
+        pollFeishuRegistration: typeof pollFeishuRegistration;
+    };
     /** Override the global fetch — used by `test_gateway` for Telegram getMe. */
     fetchImpl?: FetchLike;
 }