@gakr-gakr/feishu 0.1.0

package/src/post.ts

@@ -0,0 +1,275 @@
+import { normalizeLowercaseStringOrEmpty } from "autobot/plugin-sdk/string-coerce-runtime";
+import { isRecord } from "./comment-shared.js";
+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 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 = normalizeLowercaseStringOrEmpty(toStringOrEmpty(element.tag));
+  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 "md":
+    case "lark_md":
+      return toStringOrEmpty(element.text) || toStringOrEmpty(element.content);
+    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.ts

@@ -0,0 +1,166 @@
+import { formatErrorMessage } from "autobot/plugin-sdk/error-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 {
+  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) as FeishuRequestClient;
+    // Feishu-provided endpoint for AutoBot, 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/autobot_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();
+}

package/src/processing-claims.ts

@@ -0,0 +1,59 @@
+const EVENT_DEDUP_TTL_MS = 5 * 60 * 1000;
+const EVENT_MEMORY_MAX_SIZE = 2_000;
+
+const processingClaims = new Map<string, number>();
+
+function resolveEventDedupeKey(
+  namespace: string,
+  messageId: string | undefined | null,
+): string | null {
+  const trimmed = messageId?.trim();
+  return trimmed ? `${namespace}:${trimmed}` : null;
+}
+
+function pruneProcessingClaims(now: number): void {
+  const cutoff = now - EVENT_DEDUP_TTL_MS;
+  for (const [key, seenAt] of processingClaims) {
+    if (seenAt < cutoff) {
+      processingClaims.delete(key);
+    }
+  }
+  while (processingClaims.size > EVENT_MEMORY_MAX_SIZE) {
+    const oldestKey = processingClaims.keys().next().value;
+    if (!oldestKey) {
+      return;
+    }
+    processingClaims.delete(oldestKey);
+  }
+}
+
+export function tryBeginFeishuMessageProcessing(
+  messageId: string | undefined | null,
+  namespace = "global",
+): boolean {
+  const key = resolveEventDedupeKey(namespace, messageId);
+  if (!key) {
+    return true;
+  }
+  const now = Date.now();
+  pruneProcessingClaims(now);
+  if (processingClaims.has(key)) {
+    processingClaims.delete(key);
+    processingClaims.set(key, now);
+    pruneProcessingClaims(now);
+    return false;
+  }
+  processingClaims.set(key, now);
+  pruneProcessingClaims(now);
+  return true;
+}
+
+export function releaseFeishuMessageProcessing(
+  messageId: string | undefined | null,
+  namespace = "global",
+): void {
+  const key = resolveEventDedupeKey(namespace, messageId);
+  if (key) {
+    processingClaims.delete(key);
+  }
+}

package/src/qr-terminal.ts

@@ -0,0 +1 @@
+export { renderQrTerminal } from "autobot/plugin-sdk/media-runtime";

package/src/reactions.ts

@@ -0,0 +1,123 @@
+import type { ClawdbotConfig } from "../runtime-api.js";
+import { resolveFeishuRuntimeAccount } from "./accounts.js";
+import { createFeishuClient } from "./client.js";
+
+type FeishuReaction = {
+  reactionId: string;
+  emojiType: string;
+  operatorType: "app" | "user";
+  operatorId: string;
+};
+
+function resolveConfiguredFeishuClient(params: { cfg: ClawdbotConfig; accountId?: string }) {
+  const account = resolveFeishuRuntimeAccount(params);
+  if (!account.configured) {
+    throw new Error(`Feishu account "${account.accountId}" not configured`);
+  }
+  return createFeishuClient(account);
+}
+
+function assertFeishuReactionApiSuccess(response: { code?: number; msg?: string }, action: string) {
+  if (response.code !== 0) {
+    throw new Error(`Feishu ${action} failed: ${response.msg || `code ${response.code}`}`);
+  }
+}
+
+/**
+ * Add a reaction (emoji) to a message.
+ * @param emojiType - Feishu emoji type, e.g., "SMILE", "THUMBSUP", "HEART"
+ * @see https://open.feishu.cn/document/server-docs/im-v1/message-reaction/emojis-introduce
+ */
+export async function addReactionFeishu(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+  emojiType: string;
+  accountId?: string;
+}): Promise<{ reactionId: string }> {
+  const { cfg, messageId, emojiType, accountId } = params;
+  const client = resolveConfiguredFeishuClient({ cfg, accountId });
+
+  const response = (await client.im.messageReaction.create({
+    path: { message_id: messageId },
+    data: {
+      reaction_type: {
+        emoji_type: emojiType,
+      },
+    },
+  })) as {
+    code?: number;
+    msg?: string;
+    data?: { reaction_id?: string };
+  };
+
+  assertFeishuReactionApiSuccess(response, "add reaction");
+
+  const reactionId = response.data?.reaction_id;
+  if (!reactionId) {
+    throw new Error("Feishu add reaction failed: no reaction_id returned");
+  }
+
+  return { reactionId };
+}
+
+/**
+ * Remove a reaction from a message.
+ */
+export async function removeReactionFeishu(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+  reactionId: string;
+  accountId?: string;
+}): Promise<void> {
+  const { cfg, messageId, reactionId, accountId } = params;
+  const client = resolveConfiguredFeishuClient({ cfg, accountId });
+
+  const response = (await client.im.messageReaction.delete({
+    path: {
+      message_id: messageId,
+      reaction_id: reactionId,
+    },
+  })) as { code?: number; msg?: string };
+
+  assertFeishuReactionApiSuccess(response, "remove reaction");
+}
+
+/**
+ * List all reactions for a message.
+ */
+export async function listReactionsFeishu(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+  emojiType?: string;
+  accountId?: string;
+}): Promise<FeishuReaction[]> {
+  const { cfg, messageId, emojiType, accountId } = params;
+  const client = resolveConfiguredFeishuClient({ cfg, accountId });
+
+  const response = (await client.im.messageReaction.list({
+    path: { message_id: messageId },
+    params: emojiType ? { reaction_type: emojiType } : undefined,
+  })) as {
+    code?: number;
+    msg?: string;
+    data?: {
+      items?: Array<{
+        reaction_id?: string;
+        reaction_type?: { emoji_type?: string };
+        operator_type?: string;
+        operator_id?: { open_id?: string; user_id?: string; union_id?: string };
+      }>;
+    };
+  };
+
+  assertFeishuReactionApiSuccess(response, "list reactions");
+
+  const items = response.data?.items ?? [];
+  return items.map((item) => ({
+    reactionId: item.reaction_id ?? "",
+    emojiType: item.reaction_type?.emoji_type ?? "",
+    operatorType: item.operator_type === "app" ? "app" : "user",
+    operatorId:
+      item.operator_id?.open_id ?? item.operator_id?.user_id ?? item.operator_id?.union_id ?? "",
+  }));
+}

package/src/reasoning-preview.ts

@@ -0,0 +1,28 @@
+import { resolveFeishuConfigReasoningDefault } from "./agent-config.js";
+import { loadSessionStore, resolveSessionStoreEntry } from "./bot-runtime-api.js";
+import type { ClawdbotConfig } from "./bot-runtime-api.js";
+
+export function resolveFeishuReasoningPreviewEnabled(params: {
+  cfg: ClawdbotConfig;
+  agentId: string;
+  storePath: string;
+  sessionKey?: string;
+}): boolean {
+  const configDefault = resolveFeishuConfigReasoningDefault(params.cfg, params.agentId);
+
+  if (!params.sessionKey) {
+    return configDefault === "stream";
+  }
+
+  try {
+    const store = loadSessionStore(params.storePath, { skipCache: true });
+    const level = resolveSessionStoreEntry({ store, sessionKey: params.sessionKey }).existing
+      ?.reasoningLevel;
+    if (level === "on" || level === "stream" || level === "off") {
+      return level === "stream";
+    }
+  } catch {
+    return false;
+  }
+  return configDefault === "stream";
+}

package/src/reply-dispatcher-runtime-api.ts

@@ -0,0 +1,7 @@
+export {
+  createReplyPrefixContext,
+  type ClawdbotConfig,
+  type OutboundIdentity,
+  type ReplyPayload,
+  type RuntimeEnv,
+} from "../runtime-api.js";