@nextclaw/channel-plugin-feishu 0.2.12 → 0.2.14

package/src/streaming-card.ts

@@ -0,0 +1,374 @@
+/**
+ * Feishu Streaming Card - Card Kit streaming API for real-time text output
+ */
+
+import type { Client } from "@larksuiteoapi/node-sdk";
+import { fetchWithSsrFGuard } from "openclaw/plugin-sdk/feishu";
+import type { FeishuDomain } from "./types.js";
+
+type Credentials = { appId: string; appSecret: string; domain?: FeishuDomain };
+type CardState = { cardId: string; messageId: string; sequence: number; currentText: string };
+
+/** Optional header for streaming cards (title bar with color template) */
+export type StreamingCardHeader = {
+  title: string;
+  /** Color template: blue, green, red, orange, purple, indigo, wathet, turquoise, yellow, grey, carmine, violet, lime */
+  template?: string;
+};
+
+type StreamingStartOptions = {
+  replyToMessageId?: string;
+  replyInThread?: boolean;
+  rootId?: string;
+  header?: StreamingCardHeader;
+};
+
+// Token cache (keyed by domain + appId)
+const tokenCache = new Map<string, { token: string; expiresAt: number }>();
+
+function resolveApiBase(domain?: FeishuDomain): string {
+  if (domain === "lark") {
+    return "https://open.larksuite.com/open-apis";
+  }
+  if (domain && domain !== "feishu" && domain.startsWith("http")) {
+    return `${domain.replace(/\/+$/, "")}/open-apis`;
+  }
+  return "https://open.feishu.cn/open-apis";
+}
+
+function resolveAllowedHostnames(domain?: FeishuDomain): string[] {
+  if (domain === "lark") {
+    return ["open.larksuite.com"];
+  }
+  if (domain && domain !== "feishu" && domain.startsWith("http")) {
+    try {
+      return [new URL(domain).hostname];
+    } catch {
+      return [];
+    }
+  }
+  return ["open.feishu.cn"];
+}
+
+async function getToken(creds: Credentials): Promise<string> {
+  const key = `${creds.domain ?? "feishu"}|${creds.appId}`;
+  const cached = tokenCache.get(key);
+  if (cached && cached.expiresAt > Date.now() + 60000) {
+    return cached.token;
+  }
+
+  const { response, release } = await fetchWithSsrFGuard({
+    url: `${resolveApiBase(creds.domain)}/auth/v3/tenant_access_token/internal`,
+    init: {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ app_id: creds.appId, app_secret: creds.appSecret }),
+    },
+    policy: { allowedHostnames: resolveAllowedHostnames(creds.domain) },
+    auditContext: "feishu.streaming-card.token",
+  });
+  if (!response.ok) {
+    await release();
+    throw new Error(`Token request failed with HTTP ${response.status}`);
+  }
+  const data = (await response.json()) as {
+    code: number;
+    msg: string;
+    tenant_access_token?: string;
+    expire?: number;
+  };
+  await release();
+  if (data.code !== 0 || !data.tenant_access_token) {
+    throw new Error(`Token error: ${data.msg}`);
+  }
+  tokenCache.set(key, {
+    token: data.tenant_access_token,
+    expiresAt: Date.now() + (data.expire ?? 7200) * 1000,
+  });
+  return data.tenant_access_token;
+}
+
+function truncateSummary(text: string, max = 50): string {
+  if (!text) {
+    return "";
+  }
+  const clean = text.replace(/\n/g, " ").trim();
+  return clean.length <= max ? clean : clean.slice(0, max - 3) + "...";
+}
+
+export function mergeStreamingText(
+  previousText: string | undefined,
+  nextText: string | undefined,
+): string {
+  const previous = typeof previousText === "string" ? previousText : "";
+  const next = typeof nextText === "string" ? nextText : "";
+  if (!next) {
+    return previous;
+  }
+  if (!previous || next === previous) {
+    return next;
+  }
+  if (next.startsWith(previous)) {
+    return next;
+  }
+  if (previous.startsWith(next)) {
+    return previous;
+  }
+  if (next.includes(previous)) {
+    return next;
+  }
+  if (previous.includes(next)) {
+    return previous;
+  }
+
+  // Merge partial overlaps, e.g. "这" + "这是" => "这是".
+  const maxOverlap = Math.min(previous.length, next.length);
+  for (let overlap = maxOverlap; overlap > 0; overlap -= 1) {
+    if (previous.slice(-overlap) === next.slice(0, overlap)) {
+      return `${previous}${next.slice(overlap)}`;
+    }
+  }
+  // Fallback for fragmented partial chunks: append as-is to avoid losing tokens.
+  return `${previous}${next}`;
+}
+
+export function resolveStreamingCardSendMode(options?: StreamingStartOptions) {
+  if (options?.replyToMessageId) {
+    return "reply";
+  }
+  if (options?.rootId) {
+    return "root_create";
+  }
+  return "create";
+}
+
+/** Streaming card session manager */
+export class FeishuStreamingSession {
+  private client: Client;
+  private creds: Credentials;
+  private state: CardState | null = null;
+  private queue: Promise<void> = Promise.resolve();
+  private closed = false;
+  private log?: (msg: string) => void;
+  private lastUpdateTime = 0;
+  private pendingText: string | null = null;
+  private updateThrottleMs = 100; // Throttle updates to max 10/sec
+
+  constructor(client: Client, creds: Credentials, log?: (msg: string) => void) {
+    this.client = client;
+    this.creds = creds;
+    this.log = log;
+  }
+
+  async start(
+    receiveId: string,
+    receiveIdType: "open_id" | "user_id" | "union_id" | "email" | "chat_id" = "chat_id",
+    options?: StreamingStartOptions,
+  ): Promise<void> {
+    if (this.state) {
+      return;
+    }
+
+    const apiBase = resolveApiBase(this.creds.domain);
+    const cardJson: Record<string, unknown> = {
+      schema: "2.0",
+      config: {
+        streaming_mode: true,
+        summary: { content: "[Generating...]" },
+        streaming_config: { print_frequency_ms: { default: 50 }, print_step: { default: 1 } },
+      },
+      body: {
+        elements: [{ tag: "markdown", content: "⏳ Thinking...", element_id: "content" }],
+      },
+    };
+    if (options?.header) {
+      cardJson.header = {
+        title: { tag: "plain_text", content: options.header.title },
+        template: options.header.template ?? "blue",
+      };
+    }
+
+    // Create card entity
+    const { response: createRes, release: releaseCreate } = await fetchWithSsrFGuard({
+      url: `${apiBase}/cardkit/v1/cards`,
+      init: {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${await getToken(this.creds)}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ type: "card_json", data: JSON.stringify(cardJson) }),
+      },
+      policy: { allowedHostnames: resolveAllowedHostnames(this.creds.domain) },
+      auditContext: "feishu.streaming-card.create",
+    });
+    if (!createRes.ok) {
+      await releaseCreate();
+      throw new Error(`Create card request failed with HTTP ${createRes.status}`);
+    }
+    const createData = (await createRes.json()) as {
+      code: number;
+      msg: string;
+      data?: { card_id: string };
+    };
+    await releaseCreate();
+    if (createData.code !== 0 || !createData.data?.card_id) {
+      throw new Error(`Create card failed: ${createData.msg}`);
+    }
+    const cardId = createData.data.card_id;
+    const cardContent = JSON.stringify({ type: "card", data: { card_id: cardId } });
+
+    // Prefer message.reply when we have a reply target — reply_in_thread
+    // reliably routes streaming cards into Feishu topics, whereas
+    // message.create with root_id may silently ignore root_id for card
+    // references (card_id format).
+    let sendRes;
+    const sendOptions = options ?? {};
+    const sendMode = resolveStreamingCardSendMode(sendOptions);
+    if (sendMode === "reply") {
+      sendRes = await this.client.im.message.reply({
+        path: { message_id: sendOptions.replyToMessageId! },
+        data: {
+          msg_type: "interactive",
+          content: cardContent,
+          ...(sendOptions.replyInThread ? { reply_in_thread: true } : {}),
+        },
+      });
+    } else if (sendMode === "root_create") {
+      // root_id is undeclared in the SDK types but accepted at runtime
+      sendRes = await this.client.im.message.create({
+        params: { receive_id_type: receiveIdType },
+        data: Object.assign(
+          { receive_id: receiveId, msg_type: "interactive", content: cardContent },
+          { root_id: sendOptions.rootId },
+        ),
+      });
+    } else {
+      sendRes = await this.client.im.message.create({
+        params: { receive_id_type: receiveIdType },
+        data: {
+          receive_id: receiveId,
+          msg_type: "interactive",
+          content: cardContent,
+        },
+      });
+    }
+    if (sendRes.code !== 0 || !sendRes.data?.message_id) {
+      throw new Error(`Send card failed: ${sendRes.msg}`);
+    }
+
+    this.state = { cardId, messageId: sendRes.data.message_id, sequence: 1, currentText: "" };
+    this.log?.(`Started streaming: cardId=${cardId}, messageId=${sendRes.data.message_id}`);
+  }
+
+  private async updateCardContent(text: string, onError?: (error: unknown) => void): Promise<void> {
+    if (!this.state) {
+      return;
+    }
+    const apiBase = resolveApiBase(this.creds.domain);
+    this.state.sequence += 1;
+    await fetchWithSsrFGuard({
+      url: `${apiBase}/cardkit/v1/cards/${this.state.cardId}/elements/content/content`,
+      init: {
+        method: "PUT",
+        headers: {
+          Authorization: `Bearer ${await getToken(this.creds)}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          content: text,
+          sequence: this.state.sequence,
+          uuid: `s_${this.state.cardId}_${this.state.sequence}`,
+        }),
+      },
+      policy: { allowedHostnames: resolveAllowedHostnames(this.creds.domain) },
+      auditContext: "feishu.streaming-card.update",
+    })
+      .then(async ({ release }) => {
+        await release();
+      })
+      .catch((error) => onError?.(error));
+  }
+
+  async update(text: string): Promise<void> {
+    if (!this.state || this.closed) {
+      return;
+    }
+    const mergedInput = mergeStreamingText(this.pendingText ?? this.state.currentText, text);
+    if (!mergedInput || mergedInput === this.state.currentText) {
+      return;
+    }
+
+    // Throttle: skip if updated recently, but remember pending text
+    const now = Date.now();
+    if (now - this.lastUpdateTime < this.updateThrottleMs) {
+      this.pendingText = mergedInput;
+      return;
+    }
+    this.pendingText = null;
+    this.lastUpdateTime = now;
+
+    this.queue = this.queue.then(async () => {
+      if (!this.state || this.closed) {
+        return;
+      }
+      const mergedText = mergeStreamingText(this.state.currentText, mergedInput);
+      if (!mergedText || mergedText === this.state.currentText) {
+        return;
+      }
+      this.state.currentText = mergedText;
+      await this.updateCardContent(mergedText, (e) => this.log?.(`Update failed: ${String(e)}`));
+    });
+    await this.queue;
+  }
+
+  async close(finalText?: string): Promise<void> {
+    if (!this.state || this.closed) {
+      return;
+    }
+    this.closed = true;
+    await this.queue;
+
+    const pendingMerged = mergeStreamingText(this.state.currentText, this.pendingText ?? undefined);
+    const text = finalText ? mergeStreamingText(pendingMerged, finalText) : pendingMerged;
+    const apiBase = resolveApiBase(this.creds.domain);
+
+    // Only send final update if content differs from what's already displayed
+    if (text && text !== this.state.currentText) {
+      await this.updateCardContent(text);
+      this.state.currentText = text;
+    }
+
+    // Close streaming mode
+    this.state.sequence += 1;
+    await fetchWithSsrFGuard({
+      url: `${apiBase}/cardkit/v1/cards/${this.state.cardId}/settings`,
+      init: {
+        method: "PATCH",
+        headers: {
+          Authorization: `Bearer ${await getToken(this.creds)}`,
+          "Content-Type": "application/json; charset=utf-8",
+        },
+        body: JSON.stringify({
+          settings: JSON.stringify({
+            config: { streaming_mode: false, summary: { content: truncateSummary(text) } },
+          }),
+          sequence: this.state.sequence,
+          uuid: `c_${this.state.cardId}_${this.state.sequence}`,
+        }),
+      },
+      policy: { allowedHostnames: resolveAllowedHostnames(this.creds.domain) },
+      auditContext: "feishu.streaming-card.close",
+    })
+      .then(async ({ release }) => {
+        await release();
+      })
+      .catch((e) => this.log?.(`Close failed: ${String(e)}`));
+
+    this.log?.(`Closed streaming: cardId=${this.state.cardId}`);
+  }
+
+  isActive(): boolean {
+    return this.state !== null && !this.closed;
+  }
+}

package/src/targets.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import { looksLikeFeishuId, normalizeFeishuTarget, resolveReceiveIdType } from "./targets.js";
+
+describe("resolveReceiveIdType", () => {
+  it("resolves chat IDs by oc_ prefix", () => {
+    expect(resolveReceiveIdType("oc_123")).toBe("chat_id");
+  });
+
+  it("resolves open IDs by ou_ prefix", () => {
+    expect(resolveReceiveIdType("ou_123")).toBe("open_id");
+  });
+
+  it("defaults unprefixed IDs to user_id", () => {
+    expect(resolveReceiveIdType("u_123")).toBe("user_id");
+  });
+
+  it("treats explicit group targets as chat_id", () => {
+    expect(resolveReceiveIdType("group:oc_123")).toBe("chat_id");
+  });
+
+  it("treats explicit channel targets as chat_id", () => {
+    expect(resolveReceiveIdType("channel:oc_123")).toBe("chat_id");
+  });
+
+  it("treats dm-prefixed open IDs as open_id", () => {
+    expect(resolveReceiveIdType("dm:ou_123")).toBe("open_id");
+  });
+});
+
+describe("normalizeFeishuTarget", () => {
+  it("strips provider and user prefixes", () => {
+    expect(normalizeFeishuTarget("feishu:user:ou_123")).toBe("ou_123");
+    expect(normalizeFeishuTarget("lark:user:ou_123")).toBe("ou_123");
+  });
+
+  it("strips provider and chat prefixes", () => {
+    expect(normalizeFeishuTarget("feishu:chat:oc_123")).toBe("oc_123");
+  });
+
+  it("normalizes group/channel prefixes to chat ids", () => {
+    expect(normalizeFeishuTarget("group:oc_123")).toBe("oc_123");
+    expect(normalizeFeishuTarget("feishu:group:oc_123")).toBe("oc_123");
+    expect(normalizeFeishuTarget("channel:oc_456")).toBe("oc_456");
+    expect(normalizeFeishuTarget("lark:channel:oc_456")).toBe("oc_456");
+  });
+
+  it("accepts provider-prefixed raw ids", () => {
+    expect(normalizeFeishuTarget("feishu:ou_123")).toBe("ou_123");
+  });
+
+  it("strips provider and dm prefixes", () => {
+    expect(normalizeFeishuTarget("lark:dm:ou_123")).toBe("ou_123");
+  });
+});
+
+describe("looksLikeFeishuId", () => {
+  it("accepts provider-prefixed user targets", () => {
+    expect(looksLikeFeishuId("feishu:user:ou_123")).toBe(true);
+  });
+
+  it("accepts provider-prefixed chat targets", () => {
+    expect(looksLikeFeishuId("lark:chat:oc_123")).toBe(true);
+  });
+
+  it("accepts group/channel targets", () => {
+    expect(looksLikeFeishuId("feishu:group:oc_123")).toBe(true);
+    expect(looksLikeFeishuId("group:oc_123")).toBe(true);
+    expect(looksLikeFeishuId("channel:oc_456")).toBe(true);
+  });
+});

package/src/targets.ts

@@ -0,0 +1,107 @@
+import type { FeishuIdType } from "./types.js";
+
+const CHAT_ID_PREFIX = "oc_";
+const OPEN_ID_PREFIX = "ou_";
+const USER_ID_REGEX = /^[a-zA-Z0-9_-]+$/;
+
+function stripProviderPrefix(raw: string): string {
+  return raw.replace(/^(feishu|lark):/i, "").trim();
+}
+
+export function detectIdType(id: string): FeishuIdType | null {
+  const trimmed = id.trim();
+  if (trimmed.startsWith(CHAT_ID_PREFIX)) {
+    return "chat_id";
+  }
+  if (trimmed.startsWith(OPEN_ID_PREFIX)) {
+    return "open_id";
+  }
+  if (USER_ID_REGEX.test(trimmed)) {
+    return "user_id";
+  }
+  return null;
+}
+
+export function normalizeFeishuTarget(raw: string): string | null {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  const withoutProvider = stripProviderPrefix(trimmed);
+  const lowered = withoutProvider.toLowerCase();
+  if (lowered.startsWith("chat:")) {
+    return withoutProvider.slice("chat:".length).trim() || null;
+  }
+  if (lowered.startsWith("group:")) {
+    return withoutProvider.slice("group:".length).trim() || null;
+  }
+  if (lowered.startsWith("channel:")) {
+    return withoutProvider.slice("channel:".length).trim() || null;
+  }
+  if (lowered.startsWith("user:")) {
+    return withoutProvider.slice("user:".length).trim() || null;
+  }
+  if (lowered.startsWith("dm:")) {
+    return withoutProvider.slice("dm:".length).trim() || null;
+  }
+  if (lowered.startsWith("open_id:")) {
+    return withoutProvider.slice("open_id:".length).trim() || null;
+  }
+
+  return withoutProvider;
+}
+
+export function formatFeishuTarget(id: string, type?: FeishuIdType): string {
+  const trimmed = id.trim();
+  if (type === "chat_id" || trimmed.startsWith(CHAT_ID_PREFIX)) {
+    return `chat:${trimmed}`;
+  }
+  if (type === "open_id" || trimmed.startsWith(OPEN_ID_PREFIX)) {
+    return `user:${trimmed}`;
+  }
+  return trimmed;
+}
+
+export function resolveReceiveIdType(id: string): "chat_id" | "open_id" | "user_id" {
+  const trimmed = id.trim();
+  const lowered = trimmed.toLowerCase();
+  if (
+    lowered.startsWith("chat:") ||
+    lowered.startsWith("group:") ||
+    lowered.startsWith("channel:")
+  ) {
+    return "chat_id";
+  }
+  if (lowered.startsWith("open_id:")) {
+    return "open_id";
+  }
+  if (lowered.startsWith("user:") || lowered.startsWith("dm:")) {
+    const normalized = trimmed.replace(/^(user|dm):/i, "").trim();
+    return normalized.startsWith(OPEN_ID_PREFIX) ? "open_id" : "user_id";
+  }
+  if (trimmed.startsWith(CHAT_ID_PREFIX)) {
+    return "chat_id";
+  }
+  if (trimmed.startsWith(OPEN_ID_PREFIX)) {
+    return "open_id";
+  }
+  return "user_id";
+}
+
+export function looksLikeFeishuId(raw: string): boolean {
+  const trimmed = stripProviderPrefix(raw.trim());
+  if (!trimmed) {
+    return false;
+  }
+  if (/^(chat|group|channel|user|dm|open_id):/i.test(trimmed)) {
+    return true;
+  }
+  if (trimmed.startsWith(CHAT_ID_PREFIX)) {
+    return true;
+  }
+  if (trimmed.startsWith(OPEN_ID_PREFIX)) {
+    return true;
+  }
+  return false;
+}

package/src/tool-account-routing.test.ts

@@ -0,0 +1,129 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/feishu";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { registerFeishuBitableTools } from "./bitable.js";
+import { registerFeishuDriveTools } from "./drive.js";
+import { registerFeishuPermTools } from "./perm.js";
+import { createToolFactoryHarness } from "./tool-factory-test-harness.js";
+import { registerFeishuWikiTools } from "./wiki.js";
+
+const createFeishuClientMock = vi.fn((account: { appId?: string } | undefined) => ({
+  __appId: account?.appId,
+}));
+
+vi.mock("./client.js", () => ({
+  createFeishuClient: (account: { appId?: string } | undefined) => createFeishuClientMock(account),
+}));
+
+function createConfig(params: {
+  toolsA?: {
+    wiki?: boolean;
+    drive?: boolean;
+    perm?: boolean;
+  };
+  toolsB?: {
+    wiki?: boolean;
+    drive?: boolean;
+    perm?: boolean;
+  };
+  defaultAccount?: string;
+}): OpenClawPluginApi["config"] {
+  return {
+    channels: {
+      feishu: {
+        enabled: true,
+        defaultAccount: params.defaultAccount,
+        accounts: {
+          a: {
+            appId: "app-a",
+            appSecret: "sec-a", // pragma: allowlist secret
+            tools: params.toolsA,
+          },
+          b: {
+            appId: "app-b",
+            appSecret: "sec-b", // pragma: allowlist secret
+            tools: params.toolsB,
+          },
+        },
+      },
+    },
+  } as OpenClawPluginApi["config"];
+}
+
+describe("feishu tool account routing", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  test("wiki tool registers when first account disables it and routes to agentAccountId", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(
+      createConfig({
+        toolsA: { wiki: false },
+        toolsB: { wiki: true },
+      }),
+    );
+    registerFeishuWikiTools(api);
+
+    const tool = resolveTool("feishu_wiki", { agentAccountId: "b" });
+    await tool.execute("call", { action: "search" });
+
+    expect(createFeishuClientMock.mock.calls.at(-1)?.[0]?.appId).toBe("app-b");
+  });
+
+  test("wiki tool prefers configured defaultAccount over inherited default account context", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(
+      createConfig({
+        defaultAccount: "b",
+        toolsA: { wiki: true },
+        toolsB: { wiki: true },
+      }),
+    );
+    registerFeishuWikiTools(api);
+
+    const tool = resolveTool("feishu_wiki", { agentAccountId: "a" });
+    await tool.execute("call", { action: "search" });
+
+    expect(createFeishuClientMock.mock.calls.at(-1)?.[0]?.appId).toBe("app-b");
+  });
+
+  test("drive tool registers when first account disables it and routes to agentAccountId", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(
+      createConfig({
+        toolsA: { drive: false },
+        toolsB: { drive: true },
+      }),
+    );
+    registerFeishuDriveTools(api);
+
+    const tool = resolveTool("feishu_drive", { agentAccountId: "b" });
+    await tool.execute("call", { action: "unknown_action" });
+
+    expect(createFeishuClientMock.mock.calls.at(-1)?.[0]?.appId).toBe("app-b");
+  });
+
+  test("perm tool registers when only second account enables it and routes to agentAccountId", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(
+      createConfig({
+        toolsA: { perm: false },
+        toolsB: { perm: true },
+      }),
+    );
+    registerFeishuPermTools(api);
+
+    const tool = resolveTool("feishu_perm", { agentAccountId: "b" });
+    await tool.execute("call", { action: "unknown_action" });
+
+    expect(createFeishuClientMock.mock.calls.at(-1)?.[0]?.appId).toBe("app-b");
+  });
+
+  test("bitable tool routes to agentAccountId and allows explicit accountId override", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(createConfig({}));
+    registerFeishuBitableTools(api);
+
+    const tool = resolveTool("feishu_bitable_get_meta", { agentAccountId: "b" });
+    await tool.execute("call-ctx", { url: "invalid-url" });
+    await tool.execute("call-override", { url: "invalid-url", accountId: "a" });
+
+    expect(createFeishuClientMock.mock.calls[0]?.[0]?.appId).toBe("app-b");
+    expect(createFeishuClientMock.mock.calls[1]?.[0]?.appId).toBe("app-a");
+  });
+});