@rynx-ai/plugin-channel-lark 0.1.9

package/dist/lark-resume-card.js

@@ -0,0 +1,105 @@
+/** applink that opens a chat (p2p or group) in the Feishu client. Topic
+ *  threads have no deep-link, so those are forwarded instead (see the
+ *  `resume_forward` card action). */
+export function buildChatApplink(chatId) {
+    return `https://applink.feishu.cn/client/chat/open?openChatId=${encodeURIComponent(chatId)}`;
+}
+/** A single-button card whose button opens `chatId` (used by /fork to give the
+ *  user a one-tap entry into the new group from the current conversation). */
+export function buildOpenChatCardJson(chatId, chatName) {
+    const url = buildChatApplink(chatId);
+    const card = {
+        schema: "2.0",
+        header: {
+            title: { tag: "plain_text", content: "已 fork 到新群" },
+            template: "green",
+        },
+        body: {
+            elements: [
+                { tag: "markdown", content: `新群聊：**${chatName}**\n已搬运历史记录并带上当前会话上下文。` },
+                {
+                    tag: "button",
+                    text: { tag: "plain_text", content: "进入新群聊" },
+                    type: "primary",
+                    behaviors: [
+                        { type: "open_url", default_url: url, pc_url: url, ios_url: url, android_url: url },
+                    ],
+                },
+            ],
+        },
+    };
+    return JSON.stringify(card);
+}
+function buildResumeButton(record, target) {
+    if (record.kind === "thread" && record.threadId) {
+        return {
+            tag: "button",
+            text: { tag: "plain_text", content: "转发到此" },
+            type: "primary",
+            size: "small",
+            behaviors: [
+                {
+                    type: "callback",
+                    value: {
+                        kind: "resume_forward",
+                        shortId: record.shortId,
+                        sourceThreadId: record.threadId,
+                        targetChatId: target.chatId,
+                        ...(target.threadId ? { targetThreadId: target.threadId } : {}),
+                    },
+                },
+            ],
+        };
+    }
+    const url = buildChatApplink(record.chatId);
+    return {
+        tag: "button",
+        text: { tag: "plain_text", content: "打开" },
+        type: "primary",
+        size: "small",
+        behaviors: [
+            { type: "open_url", default_url: url, pc_url: url, ios_url: url, android_url: url },
+        ],
+    };
+}
+/**
+ * Build a CardKit 2.0 card listing recent conversations. Each row shows the
+ * title + short id, with a button that either opens the chat (applink) or
+ * forwards the topic thread into `targetChatId`.
+ */
+export function buildResumeCardJson(records, target) {
+    const elements = records.map((record, index) => ({
+        tag: "column_set",
+        flex_mode: "none",
+        horizontal_align: "left",
+        columns: [
+            {
+                tag: "column",
+                width: "weighted",
+                weight: 1,
+                vertical_align: "center",
+                elements: [
+                    {
+                        tag: "markdown",
+                        content: `**${index + 1}.** ${record.title}  <font color='grey'>\`${record.shortId}\`</font>`,
+                    },
+                ],
+            },
+            {
+                tag: "column",
+                width: "auto",
+                vertical_align: "center",
+                elements: [buildResumeButton(record, target)],
+            },
+        ],
+    }));
+    const card = {
+        schema: "2.0",
+        header: {
+            title: { tag: "plain_text", content: "最近会话" },
+            template: "blue",
+        },
+        body: { elements },
+    };
+    return JSON.stringify(card);
+}

package/dist/lark-sdk/client.d.ts

@@ -0,0 +1,8 @@
+import * as Lark from "@larksuiteoapi/node-sdk";
+export interface LarkSdkClientConfig {
+    appId?: string;
+    appSecret?: string;
+}
+export declare function createLarkSdkClientConfig(env?: NodeJS.ProcessEnv): LarkSdkClientConfig;
+export declare function createLarkSdkClient(config?: LarkSdkClientConfig, logger?: Lark.Logger): Lark.Client;
+export declare function createLarkWsClient(config?: LarkSdkClientConfig, logger?: Lark.Logger): Lark.WSClient;

package/dist/lark-sdk/client.js

@@ -0,0 +1,32 @@
+import * as Lark from "@larksuiteoapi/node-sdk";
+export function createLarkSdkClientConfig(env = process.env) {
+    return {
+        appId: env.LARK_APP_ID?.trim() || undefined,
+        appSecret: env.LARK_APP_SECRET?.trim() || undefined,
+    };
+}
+export function createLarkSdkClient(config = createLarkSdkClientConfig(), logger) {
+    return new Lark.Client({
+        appId: requireLarkConfig(config.appId, "LARK_APP_ID"),
+        appSecret: requireLarkConfig(config.appSecret, "LARK_APP_SECRET"),
+        appType: Lark.AppType.SelfBuild,
+        domain: Lark.Domain.Feishu,
+        loggerLevel: Lark.LoggerLevel.info,
+        ...(logger ? { logger } : {}),
+    });
+}
+export function createLarkWsClient(config = createLarkSdkClientConfig(), logger) {
+    return new Lark.WSClient({
+        appId: requireLarkConfig(config.appId, "LARK_APP_ID"),
+        appSecret: requireLarkConfig(config.appSecret, "LARK_APP_SECRET"),
+        autoReconnect: true,
+        loggerLevel: Lark.LoggerLevel.info,
+        ...(logger ? { logger } : {}),
+    });
+}
+function requireLarkConfig(value, key) {
+    if (!value) {
+        throw new Error(`Missing required configuration ${key}`);
+    }
+    return value;
+}

package/dist/lark-sdk/index.d.ts

@@ -0,0 +1 @@
+export * from "./client.js";

package/dist/lark-sdk/index.js

@@ -0,0 +1 @@
+export * from "./client.js";

package/dist/lark-sender.d.ts

@@ -0,0 +1,114 @@
+import * as Lark from "@larksuiteoapi/node-sdk";
+import type { LarkFetchedMessage, LarkMessageSender, LarkWsClientProvider, LarkWsClientStartOptions } from "./lark.js";
+export declare class LarkSdkMessageSender implements LarkMessageSender {
+    private readonly client;
+    constructor(client: Lark.Client);
+    getMessage({ messageId }: {
+        messageId: string;
+    }): Promise<LarkFetchedMessage | null>;
+    createText({ chatId, text, uuid, }: {
+        chatId: string;
+        text: string;
+        uuid: string;
+    }): Promise<void>;
+    createReaction({ messageId, emojiType, }: {
+        messageId: string;
+        emojiType: string;
+    }): Promise<string | undefined>;
+    deleteReaction({ messageId, reactionId, }: {
+        messageId: string;
+        reactionId: string;
+    }): Promise<void>;
+    replyText({ messageId, text, uuid, replyInThread, }: {
+        messageId: string;
+        text: string;
+        uuid: string;
+        replyInThread: boolean;
+    }): Promise<void>;
+    createCard({ cardJson }: {
+        cardJson: string;
+    }): Promise<{
+        cardId: string;
+    }>;
+    batchUpdateCard({ cardId, sequence, actions, uuid, }: {
+        cardId: string;
+        sequence: number;
+        actions: string;
+        uuid?: string;
+    }): Promise<void>;
+    sendInteractive({ chatId, cardId, uuid, }: {
+        chatId: string;
+        cardId: string;
+        uuid: string;
+    }): Promise<{
+        messageId: string;
+    }>;
+    replyInteractive({ messageId, cardId, uuid, replyInThread, }: {
+        messageId: string;
+        cardId: string;
+        uuid: string;
+        replyInThread: boolean;
+    }): Promise<{
+        messageId: string;
+    }>;
+    forwardThread({ threadId, receiveId, receiveIdType, uuid, }: {
+        /** Source thread being forwarded. */
+        threadId: string;
+        /** Target id: a chat_id, or a thread_id to land inside that thread. */
+        receiveId: string;
+        receiveIdType: "chat_id" | "thread_id";
+        uuid: string;
+    }): Promise<void>;
+    sendText({ chatId, text, uuid, }: {
+        chatId: string;
+        text: string;
+        uuid: string;
+    }): Promise<{
+        messageId: string;
+        threadId?: string;
+    }>;
+    createChat({ name, userIdList, uuid, }: {
+        name: string;
+        userIdList: string[];
+        uuid: string;
+    }): Promise<{
+        chatId: string;
+    }>;
+    getChat({ chatId }: {
+        chatId: string;
+    }): Promise<{
+        name: string;
+    }>;
+    listChatMembers({ chatId, }: {
+        chatId: string;
+    }): Promise<Array<{
+        memberId: string;
+        name: string;
+    }>>;
+    listMessages({ containerIdType, containerId, pageSize, }: {
+        containerIdType: "chat" | "thread";
+        containerId: string;
+        pageSize?: number;
+    }): Promise<Array<{
+        msgType: string;
+        senderId?: string;
+        senderType?: string;
+        content: string;
+    }>>;
+}
+export declare class LarkClientProvider implements LarkWsClientProvider {
+    readonly client: Lark.Client;
+    private readonly wsClient;
+    private botOpenIdPromise?;
+    constructor(options?: Record<string, unknown>, logger?: Lark.Logger);
+    getMessageSender(): LarkMessageSender;
+    /**
+     * This bot's own `open_id`, fetched once from the bot info API and memoized.
+     * Lets the ingestor tell, in a group hosting multiple bots, whether an
+     * incoming `@` actually targets us. Returns `null` if the lookup fails so the
+     * caller can fall back to its legacy behavior rather than going silent.
+     */
+    getBotOpenId(): Promise<string | null>;
+    start({ onMessage, onCardAction }: LarkWsClientStartOptions): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/lark-sender.js

@@ -0,0 +1,323 @@
+import * as Lark from "@larksuiteoapi/node-sdk";
+import { createLarkSdkClient, createLarkWsClient } from "./lark-sdk/index.js";
+export class LarkSdkMessageSender {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async getMessage({ messageId }) {
+        const response = await this.client.im.v1.message.get({
+            path: {
+                message_id: messageId,
+            },
+        });
+        if (response.code && response.code !== 0) {
+            throw new Error(response.msg ?? "Failed to get the Feishu message.");
+        }
+        const item = response.data?.items?.[0];
+        if (!item) {
+            return null;
+        }
+        return {
+            messageId: item.message_id,
+            msgType: item.msg_type,
+            body: {
+                content: item.body?.content,
+            },
+        };
+    }
+    async createText({ chatId, text, uuid, }) {
+        const response = await this.client.im.message.create({
+            params: {
+                receive_id_type: "chat_id",
+            },
+            data: {
+                receive_id: chatId,
+                msg_type: "text",
+                content: JSON.stringify({ text }),
+                uuid,
+            },
+        });
+        if (response.code && response.code !== 0) {
+            throw new Error(response.msg ?? "Failed to send Feishu chat message.");
+        }
+    }
+    async createReaction({ messageId, emojiType, }) {
+        const response = await this.client.im.messageReaction.create({
+            path: {
+                message_id: messageId,
+            },
+            data: {
+                reaction_type: {
+                    emoji_type: emojiType,
+                },
+            },
+        });
+        if (response.code && response.code !== 0) {
+            throw new Error(response.msg ?? "Failed to add Feishu message reaction.");
+        }
+        return response.data?.reaction_id;
+    }
+    async deleteReaction({ messageId, reactionId, }) {
+        const response = await this.client.im.messageReaction.delete({
+            path: {
+                message_id: messageId,
+                reaction_id: reactionId,
+            },
+        });
+        if (response.code && response.code !== 0) {
+            throw new Error(response.msg ?? "Failed to delete Feishu message reaction.");
+        }
+    }
+    async replyText({ messageId, text, uuid, replyInThread, }) {
+        const response = await this.client.im.message.reply({
+            path: {
+                message_id: messageId,
+            },
+            data: {
+                msg_type: "text",
+                content: JSON.stringify({ text }),
+                reply_in_thread: replyInThread,
+                uuid,
+            },
+        });
+        if (response.code && response.code !== 0) {
+            throw new Error(response.msg ?? "Failed to reply to the Feishu message.");
+        }
+    }
+    async createCard({ cardJson }) {
+        const response = await this.client.cardkit.v1.card.create({
+            data: {
+                type: "card_json",
+                data: cardJson,
+            },
+        });
+        if (response.code && response.code !== 0) {
+            throw new Error(response.msg ?? "Failed to create the Feishu CardKit card.");
+        }
+        const cardId = response.data?.card_id;
+        if (!cardId) {
+            throw new Error("Feishu CardKit create returned no card_id.");
+        }
+        return { cardId };
+    }
+    async batchUpdateCard({ cardId, sequence, actions, uuid, }) {
+        const response = await this.client.cardkit.v1.card.batchUpdate({
+            data: {
+                sequence,
+                actions,
+                ...(uuid ? { uuid } : {}),
+            },
+            path: {
+                card_id: cardId,
+            },
+        });
+        if (response.code && response.code !== 0) {
+            throw new Error(response.msg ?? "Failed to batch update the Feishu CardKit card.");
+        }
+    }
+    async sendInteractive({ chatId, cardId, uuid, }) {
+        const response = await this.client.im.message.create({
+            params: {
+                receive_id_type: "chat_id",
+            },
+            data: {
+                receive_id: chatId,
+                msg_type: "interactive",
+                content: JSON.stringify({ type: "card", data: { card_id: cardId } }),
+                uuid,
+            },
+        });
+        if (response.code && response.code !== 0) {
+            throw new Error(response.msg ?? "Failed to send the Feishu interactive card.");
+        }
+        const messageId = response.data?.message_id;
+        if (!messageId) {
+            throw new Error("Feishu interactive send returned no message_id.");
+        }
+        return { messageId };
+    }
+    async replyInteractive({ messageId, cardId, uuid, replyInThread, }) {
+        const response = await this.client.im.message.reply({
+            path: {
+                message_id: messageId,
+            },
+            data: {
+                msg_type: "interactive",
+                content: JSON.stringify({ type: "card", data: { card_id: cardId } }),
+                reply_in_thread: replyInThread,
+                uuid,
+            },
+        });
+        if (response.code && response.code !== 0) {
+            throw new Error(response.msg ?? "Failed to reply with the Feishu interactive card.");
+        }
+        const replyMessageId = response.data?.message_id;
+        if (!replyMessageId) {
+            throw new Error("Feishu interactive reply returned no message_id.");
+        }
+        return { messageId: replyMessageId };
+    }
+    async forwardThread({ threadId, receiveId, receiveIdType, uuid, }) {
+        const response = await this.client.im.v1.thread.forward({
+            path: { thread_id: threadId },
+            params: { receive_id_type: receiveIdType, uuid },
+            data: { receive_id: receiveId },
+        });
+        if (response.code && response.code !== 0) {
+            throw new Error(response.msg ?? "Failed to forward the Feishu thread.");
+        }
+    }
+    async sendText({ chatId, text, uuid, }) {
+        const response = await this.client.im.message.create({
+            params: { receive_id_type: "chat_id" },
+            data: {
+                receive_id: chatId,
+                msg_type: "text",
+                content: JSON.stringify({ text }),
+                uuid,
+            },
+        });
+        if (response.code && response.code !== 0) {
+            throw new Error(response.msg ?? "Failed to send Feishu chat message.");
+        }
+        const data = response.data;
+        return { messageId: data?.message_id ?? "", threadId: data?.thread_id };
+    }
+    async createChat({ name, userIdList, uuid, }) {
+        const response = await this.client.im.v1.chat.create({
+            params: { user_id_type: "open_id", uuid },
+            data: { name, user_id_list: userIdList, group_message_type: "chat" },
+        });
+        if (response.code && response.code !== 0) {
+            throw new Error(response.msg ?? "Failed to create the Feishu chat.");
+        }
+        const chatId = response.data?.chat_id;
+        if (!chatId) {
+            throw new Error("Feishu chat create returned no chat_id.");
+        }
+        return { chatId };
+    }
+    async getChat({ chatId }) {
+        const response = await this.client.im.v1.chat.get({ path: { chat_id: chatId } });
+        if (response.code && response.code !== 0) {
+            throw new Error(response.msg ?? "Failed to get the Feishu chat.");
+        }
+        const name = response.data?.name ?? "";
+        return { name };
+    }
+    async listChatMembers({ chatId, }) {
+        const response = await this.client.im.v1.chatMembers.get({
+            path: { chat_id: chatId },
+            params: { member_id_type: "open_id", page_size: 100 },
+        });
+        if (response.code && response.code !== 0) {
+            throw new Error(response.msg ?? "Failed to list Feishu chat members.");
+        }
+        const items = response.data
+            ?.items ?? [];
+        return items
+            .filter((item) => item.member_id)
+            .map((item) => ({ memberId: item.member_id, name: item.name ?? "" }));
+    }
+    async listMessages({ containerIdType, containerId, pageSize = 50, }) {
+        const response = await this.client.im.v1.message.list({
+            params: {
+                container_id_type: containerIdType,
+                container_id: containerId,
+                sort_type: "ByCreateTimeAsc",
+                page_size: pageSize,
+            },
+        });
+        if (response.code && response.code !== 0) {
+            throw new Error(response.msg ?? "Failed to list Feishu messages.");
+        }
+        const items = response.data?.items ?? [];
+        return items.map((item) => ({
+            msgType: item.msg_type ?? "",
+            senderId: item.sender?.id,
+            senderType: item.sender?.sender_type,
+            content: item.body?.content ?? "",
+        }));
+    }
+}
+/** Read a per-instance string option, trimmed; undefined when absent/blank. */
+function larkOption(options, key) {
+    const value = options?.[key];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+export class LarkClientProvider {
+    client;
+    wsClient;
+    botOpenIdPromise;
+    constructor(options, logger) {
+        // Credentials come from this channel instance's stored config (`options`).
+        const appId = larkOption(options, "LARK_APP_ID");
+        const appSecret = larkOption(options, "LARK_APP_SECRET");
+        this.client = createLarkSdkClient({ appId: appId, appSecret: appSecret }, logger);
+        this.wsClient = createLarkWsClient({ appId: appId, appSecret: appSecret }, logger);
+    }
+    getMessageSender() {
+        return new LarkSdkMessageSender(this.client);
+    }
+    /**
+     * This bot's own `open_id`, fetched once from the bot info API and memoized.
+     * Lets the ingestor tell, in a group hosting multiple bots, whether an
+     * incoming `@` actually targets us. Returns `null` if the lookup fails so the
+     * caller can fall back to its legacy behavior rather than going silent.
+     */
+    async getBotOpenId() {
+        if (!this.botOpenIdPromise) {
+            this.botOpenIdPromise = this.client
+                .request({
+                method: "GET",
+                url: "/open-apis/bot/v3/info",
+            })
+                .then((response) => response?.bot?.open_id ?? null)
+                .catch(() => null);
+        }
+        return this.botOpenIdPromise;
+    }
+    async start({ onMessage, onCardAction }) {
+        const handlers = {
+            "im.message.receive_v1": async (data) => {
+                onMessage(data);
+            },
+        };
+        if (onCardAction) {
+            // Feishu CardKit button clicks arrive as `card.action.trigger` events
+            // over the same WS pipe (self-built bot, persistent connection).
+            // The return value (e.g. `{ toast: {...} }`) is forwarded back to
+            // Feishu so the user gets immediate UI feedback — also required for
+            // Feishu to consider the callback well-formed (avoids error 200340).
+            handlers["card.action.trigger"] = async (data) => {
+                const payload = data;
+                const rawValue = payload.action?.value;
+                const value = rawValue && typeof rawValue === "object" && !Array.isArray(rawValue)
+                    ? rawValue
+                    : null;
+                // `option` carries the picked value of a `select_static`; `form_value`
+                // carries all fields of a `form_submit`. Both are surfaced so settings
+                // cards can read selections without a dedicated form round-trip.
+                const option = typeof payload.action?.option === "string" ? payload.action.option : null;
+                const rawForm = payload.action?.form_value;
+                const formValue = rawForm && typeof rawForm === "object" && !Array.isArray(rawForm)
+                    ? rawForm
+                    : null;
+                return await onCardAction({
+                    value,
+                    option,
+                    formValue,
+                    messageId: payload.context?.open_message_id,
+                });
+            };
+        }
+        const eventDispatcher = new Lark.EventDispatcher({}).register(handlers);
+        await this.wsClient.start({
+            eventDispatcher,
+        });
+    }
+    async stop() {
+        this.wsClient.close();
+    }
+}

package/dist/lark-session-store.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Lark binding over the channel-agnostic @rynx-ai/core conversation session store.
+ * The store engine (the conversation → current-session + execution binding) lives
+ * in core; Lark only supplies the per-instance file path + keeps the historical
+ * `Lark*` export names so existing importers are unchanged.
+ */
+import { FileConversationSessionStore, type ConversationSessionStoreOptions } from "@rynx-ai/core";
+export type { ConversationSessionRecord as LarkActiveSessionRecord, ConversationSessionStore as LarkActiveSessionStore, SessionSettingsUpdate as LarkSettingsUpdate, EnsureSessionResult as LarkEnsureSessionResult, RotateSessionResult as LarkRotateSessionResult, SessionExecution as LarkSessionExecution, } from "@rynx-ai/core";
+/** File-backed active-session store for a Lark bot instance: the core engine with
+ *  the Lark per-instance file path injected by default. */
+export declare class FileLarkActiveSessionStore extends FileConversationSessionStore {
+    constructor(options: ConversationSessionStoreOptions);
+}

package/dist/lark-session-store.js

@@ -0,0 +1,14 @@
+/**
+ * Lark binding over the channel-agnostic @rynx-ai/core conversation session store.
+ * The store engine (the conversation → current-session + execution binding) lives
+ * in core; Lark only supplies the per-instance file path + keeps the historical
+ * `Lark*` export names so existing importers are unchanged.
+ */
+import { FileConversationSessionStore, } from "@rynx-ai/core";
+/** File-backed active-session store for a Lark bot instance: the core engine with
+ *  the Lark per-instance file path injected by default. */
+export class FileLarkActiveSessionStore extends FileConversationSessionStore {
+    constructor(options) {
+        super(options);
+    }
+}

package/dist/lark-settings-card.d.ts

@@ -0,0 +1,55 @@
+import type { AgentRuntimeId } from "@rynx-ai/core";
+import type { ReasoningEffort } from "@rynx-ai/core";
+/** Sentinel option value meaning "use the runtime/model default". */
+export declare const SETTINGS_DEFAULT_VALUE = "__default__";
+export interface SettingsCardModelOption {
+    value: string;
+    label: string;
+    isDefault?: boolean;
+    /** Reasoning efforts this model supports; empty/unknown → full effort set. */
+    supportedEfforts?: ReasoningEffort[];
+}
+export interface SettingsCardRuntimeOption {
+    value: AgentRuntimeId;
+    label: string;
+}
+export interface SettingsCardInput {
+    sessionKey: string;
+    /** `/runtime` shows the runtime selector; `/model` hides it. */
+    includeRuntime: boolean;
+    runtimeOptions: SettingsCardRuntimeOption[];
+    /** Models available for the selected runtime (excludes the default sentinel). */
+    models: SettingsCardModelOption[];
+    /** Pre-selected dropdown values (drive `initial_option`). */
+    selectedRuntime: AgentRuntimeId;
+    selectedModel: string;
+    selectedEffort: string;
+}
+export declare const SETTINGS_EFFORT_VALUES: ReasoningEffort[];
+/**
+ * Build the `/runtime` / `/model` settings card object: dropdowns for runtime
+ * (optional), model and reasoning effort, plus confirm / cancel buttons.
+ * Selections round-trip via `card.action.trigger` callbacks (`settings_select`
+ * per change — runtime/model changes re-render this card; `settings_apply` /
+ * `settings_cancel` on the buttons). The effort options reflect the currently
+ * selected model's supported efforts.
+ */
+export declare function buildSettingsCard(input: SettingsCardInput): Record<string, unknown>;
+/** String form of {@link buildSettingsCard} (for the initial card send). */
+export declare function buildSettingsCardJson(input: SettingsCardInput): string;
+/**
+ * Build a static result card shown after the user confirms or cancels the
+ * settings card — replaces the interactive form with a plain conclusion.
+ * Returned as a plain object so it can be embedded in a card-action response.
+ */
+export declare function buildSettingsResultCard(input: {
+    includeRuntime: boolean;
+    template: "green" | "grey";
+    content: string;
+}): Record<string, unknown>;
+/** String form of {@link buildSettingsResultCard}. */
+export declare function buildSettingsResultCardJson(input: {
+    includeRuntime: boolean;
+    template: "green" | "grey";
+    content: string;
+}): string;