@nextclaw/channel-plugin-feishu 0.2.13 → 0.2.15

package/src/post.ts

@@ -0,0 +1,274 @@
+import { normalizeFeishuExternalKey } from "./external-keys.js";
+
+const FALLBACK_POST_TEXT = "[Rich text message]";
+const MARKDOWN_SPECIAL_CHARS = /([\\`*_{}\[\]()#+\-!|>~])/g;
+
+type PostParseResult = {
+  textContent: string;
+  imageKeys: string[];
+  mediaKeys: Array<{ fileKey: string; fileName?: string }>;
+  mentionedOpenIds: string[];
+};
+
+type PostPayload = {
+  title: string;
+  content: unknown[];
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function toStringOrEmpty(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function escapeMarkdownText(text: string): string {
+  return text.replace(MARKDOWN_SPECIAL_CHARS, "\\$1");
+}
+
+function toBoolean(value: unknown): boolean {
+  return value === true || value === 1 || value === "true";
+}
+
+function isStyleEnabled(style: Record<string, unknown> | undefined, key: string): boolean {
+  if (!style) {
+    return false;
+  }
+  return toBoolean(style[key]);
+}
+
+function wrapInlineCode(text: string): string {
+  const maxRun = Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
+  const fence = "`".repeat(maxRun + 1);
+  const needsPadding = text.startsWith("`") || text.endsWith("`");
+  const body = needsPadding ? ` ${text} ` : text;
+  return `${fence}${body}${fence}`;
+}
+
+function sanitizeFenceLanguage(language: string): string {
+  return language.trim().replace(/[^A-Za-z0-9_+#.-]/g, "");
+}
+
+function renderTextElement(element: Record<string, unknown>): string {
+  const text = toStringOrEmpty(element.text);
+  const style = isRecord(element.style) ? element.style : undefined;
+
+  if (isStyleEnabled(style, "code")) {
+    return wrapInlineCode(text);
+  }
+
+  let rendered = escapeMarkdownText(text);
+  if (!rendered) {
+    return "";
+  }
+
+  if (isStyleEnabled(style, "bold")) {
+    rendered = `**${rendered}**`;
+  }
+  if (isStyleEnabled(style, "italic")) {
+    rendered = `*${rendered}*`;
+  }
+  if (isStyleEnabled(style, "underline")) {
+    rendered = `<u>${rendered}</u>`;
+  }
+  if (
+    isStyleEnabled(style, "strikethrough") ||
+    isStyleEnabled(style, "line_through") ||
+    isStyleEnabled(style, "lineThrough")
+  ) {
+    rendered = `~~${rendered}~~`;
+  }
+  return rendered;
+}
+
+function renderLinkElement(element: Record<string, unknown>): string {
+  const href = toStringOrEmpty(element.href).trim();
+  const rawText = toStringOrEmpty(element.text);
+  const text = rawText || href;
+  if (!text) {
+    return "";
+  }
+  if (!href) {
+    return escapeMarkdownText(text);
+  }
+  return `[${escapeMarkdownText(text)}](${href})`;
+}
+
+function renderMentionElement(element: Record<string, unknown>): string {
+  const mention =
+    toStringOrEmpty(element.user_name) ||
+    toStringOrEmpty(element.user_id) ||
+    toStringOrEmpty(element.open_id);
+  if (!mention) {
+    return "";
+  }
+  return `@${escapeMarkdownText(mention)}`;
+}
+
+function renderEmotionElement(element: Record<string, unknown>): string {
+  const text =
+    toStringOrEmpty(element.emoji) ||
+    toStringOrEmpty(element.text) ||
+    toStringOrEmpty(element.emoji_type);
+  return escapeMarkdownText(text);
+}
+
+function renderCodeBlockElement(element: Record<string, unknown>): string {
+  const language = sanitizeFenceLanguage(
+    toStringOrEmpty(element.language) || toStringOrEmpty(element.lang),
+  );
+  const code = (toStringOrEmpty(element.text) || toStringOrEmpty(element.content)).replace(
+    /\r\n/g,
+    "\n",
+  );
+  const trailingNewline = code.endsWith("\n") ? "" : "\n";
+  return `\`\`\`${language}\n${code}${trailingNewline}\`\`\``;
+}
+
+function renderElement(
+  element: unknown,
+  imageKeys: string[],
+  mediaKeys: Array<{ fileKey: string; fileName?: string }>,
+  mentionedOpenIds: string[],
+): string {
+  if (!isRecord(element)) {
+    return escapeMarkdownText(toStringOrEmpty(element));
+  }
+
+  const tag = toStringOrEmpty(element.tag).toLowerCase();
+  switch (tag) {
+    case "text":
+      return renderTextElement(element);
+    case "a":
+      return renderLinkElement(element);
+    case "at":
+      {
+        const mentioned = toStringOrEmpty(element.open_id) || toStringOrEmpty(element.user_id);
+        const normalizedMention = normalizeFeishuExternalKey(mentioned);
+        if (normalizedMention) {
+          mentionedOpenIds.push(normalizedMention);
+        }
+      }
+      return renderMentionElement(element);
+    case "img": {
+      const imageKey = normalizeFeishuExternalKey(toStringOrEmpty(element.image_key));
+      if (imageKey) {
+        imageKeys.push(imageKey);
+      }
+      return "![image]";
+    }
+    case "media": {
+      const fileKey = normalizeFeishuExternalKey(toStringOrEmpty(element.file_key));
+      if (fileKey) {
+        const fileName = toStringOrEmpty(element.file_name) || undefined;
+        mediaKeys.push({ fileKey, fileName });
+      }
+      return "[media]";
+    }
+    case "emotion":
+      return renderEmotionElement(element);
+    case "br":
+      return "\n";
+    case "hr":
+      return "\n\n---\n\n";
+    case "code": {
+      const code = toStringOrEmpty(element.text) || toStringOrEmpty(element.content);
+      return code ? wrapInlineCode(code) : "";
+    }
+    case "code_block":
+    case "pre":
+      return renderCodeBlockElement(element);
+    default:
+      return escapeMarkdownText(toStringOrEmpty(element.text));
+  }
+}
+
+function toPostPayload(candidate: unknown): PostPayload | null {
+  if (!isRecord(candidate) || !Array.isArray(candidate.content)) {
+    return null;
+  }
+  return {
+    title: toStringOrEmpty(candidate.title),
+    content: candidate.content,
+  };
+}
+
+function resolveLocalePayload(candidate: unknown): PostPayload | null {
+  const direct = toPostPayload(candidate);
+  if (direct) {
+    return direct;
+  }
+  if (!isRecord(candidate)) {
+    return null;
+  }
+  for (const value of Object.values(candidate)) {
+    const localePayload = toPostPayload(value);
+    if (localePayload) {
+      return localePayload;
+    }
+  }
+  return null;
+}
+
+function resolvePostPayload(parsed: unknown): PostPayload | null {
+  const direct = toPostPayload(parsed);
+  if (direct) {
+    return direct;
+  }
+
+  if (!isRecord(parsed)) {
+    return null;
+  }
+
+  const wrappedPost = resolveLocalePayload(parsed.post);
+  if (wrappedPost) {
+    return wrappedPost;
+  }
+
+  return resolveLocalePayload(parsed);
+}
+
+export function parsePostContent(content: string): PostParseResult {
+  try {
+    const parsed = JSON.parse(content);
+    const payload = resolvePostPayload(parsed);
+    if (!payload) {
+      return {
+        textContent: FALLBACK_POST_TEXT,
+        imageKeys: [],
+        mediaKeys: [],
+        mentionedOpenIds: [],
+      };
+    }
+
+    const imageKeys: string[] = [];
+    const mediaKeys: Array<{ fileKey: string; fileName?: string }> = [];
+    const mentionedOpenIds: string[] = [];
+    const paragraphs: string[] = [];
+
+    for (const paragraph of payload.content) {
+      if (!Array.isArray(paragraph)) {
+        continue;
+      }
+      let renderedParagraph = "";
+      for (const element of paragraph) {
+        renderedParagraph += renderElement(element, imageKeys, mediaKeys, mentionedOpenIds);
+      }
+      paragraphs.push(renderedParagraph);
+    }
+
+    const title = escapeMarkdownText(payload.title.trim());
+    const body = paragraphs.join("\n").trim();
+    const textContent = [title, body].filter(Boolean).join("\n\n").trim();
+
+    return {
+      textContent: textContent || FALLBACK_POST_TEXT,
+      imageKeys,
+      mediaKeys,
+      mentionedOpenIds,
+    };
+  } catch {
+    return { textContent: FALLBACK_POST_TEXT, imageKeys: [], mediaKeys: [], mentionedOpenIds: [] };
+  }
+}

package/src/probe.test.ts

@@ -0,0 +1,270 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const createFeishuClientMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./client.js", () => ({
+  createFeishuClient: createFeishuClientMock,
+}));
+
+import { FEISHU_PROBE_REQUEST_TIMEOUT_MS, probeFeishu, clearProbeCache } from "./probe.js";
+
+const DEFAULT_CREDS = { appId: "cli_123", appSecret: "secret" } as const; // pragma: allowlist secret
+const DEFAULT_SUCCESS_RESPONSE = {
+  code: 0,
+  bot: { bot_name: "TestBot", open_id: "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,
+  bot: { bot_name: "Bot1", open_id: "ou_1" },
+} as const;
+
+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: Awaited<ReturnType<typeof probeFeishu>> = 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);
+  expect(first).toMatchObject({ ok: false, error: params.expectedError });
+  expect(second).toMatchObject({ ok: false, error: params.expectedError });
+  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(
+      expect.objectContaining({
+        method: "GET",
+        url: "/open-apis/bot/v3/info",
+        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).toMatchObject({ ok: false, 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).toMatchObject({ ok: false, 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("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.data.bot fallback path", async () => {
+    setupClient({
+      code: 0,
+      data: { bot: { bot_name: "DataBot", open_id: "ou_data" } },
+    });
+
+    await expectDefaultSuccessResult(DEFAULT_CREDS, {
+      ...DEFAULT_SUCCESS_RESULT,
+      botName: "DataBot",
+      botOpenId: "ou_data",
+    });
+  });
+});

package/src/probe.ts

@@ -0,0 +1,156 @@
+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 FeishuBotInfoResponse = {
+  code: number;
+  msg?: string;
+  bot?: { bot_name?: string; open_id?: string };
+  data?: { bot?: { bot_name?: string; open_id?: string } };
+};
+
+function setCachedProbeResult(
+  cacheKey: string,
+  result: FeishuProbeResult,
+  ttlMs: number,
+): FeishuProbeResult {
+  probeCache.set(cacheKey, { result, expiresAt: Date.now() + ttlMs });
+  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 && cached.expiresAt > Date.now()) {
+    return cached.result;
+  }
+
+  try {
+    const client = createFeishuClient(creds);
+    // Use bot/v3/info API to get bot information
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK generic request method
+    const responseResult = await raceWithTimeoutAndAbort<FeishuBotInfoResponse>(
+      (client as any).request({
+        method: "GET",
+        url: "/open-apis/bot/v3/info",
+        data: {},
+        timeout: timeoutMs,
+      }) as Promise<FeishuBotInfoResponse>,
+      {
+        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 bot = response.bot || response.data?.bot;
+    return setCachedProbeResult(
+      cacheKey,
+      {
+        ok: true,
+        appId: creds.appId,
+        botName: bot?.bot_name,
+        botOpenId: bot?.open_id,
+      },
+      PROBE_SUCCESS_TTL_MS,
+    );
+  } catch (err) {
+    return setCachedProbeResult(
+      cacheKey,
+      {
+        ok: false,
+        appId: creds.appId,
+        error: err instanceof Error ? err.message : String(err),
+      },
+      PROBE_ERROR_TTL_MS,
+    );
+  }
+}
+
+/** Clear the probe cache (for testing). */
+export function clearProbeCache(): void {
+  probeCache.clear();
+}