moltbot-channel-feishu 0.0.8

package/src/core/policy.ts

@@ -0,0 +1,199 @@
+/**
+ * Access policy engine for DM and group messages.
+ */
+
+import type { Config, GroupConfig } from "../config/schema.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface PolicyResult {
+  allowed: boolean;
+  reason?: string;
+}
+
+export interface AllowlistMatch {
+  allowed: boolean;
+  matchKey?: string;
+  matchSource?: "wildcard" | "id" | "name";
+}
+
+// ============================================================================
+// Allowlist Matching
+// ============================================================================
+
+/**
+ * Check if a sender matches an allowlist.
+ */
+export function matchAllowlist(
+  allowFrom: (string | number)[],
+  senderId: string,
+  senderName?: string | null
+): AllowlistMatch {
+  const normalized = allowFrom.map((entry) => String(entry).trim().toLowerCase()).filter(Boolean);
+
+  if (normalized.length === 0) {
+    return { allowed: false };
+  }
+
+  // Check for wildcard
+  if (normalized.includes("*")) {
+    return { allowed: true, matchKey: "*", matchSource: "wildcard" };
+  }
+
+  // Check by ID
+  const lowerSenderId = senderId.toLowerCase();
+  if (normalized.includes(lowerSenderId)) {
+    return { allowed: true, matchKey: lowerSenderId, matchSource: "id" };
+  }
+
+  // Check by name
+  const lowerName = senderName?.toLowerCase();
+  if (lowerName && normalized.includes(lowerName)) {
+    return { allowed: true, matchKey: lowerName, matchSource: "name" };
+  }
+
+  return { allowed: false };
+}
+
+// ============================================================================
+// DM Policy
+// ============================================================================
+
+/**
+ * Check if a DM from a sender is allowed.
+ */
+export function checkDmPolicy(
+  config: Config,
+  senderId: string,
+  senderName?: string | null
+): PolicyResult {
+  const policy = config.dmPolicy ?? "pairing";
+
+  switch (policy) {
+    case "open":
+      return { allowed: true };
+
+    case "pairing":
+      // Pairing requires verification flow handled elsewhere
+      return { allowed: true };
+
+    case "allowlist": {
+      const allowFrom = config.allowFrom ?? [];
+      const match = matchAllowlist(allowFrom, senderId, senderName);
+      return match.allowed
+        ? { allowed: true }
+        : { allowed: false, reason: "Sender not in DM allowlist" };
+    }
+
+    default:
+      return { allowed: false, reason: `Unknown DM policy: ${policy}` };
+  }
+}
+
+// ============================================================================
+// Group Policy
+// ============================================================================
+
+/**
+ * Resolve group-specific configuration.
+ */
+export function resolveGroupConfig(
+  config: Config,
+  groupId: string | null | undefined
+): GroupConfig | undefined {
+  if (!groupId) return undefined;
+
+  const groups = config.groups ?? {};
+  const trimmed = groupId.trim();
+
+  // Direct match
+  const direct = groups[trimmed];
+  if (direct) return direct;
+
+  // Case-insensitive match
+  const lowered = trimmed.toLowerCase();
+  const matchKey = Object.keys(groups).find((key) => key.toLowerCase() === lowered);
+  return matchKey ? groups[matchKey] : undefined;
+}
+
+/**
+ * Check if a message in a group from a sender is allowed.
+ */
+export function checkGroupPolicy(
+  config: Config,
+  groupId: string,
+  senderId: string,
+  senderName?: string | null
+): PolicyResult {
+  const policy = config.groupPolicy ?? "allowlist";
+
+  switch (policy) {
+    case "disabled":
+      return { allowed: false, reason: "Group messages disabled" };
+
+    case "open":
+      return { allowed: true };
+
+    case "allowlist": {
+      // Check group-specific allowlist first
+      const groupConfig = resolveGroupConfig(config, groupId);
+      const groupAllowFrom = groupConfig?.allowFrom ?? config.groupAllowFrom ?? [];
+
+      if (groupAllowFrom.length === 0) {
+        // No allowlist configured, deny by default
+        return {
+          allowed: false,
+          reason: "No group allowlist configured",
+        };
+      }
+
+      const match = matchAllowlist(groupAllowFrom, senderId, senderName);
+      return match.allowed
+        ? { allowed: true }
+        : { allowed: false, reason: "Sender not in group allowlist" };
+    }
+
+    default:
+      return { allowed: false, reason: `Unknown group policy: ${policy}` };
+  }
+}
+
+// ============================================================================
+// Mention Policy
+// ============================================================================
+
+/**
+ * Check if an @mention is required for the given context.
+ */
+export function shouldRequireMention(
+  config: Config,
+  chatType: "p2p" | "group",
+  groupId?: string | null
+): boolean {
+  // Never require mention in DMs
+  if (chatType === "p2p") {
+    return false;
+  }
+
+  // Check group-specific config
+  const groupConfig = resolveGroupConfig(config, groupId);
+  if (groupConfig?.requireMention !== undefined) {
+    return groupConfig.requireMention;
+  }
+
+  // Fall back to global config
+  return config.requireMention ?? true;
+}
+
+/**
+ * Get tool policy for a group.
+ */
+export function resolveGroupToolPolicy(
+  config: Config,
+  groupId: string | null | undefined
+): { allow?: string[]; deny?: string[] } | undefined {
+  const groupConfig = resolveGroupConfig(config, groupId);
+  return groupConfig?.tools;
+}

package/src/core/reply-dispatcher.ts

@@ -0,0 +1,151 @@
+/**
+ * Reply dispatcher for Feishu.
+ * Creates a dispatcher that sends agent replies back to Feishu.
+ */
+
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+
+import type { ClawdbotConfig, RuntimeEnv, ReplyPayload, PluginRuntime } from "clawdbot/plugin-sdk";
+import {
+  createReplyPrefixContext,
+  createTypingCallbacks,
+  logTypingFailure,
+} from "clawdbot/plugin-sdk";
+
+import { getRuntime } from "./runtime.js";
+import { sendTextMessage } from "../api/messages.js";
+import { addReaction, removeReaction, Emoji } from "../api/reactions.js";
+import type { Config } from "../config/schema.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface CreateReplyDispatcherParams {
+  cfg: ClawdbotConfig;
+  agentId: string;
+  runtime: RuntimeEnv;
+  chatId: string;
+  replyToMessageId?: string;
+}
+
+interface TypingIndicatorState {
+  messageId: string;
+  emoji: string;
+}
+
+// ============================================================================
+// Reply Dispatcher
+// ============================================================================
+
+export function createReplyDispatcher(params: CreateReplyDispatcherParams) {
+  const core = getRuntime() as PluginRuntime;
+  const { cfg, agentId, chatId, replyToMessageId } = params;
+  const feishuCfg = cfg.channels?.feishu as Config | undefined;
+
+  const prefixContext = createReplyPrefixContext({
+    cfg,
+    agentId,
+  });
+
+  // Typing indicator using reactions
+  let typingState: TypingIndicatorState | null = null;
+
+  const typingCallbacks = createTypingCallbacks({
+    start: async () => {
+      if (!replyToMessageId || !feishuCfg) return;
+      try {
+        const reactionId = await addReaction(feishuCfg, {
+          messageId: replyToMessageId,
+          emojiType: Emoji.TYPING,
+        });
+        typingState = { messageId: replyToMessageId, emoji: reactionId };
+        params.runtime.log?.(`Added typing indicator reaction`);
+      } catch (err) {
+        params.runtime.log?.(`Failed to add typing reaction: ${String(err)}`);
+      }
+    },
+    stop: async () => {
+      if (!typingState || !feishuCfg) return;
+      try {
+        await removeReaction(feishuCfg, {
+          messageId: typingState.messageId,
+          reactionId: typingState.emoji,
+        });
+        typingState = null;
+        params.runtime.log?.(`Removed typing indicator reaction`);
+      } catch (err) {
+        params.runtime.log?.(`Failed to remove typing reaction: ${String(err)}`);
+      }
+    },
+    onStartError: (err) => {
+      logTypingFailure({
+        log: (message) => params.runtime.log?.(message),
+        channel: "feishu",
+        action: "start",
+        error: err,
+      });
+    },
+    onStopError: (err) => {
+      logTypingFailure({
+        log: (message) => params.runtime.log?.(message),
+        channel: "feishu",
+        action: "stop",
+        error: err,
+      });
+    },
+  });
+
+  const textChunkLimit = core.channel.text.resolveTextChunkLimit({
+    cfg,
+    channel: "feishu",
+    defaultLimit: 4000,
+  });
+  const chunkMode = core.channel.text.resolveChunkMode(cfg, "feishu");
+  const tableMode = core.channel.text.resolveMarkdownTableMode({
+    cfg,
+    channel: "feishu",
+  });
+
+  const { dispatcher, replyOptions, markDispatchIdle } =
+    core.channel.reply.createReplyDispatcherWithTyping({
+      responsePrefix: prefixContext.responsePrefix,
+      responsePrefixContextProvider: prefixContext.responsePrefixContextProvider,
+      humanDelay: core.channel.reply.resolveHumanDelayConfig(cfg, agentId),
+      onReplyStart: typingCallbacks.onReplyStart,
+      deliver: async (payload: ReplyPayload) => {
+        params.runtime.log?.(`Deliver called: text=${payload.text?.slice(0, 100)}`);
+        const text = payload.text ?? "";
+        if (!text.trim()) {
+          params.runtime.log?.(`Deliver: empty text, skipping`);
+          return;
+        }
+
+        const converted = core.channel.text.convertMarkdownTables(text, tableMode);
+        const chunks = core.channel.text.chunkTextWithMode(converted, textChunkLimit, chunkMode);
+
+        params.runtime.log?.(`Deliver: sending ${chunks.length} chunks to ${chatId}`);
+        for (const chunk of chunks) {
+          await sendTextMessage(feishuCfg!, {
+            to: chatId,
+            text: chunk,
+            replyToMessageId,
+          });
+        }
+      },
+      onError: (err, info) => {
+        params.runtime.error?.(`${info.kind} reply failed: ${String(err)}`);
+        typingCallbacks.onIdle?.();
+      },
+      onIdle: typingCallbacks.onIdle,
+    });
+
+  return {
+    dispatcher,
+    replyOptions: {
+      ...replyOptions,
+      onModelSelected: prefixContext.onModelSelected,
+    },
+    markDispatchIdle,
+  };
+}

package/src/core/runtime.ts

@@ -0,0 +1,27 @@
+/**
+ * Runtime management for Feishu plugin.
+ * Separated to avoid circular dependencies between plugin and core modules.
+ */
+
+import type { PluginRuntime } from "clawdbot/plugin-sdk";
+
+let feishuRuntime: PluginRuntime | null = null;
+
+/**
+ * Initialize the runtime for Feishu operations.
+ * Called during plugin registration.
+ */
+export function initializeRuntime(runtime: PluginRuntime): void {
+  feishuRuntime = runtime;
+}
+
+/**
+ * Get the current runtime.
+ * @throws Error if runtime not initialized
+ */
+export function getRuntime(): PluginRuntime {
+  if (!feishuRuntime) {
+    throw new Error("Feishu runtime not initialized");
+  }
+  return feishuRuntime;
+}

package/src/index.ts

@@ -0,0 +1,108 @@
+/**
+ * Package entry point.
+ * Exports all public APIs for the Feishu channel plugin.
+ */
+
+// Plugin (default export)
+export { default } from "./plugin/index.js";
+
+// Channel plugin
+export { feishuChannel } from "./plugin/channel.js";
+
+// Runtime management
+export { initializeRuntime, getRuntime } from "./plugin/index.js";
+
+// API operations
+export {
+  sendTextMessage,
+  sendCardMessage,
+  editMessage,
+  updateCard,
+  getMessage,
+  normalizeTarget,
+  isValidId,
+} from "./api/messages.js";
+
+export {
+  uploadImage,
+  uploadFile,
+  sendMedia,
+  sendImage,
+  sendFile,
+  detectFileType,
+} from "./api/media.js";
+
+export { addReaction, removeReaction, listReactions, Emoji } from "./api/reactions.js";
+
+export { listUsers, listGroups } from "./api/directory.js";
+
+export { probeConnection, getApiClient, clearClientCache } from "./api/client.js";
+
+// Core utilities
+export { startGateway, stopGateway, getBotOpenId } from "./core/gateway.js";
+
+export { parseMessageEvent, isBotMentioned, stripMentions } from "./core/parser.js";
+
+export {
+  checkDmPolicy,
+  checkGroupPolicy,
+  shouldRequireMention,
+  matchAllowlist,
+} from "./core/policy.js";
+
+export {
+  validateMessage,
+  sendReply,
+  sendChunkedReply,
+  addTypingIndicator,
+  removeTypingIndicator,
+} from "./core/dispatcher.js";
+
+// Configuration
+export {
+  ConfigSchema,
+  resolveCredentials,
+  type Config,
+  type GroupConfig,
+  type Credentials,
+} from "./config/schema.js";
+
+// Types
+export type {
+  // Events
+  MessageReceivedEvent,
+  BotAddedEvent,
+  BotRemovedEvent,
+  MessageSender,
+  MessagePayload,
+  MessageMention,
+  EventHandlers,
+  // Messages
+  SendTextParams,
+  SendCardParams,
+  EditMessageParams,
+  SendResult,
+  MessageInfo,
+  ParsedMessage,
+  ReceiveIdType,
+  ChatType,
+  // Media
+  UploadImageParams,
+  UploadFileParams,
+  SendMediaParams,
+  ImageUploadResult,
+  FileUploadResult,
+  FileType,
+  SendImageParams,
+  SendFileParams,
+  // Reactions
+  Reaction,
+  AddReactionParams,
+  RemoveReactionParams,
+  // Directory
+  DirectoryUser,
+  DirectoryGroup,
+  ListDirectoryParams,
+  // Probe
+  ProbeResult,
+} from "./types/index.js";