Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

15.9 KB
Raw Blame
/**
 * Messaging binding form helpers — conversion between the channel-aware editor's editable
 * state and the per-channel PUT/test DTOs (pure logic, unit-tested without a DOM; the
 * mcp-servers-form convention). The form keeps one sub-state per channel so switching the
 * selector back and forth never loses what was typed; `channel` names the selected one,
 * and only its fields are validated or submitted.
 *
 * QQ's sub-state mirrors Feishu's minus the domain field: the platform has one host, so
 * there is nothing for a domain to switch between. WeChat's has no credential at all — its
 * token comes only from a scan, which writes it server-side — so its sub-state is the
 * delivery preferences plus the clear checkbox, and its submit can never fail validation.
 *
 * Not every field is a credential: `linePerMessage` (send a reply one message per non-blank
 * line), `finalReplyOnly` (send only a run's last reply, when the run ends) and
 * `renderMarkdown` (render its Markdown in the channel's own markup) are per-binding
 * delivery preferences that ride the same Save as the rest, which is why they live in the form
 * state rather than behind toggles of their own.
 *
 * Secrets never round-trip: `bindingToForm` always leaves the secret field empty (the
 * server only ever returns a masked value), and `formToPut` omits a blank one so the
 * server keeps the stored value. Validation errors come back as codes; the component maps
 * them to localized messages.
 */
import type {
  FeishuBindingPutRequest,
  FeishuTestRequest,
  MessagingBindingInfo,
  MessagingChannel,
  QQBindingPutRequest,
  QQTestRequest,
  TelegramBindingPutRequest,
  TelegramTestRequest,
  WeChatBindingPutRequest,
} from "@adelie/server/api";

/** Default Feishu open-platform domain (shown prefilled; Lark tenants overwrite it). */
export const FEISHU_DEFAULT_DOMAIN = "https://open.feishu.cn";

/** The token shape @BotFather issues — mirrors the server's identity rule, for immediate feedback. */
const TELEGRAM_TOKEN_RE = /^\d+:[A-Za-z0-9_-]{5,}$/;

/**
 * The delivery preferences every channel carries — the saved fields that are not credentials,
 * identical in meaning on every channel, which is what lets one row render each of them
 * whichever channel is selected.
 */
export interface MessagingDeliveryFields {
  /** Deliver a reply as one message per non-blank line. */
  linePerMessage: boolean;
  /** Deliver only a run's LAST completed reply, at the run's end, instead of each as it completes. */
  finalReplyOnly: boolean;
  /** Render a reply's Markdown in this channel's own markup instead of sending its characters. */
  renderMarkdown: boolean;
}

export interface FeishuFormFields extends MessagingDeliveryFields {
  appId: string;
  /** Always starts empty; a non-empty value replaces the stored secret on save. */
  appSecret: string;
  baseDomain: string;
  /** The stored-secret clear checkbox (models idiom): applied on save, a typed secret wins over it. */
  clearSecret: boolean;
}

export interface QQFormFields extends MessagingDeliveryFields {
  appId: string;
  /** Always starts empty; a non-empty value replaces the stored secret on save. */
  appSecret: string;
  /** The stored-secret clear checkbox (models idiom): applied on save, a typed secret wins over it. */
  clearSecret: boolean;
}

/**
 * WeChat's editable state: the delivery preferences, and the clear checkbox.
 *
 * No credential field, because there is nothing to type — the bot token arrives from a scan
 * and is stored without ever passing through this form.
 */
export interface WeChatFormFields extends MessagingDeliveryFields {
  /** The stored-token clear checkbox (models idiom): applied on save. */
  clearToken: boolean;
}

export interface TelegramFormFields extends MessagingDeliveryFields {
  /** Always starts empty; a non-empty value replaces the stored token on save. */
  botToken: string;
  /** The stored-token clear checkbox (models idiom): applied on save, a typed token wins over it. */
  clearToken: boolean;
}

/** Editable state backing the binding editor: the selected channel plus every channel's fields. */
export interface MessagingFormState {
  channel: MessagingChannel;
  feishu: FeishuFormFields;
  telegram: TelegramFormFields;
  qq: QQFormFields;
  wechat: WeChatFormFields;
}

export type MessagingFormField = "appId" | "appSecret" | "baseDomain" | "botToken";

export type MessagingFormErrorCode = "required" | "url_invalid" | "token_invalid";

export type MessagingFormErrors = Partial<Record<MessagingFormField, MessagingFormErrorCode>>;

/** A valid submit names its channel so the caller picks that channel's endpoint. */
export type MessagingFormResult =
  | { ok: true; channel: "feishu"; body: FeishuBindingPutRequest }
  | { ok: true; channel: "telegram"; body: TelegramBindingPutRequest }
  | { ok: true; channel: "qq"; body: QQBindingPutRequest }
  | { ok: true; channel: "wechat"; body: WeChatBindingPutRequest }
  | { ok: false; errors: MessagingFormErrors };

export type MessagingTestRequestByChannel =
  | { channel: "feishu"; body: FeishuTestRequest }
  | { channel: "telegram"; body: TelegramTestRequest }
  | { channel: "qq"; body: QQTestRequest }
  /** WeChat's probe carries no body: nothing on its form is a credential to send. */
  | { channel: "wechat" };

export function emptyMessagingForm(channel: MessagingChannel = "feishu"): MessagingFormState {
  return {
    channel,
    // `renderMarkdown` starts ON, matching what the server gives a binding created without
    // an opinion: a reply's Markdown is meant to render, and raw `**bold**` was the defect.
    feishu: {
      appId: "",
      appSecret: "",
      baseDomain: FEISHU_DEFAULT_DOMAIN,
      clearSecret: false,
      linePerMessage: false,
      finalReplyOnly: false,
      renderMarkdown: true,
    },
    telegram: {
      botToken: "",
      clearToken: false,
      linePerMessage: false,
      finalReplyOnly: false,
      renderMarkdown: true,
    },
    qq: {
      appId: "",
      appSecret: "",
      clearSecret: false,
      linePerMessage: false,
      finalReplyOnly: false,
      renderMarkdown: true,
    },
    wechat: {
      clearToken: false,
      linePerMessage: false,
      finalReplyOnly: false,
      renderMarkdown: true,
    },
  };
}

/**
 * Builds the editor's form from every saved config: each channel's non-secret fields
 * load (secrets stay empty — masked values never round-trip — and clear checkboxes start
 * unchecked), and the selector starts on the enabled channel, else the first saved one,
 * else Feishu.
 */
export function bindingsToForm(bindings: MessagingBindingInfo[]): MessagingFormState {
  const enabled = bindings.find((b) => b.enabled)?.channel;
  const form = emptyMessagingForm(enabled ?? bindings[0]?.channel ?? "feishu");
  for (const info of bindings) {
    if (info.channel === "feishu") {
      form.feishu = {
        appId: info.appId,
        appSecret: "",
        baseDomain: info.baseDomain,
        clearSecret: false,
        linePerMessage: info.linePerMessage,
        finalReplyOnly: info.finalReplyOnly,
        renderMarkdown: info.renderMarkdown,
      };
    } else if (info.channel === "wechat") {
      // Nothing but preferences loads: this channel's only credential is the token, which
      // the form never holds.
      form.wechat = {
        clearToken: false,
        linePerMessage: info.linePerMessage,
        finalReplyOnly: info.finalReplyOnly,
        renderMarkdown: info.renderMarkdown,
      };
    } else if (info.channel === "qq") {
      form.qq = {
        appId: info.appId,
        appSecret: "",
        clearSecret: false,
        linePerMessage: info.linePerMessage,
        finalReplyOnly: info.finalReplyOnly,
        renderMarkdown: info.renderMarkdown,
      };
    } else {
      // Telegram's only credential field is the secret itself, so its sub-state loads empty
      // apart from the delivery preferences, which are not credentials.
      form.telegram = {
        botToken: "",
        clearToken: false,
        linePerMessage: info.linePerMessage,
        finalReplyOnly: info.finalReplyOnly,
        renderMarkdown: info.renderMarkdown,
      };
    }
  }
  return form;
}

/** A syntactically valid http(s) URL (the server normalizes to the origin). */
function isHttpUrl(raw: string): boolean {
  try {
    const url = new URL(raw);
    return url.protocol === "http:" || url.protocol === "https:";
  } catch {
    return false;
  }
}

/**
 * Validates the selected channel's fields and builds its PUT body. `hasStoredSecret`
 * relaxes the secret requirement: with a saved binding an empty field means "keep it",
 * on a first bind it is an error. A blank Feishu domain falls back to the default rather
 * than erroring — the field is prefilled, and clearing it is a "give me the default"
 * gesture.
 */
export function formToPut(form: MessagingFormState, hasStoredSecret: boolean): MessagingFormResult {
  const errors: MessagingFormErrors = {};
  if (form.channel === "telegram") {
    const botToken = form.telegram.botToken.trim();
    // A typed token wins over a stale clear checkbox (the models idiom).
    const clearing = botToken === "" && form.telegram.clearToken && hasStoredSecret;
    if (botToken === "" && !hasStoredSecret) errors.botToken = "required";
    else if (botToken !== "" && !TELEGRAM_TOKEN_RE.test(botToken)) {
      errors.botToken = "token_invalid";
    }
    if (Object.keys(errors).length > 0) return { ok: false, errors };
    return {
      ok: true,
      channel: "telegram",
      body: {
        ...(botToken !== "" ? { botToken } : {}),
        ...(clearing ? { clearBotToken: true } : {}),
        // Always sent, unlike the credential fields: an omitted flag means "keep", which
        // would make turning either option back off impossible.
        linePerMessage: form.telegram.linePerMessage,
        finalReplyOnly: form.telegram.finalReplyOnly,
        renderMarkdown: form.telegram.renderMarkdown,
      },
    };
  }
  if (form.channel === "wechat") {
    // The one submit that cannot fail: there is no field to leave blank or to mistype.
    return {
      ok: true,
      channel: "wechat",
      body: {
        ...(form.wechat.clearToken && hasStoredSecret ? { clearBotToken: true } : {}),
        // Always sent, for the same reason as the other channels': an omitted flag means "keep".
        linePerMessage: form.wechat.linePerMessage,
        finalReplyOnly: form.wechat.finalReplyOnly,
        renderMarkdown: form.wechat.renderMarkdown,
      },
    };
  }
  if (form.channel === "qq") {
    const appId = form.qq.appId.trim();
    if (appId === "") errors.appId = "required";
    const appSecret = form.qq.appSecret.trim();
    const clearing = appSecret === "" && form.qq.clearSecret && hasStoredSecret;
    if (appSecret === "" && !hasStoredSecret) errors.appSecret = "required";
    if (Object.keys(errors).length > 0) return { ok: false, errors };
    return {
      ok: true,
      channel: "qq",
      body: {
        appId,
        ...(appSecret !== "" ? { appSecret } : {}),
        ...(clearing ? { clearAppSecret: true } : {}),
        // Always sent, for the same reason as the other channels': an omitted flag means "keep".
        linePerMessage: form.qq.linePerMessage,
        finalReplyOnly: form.qq.finalReplyOnly,
        renderMarkdown: form.qq.renderMarkdown,
      },
    };
  }
  const appId = form.feishu.appId.trim();
  if (appId === "") errors.appId = "required";
  const appSecret = form.feishu.appSecret.trim();
  const clearing = appSecret === "" && form.feishu.clearSecret && hasStoredSecret;
  if (appSecret === "" && !hasStoredSecret) errors.appSecret = "required";
  const baseDomain = form.feishu.baseDomain.trim() || FEISHU_DEFAULT_DOMAIN;
  if (!isHttpUrl(baseDomain)) errors.baseDomain = "url_invalid";
  if (Object.keys(errors).length > 0) return { ok: false, errors };
  return {
    ok: true,
    channel: "feishu",
    body: {
      appId,
      ...(appSecret !== "" ? { appSecret } : {}),
      ...(clearing ? { clearAppSecret: true } : {}),
      baseDomain,
      // Always sent, for the same reason as Telegram's: an omitted flag means "keep".
      linePerMessage: form.feishu.linePerMessage,
      finalReplyOnly: form.feishu.finalReplyOnly,
      renderMarkdown: form.feishu.renderMarkdown,
    },
  };
}

/**
 * The credential test's request: only the fields the form actually carries — omitted ones
 * fall back to the stored binding server-side, so testing a saved binding needs no
 * re-typed secret.
 */
export function formToTest(form: MessagingFormState): MessagingTestRequestByChannel {
  if (form.channel === "telegram") {
    const botToken = form.telegram.botToken.trim();
    return { channel: "telegram", body: { ...(botToken !== "" ? { botToken } : {}) } };
  }
  // No draft to send: this channel's probe reads the stored binding.
  if (form.channel === "wechat") return { channel: "wechat" };
  if (form.channel === "qq") {
    const appId = form.qq.appId.trim();
    const appSecret = form.qq.appSecret.trim();
    return {
      channel: "qq",
      body: {
        ...(appId !== "" ? { appId } : {}),
        ...(appSecret !== "" ? { appSecret } : {}),
      },
    };
  }
  const appId = form.feishu.appId.trim();
  const appSecret = form.feishu.appSecret.trim();
  const baseDomain = form.feishu.baseDomain.trim();
  return {
    channel: "feishu",
    body: {
      ...(appId !== "" ? { appId } : {}),
      ...(appSecret !== "" ? { appSecret } : {}),
      ...(baseDomain !== "" ? { baseDomain } : {}),
    },
  };
}

/**
 * Unsaved edits on the selected channel: any field differing from the loaded baseline (a
 * typed secret always counts — it always loads empty — and so does a checked clear box, and
 * so does either delivery preference, which are the only edits a Telegram form can otherwise
 * have nothing to show for).
 */
export function formDirty(form: MessagingFormState, baseline: MessagingFormState): boolean {
  if (form.channel === "telegram") {
    return (
      form.telegram.botToken.trim() !== "" ||
      form.telegram.clearToken ||
      form.telegram.linePerMessage !== baseline.telegram.linePerMessage ||
      form.telegram.finalReplyOnly !== baseline.telegram.finalReplyOnly ||
      form.telegram.renderMarkdown !== baseline.telegram.renderMarkdown
    );
  }
  if (form.channel === "wechat") {
    return (
      form.wechat.clearToken ||
      form.wechat.linePerMessage !== baseline.wechat.linePerMessage ||
      form.wechat.finalReplyOnly !== baseline.wechat.finalReplyOnly ||
      form.wechat.renderMarkdown !== baseline.wechat.renderMarkdown
    );
  }
  if (form.channel === "qq") {
    return (
      form.qq.appId !== baseline.qq.appId ||
      form.qq.appSecret.trim() !== "" ||
      form.qq.clearSecret ||
      form.qq.linePerMessage !== baseline.qq.linePerMessage ||
      form.qq.finalReplyOnly !== baseline.qq.finalReplyOnly ||
      form.qq.renderMarkdown !== baseline.qq.renderMarkdown
    );
  }
  return (
    form.feishu.appId !== baseline.feishu.appId ||
    form.feishu.baseDomain !== baseline.feishu.baseDomain ||
    form.feishu.appSecret.trim() !== "" ||
    form.feishu.clearSecret ||
    form.feishu.linePerMessage !== baseline.feishu.linePerMessage ||
    form.feishu.finalReplyOnly !== baseline.feishu.finalReplyOnly ||
    form.feishu.renderMarkdown !== baseline.feishu.renderMarkdown
  );
}

/**
 * The credential probe needs a testable credential: the selected channel's draft, or its
 * stored secret (`secretConfigured` — a stored config whose secret was cleared has
 * nothing to probe).
 */
export function formTestable(form: MessagingFormState, secretConfigured: boolean): boolean {
  if (form.channel === "telegram") {
    return form.telegram.botToken.trim() !== "" || secretConfigured;
  }
  // WeChat has no draft to probe: only a stored token can be tested.
  if (form.channel === "wechat") return secretConfigured;
  if (form.channel === "qq") {
    return (form.qq.appId.trim() !== "" && form.qq.appSecret.trim() !== "") || secretConfigured;
  }
  return (
    (form.feishu.appId.trim() !== "" && form.feishu.appSecret.trim() !== "") || secretConfigured
  );
}