@openclaw/feishu 2026.5.2-beta.2 → 2026.5.3-beta.1

package/src/streaming-card.test.ts

@@ -1,190 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-const fetchWithSsrFGuardMock = vi.hoisted(() => vi.fn());
-
-vi.mock("openclaw/plugin-sdk/ssrf-runtime", () => ({
-  fetchWithSsrFGuard: fetchWithSsrFGuardMock,
-}));
-
-import {
-  FeishuStreamingSession,
-  mergeStreamingText,
-  resolveStreamingCardSendMode,
-} from "./streaming-card.js";
-
-type StreamingSessionState = {
-  cardId: string;
-  messageId: string;
-  sequence: number;
-  currentText: string;
-  hasNote: boolean;
-};
-
-function setStreamingSessionInternals(
-  session: FeishuStreamingSession,
-  values: {
-    state: StreamingSessionState;
-    lastUpdateTime?: number;
-  },
-) {
-  const internals = session as unknown as {
-    state: StreamingSessionState;
-    lastUpdateTime: number;
-  };
-  internals.state = values.state;
-  if (values.lastUpdateTime !== undefined) {
-    internals.lastUpdateTime = values.lastUpdateTime;
-  }
-}
-
-describe("FeishuStreamingSession", () => {
-  beforeEach(() => {
-    vi.useRealTimers();
-    fetchWithSsrFGuardMock.mockReset();
-  });
-
-  function mockFetches(updateBodies: string[]) {
-    fetchWithSsrFGuardMock.mockImplementation(
-      async ({ url, init }: { url: string; init?: { body?: string } }) => {
-        const release = vi.fn(async () => {});
-        if (url.includes("/auth/")) {
-          return {
-            response: {
-              ok: true,
-              json: async () => ({
-                code: 0,
-                msg: "ok",
-                tenant_access_token: "token",
-                expire: 7200,
-              }),
-            },
-            release,
-          };
-        }
-        if (url.includes("/elements/content/content")) {
-          updateBodies.push(init?.body ?? "");
-        }
-        return {
-          response: {
-            ok: true,
-            json: async () => ({ code: 0, msg: "ok" }),
-          },
-          release,
-        };
-      },
-    );
-  }
-
-  it("flushes throttled pending text after the throttle window", async () => {
-    vi.useFakeTimers();
-    vi.setSystemTime(1_000);
-    const updateBodies: string[] = [];
-    mockFetches(updateBodies);
-
-    const session = new FeishuStreamingSession({} as never, {
-      appId: "app_pending_flush",
-      appSecret: "secret",
-    });
-    setStreamingSessionInternals(session, {
-      state: {
-        cardId: "card_1",
-        messageId: "om_1",
-        sequence: 1,
-        currentText: "hello",
-        hasNote: false,
-      },
-      lastUpdateTime: 1_000,
-    });
-
-    await session.update("hello small");
-    expect(updateBodies).toHaveLength(0);
-
-    await vi.advanceTimersByTimeAsync(160);
-
-    expect(updateBodies).toHaveLength(1);
-    expect(JSON.parse(updateBodies[0] ?? "{}")).toMatchObject({
-      content: "hello small",
-    });
-  });
-
-  it("pushes natural-boundary updates immediately inside the throttle window", async () => {
-    vi.useFakeTimers();
-    vi.setSystemTime(2_000);
-    const updateBodies: string[] = [];
-    mockFetches(updateBodies);
-
-    const session = new FeishuStreamingSession({} as never, {
-      appId: "app_boundary_flush",
-      appSecret: "secret",
-    });
-    setStreamingSessionInternals(session, {
-      state: {
-        cardId: "card_2",
-        messageId: "om_2",
-        sequence: 1,
-        currentText: "hello",
-        hasNote: false,
-      },
-      lastUpdateTime: 2_000,
-    });
-
-    await session.update("hello!");
-
-    expect(updateBodies).toHaveLength(1);
-    expect(JSON.parse(updateBodies[0] ?? "{}")).toMatchObject({
-      content: "hello!",
-    });
-  });
-});
-
-describe("mergeStreamingText", () => {
-  it("prefers the latest full text when it already includes prior text", () => {
-    expect(mergeStreamingText("hello", "hello world")).toBe("hello world");
-  });
-
-  it("keeps previous text when the next partial is empty or redundant", () => {
-    expect(mergeStreamingText("hello", "")).toBe("hello");
-    expect(mergeStreamingText("hello world", "hello")).toBe("hello world");
-  });
-
-  it("appends fragmented chunks without injecting newlines", () => {
-    expect(mergeStreamingText("hello wor", "ld")).toBe("hello world");
-    expect(mergeStreamingText("line1", "line2")).toBe("line1line2");
-  });
-
-  it("merges overlap between adjacent partial snapshots", () => {
-    expect(mergeStreamingText("好的，让我", "让我再读取一遍")).toBe("好的，让我再读取一遍");
-    expect(mergeStreamingText("revision_id: 552", "2，一点变化都没有")).toBe(
-      "revision_id: 552，一点变化都没有",
-    );
-    expect(mergeStreamingText("abc", "cabc")).toBe("cabc");
-  });
-});
-
-describe("resolveStreamingCardSendMode", () => {
-  it("prefers message.reply when reply target and root id both exist", () => {
-    expect(
-      resolveStreamingCardSendMode({
-        replyToMessageId: "om_parent",
-        rootId: "om_topic_root",
-      }),
-    ).toBe("reply");
-  });
-
-  it("falls back to root create when reply target is absent", () => {
-    expect(
-      resolveStreamingCardSendMode({
-        rootId: "om_topic_root",
-      }),
-    ).toBe("root_create");
-  });
-
-  it("uses create mode when no reply routing fields are provided", () => {
-    expect(resolveStreamingCardSendMode()).toBe("create");
-    expect(
-      resolveStreamingCardSendMode({
-        replyInThread: true,
-      }),
-    ).toBe("create");
-  });
-});

package/src/streaming-card.ts

@@ -1,490 +0,0 @@
-/**
- * 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/ssrf-runtime";
-import { getFeishuUserAgent } from "./client.js";
-import { resolveFeishuCardTemplate, type CardHeaderConfig } from "./send.js";
-import type { FeishuDomain } from "./types.js";
-
-type Credentials = { appId: string; appSecret: string; domain?: FeishuDomain };
-type CardState = {
-  cardId: string;
-  messageId: string;
-  sequence: number;
-  currentText: string;
-  hasNote: boolean;
-};
-
-/** Options for customising the initial streaming card appearance. */
-type StreamingCardOptions = {
-  /** Optional header with title and color template. */
-  header?: CardHeaderConfig;
-  /** Optional grey note footer text. */
-  note?: string;
-};
-
-/** Optional header for streaming cards (title bar with color template) */
-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;
-};
-
-const STREAMING_UPDATE_THROTTLE_MS = 160;
-const STREAMING_SIGNIFICANT_DELTA_CHARS = 18;
-
-// 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", "User-Agent": getFeishuUserAgent() },
-      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) + "...";
-}
-
-function hasNaturalStreamingBoundary(text: string): boolean {
-  return /[\n。！？!?；;：:]$/.test(text);
-}
-
-function shouldPushStreamingUpdate(previousText: string, nextText: string): boolean {
-  if (!previousText) {
-    return true;
-  }
-  if (hasNaturalStreamingBoundary(nextText)) {
-    return true;
-  }
-  return nextText.length - previousText.length >= STREAMING_SIGNIFICANT_DELTA_CHARS;
-}
-
-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 flushTimer: ReturnType<typeof setTimeout> | null = null;
-  private updateThrottleMs = STREAMING_UPDATE_THROTTLE_MS;
-
-  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?: StreamingCardOptions & StreamingStartOptions,
-  ): Promise<void> {
-    if (this.state) {
-      return;
-    }
-
-    const apiBase = resolveApiBase(this.creds.domain);
-    const elements: Record<string, unknown>[] = [
-      { tag: "markdown", content: "⏳ Thinking...", element_id: "content" },
-    ];
-    if (options?.note) {
-      elements.push({ tag: "hr" });
-      elements.push({
-        tag: "markdown",
-        content: `<font color='grey'>${options.note}</font>`,
-        element_id: "note",
-      });
-    }
-    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 },
-    };
-    if (options?.header) {
-      cardJson.header = {
-        title: { tag: "plain_text", content: options.header.title },
-        template: resolveFeishuCardTemplate(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",
-          "User-Agent": getFeishuUserAgent(),
-        },
-        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: "",
-      hasNote: !!options?.note,
-    };
-    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",
-          "User-Agent": getFeishuUserAgent(),
-        },
-        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));
-  }
-
-  private clearFlushTimer(): void {
-    if (this.flushTimer) {
-      clearTimeout(this.flushTimer);
-      this.flushTimer = null;
-    }
-  }
-
-  private schedulePendingFlush(): void {
-    if (this.flushTimer || !this.pendingText || this.closed) {
-      return;
-    }
-    const delayMs = Math.max(0, this.updateThrottleMs - (Date.now() - this.lastUpdateTime));
-    this.flushTimer = setTimeout(() => {
-      this.flushTimer = null;
-      const pending = this.pendingText;
-      if (!pending || this.closed) {
-        return;
-      }
-      void this.update(pending);
-    }, delayMs);
-  }
-
-  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;
-    }
-    this.pendingText = mergedInput;
-    this.clearFlushTimer();
-
-    const shouldForceUpdate = shouldPushStreamingUpdate(this.state.currentText, mergedInput);
-    const now = Date.now();
-    if (!shouldForceUpdate && now - this.lastUpdateTime < this.updateThrottleMs) {
-      this.schedulePendingFlush();
-      return;
-    }
-    this.lastUpdateTime = now;
-
-    this.queue = this.queue.then(async () => {
-      if (!this.state || this.closed) {
-        return;
-      }
-      const nextText = this.pendingText ?? mergedInput;
-      const mergedText = mergeStreamingText(this.state.currentText, nextText);
-      if (!mergedText || mergedText === this.state.currentText) {
-        return;
-      }
-      this.pendingText = null;
-      this.state.currentText = mergedText;
-      await this.updateCardContent(mergedText, (e) => this.log?.(`Update failed: ${String(e)}`));
-    });
-    await this.queue;
-  }
-
-  private async updateNoteContent(note: string): Promise<void> {
-    if (!this.state || !this.state.hasNote) {
-      return;
-    }
-    const apiBase = resolveApiBase(this.creds.domain);
-    this.state.sequence += 1;
-    await fetchWithSsrFGuard({
-      url: `${apiBase}/cardkit/v1/cards/${this.state.cardId}/elements/note/content`,
-      init: {
-        method: "PUT",
-        headers: {
-          Authorization: `Bearer ${await getToken(this.creds)}`,
-          "Content-Type": "application/json",
-          "User-Agent": getFeishuUserAgent(),
-        },
-        body: JSON.stringify({
-          content: `<font color='grey'>${note}</font>`,
-          sequence: this.state.sequence,
-          uuid: `n_${this.state.cardId}_${this.state.sequence}`,
-        }),
-      },
-      policy: { allowedHostnames: resolveAllowedHostnames(this.creds.domain) },
-      auditContext: "feishu.streaming-card.note-update",
-    })
-      .then(async ({ release }) => {
-        await release();
-      })
-      .catch((e) => this.log?.(`Note update failed: ${String(e)}`));
-  }
-
-  async close(finalText?: string, options?: { note?: string }): Promise<void> {
-    if (!this.state || this.closed) {
-      return;
-    }
-    this.closed = true;
-    this.clearFlushTimer();
-    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;
-    }
-
-    // Update note with final model/provider info
-    if (options?.note) {
-      await this.updateNoteContent(options.note);
-    }
-
-    // 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",
-          "User-Agent": getFeishuUserAgent(),
-        },
-        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)}`));
-    const finalState = this.state;
-    this.state = null;
-    this.pendingText = null;
-
-    this.log?.(`Closed streaming: cardId=${finalState.cardId}`);
-  }
-
-  isActive(): boolean {
-    return this.state !== null && !this.closed;
-  }
-}