@actagent/feishu 2026.6.2

package/src/presentation-card.ts

@@ -0,0 +1,204 @@
+// Feishu plugin module implements presentation card behavior.
+import {
+  normalizeMessagePresentation,
+  renderMessagePresentationFallbackText,
+  type MessagePresentationBlock,
+  type MessagePresentationButton,
+} from "actagent/plugin-sdk/interactive-runtime";
+import { createFeishuCardInteractionEnvelope } from "./card-interaction.js";
+
+type NormalizedMessagePresentation = NonNullable<ReturnType<typeof normalizeMessagePresentation>>;
+
+function escapeFeishuCardMarkdownText(text: string): string {
+  return text.replace(/[&<>]/g, (char) => {
+    switch (char) {
+      case "&":
+        return "&amp;";
+      case "<":
+        return "&lt;";
+      case ">":
+        return "&gt;";
+      default:
+        return char;
+    }
+  });
+}
+
+function resolveSafeFeishuButtonUrl(url: string | undefined): string | undefined {
+  const trimmed = url?.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  try {
+    const parsed = new URL(trimmed);
+    return parsed.protocol === "https:" || parsed.protocol === "http:" ? trimmed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveFeishuButtonUrl(button: MessagePresentationButton): string | undefined {
+  return button.url ?? button.webApp?.url ?? button.web_app?.url;
+}
+
+function resolveFeishuCommandButtonValue(button: MessagePresentationButton): string | undefined {
+  if (button.action?.type === "callback") {
+    return undefined;
+  }
+  if (button.action?.type === "command") {
+    return button.action.command;
+  }
+  return button.value;
+}
+
+function mapFeishuButtonType(style: MessagePresentationButton["style"]) {
+  if (style === "primary" || style === "success") {
+    return "primary";
+  }
+  if (style === "danger") {
+    return "danger";
+  }
+  return "default";
+}
+
+function buildFeishuPayloadButton(
+  button: MessagePresentationButton,
+): Record<string, unknown> | undefined {
+  const behaviors: Record<string, unknown>[] = [];
+  const rendered: Record<string, unknown> = {
+    tag: "button",
+    text: {
+      tag: "plain_text",
+      content: button.label,
+    },
+    type: mapFeishuButtonType(button.style),
+  };
+  const url = resolveFeishuButtonUrl(button);
+  if (url) {
+    const safeUrl = resolveSafeFeishuButtonUrl(url);
+    if (safeUrl) {
+      behaviors.push({ type: "open_url", default_url: safeUrl });
+    }
+  }
+  const value = resolveFeishuCommandButtonValue(button);
+  if (value) {
+    behaviors.push({
+      type: "callback",
+      value: createFeishuCardInteractionEnvelope({
+        k: "quick",
+        a: "feishu.payload.button",
+        q: value,
+      }),
+    });
+  }
+  if (behaviors.length === 0) {
+    return undefined;
+  }
+  rendered.behaviors = behaviors;
+  return rendered;
+}
+
+export function buildFeishuCardElementsForBlock(
+  block: MessagePresentationBlock,
+): Record<string, unknown>[] {
+  if (block.type === "text") {
+    return [{ tag: "markdown", content: escapeFeishuCardMarkdownText(block.text) }];
+  }
+  if (block.type === "context") {
+    return [
+      {
+        tag: "markdown",
+        content: `<font color='grey'>${escapeFeishuCardMarkdownText(block.text)}</font>`,
+      },
+    ];
+  }
+  if (block.type === "divider") {
+    return [{ tag: "hr" }];
+  }
+  if (block.type === "buttons") {
+    return block.buttons
+      .map((button) => buildFeishuPayloadButton(button))
+      .filter((button): button is Record<string, unknown> => Boolean(button));
+  }
+  const labels = block.options.map((option) => `- ${option.label}`).join("\n");
+  return [
+    {
+      tag: "markdown",
+      content: `${escapeFeishuCardMarkdownText(
+        block.placeholder?.trim() || "Options",
+      )}:\n${escapeFeishuCardMarkdownText(labels)}`,
+    },
+  ];
+}
+
+function resolvePresentationHeaderTemplate(tone: NormalizedMessagePresentation["tone"]) {
+  if (tone === "danger") {
+    return "red";
+  }
+  if (tone === "warning") {
+    return "orange";
+  }
+  if (tone === "success") {
+    return "green";
+  }
+  return "blue";
+}
+
+export function buildFeishuPresentationCardElements(params: {
+  presentation: NormalizedMessagePresentation;
+  fallbackText?: string;
+}): Record<string, unknown>[] {
+  const elements: Record<string, unknown>[] = [];
+  const fallbackText = params.fallbackText?.trim();
+  if (fallbackText) {
+    elements.push({
+      tag: "markdown",
+      content: escapeFeishuCardMarkdownText(fallbackText),
+    });
+  }
+  for (const block of params.presentation.blocks) {
+    for (const element of buildFeishuCardElementsForBlock(block)) {
+      elements.push(element);
+    }
+  }
+  if (elements.length > 0) {
+    return elements;
+  }
+  return [
+    {
+      tag: "markdown",
+      content: renderMessagePresentationFallbackText({
+        text: params.fallbackText,
+        presentation: params.presentation.title
+          ? {
+              ...(params.presentation.tone ? { tone: params.presentation.tone } : {}),
+              blocks: params.presentation.blocks,
+            }
+          : params.presentation,
+      }),
+    },
+  ];
+}
+
+export function buildFeishuPresentationCard(params: {
+  presentation: NormalizedMessagePresentation;
+  fallbackText?: string;
+}): Record<string, unknown> {
+  return {
+    schema: "2.0",
+    config: {
+      width_mode: "fill",
+    },
+    ...(params.presentation.title
+      ? {
+          header: {
+            title: { tag: "plain_text", content: params.presentation.title },
+            template: resolvePresentationHeaderTemplate(params.presentation.tone),
+          },
+        }
+      : {}),
+    body: {
+      elements: buildFeishuPresentationCardElements(params),
+    },
+  };
+}

package/src/probe.test.ts

@@ -0,0 +1,310 @@
+// Feishu tests cover probe plugin behavior.
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { clearProbeCache, FEISHU_PROBE_REQUEST_TIMEOUT_MS, probeFeishu } from "./probe.js";
+
+const createFeishuClientMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./client.js", () => ({
+  createFeishuClient: createFeishuClientMock,
+}));
+
+const DEFAULT_CREDS = { appId: "cli_123", appSecret: "secret" } as const; // pragma: allowlist secret
+const DEFAULT_SUCCESS_RESPONSE = {
+  code: 0,
+  data: { pingBotInfo: { botName: "TestBot", botID: "ou_abc123" } },
+} as const;
+const DEFAULT_SUCCESS_RESULT = {
+  ok: true,
+  appId: "cli_123",
+  botName: "TestBot",
+  botOpenId: "ou_abc123",
+} as const;
+const BOT1_RESPONSE = {
+  code: 0,
+  data: { pingBotInfo: { botName: "Bot1", botID: "ou_1" } },
+} as const;
+
+afterAll(() => {
+  vi.doUnmock("./client.js");
+  vi.resetModules();
+});
+
+function makeRequestFn(response: Record<string, unknown>) {
+  return vi.fn().mockResolvedValue(response);
+}
+
+function setupClient(response: Record<string, unknown>) {
+  const requestFn = makeRequestFn(response);
+  createFeishuClientMock.mockReturnValue({ request: requestFn });
+  return requestFn;
+}
+
+function setupSuccessClient() {
+  return setupClient(DEFAULT_SUCCESS_RESPONSE);
+}
+
+async function expectDefaultSuccessResult(
+  creds = DEFAULT_CREDS,
+  expected: {
+    ok: true;
+    appId: string;
+    botName: string;
+    botOpenId: string;
+  } = DEFAULT_SUCCESS_RESULT,
+) {
+  const result = await probeFeishu(creds);
+  expect(result).toEqual(expected);
+}
+
+async function withFakeTimers(run: () => Promise<void>) {
+  vi.useFakeTimers();
+  try {
+    await run();
+  } finally {
+    vi.useRealTimers();
+  }
+}
+
+async function expectErrorResultCached(params: {
+  requestFn: ReturnType<typeof vi.fn>;
+  expectedError: string;
+  ttlMs: number;
+}) {
+  createFeishuClientMock.mockReturnValue({ request: params.requestFn });
+
+  const first = await probeFeishu(DEFAULT_CREDS);
+  const second = await probeFeishu(DEFAULT_CREDS);
+  const expected = { ok: false, appId: DEFAULT_CREDS.appId, error: params.expectedError };
+  expect(first).toEqual(expected);
+  expect(second).toEqual(expected);
+  expect(params.requestFn).toHaveBeenCalledTimes(1);
+
+  vi.advanceTimersByTime(params.ttlMs + 1);
+
+  await probeFeishu(DEFAULT_CREDS);
+  expect(params.requestFn).toHaveBeenCalledTimes(2);
+}
+
+async function expectFreshDefaultProbeAfter(
+  requestFn: ReturnType<typeof vi.fn>,
+  invalidate: () => void,
+) {
+  await probeFeishu(DEFAULT_CREDS);
+  expect(requestFn).toHaveBeenCalledTimes(1);
+
+  invalidate();
+
+  await probeFeishu(DEFAULT_CREDS);
+  expect(requestFn).toHaveBeenCalledTimes(2);
+}
+
+async function readSequentialDefaultProbePair() {
+  const first = await probeFeishu(DEFAULT_CREDS);
+  return { first, second: await probeFeishu(DEFAULT_CREDS) };
+}
+
+describe("probeFeishu", () => {
+  beforeEach(() => {
+    clearProbeCache();
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    clearProbeCache();
+  });
+
+  it("returns error when credentials are missing", async () => {
+    const result = await probeFeishu();
+    expect(result).toEqual({ ok: false, error: "missing credentials (appId, appSecret)" });
+  });
+
+  it("returns error when appId is missing", async () => {
+    const result = await probeFeishu({ appSecret: "secret" } as never); // pragma: allowlist secret
+    expect(result).toEqual({ ok: false, error: "missing credentials (appId, appSecret)" });
+  });
+
+  it("returns error when appSecret is missing", async () => {
+    const result = await probeFeishu({ appId: "cli_123" } as never);
+    expect(result).toEqual({ ok: false, error: "missing credentials (appId, appSecret)" });
+  });
+
+  it("returns bot info on successful probe", async () => {
+    const requestFn = setupSuccessClient();
+
+    await expectDefaultSuccessResult();
+    expect(requestFn).toHaveBeenCalledTimes(1);
+  });
+
+  it("passes the probe timeout to the Feishu request", async () => {
+    const requestFn = setupSuccessClient();
+
+    await probeFeishu(DEFAULT_CREDS);
+
+    expect(requestFn).toHaveBeenCalledWith({
+      method: "POST",
+      url: "/open-apis/bot/v1/actagent_bot/ping",
+      data: { needBotInfo: true },
+      timeout: FEISHU_PROBE_REQUEST_TIMEOUT_MS,
+    });
+  });
+
+  it("returns timeout error when request exceeds timeout", async () => {
+    await withFakeTimers(async () => {
+      const requestFn = vi.fn().mockImplementation(() => new Promise(() => {}));
+      createFeishuClientMock.mockReturnValue({ request: requestFn });
+
+      const promise = probeFeishu(DEFAULT_CREDS, { timeoutMs: 1_000 });
+      await vi.advanceTimersByTimeAsync(1_000);
+      const result = await promise;
+
+      expect(result).toEqual({
+        ok: false,
+        appId: DEFAULT_CREDS.appId,
+        error: "probe timed out after 1000ms",
+      });
+    });
+  });
+
+  it("returns aborted when abort signal is already aborted", async () => {
+    createFeishuClientMock.mockClear();
+    const abortController = new AbortController();
+    abortController.abort();
+
+    const result = await probeFeishu(
+      { appId: "cli_123", appSecret: "secret" }, // pragma: allowlist secret
+      { abortSignal: abortController.signal },
+    );
+
+    expect(result).toEqual({ ok: false, appId: "cli_123", error: "probe aborted" });
+    expect(createFeishuClientMock).not.toHaveBeenCalled();
+  });
+  it("returns cached result on subsequent calls within TTL", async () => {
+    const requestFn = setupSuccessClient();
+
+    const { first, second } = await readSequentialDefaultProbePair();
+
+    expect(first).toEqual(second);
+    // Only one API call should have been made
+    expect(requestFn).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not cache probe results when the expiry would exceed a valid Date", async () => {
+    await withFakeTimers(async () => {
+      vi.setSystemTime(new Date(8_640_000_000_000_000));
+      const requestFn = setupSuccessClient();
+
+      const { first, second } = await readSequentialDefaultProbePair();
+
+      expect(first).toEqual(second);
+      expect(requestFn).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  it("evicts cached probe results when the current clock is invalid", async () => {
+    const requestFn = setupSuccessClient();
+
+    await probeFeishu(DEFAULT_CREDS);
+    const dateNow = vi.spyOn(Date, "now").mockReturnValue(Number.NaN);
+    try {
+      await probeFeishu(DEFAULT_CREDS);
+    } finally {
+      dateNow.mockRestore();
+    }
+
+    expect(requestFn).toHaveBeenCalledTimes(2);
+  });
+
+  it("makes a fresh API call after cache expires", async () => {
+    await withFakeTimers(async () => {
+      const requestFn = setupSuccessClient();
+
+      await expectFreshDefaultProbeAfter(requestFn, () => {
+        vi.advanceTimersByTime(10 * 60 * 1000 + 1);
+      });
+    });
+  });
+
+  it("caches failed probe results (API error) for the error TTL", async () => {
+    await withFakeTimers(async () => {
+      await expectErrorResultCached({
+        requestFn: makeRequestFn({ code: 99, msg: "token expired" }),
+        expectedError: "API error: token expired",
+        ttlMs: 60 * 1000,
+      });
+    });
+  });
+
+  it("caches thrown request errors for the error TTL", async () => {
+    await withFakeTimers(async () => {
+      await expectErrorResultCached({
+        requestFn: vi.fn().mockRejectedValue(new Error("network error")),
+        expectedError: "network error",
+        ttlMs: 60 * 1000,
+      });
+    });
+  });
+
+  it("caches per account independently", async () => {
+    const requestFn = setupClient(BOT1_RESPONSE);
+
+    await probeFeishu({ appId: "cli_aaa", appSecret: "s1" }); // pragma: allowlist secret
+    expect(requestFn).toHaveBeenCalledTimes(1);
+
+    // Different appId should trigger a new API call
+    await probeFeishu({ appId: "cli_bbb", appSecret: "s2" }); // pragma: allowlist secret
+    expect(requestFn).toHaveBeenCalledTimes(2);
+
+    // Same appId + appSecret as first call should return cached
+    await probeFeishu({ appId: "cli_aaa", appSecret: "s1" }); // pragma: allowlist secret
+    expect(requestFn).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not share cache between accounts with same appId but different appSecret", async () => {
+    const requestFn = setupClient(BOT1_RESPONSE);
+
+    // First account with appId + secret A
+    await probeFeishu({ appId: "cli_shared", appSecret: "secret_aaa" }); // pragma: allowlist secret
+    expect(requestFn).toHaveBeenCalledTimes(1);
+
+    // Second account with same appId but different secret (e.g. after rotation)
+    // must NOT reuse the cached result
+    await probeFeishu({ appId: "cli_shared", appSecret: "secret_bbb" }); // pragma: allowlist secret
+    expect(requestFn).toHaveBeenCalledTimes(2);
+  });
+
+  it("uses accountId for cache key when available", async () => {
+    const requestFn = setupClient(BOT1_RESPONSE);
+
+    // Two accounts with same appId+appSecret but different accountIds are cached separately
+    await probeFeishu({ accountId: "acct-1", appId: "cli_123", appSecret: "secret" }); // pragma: allowlist secret
+    expect(requestFn).toHaveBeenCalledTimes(1);
+
+    await probeFeishu({ accountId: "acct-2", appId: "cli_123", appSecret: "secret" }); // pragma: allowlist secret
+    expect(requestFn).toHaveBeenCalledTimes(2);
+
+    // Same accountId should return cached
+    await probeFeishu({ accountId: "acct-1", appId: "cli_123", appSecret: "secret" }); // pragma: allowlist secret
+    expect(requestFn).toHaveBeenCalledTimes(2);
+  });
+
+  it("clearProbeCache forces fresh API call", async () => {
+    const requestFn = setupSuccessClient();
+
+    await expectFreshDefaultProbeAfter(requestFn, () => {
+      clearProbeCache();
+    });
+  });
+
+  it("handles response with pingBotInfo in data", async () => {
+    setupClient({
+      code: 0,
+      data: { pingBotInfo: { botName: "DataBot", botID: "ou_data" } },
+    });
+
+    await expectDefaultSuccessResult(DEFAULT_CREDS, {
+      ...DEFAULT_SUCCESS_RESULT,
+      botName: "DataBot",
+      botOpenId: "ou_data",
+    });
+  });
+});

package/src/probe.ts

@@ -0,0 +1,181 @@
+// Feishu plugin module implements probe behavior.
+import { formatErrorMessage } from "actagent/plugin-sdk/error-runtime";
+import {
+  asDateTimestampMs,
+  resolveExpiresAtMsFromDurationMs,
+} from "actagent/plugin-sdk/number-runtime";
+import { raceWithTimeoutAndAbort } from "./async.js";
+import { createFeishuClient, type FeishuClientCredentials } from "./client.js";
+import type { FeishuProbeResult } from "./types.js";
+
+/** Cache probe results to reduce repeated health-check calls.
+ * Gateway health checks call probeFeishu() every minute; without caching this
+ * burns ~43,200 calls/month, easily exceeding Feishu's free-tier quota.
+ * Successful bot info is effectively static, while failures are cached briefly
+ * to avoid hammering the API during transient outages. */
+const probeCache = new Map<string, { result: FeishuProbeResult; expiresAt: number }>();
+const PROBE_SUCCESS_TTL_MS = 10 * 60 * 1000; // 10 minutes
+const PROBE_ERROR_TTL_MS = 60 * 1000; // 1 minute
+const MAX_PROBE_CACHE_SIZE = 64;
+export const FEISHU_PROBE_REQUEST_TIMEOUT_MS = 10_000;
+export type ProbeFeishuOptions = {
+  timeoutMs?: number;
+  abortSignal?: AbortSignal;
+};
+
+type FeishuPingResponse = {
+  code: number;
+  msg?: string;
+  data?: { pingBotInfo?: { botID?: string; botName?: string } };
+};
+
+type FeishuRequestClient = ReturnType<typeof createFeishuClient> & {
+  request(params: {
+    method: "POST";
+    url: string;
+    data: Record<string, unknown>;
+    timeout: number;
+  }): Promise<FeishuPingResponse>;
+};
+
+function setCachedProbeResult(
+  cacheKey: string,
+  result: FeishuProbeResult,
+  ttlMs: number,
+): FeishuProbeResult {
+  const expiresAt = resolveExpiresAtMsFromDurationMs(ttlMs);
+  if (expiresAt === undefined) {
+    probeCache.delete(cacheKey);
+    return result;
+  }
+  probeCache.set(cacheKey, { result, expiresAt });
+  if (probeCache.size > MAX_PROBE_CACHE_SIZE) {
+    const oldest = probeCache.keys().next().value;
+    if (oldest !== undefined) {
+      probeCache.delete(oldest);
+    }
+  }
+  return result;
+}
+
+export async function probeFeishu(
+  creds?: FeishuClientCredentials,
+  options: ProbeFeishuOptions = {},
+): Promise<FeishuProbeResult> {
+  if (!creds?.appId || !creds?.appSecret) {
+    return {
+      ok: false,
+      error: "missing credentials (appId, appSecret)",
+    };
+  }
+  if (options.abortSignal?.aborted) {
+    return {
+      ok: false,
+      appId: creds.appId,
+      error: "probe aborted",
+    };
+  }
+
+  const timeoutMs = options.timeoutMs ?? FEISHU_PROBE_REQUEST_TIMEOUT_MS;
+
+  // Return cached result if still valid.
+  // Use accountId when available; otherwise include appSecret prefix so two
+  // accounts sharing the same appId (e.g. after secret rotation) don't
+  // pollute each other's cache entry.
+  const cacheKey = creds.accountId ?? `${creds.appId}:${creds.appSecret.slice(0, 8)}`;
+  const cached = probeCache.get(cacheKey);
+  if (cached) {
+    const now = asDateTimestampMs(Date.now());
+    const expiresAt = asDateTimestampMs(cached.expiresAt);
+    if (now !== undefined && expiresAt !== undefined && expiresAt > now) {
+      return cached.result;
+    }
+    probeCache.delete(cacheKey);
+  }
+
+  try {
+    const client = createFeishuClient(creds) as FeishuRequestClient;
+    // Feishu-provided endpoint for ACTAgent, supported on both Feishu (CN)
+    // and Lark (international). No OAuth scopes required. Validates
+    // credentials and registers the app as an AI agent (智能体).
+    const responseResult = await raceWithTimeoutAndAbort<FeishuPingResponse>(
+      client.request({
+        method: "POST",
+        url: "/open-apis/bot/v1/actagent_bot/ping",
+        data: { needBotInfo: true },
+        timeout: timeoutMs,
+      }),
+      {
+        timeoutMs,
+        abortSignal: options.abortSignal,
+      },
+    );
+
+    if (responseResult.status === "aborted") {
+      return {
+        ok: false,
+        appId: creds.appId,
+        error: "probe aborted",
+      };
+    }
+    if (responseResult.status === "timeout") {
+      return setCachedProbeResult(
+        cacheKey,
+        {
+          ok: false,
+          appId: creds.appId,
+          error: `probe timed out after ${timeoutMs}ms`,
+        },
+        PROBE_ERROR_TTL_MS,
+      );
+    }
+
+    const response = responseResult.value;
+    if (options.abortSignal?.aborted) {
+      return {
+        ok: false,
+        appId: creds.appId,
+        error: "probe aborted",
+      };
+    }
+
+    if (response.code !== 0) {
+      return setCachedProbeResult(
+        cacheKey,
+        {
+          ok: false,
+          appId: creds.appId,
+          error: `API error: ${response.msg || `code ${response.code}`}`,
+        },
+        PROBE_ERROR_TTL_MS,
+      );
+    }
+
+    const botInfo = response.data?.pingBotInfo;
+    return setCachedProbeResult(
+      cacheKey,
+      {
+        ok: true,
+        appId: creds.appId,
+        botName: botInfo?.botName,
+        botOpenId: botInfo?.botID,
+      },
+      PROBE_SUCCESS_TTL_MS,
+    );
+  } catch (err) {
+    return setCachedProbeResult(
+      cacheKey,
+      {
+        ok: false,
+        appId: creds.appId,
+        error: formatErrorMessage(err),
+      },
+      PROBE_ERROR_TTL_MS,
+    );
+  }
+}
+
+/** Clear the probe cache (for testing). */
+export function clearProbeCache(): void {
+  probeCache.clear();
+}