@nextclaw/channel-extension-feishu 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NextClaw contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @nextclaw/channel-extension-feishu
+
+Lightweight Feishu/Lark channel extension for NextClaw.
+
+This extension uses the new NextClaw extension process model and supports QR
+scan-to-create onboarding inspired by Hermes Agent:
+
+1. Start channel auth from the UI or service API.
+2. Scan the Feishu/Lark QR code.
+3. The platform creates a bot application and returns app credentials.
+4. Credentials are stored under `NEXTCLAW_HOME/channels/feishu`.
+5. The extension connects through the Lark WebSocket client.
+
+This extension replaces the removed legacy Feishu channel plugin. It contributes
+the built-in `feishu` channel id through the extension mechanism, so QR
+onboarding, WebSocket inbound messages, NCP replies, and Feishu processing
+reactions now live in one lightweight channel owner.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { FeishuAccountConfig, FeishuChannelConfig, FeishuDomain, FeishuInboundMessage, FeishuRuntimeAccount } from "./types/feishu-extension.types.js";
+import { FeishuRegistrationService } from "./services/feishu-registration.service.js";
+import { FeishuAuthCapability } from "./services/feishu-auth-capability.service.js";
+import { FeishuChannelAdapter } from "./services/feishu-channel-adapter.service.js";
+import { FeishuExtensionRuntime } from "./services/feishu-extension-runtime.service.js";
+export { type FeishuAccountConfig, FeishuAuthCapability, FeishuChannelAdapter, type FeishuChannelConfig, type FeishuDomain, FeishuExtensionRuntime, type FeishuInboundMessage, FeishuRegistrationService, type FeishuRuntimeAccount };

package/dist/index.js

@@ -0,0 +1,5 @@
+import { FeishuRegistrationService } from "./services/feishu-registration.service.js";
+import { FeishuAuthCapability } from "./services/feishu-auth-capability.service.js";
+import { FeishuChannelAdapter } from "./services/feishu-channel-adapter.service.js";
+import { FeishuExtensionRuntime } from "./services/feishu-extension-runtime.service.js";
+export { FeishuAuthCapability, FeishuChannelAdapter, FeishuExtensionRuntime, FeishuRegistrationService };

package/dist/main.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/main.js

@@ -0,0 +1,12 @@
+import { FeishuAuthCapability } from "./services/feishu-auth-capability.service.js";
+import { FeishuChannelAdapter } from "./services/feishu-channel-adapter.service.js";
+import { FeishuExtensionRuntime } from "./services/feishu-extension-runtime.service.js";
+import { NextClawExtension } from "@nextclaw/extension-sdk";
+//#region src/main.ts
+const extension = new NextClawExtension();
+const feishu = extension.channels.use("feishu");
+const runtime = new FeishuExtensionRuntime(feishu, new FeishuChannelAdapter());
+extension.capabilities.provide("channel.auth", new FeishuAuthCapability({ channel: feishu }));
+await runtime.start();
+//#endregion
+export {};

package/dist/services/feishu-auth-capability.service.d.ts

@@ -0,0 +1,20 @@
+import { FeishuRegistrationService } from "./feishu-registration.service.js";
+import { ExtensionCapabilityPayload, ExtensionChannel } from "@nextclaw/extension-sdk";
+
+//#region src/services/feishu-auth-capability.service.d.ts
+type FeishuAuthCapabilityDeps = {
+  channel: ExtensionChannel;
+  registrationService?: Pick<FeishuRegistrationService, "start" | "poll">;
+};
+declare class FeishuAuthCapability {
+  private readonly channel;
+  private readonly registrationService;
+  constructor(deps: FeishuAuthCapabilityDeps);
+  readonly start: (request: ExtensionCapabilityPayload) => Promise<unknown>;
+  readonly poll: (request: ExtensionCapabilityPayload) => Promise<unknown>;
+  private readonly readCurrentConfig;
+  private readonly readString;
+  private readonly readDomain;
+}
+//#endregion
+export { FeishuAuthCapability };

package/dist/services/feishu-auth-capability.service.js

@@ -0,0 +1,32 @@
+import { FeishuRegistrationService } from "./feishu-registration.service.js";
+//#region src/services/feishu-auth-capability.service.ts
+var FeishuAuthCapability = class {
+	channel;
+	registrationService;
+	constructor(deps) {
+		this.channel = deps.channel;
+		this.registrationService = deps.registrationService ?? new FeishuRegistrationService();
+	}
+	start = async (request) => await this.registrationService.start({
+		pluginConfig: await this.readCurrentConfig(),
+		requestedAccountId: this.readString(request.accountId),
+		domain: this.readDomain(request.domain),
+		verbose: request.verbose === true
+	});
+	poll = async (request) => {
+		const sessionId = this.readString(request.sessionId);
+		if (!sessionId) throw new Error("sessionId is required");
+		return await this.registrationService.poll({ sessionId });
+	};
+	readCurrentConfig = async () => {
+		const config = await this.channel.config.get();
+		return config && typeof config === "object" && !Array.isArray(config) ? config : {};
+	};
+	readString = (value) => typeof value === "string" && value.trim() ? value.trim() : null;
+	readDomain = (value) => {
+		const text = this.readString(value);
+		return text === "feishu" || text === "lark" ? text : null;
+	};
+};
+//#endregion
+export { FeishuAuthCapability };

package/dist/services/feishu-channel-adapter.service.d.ts

@@ -0,0 +1,46 @@
+import { FeishuChannelAdapterContract, FeishuChannelConfig, FeishuInboundMessage } from "../types/feishu-extension.types.js";
+import { FeishuAccountStore } from "../stores/feishu-account.store.js";
+import { FeishuSdkService } from "./feishu-sdk.service.js";
+import { NcpEndpointEvent } from "@nextclaw/ncp";
+
+//#region src/services/feishu-channel-adapter.service.d.ts
+type FeishuAdapterDeps = {
+  sdk?: FeishuSdkService;
+  store?: FeishuAccountStore;
+  logger?: Pick<typeof console, "warn" | "log">;
+};
+declare class FeishuChannelAdapter implements FeishuChannelAdapterContract {
+  private messageHandler;
+  private readonly sdk;
+  private readonly store;
+  private readonly logger;
+  private readonly replyConsumer;
+  private readonly wsClients;
+  private readonly replySessions;
+  private readonly canonicalRoutes;
+  private readonly processingReactions;
+  private running;
+  private config;
+  constructor(deps?: FeishuAdapterDeps);
+  readonly configure: (config: FeishuChannelConfig) => Promise<void>;
+  readonly start: () => Promise<void>;
+  readonly stop: () => Promise<void>;
+  readonly onMessage: (handler: (message: FeishuInboundMessage) => void | Promise<void>) => (() => void);
+  readonly sendNcpEvent: (event: NcpEndpointEvent) => Promise<void>;
+  readonly emitMessageForTest: (message: FeishuInboundMessage) => Promise<void>;
+  private readonly startAccount;
+  private readonly listAvailableAccountIds;
+  private readonly resolveRuntimeAccount;
+  private readonly resolveSelectedAccountId;
+  private readonly resolveSendAccount;
+  private readonly resolveReplySession;
+  private readonly resolveCanonicalRoute;
+  private readonly handleInboundEvent;
+  private readonly startProcessingReaction;
+  private readonly finalizeProcessingReaction;
+  private readonly deleteProcessingReaction;
+  private readonly addFailedReaction;
+  private readonly sendText;
+}
+//#endregion
+export { FeishuChannelAdapter };

package/dist/services/feishu-channel-adapter.service.js

@@ -0,0 +1,251 @@
+import { FileFeishuAccountStore } from "../stores/feishu-account.store.js";
+import { FeishuReplyChat, NcpEventQueue, TERMINAL_NCP_EVENT_TYPES } from "./feishu-reply-chat.service.js";
+import { FeishuSdkService } from "./feishu-sdk.service.js";
+import { isFeishuBotMentioned, isFeishuGroupChat, parseFeishuInboundMessage } from "../utils/feishu-message.utils.js";
+import { readFeishuEventSessionId, resolveFeishuSessionRoute } from "../utils/feishu-session-route.utils.js";
+import { NcpEventType } from "@nextclaw/ncp";
+import { NcpReplyConsumer } from "@nextclaw/ncp-toolkit";
+//#region src/services/feishu-channel-adapter.service.ts
+const FEISHU_PROCESSING_REACTION = "Typing";
+const FEISHU_FAILED_REACTION = "CrossMark";
+const FAILED_NCP_EVENT_TYPES = new Set([NcpEventType.MessageFailed, NcpEventType.RunError]);
+function readStringArray(value) {
+	if (!Array.isArray(value)) return [];
+	return value.map((entry) => typeof entry === "string" ? entry.trim() : "").filter(Boolean);
+}
+function normalizeRouteKey(conversationId) {
+	return conversationId.toLowerCase();
+}
+function isAllowedSender(allowFrom, senderId) {
+	return allowFrom.length === 0 || allowFrom.includes(senderId);
+}
+var FeishuChannelAdapter = class {
+	messageHandler = null;
+	sdk;
+	store;
+	logger;
+	replyConsumer;
+	wsClients = /* @__PURE__ */ new Map();
+	replySessions = /* @__PURE__ */ new Map();
+	canonicalRoutes = /* @__PURE__ */ new Map();
+	processingReactions = /* @__PURE__ */ new Map();
+	running = false;
+	config = {};
+	constructor(deps = {}) {
+		this.sdk = deps.sdk ?? new FeishuSdkService();
+		this.store = deps.store ?? new FileFeishuAccountStore();
+		this.logger = deps.logger ?? console;
+		this.replyConsumer = new NcpReplyConsumer(new FeishuReplyChat({
+			resolveAccount: this.resolveSendAccount,
+			sendText: this.sendText
+		}));
+	}
+	configure = async (config) => {
+		this.config = config;
+		if (!this.running) return;
+		await this.stop();
+		await this.start();
+	};
+	start = async () => {
+		if (this.running) return;
+		this.running = true;
+		for (const accountId of this.listAvailableAccountIds()) {
+			const account = this.resolveRuntimeAccount(accountId);
+			if (account?.enabled) this.startAccount(account);
+		}
+	};
+	stop = async () => {
+		if (!this.running) return;
+		this.running = false;
+		for (const client of this.wsClients.values()) {
+			client.close?.();
+			client.stop?.();
+		}
+		this.wsClients.clear();
+		for (const session of this.replySessions.values()) session.queue.close();
+		this.replySessions.clear();
+		this.processingReactions.clear();
+	};
+	onMessage = (handler) => {
+		this.messageHandler = handler;
+		return () => {
+			if (this.messageHandler === handler) this.messageHandler = null;
+		};
+	};
+	sendNcpEvent = async (event) => {
+		if (!this.running) return;
+		const route = resolveFeishuSessionRoute(event);
+		if (!route) return;
+		const sessionId = readFeishuEventSessionId(event);
+		if (!sessionId) return;
+		const canonicalRoute = this.resolveCanonicalRoute(route);
+		const session = this.resolveReplySession(sessionId, canonicalRoute);
+		session.queue.push(event);
+		if (TERMINAL_NCP_EVENT_TYPES.has(event.type)) {
+			session.queue.close();
+			this.replySessions.delete(sessionId);
+			await session.consuming;
+			await this.finalizeProcessingReaction(canonicalRoute, FAILED_NCP_EVENT_TYPES.has(event.type));
+		}
+	};
+	emitMessageForTest = async (message) => {
+		await this.messageHandler?.(message);
+	};
+	startAccount = (account) => {
+		const dispatcher = this.sdk.createEventDispatcher();
+		dispatcher.register({ "im.message.receive_v1": async (data) => {
+			await this.handleInboundEvent(account, data);
+		} });
+		const wsClient = this.sdk.createWsClient(account);
+		wsClient.start({ eventDispatcher: dispatcher });
+		this.wsClients.set(account.accountId, wsClient);
+		this.logger.log?.(`[feishu] websocket started for ${account.accountId}`);
+	};
+	listAvailableAccountIds = () => {
+		return Array.from(new Set([
+			...this.config.defaultAccountId ? [this.config.defaultAccountId] : [],
+			...Object.keys(this.config.accounts ?? {}),
+			...this.store.listAccountIds()
+		]));
+	};
+	resolveRuntimeAccount = (accountId) => {
+		const stored = this.store.loadAccount(accountId);
+		if (!stored?.appId || !stored.appSecret) return null;
+		const accountConfig = this.config.accounts?.[accountId] ?? {};
+		return {
+			accountId,
+			appId: stored.appId,
+			appSecret: stored.appSecret,
+			domain: accountConfig.domain ?? stored.domain ?? this.config.domain ?? "feishu",
+			enabled: accountConfig.enabled !== false && this.config.enabled !== false,
+			name: accountConfig.name ?? stored.botName,
+			botOpenId: stored.botOpenId,
+			allowFrom: Array.from(new Set([...readStringArray(this.config.allowFrom), ...readStringArray(accountConfig.allowFrom)])),
+			groupPolicy: accountConfig.groupPolicy ?? this.config.groupPolicy ?? "open",
+			requireMention: accountConfig.requireMention ?? this.config.requireMention ?? true
+		};
+	};
+	resolveSelectedAccountId = (requestedAccountId) => {
+		if (requestedAccountId) return requestedAccountId;
+		if (this.config.defaultAccountId) return this.config.defaultAccountId;
+		const accountIds = this.listAvailableAccountIds();
+		if (accountIds.length === 1 && accountIds[0]) return accountIds[0];
+		throw new Error("feishu send failed: accountId is required when multiple accounts are configured");
+	};
+	resolveSendAccount = (target) => {
+		const account = this.resolveRuntimeAccount(this.resolveSelectedAccountId(target.accountId));
+		if (!account?.enabled) throw new Error(`feishu send failed: account "${target.accountId ?? this.config.defaultAccountId ?? ""}" is not connected`);
+		return account;
+	};
+	resolveReplySession = (sessionId, route) => {
+		const existing = this.replySessions.get(sessionId);
+		if (existing) return existing;
+		const queue = new NcpEventQueue();
+		const session = {
+			queue,
+			consuming: this.replyConsumer.consume({
+				target: {
+					conversationId: route.conversationId,
+					...route.accountId ? { accountId: route.accountId } : {}
+				},
+				eventStream: queue
+			})
+		};
+		this.replySessions.set(sessionId, session);
+		return session;
+	};
+	resolveCanonicalRoute = (route) => {
+		const remembered = this.canonicalRoutes.get(normalizeRouteKey(route.conversationId));
+		if (remembered) return {
+			...remembered,
+			...route.accountId ? { accountId: route.accountId } : {}
+		};
+		return route;
+	};
+	handleInboundEvent = async (account, rawEvent) => {
+		const parsed = parseFeishuInboundMessage(rawEvent);
+		if (!parsed || !isAllowedSender(account.allowFrom, parsed.senderOpenId)) return;
+		if (isFeishuGroupChat(parsed.chatType)) {
+			if (account.groupPolicy === "disabled") return;
+			if (account.groupPolicy === "allowlist" && !account.allowFrom.includes(parsed.chatId)) return;
+			if (account.requireMention && !isFeishuBotMentioned({
+				botOpenId: account.botOpenId,
+				mentionedOpenIds: parsed.mentionedOpenIds
+			})) return;
+		}
+		this.canonicalRoutes.set(normalizeRouteKey(parsed.chatId), {
+			accountId: account.accountId,
+			conversationId: parsed.chatId
+		});
+		await this.startProcessingReaction(account, parsed.messageId, parsed.chatId);
+		await this.messageHandler?.({
+			conversationId: parsed.chatId,
+			senderId: parsed.senderOpenId,
+			text: parsed.text,
+			accountId: account.accountId,
+			peerKind: isFeishuGroupChat(parsed.chatType) ? "group" : "direct",
+			messageId: parsed.messageId,
+			raw: rawEvent
+		});
+	};
+	startProcessingReaction = async (account, messageId, conversationId) => {
+		if (!messageId) return;
+		const routeKey = normalizeRouteKey(conversationId);
+		try {
+			const reactionId = await this.sdk.addReaction({
+				account,
+				messageId,
+				emojiType: FEISHU_PROCESSING_REACTION
+			});
+			this.processingReactions.set(routeKey, {
+				accountId: account.accountId,
+				messageId,
+				reactionId
+			});
+		} catch (error) {
+			this.logger.warn?.(`[feishu] failed to add processing reaction for ${messageId}: ${String(error)}`);
+		}
+	};
+	finalizeProcessingReaction = async (route, failed) => {
+		const routeKey = normalizeRouteKey(route.conversationId);
+		const state = this.processingReactions.get(routeKey);
+		if (!state) return;
+		this.processingReactions.delete(routeKey);
+		const account = this.resolveRuntimeAccount(state.accountId);
+		if (!account?.enabled) return;
+		await this.deleteProcessingReaction(account, state);
+		if (failed) await this.addFailedReaction(account, state.messageId);
+	};
+	deleteProcessingReaction = async (account, state) => {
+		if (!state.reactionId) return;
+		try {
+			await this.sdk.deleteReaction({
+				account,
+				messageId: state.messageId,
+				reactionId: state.reactionId
+			});
+		} catch (error) {
+			this.logger.warn?.(`[feishu] failed to remove processing reaction for ${state.messageId}: ${String(error)}`);
+		}
+	};
+	addFailedReaction = async (account, messageId) => {
+		try {
+			await this.sdk.addReaction({
+				account,
+				messageId,
+				emojiType: FEISHU_FAILED_REACTION
+			});
+		} catch (error) {
+			this.logger.warn?.(`[feishu] failed to add failure reaction for ${messageId}: ${String(error)}`);
+		}
+	};
+	sendText = async (params) => {
+		await this.sdk.sendText({
+			account: params.account,
+			chatId: params.conversationId,
+			text: params.text
+		});
+	};
+};
+//#endregion
+export { FeishuChannelAdapter };

package/dist/services/feishu-extension-runtime.service.d.ts

@@ -0,0 +1,19 @@
+import { FeishuChannelAdapterContract } from "../types/feishu-extension.types.js";
+import { ExtensionChannel } from "@nextclaw/extension-sdk";
+
+//#region src/services/feishu-extension-runtime.service.d.ts
+declare class FeishuExtensionRuntime {
+  private readonly channel;
+  private readonly adapter;
+  private unsubscribeConfig;
+  private unsubscribeMessages;
+  private unsubscribeNcpEvents;
+  constructor(channel: ExtensionChannel, adapter: FeishuChannelAdapterContract);
+  readonly start: () => Promise<void>;
+  readonly stop: () => Promise<void>;
+  private readonly applyConfig;
+  private readonly submitMessage;
+  private readonly sendNcpEvent;
+}
+//#endregion
+export { FeishuExtensionRuntime };

package/dist/services/feishu-extension-runtime.service.js

@@ -0,0 +1,66 @@
+//#region src/services/feishu-extension-runtime.service.ts
+var FeishuExtensionRuntime = class {
+	unsubscribeConfig = null;
+	unsubscribeMessages = null;
+	unsubscribeNcpEvents = null;
+	constructor(channel, adapter) {
+		this.channel = channel;
+		this.adapter = adapter;
+	}
+	start = async () => {
+		this.unsubscribeMessages = this.adapter.onMessage(this.submitMessage);
+		this.unsubscribeNcpEvents = this.channel.onNcpEvent(this.sendNcpEvent);
+		this.unsubscribeConfig = this.channel.config.onChange(async () => {
+			await this.applyConfig();
+		});
+		await this.applyConfig();
+	};
+	stop = async () => {
+		this.unsubscribeConfig?.();
+		this.unsubscribeMessages?.();
+		this.unsubscribeNcpEvents?.();
+		this.unsubscribeConfig = null;
+		this.unsubscribeMessages = null;
+		this.unsubscribeNcpEvents = null;
+		await this.adapter.stop();
+	};
+	applyConfig = async () => {
+		const config = await this.channel.config.get();
+		await this.adapter.configure(config);
+		if (config.enabled === false) {
+			await this.adapter.stop();
+			return;
+		}
+		await this.adapter.start();
+	};
+	submitMessage = async (message) => {
+		await this.channel.submitMessage({
+			conversationId: message.conversationId,
+			senderId: message.senderId,
+			content: {
+				type: "text",
+				text: message.text
+			},
+			metadata: {
+				accountId: message.accountId,
+				account_id: message.accountId,
+				peerId: message.conversationId,
+				peer_id: message.conversationId,
+				peerKind: message.peerKind,
+				peer_kind: message.peerKind,
+				...message.messageId ? { message_id: message.messageId } : {},
+				...message.raw === void 0 ? {} : { raw: message.raw }
+			}
+		});
+	};
+	sendNcpEvent = async (event) => {
+		try {
+			await this.adapter.sendNcpEvent(event);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			console.warn(`[feishu] failed to send NCP event: ${message}`);
+		}
+	};
+};
+//#endregion
+export { FeishuExtensionRuntime };

package/dist/services/feishu-registration.service.d.ts

@@ -0,0 +1,54 @@
+import { FeishuDomain } from "../types/feishu-extension.types.js";
+import { FeishuAccountStore } from "../stores/feishu-account.store.js";
+
+//#region src/services/feishu-registration.service.d.ts
+type FeishuRegistrationStartParams = {
+  pluginConfig?: Record<string, unknown>;
+  requestedAccountId?: string | null;
+  domain?: FeishuDomain | null;
+  verbose?: boolean;
+};
+type FeishuAuthStartResult = {
+  channel: string;
+  kind: "qr_code";
+  sessionId: string;
+  qrCode: string;
+  qrCodeUrl: string;
+  expiresAt: string;
+  intervalMs: number;
+  note?: string;
+};
+type FeishuAuthPollResult = {
+  channel: string;
+  status: "pending" | "scanned" | "authorized" | "expired" | "error";
+  message?: string;
+  nextPollMs?: number;
+  accountId?: string | null;
+  notes?: string[];
+  pluginConfig?: Record<string, unknown>;
+};
+type FeishuRegistrationServiceDeps = {
+  store?: FeishuAccountStore;
+  fetchImpl?: typeof fetch;
+};
+declare class FeishuRegistrationService {
+  private readonly store;
+  private readonly fetchImpl;
+  private readonly sessions;
+  constructor(deps?: FeishuRegistrationServiceDeps);
+  readonly start: (params: FeishuRegistrationStartParams) => Promise<FeishuAuthStartResult>;
+  readonly poll: ({
+    sessionId
+  }: {
+    sessionId: string;
+  }) => Promise<FeishuAuthPollResult | null>;
+  private readonly assertRegistrationSupported;
+  private readonly beginRegistration;
+  private readonly postRegistration;
+  private readonly confirmRegistration;
+  private readonly probeBot;
+  private readonly readRecord;
+  private readonly cleanupExpiredSessions;
+}
+//#endregion
+export { FeishuRegistrationService };