openclaw/extensions/mattermost/src/channel.ts

import {
  buildAccountScopedDmSecurityPolicy,
  collectAllowlistProviderRestrictSendersWarnings,
  createScopedAccountConfigAccessors,
  formatNormalizedAllowFromEntries,
} from "openclaw/plugin-sdk/compat";
import {
  applyAccountNameToChannelSection,
  applySetupAccountConfigPatch,
  buildComputedAccountStatusSnapshot,
  buildChannelConfigSchema,
  createAccountStatusSink,
  DEFAULT_ACCOUNT_ID,
  deleteAccountFromConfigSection,
  migrateBaseNameToDefaultAccount,
  normalizeAccountId,
  resolveAllowlistProviderRuntimeGroupPolicy,
  resolveDefaultGroupPolicy,
  setAccountEnabledInConfigSection,
  type ChannelMessageActionAdapter,
  type ChannelMessageActionName,
  type ChannelPlugin,
} from "openclaw/plugin-sdk/mattermost";
import { buildPassiveProbedChannelStatusSummary } from "../../shared/channel-status-summary.js";
import { MattermostConfigSchema } from "./config-schema.js";
import { resolveMattermostGroupRequireMention } from "./group-mentions.js";
import {
  listMattermostAccountIds,
  resolveDefaultMattermostAccountId,
  resolveMattermostAccount,
  resolveMattermostReplyToMode,
  type ResolvedMattermostAccount,
} from "./mattermost/accounts.js";
import { normalizeMattermostBaseUrl } from "./mattermost/client.js";
import {
  listMattermostDirectoryGroups,
  listMattermostDirectoryPeers,
} from "./mattermost/directory.js";
import { monitorMattermostProvider } from "./mattermost/monitor.js";
import { probeMattermost } from "./mattermost/probe.js";
import { addMattermostReaction, removeMattermostReaction } from "./mattermost/reactions.js";
import { sendMessageMattermost } from "./mattermost/send.js";
import { resolveMattermostOpaqueTarget } from "./mattermost/target-resolution.js";
import { looksLikeMattermostTargetId, normalizeMattermostMessagingTarget } from "./normalize.js";
import { mattermostOnboardingAdapter } from "./onboarding.js";
import { getMattermostRuntime } from "./runtime.js";

const mattermostMessageActions: ChannelMessageActionAdapter = {
  listActions: ({ cfg }) => {
    const enabledAccounts = listMattermostAccountIds(cfg)
      .map((accountId) => resolveMattermostAccount({ cfg, accountId }))
      .filter((account) => account.enabled)
      .filter((account) => Boolean(account.botToken?.trim() && account.baseUrl?.trim()));

    const actions: ChannelMessageActionName[] = [];

    // Send (buttons) is available whenever there's at least one enabled account
    if (enabledAccounts.length > 0) {
      actions.push("send");
    }

    // React requires per-account reactions config check
    const actionsConfig = cfg.channels?.mattermost?.actions as { reactions?: boolean } | undefined;
    const baseReactions = actionsConfig?.reactions;
    const hasReactionCapableAccount = enabledAccounts.some((account) => {
      const accountActions = account.config.actions as { reactions?: boolean } | undefined;
      return (accountActions?.reactions ?? baseReactions ?? true) !== false;
    });
    if (hasReactionCapableAccount) {
      actions.push("react");
    }

    return actions;
  },
  supportsAction: ({ action }) => {
    return action === "send" || action === "react";
  },
  supportsButtons: ({ cfg }) => {
    const accounts = listMattermostAccountIds(cfg)
      .map((id) => resolveMattermostAccount({ cfg, accountId: id }))
      .filter((a) => a.enabled && a.botToken?.trim() && a.baseUrl?.trim());
    return accounts.length > 0;
  },
  handleAction: async ({ action, params, cfg, accountId }) => {
    if (action === "react") {
      // Check reactions gate: per-account config takes precedence over base config
      const mmBase = cfg?.channels?.mattermost as Record<string, unknown> | undefined;
      const accounts = mmBase?.accounts as Record<string, Record<string, unknown>> | undefined;
      const resolvedAccountId = accountId ?? resolveDefaultMattermostAccountId(cfg);
      const acctConfig = accounts?.[resolvedAccountId];
      const acctActions = acctConfig?.actions as { reactions?: boolean } | undefined;
      const baseActions = mmBase?.actions as { reactions?: boolean } | undefined;
      const reactionsEnabled = acctActions?.reactions ?? baseActions?.reactions ?? true;
      if (!reactionsEnabled) {
        throw new Error("Mattermost reactions are disabled in config");
      }

      const postIdRaw =
        typeof (params as any)?.messageId === "string"
          ? (params as any).messageId
          : typeof (params as any)?.postId === "string"
            ? (params as any).postId
            : "";
      const postId = postIdRaw.trim();
      if (!postId) {
        throw new Error("Mattermost react requires messageId (post id)");
      }

      const emojiRaw = typeof (params as any)?.emoji === "string" ? (params as any).emoji : "";
      const emojiName = emojiRaw.trim().replace(/^:+|:+$/g, "");
      if (!emojiName) {
        throw new Error("Mattermost react requires emoji");
      }

      const remove = (params as any)?.remove === true;
      if (remove) {
        const result = await removeMattermostReaction({
          cfg,
          postId,
          emojiName,
          accountId: resolvedAccountId,
        });
        if (!result.ok) {
          throw new Error(result.error);
        }
        return {
          content: [
            { type: "text" as const, text: `Removed reaction :${emojiName}: from ${postId}` },
          ],
          details: {},
        };
      }

      const result = await addMattermostReaction({
        cfg,
        postId,
        emojiName,
        accountId: resolvedAccountId,
      });
      if (!result.ok) {
        throw new Error(result.error);
      }

      return {
        content: [{ type: "text" as const, text: `Reacted with :${emojiName}: on ${postId}` }],
        details: {},
      };
    }

    if (action !== "send") {
      throw new Error(`Unsupported Mattermost action: ${action}`);
    }

    // Send action with optional interactive buttons
    const to =
      typeof params.to === "string"
        ? params.to.trim()
        : typeof params.target === "string"
          ? params.target.trim()
          : "";
    if (!to) {
      throw new Error("Mattermost send requires a target (to).");
    }

    const message = typeof params.message === "string" ? params.message : "";
    // Match the shared runner semantics: trim empty reply IDs away before
    // falling back from replyToId to replyTo on direct plugin calls.
    const replyToId = readMattermostReplyToId(params);
    const resolvedAccountId = accountId || undefined;

    const mediaUrl =
      typeof params.media === "string" ? params.media.trim() || undefined : undefined;

    const result = await sendMessageMattermost(to, message, {
      accountId: resolvedAccountId,
      replyToId,
      buttons: Array.isArray(params.buttons) ? params.buttons : undefined,
      attachmentText: typeof params.attachmentText === "string" ? params.attachmentText : undefined,
      mediaUrl,
    });

    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify({
            ok: true,
            channel: "mattermost",
            messageId: result.messageId,
            channelId: result.channelId,
          }),
        },
      ],
      details: {},
    };
  },
};

const meta = {
  id: "mattermost",
  label: "Mattermost",
  selectionLabel: "Mattermost (plugin)",
  detailLabel: "Mattermost Bot",
  docsPath: "/channels/mattermost",
  docsLabel: "mattermost",
  blurb: "self-hosted Slack-style chat; install the plugin to enable.",
  systemImage: "bubble.left.and.bubble.right",
  order: 65,
  quickstartAllowFrom: true,
} as const;

function readMattermostReplyToId(params: Record<string, unknown>): string | undefined {
  const readNormalizedValue = (value: unknown) => {
    if (typeof value !== "string") {
      return undefined;
    }
    const trimmed = value.trim();
    return trimmed || undefined;
  };

  return readNormalizedValue(params.replyToId) ?? readNormalizedValue(params.replyTo);
}

function normalizeAllowEntry(entry: string): string {
  return entry
    .trim()
    .replace(/^(mattermost|user):/i, "")
    .replace(/^@/, "")
    .toLowerCase();
}

function formatAllowEntry(entry: string): string {
  const trimmed = entry.trim();
  if (!trimmed) {
    return "";
  }
  if (trimmed.startsWith("@")) {
    const username = trimmed.slice(1).trim();
    return username ? `@${username.toLowerCase()}` : "";
  }
  return trimmed.replace(/^(mattermost|user):/i, "").toLowerCase();
}

const mattermostConfigAccessors = createScopedAccountConfigAccessors({
  resolveAccount: ({ cfg, accountId }) => resolveMattermostAccount({ cfg, accountId }),
  resolveAllowFrom: (account: ResolvedMattermostAccount) => account.config.allowFrom,
  formatAllowFrom: (allowFrom) =>
    formatNormalizedAllowFromEntries({
      allowFrom,
      normalizeEntry: formatAllowEntry,
    }),
});

export const mattermostPlugin: ChannelPlugin<ResolvedMattermostAccount> = {
  id: "mattermost",
  meta: {
    ...meta,
  },
  onboarding: mattermostOnboardingAdapter,
  pairing: {
    idLabel: "mattermostUserId",
    normalizeAllowEntry: (entry) => normalizeAllowEntry(entry),
    notifyApproval: async ({ id }) => {
      console.log(`[mattermost] User ${id} approved for pairing`);
    },
  },
  capabilities: {
    chatTypes: ["direct", "channel", "group", "thread"],
    reactions: true,
    threads: true,
    media: true,
    nativeCommands: true,
  },
  streaming: {
    blockStreamingCoalesceDefaults: { minChars: 1500, idleMs: 1000 },
  },
  threading: {
    resolveReplyToMode: ({ cfg, accountId, chatType }) => {
      const account = resolveMattermostAccount({ cfg, accountId: accountId ?? "default" });
      const kind =
        chatType === "direct" || chatType === "group" || chatType === "channel"
          ? chatType
          : "channel";
      return resolveMattermostReplyToMode(account, kind);
    },
  },
  reload: { configPrefixes: ["channels.mattermost"] },
  configSchema: buildChannelConfigSchema(MattermostConfigSchema),
  config: {
    listAccountIds: (cfg) => listMattermostAccountIds(cfg),
    resolveAccount: (cfg, accountId) => resolveMattermostAccount({ cfg, accountId }),
    defaultAccountId: (cfg) => resolveDefaultMattermostAccountId(cfg),
    setAccountEnabled: ({ cfg, accountId, enabled }) =>
      setAccountEnabledInConfigSection({
        cfg,
        sectionKey: "mattermost",
        accountId,
        enabled,
        allowTopLevel: true,
      }),
    deleteAccount: ({ cfg, accountId }) =>
      deleteAccountFromConfigSection({
        cfg,
        sectionKey: "mattermost",
        accountId,
        clearBaseFields: ["botToken", "baseUrl", "name"],
      }),
    isConfigured: (account) => Boolean(account.botToken && account.baseUrl),
    describeAccount: (account) => ({
      accountId: account.accountId,
      name: account.name,
      enabled: account.enabled,
      configured: Boolean(account.botToken && account.baseUrl),
      botTokenSource: account.botTokenSource,
      baseUrl: account.baseUrl,
    }),
    ...mattermostConfigAccessors,
  },
  security: {
    resolveDmPolicy: ({ cfg, accountId, account }) => {
      return buildAccountScopedDmSecurityPolicy({
        cfg,
        channelKey: "mattermost",
        accountId,
        fallbackAccountId: account.accountId ?? DEFAULT_ACCOUNT_ID,
        policy: account.config.dmPolicy,
        allowFrom: account.config.allowFrom ?? [],
        policyPathSuffix: "dmPolicy",
        normalizeEntry: (raw) => normalizeAllowEntry(raw),
      });
    },
    collectWarnings: ({ account, cfg }) => {
      return collectAllowlistProviderRestrictSendersWarnings({
        cfg,
        providerConfigPresent: cfg.channels?.mattermost !== undefined,
        configuredGroupPolicy: account.config.groupPolicy,
        surface: "Mattermost channels",
        openScope: "any member",
        groupPolicyPath: "channels.mattermost.groupPolicy",
        groupAllowFromPath: "channels.mattermost.groupAllowFrom",
      });
    },
  },
  groups: {
    resolveRequireMention: resolveMattermostGroupRequireMention,
  },
  actions: mattermostMessageActions,
  directory: {
    listGroups: async (params) => listMattermostDirectoryGroups(params),
    listGroupsLive: async (params) => listMattermostDirectoryGroups(params),
    listPeers: async (params) => listMattermostDirectoryPeers(params),
    listPeersLive: async (params) => listMattermostDirectoryPeers(params),
  },
  messaging: {
    normalizeTarget: normalizeMattermostMessagingTarget,
    targetResolver: {
      looksLikeId: looksLikeMattermostTargetId,
      hint: "<channelId|user:ID|channel:ID>",
      resolveTarget: async ({ cfg, accountId, input }) => {
        const resolved = await resolveMattermostOpaqueTarget({
          input,
          cfg,
          accountId,
        });
        if (!resolved) {
          return null;
        }
        return {
          to: resolved.to,
          kind: resolved.kind,
          source: "directory",
        };
      },
    },
  },
  outbound: {
    deliveryMode: "direct",
    chunker: (text, limit) => getMattermostRuntime().channel.text.chunkMarkdownText(text, limit),
    chunkerMode: "markdown",
    textChunkLimit: 4000,
    resolveTarget: ({ to }) => {
      const trimmed = to?.trim();
      if (!trimmed) {
        return {
          ok: false,
          error: new Error(
            "Delivering to Mattermost requires --to <channelId|@username|user:ID|channel:ID>",
          ),
        };
      }
      return { ok: true, to: trimmed };
    },
    sendText: async ({ cfg, to, text, accountId, replyToId, threadId }) => {
      const result = await sendMessageMattermost(to, text, {
        cfg,
        accountId: accountId ?? undefined,
        replyToId: replyToId ?? (threadId != null ? String(threadId) : undefined),
      });
      return { channel: "mattermost", ...result };
    },
    sendMedia: async ({
      cfg,
      to,
      text,
      mediaUrl,
      mediaLocalRoots,
      accountId,
      replyToId,
      threadId,
    }) => {
      const result = await sendMessageMattermost(to, text, {
        cfg,
        accountId: accountId ?? undefined,
        mediaUrl,
        mediaLocalRoots,
        replyToId: replyToId ?? (threadId != null ? String(threadId) : undefined),
      });
      return { channel: "mattermost", ...result };
    },
  },
  status: {
    defaultRuntime: {
      accountId: DEFAULT_ACCOUNT_ID,
      running: false,
      connected: false,
      lastConnectedAt: null,
      lastDisconnect: null,
      lastStartAt: null,
      lastStopAt: null,
      lastError: null,
    },
    buildChannelSummary: ({ snapshot }) =>
      buildPassiveProbedChannelStatusSummary(snapshot, {
        botTokenSource: snapshot.botTokenSource ?? "none",
        connected: snapshot.connected ?? false,
        baseUrl: snapshot.baseUrl ?? null,
      }),
    probeAccount: async ({ account, timeoutMs }) => {
      const token = account.botToken?.trim();
      const baseUrl = account.baseUrl?.trim();
      if (!token || !baseUrl) {
        return { ok: false, error: "bot token or baseUrl missing" };
      }
      return await probeMattermost(baseUrl, token, timeoutMs);
    },
    buildAccountSnapshot: ({ account, runtime, probe }) => {
      const base = buildComputedAccountStatusSnapshot({
        accountId: account.accountId,
        name: account.name,
        enabled: account.enabled,
        configured: Boolean(account.botToken && account.baseUrl),
        runtime,
        probe,
      });
      return {
        ...base,
        botTokenSource: account.botTokenSource,
        baseUrl: account.baseUrl,
        connected: runtime?.connected ?? false,
        lastConnectedAt: runtime?.lastConnectedAt ?? null,
        lastDisconnect: runtime?.lastDisconnect ?? null,
      };
    },
  },
  setup: {
    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
    applyAccountName: ({ cfg, accountId, name }) =>
      applyAccountNameToChannelSection({
        cfg,
        channelKey: "mattermost",
        accountId,
        name,
      }),
    validateInput: ({ accountId, input }) => {
      if (input.useEnv && accountId !== DEFAULT_ACCOUNT_ID) {
        return "Mattermost env vars can only be used for the default account.";
      }
      const token = input.botToken ?? input.token;
      const baseUrl = input.httpUrl;
      if (!input.useEnv && (!token || !baseUrl)) {
        return "Mattermost requires --bot-token and --http-url (or --use-env).";
      }
      if (baseUrl && !normalizeMattermostBaseUrl(baseUrl)) {
        return "Mattermost --http-url must include a valid base URL.";
      }
      return null;
    },
    applyAccountConfig: ({ cfg, accountId, input }) => {
      const token = input.botToken ?? input.token;
      const baseUrl = input.httpUrl?.trim();
      const namedConfig = applyAccountNameToChannelSection({
        cfg,
        channelKey: "mattermost",
        accountId,
        name: input.name,
      });
      const next =
        accountId !== DEFAULT_ACCOUNT_ID
          ? migrateBaseNameToDefaultAccount({
              cfg: namedConfig,
              channelKey: "mattermost",
            })
          : namedConfig;
      const patch = input.useEnv
        ? {}
        : {
            ...(token ? { botToken: token } : {}),
            ...(baseUrl ? { baseUrl } : {}),
          };
      return applySetupAccountConfigPatch({
        cfg: next,
        channelKey: "mattermost",
        accountId,
        patch,
      });
    },
  },
  gateway: {
    startAccount: async (ctx) => {
      const account = ctx.account;
      const statusSink = createAccountStatusSink({
        accountId: ctx.accountId,
        setStatus: ctx.setStatus,
      });
      statusSink({
        baseUrl: account.baseUrl,
        botTokenSource: account.botTokenSource,
      });
      ctx.log?.info(`[${account.accountId}] starting channel`);
      return monitorMattermostProvider({
        botToken: account.botToken ?? undefined,
        baseUrl: account.baseUrl ?? undefined,
        accountId: account.accountId,
        config: ctx.cfg,
        runtime: ctx.runtime,
        abortSignal: ctx.abortSignal,
        statusSink,
      });
    },
  },
};