openclaw/extensions/feishu/src/config-schema.ts

// Feishu helper module supports config schema behavior.
import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
import {
  DmPolicySchema,
  GroupPolicySchema,
  buildChannelConfigSchema,
  buildGroupEntrySchema,
  buildMultiAccountChannelSchema,
} from "openclaw/plugin-sdk/channel-config-schema";
import { z } from "zod";
import { buildSecretInputSchema, hasConfiguredSecretInput } from "./secret-input.js";
import { DEFAULT_FEISHU_WEBHOOK_PATH, normalizeFeishuWebhookPath } from "./webhook-path.js";
export { z };

const ChannelActionsSchema = z
  .object({
    reactions: z.boolean().optional(),
  })
  .strict()
  .optional();

const FeishuGroupPolicySchema = z.union([
  GroupPolicySchema,
  // Preserve the shipped Feishu alias while the canonical value remains "open".
  z.literal("allowall").transform(() => "open" as const),
]);
const FeishuDomainSchema = z.union([
  z.enum(["feishu", "lark"]),
  z.string().url().startsWith("https://"),
]);
const FeishuConnectionModeSchema = z.enum(["websocket", "webhook"]);
const FeishuWebhookPathSchema = z
  .string()
  .refine((value) => normalizeFeishuWebhookPath(value) === value, {
    message:
      'webhookPath must be a canonical HTTP request path; run "openclaw doctor --fix" to repair it',
  });
const TtsOverrideSchema = z
  .object({
    auto: z.enum(["off", "always", "inbound", "tagged"]).optional(),
    enabled: z.boolean().optional(),
    mode: z.enum(["final", "all"]).optional(),
    provider: z.string().optional(),
    persona: z.string().optional(),
    personas: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
    summaryModel: z.string().optional(),
    modelOverrides: z.record(z.string(), z.unknown()).optional(),
    providers: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
    prefsPath: z.string().optional(),
    maxTextLength: z.number().int().min(1).optional(),
    timeoutMs: z.number().int().min(1000).max(120000).optional(),
  })
  .strict()
  .optional();

const ToolPolicySchema = z
  .object({
    allow: z.array(z.string()).optional(),
    deny: z.array(z.string()).optional(),
  })
  .strict()
  .optional();

const DmConfigSchema = z
  .object({
    enabled: z.boolean().optional(),
    systemPrompt: z.string().optional(),
  })
  .strict()
  .optional();

const MarkdownConfigSchema = z
  .object({
    mode: z.enum(["native", "escape", "strip"]).optional(),
    tableMode: z.enum(["native", "ascii", "simple"]).optional(),
  })
  .strict()
  .optional();

// Message render mode: auto (default) = detect markdown, raw = plain text, card = always card
const RenderModeSchema = z.enum(["auto", "raw", "card"]).optional();

// Field names must match the core coalesce reader
// (resolveChannelStreamingBlockCoalesce); the legacy feishu-local
// enabled/minDelayMs/maxDelayMs spelling was never read by any runtime path.
const BlockStreamingCoalesceSchema = z
  .object({
    minChars: z.number().int().positive().optional(),
    maxChars: z.number().int().positive().optional(),
    idleMs: z.number().int().nonnegative().optional(),
  })
  .strict()
  .optional();

// Streaming config: `mode` gates Feishu Card Kit streaming-card replies
// ("partial" = streaming cards, default; "off" = single final message);
// `chunkMode`/`block` are the shared delivery controls. Legacy boolean
// `streaming` and flat chunkMode/blockStreaming/blockStreamingCoalesce keys
// migrate via `openclaw doctor --fix`.
const FeishuStreamingSchema = z
  .object({
    mode: z.enum(["off", "partial"]).optional(),
    chunkMode: z.enum(["length", "newline"]).optional(),
    block: z
      .object({
        enabled: z.boolean().optional(),
        coalesce: BlockStreamingCoalesceSchema,
      })
      .strict()
      .optional(),
  })
  .strict()
  .optional();

const ChannelHeartbeatVisibilitySchema = z
  .object({
    visibility: z.enum(["visible", "hidden"]).optional(),
    intervalMs: z.number().int().positive().optional(),
  })
  .strict()
  .optional();

/**
 * Dynamic agent creation configuration.
 * When enabled, a new agent is created for each unique DM user.
 */
const DynamicAgentCreationSchema = z
  .object({
    enabled: z.boolean().optional(),
    workspaceTemplate: z.string().optional(),
    agentDirTemplate: z.string().optional(),
    maxAgents: z.number().int().positive().optional(),
  })
  .strict()
  .optional();

/**
 * Feishu tools configuration.
 * Controls which tool categories are enabled.
 *
 * Dependencies:
 * - wiki requires doc (wiki content is edited via doc tools)
 * - perm can work independently but is typically used with drive
 */
const FeishuToolsConfigSchema = z
  .object({
    doc: z.boolean().optional(), // Document operations (default: true)
    chat: z.boolean().optional(), // Chat info + member query operations (default: true)
    wiki: z.boolean().optional(), // Knowledge base operations (default: true, requires doc)
    drive: z.boolean().optional(), // Cloud storage operations (default: true)
    perm: z.boolean().optional(), // Permission management (default: false, sensitive)
    scopes: z.boolean().optional(), // App scopes diagnostic (default: true)
    bitable: z.boolean().optional(), // Bitable/Base operations (default: true)
  })
  .strict()
  .optional();

/**
 * Group session scope for routing Feishu group messages.
 * - "group" (default): one session per group chat
 * - "group_sender": one session per (group + sender)
 * - "group_topic": one session per group topic thread (falls back to group if no topic)
 * - "group_topic_sender": one session per (group + topic thread + sender),
 *   falls back to (group + sender) if no topic
 */
const GroupSessionScopeSchema = z
  .enum(["group", "group_sender", "group_topic", "group_topic_sender"])
  .optional();

/**
 * @deprecated Use groupSessionScope instead.
 *
 * Topic session isolation mode for group chats.
 * - "disabled" (default): All messages in a group share one session
 * - "enabled": Messages in different topics get separate sessions
 *
 * Topic routing uses Feishu topic-group `thread_id` when the event identifies a
 * native topic group, and keeps `root_id` precedence for normal groups so
 * reply-created threads stay on the initiating message session.
 */
const TopicSessionModeSchema = z.enum(["disabled", "enabled"]).optional();
const ReactionNotificationModeSchema = z.enum(["off", "own", "all"]).optional();

/**
 * Reply-in-thread mode for group chats.
 * - "disabled" (default): Bot replies are normal inline replies
 * - "enabled": Bot replies create or continue a Feishu topic thread
 *
 * When enabled, the Feishu reply API is called with `reply_in_thread: true`,
 * causing the reply to appear as a topic (话题) under the original message.
 */
const ReplyInThreadSchema = z.enum(["disabled", "enabled"]).optional();

const FeishuGroupSchema = buildGroupEntrySchema({
  tools: ToolPolicySchema,
  groupSessionScope: GroupSessionScopeSchema,
  topicSessionMode: TopicSessionModeSchema,
  replyInThread: ReplyInThreadSchema,
}).omit({ toolsBySender: true });

const FeishuSharedConfigShape = {
  webhookHost: z.string().optional(),
  webhookPort: z.number().int().positive().optional(),
  capabilities: z.array(z.string()).optional(),
  markdown: MarkdownConfigSchema,
  configWrites: z.boolean().optional(),
  dmPolicy: DmPolicySchema.optional(),
  allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
  groupPolicy: FeishuGroupPolicySchema.optional(),
  groupAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
  groupSenderAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
  requireMention: z.boolean().optional(),
  groups: z.record(z.string(), FeishuGroupSchema.optional()).optional(),
  historyLimit: z.number().int().min(0).optional(),
  dmHistoryLimit: z.number().int().min(0).optional(),
  dms: z.record(z.string(), DmConfigSchema).optional(),
  textChunkLimit: z.number().int().positive().optional(),
  mediaMaxMb: z.number().positive().optional(),
  httpTimeoutMs: z.number().int().positive().max(300_000).optional(),
  heartbeatVisibility: ChannelHeartbeatVisibilitySchema,
  renderMode: RenderModeSchema,
  streaming: FeishuStreamingSchema,
  tools: FeishuToolsConfigSchema,
  actions: ChannelActionsSchema,
  replyInThread: ReplyInThreadSchema,
  reactionNotifications: ReactionNotificationModeSchema,
  typingIndicator: z.boolean().optional(),
  resolveSenderNames: z.boolean().optional(),
  allowBots: z.boolean().optional(),
  vcAutoJoin: z.boolean().optional(),
  tts: TtsOverrideSchema,
};

/**
 * Per-account configuration.
 * All fields are optional - missing fields inherit from top-level config.
 */
export const FeishuAccountConfigSchema = z
  .object({
    enabled: z.boolean().optional(),
    name: z.string().optional(), // Display name for this account
    appId: z.string().optional(),
    appSecret: buildSecretInputSchema().optional(),
    encryptKey: buildSecretInputSchema().optional(),
    verificationToken: buildSecretInputSchema().optional(),
    domain: FeishuDomainSchema.optional(),
    connectionMode: FeishuConnectionModeSchema.optional(),
    webhookPath: FeishuWebhookPathSchema.optional(),
    ...FeishuSharedConfigShape,
    groupSessionScope: GroupSessionScopeSchema,
    topicSessionMode: TopicSessionModeSchema,
  })
  .strict();

const FeishuConfigSchemaBase = z
  .object({
    enabled: z.boolean().optional(),
    defaultAccount: z.string().optional(),
    // Top-level credentials (backward compatible for single-account mode)
    appId: z.string().optional(),
    appSecret: buildSecretInputSchema().optional(),
    encryptKey: buildSecretInputSchema().optional(),
    verificationToken: buildSecretInputSchema().optional(),
    domain: FeishuDomainSchema.optional().default("feishu"),
    connectionMode: FeishuConnectionModeSchema.optional().default("websocket"),
    webhookPath: FeishuWebhookPathSchema.optional().default(DEFAULT_FEISHU_WEBHOOK_PATH),
    ...FeishuSharedConfigShape,
    dmPolicy: DmPolicySchema.optional().default("pairing"),
    reactionNotifications: ReactionNotificationModeSchema.optional().default("own"),
    groupPolicy: FeishuGroupPolicySchema.optional().default("allowlist"),
    requireMention: z.boolean().optional(),
    groupSessionScope: GroupSessionScopeSchema,
    topicSessionMode: TopicSessionModeSchema,
    // Dynamic agent creation for DM users
    dynamicAgentCreation: DynamicAgentCreationSchema,
    // Optimization flags
    typingIndicator: z.boolean().optional().default(true),
    resolveSenderNames: z.boolean().optional().default(true),
  })
  .strict();

export const FeishuConfigSchema = buildMultiAccountChannelSchema(FeishuConfigSchemaBase, {
  accountSchema: FeishuAccountConfigSchema,
  optionalAccount: true,
}).superRefine((value, ctx) => {
  const defaultAccount = value.defaultAccount?.trim();
  if (defaultAccount && value.accounts && Object.keys(value.accounts).length > 0) {
    const normalizedDefaultAccount = normalizeAccountId(defaultAccount);
    if (!Object.hasOwn(value.accounts, normalizedDefaultAccount)) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        path: ["defaultAccount"],
        message: `channels.feishu.defaultAccount="${defaultAccount}" does not match a configured account key`,
      });
    }
  }

  const defaultConnectionMode = value.connectionMode ?? "websocket";
  const defaultVerificationTokenConfigured = hasConfiguredSecretInput(value.verificationToken);
  const defaultEncryptKeyConfigured = hasConfiguredSecretInput(value.encryptKey);
  if (defaultConnectionMode === "webhook") {
    if (!defaultVerificationTokenConfigured) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        path: ["verificationToken"],
        message:
          'channels.feishu.connectionMode="webhook" requires channels.feishu.verificationToken',
      });
    }
    if (!defaultEncryptKeyConfigured) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        path: ["encryptKey"],
        message: 'channels.feishu.connectionMode="webhook" requires channels.feishu.encryptKey',
      });
    }
  }

  for (const [accountId, account] of Object.entries(value.accounts ?? {})) {
    if (!account) {
      continue;
    }
    const accountConnectionMode = account.connectionMode ?? defaultConnectionMode;
    if (accountConnectionMode !== "webhook") {
      continue;
    }
    const accountVerificationTokenConfigured =
      hasConfiguredSecretInput(account.verificationToken) || defaultVerificationTokenConfigured;
    const accountEncryptKeyConfigured =
      hasConfiguredSecretInput(account.encryptKey) || defaultEncryptKeyConfigured;
    if (!accountVerificationTokenConfigured) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        path: ["accounts", accountId, "verificationToken"],
        message:
          `channels.feishu.accounts.${accountId}.connectionMode="webhook" requires ` +
          "a verificationToken (account-level or top-level)",
      });
    }
    if (!accountEncryptKeyConfigured) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        path: ["accounts", accountId, "encryptKey"],
        message:
          `channels.feishu.accounts.${accountId}.connectionMode="webhook" requires ` +
          "an encryptKey (account-level or top-level)",
      });
    }
  }

  if (value.dmPolicy === "open") {
    const allowFrom = value.allowFrom ?? [];
    const hasWildcard = allowFrom.some((entry) => String(entry).trim() === "*");
    if (!hasWildcard) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        path: ["allowFrom"],
        message:
          'channels.feishu.dmPolicy="open" requires channels.feishu.allowFrom to include "*"',
      });
    }
  }
});

export const FeishuChannelConfigSchema = buildChannelConfigSchema(FeishuConfigSchema, {
  jsonSchemaMode: "input",
});