@openclaw/mattermost 2026.2.21

package/src/mattermost/client.ts

@@ -0,0 +1,230 @@
+export type MattermostClient = {
+  baseUrl: string;
+  apiBaseUrl: string;
+  token: string;
+  request: <T>(path: string, init?: RequestInit) => Promise<T>;
+};
+
+export type MattermostUser = {
+  id: string;
+  username?: string | null;
+  nickname?: string | null;
+  first_name?: string | null;
+  last_name?: string | null;
+};
+
+export type MattermostChannel = {
+  id: string;
+  name?: string | null;
+  display_name?: string | null;
+  type?: string | null;
+  team_id?: string | null;
+};
+
+export type MattermostPost = {
+  id: string;
+  user_id?: string | null;
+  channel_id?: string | null;
+  message?: string | null;
+  file_ids?: string[] | null;
+  type?: string | null;
+  root_id?: string | null;
+  create_at?: number | null;
+  props?: Record<string, unknown> | null;
+};
+
+export type MattermostFileInfo = {
+  id: string;
+  name?: string | null;
+  mime_type?: string | null;
+  size?: number | null;
+};
+
+export function normalizeMattermostBaseUrl(raw?: string | null): string | undefined {
+  const trimmed = raw?.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  const withoutTrailing = trimmed.replace(/\/+$/, "");
+  return withoutTrailing.replace(/\/api\/v4$/i, "");
+}
+
+function buildMattermostApiUrl(baseUrl: string, path: string): string {
+  const normalized = normalizeMattermostBaseUrl(baseUrl);
+  if (!normalized) {
+    throw new Error("Mattermost baseUrl is required");
+  }
+  const suffix = path.startsWith("/") ? path : `/${path}`;
+  return `${normalized}/api/v4${suffix}`;
+}
+
+async function readMattermostError(res: Response): Promise<string> {
+  const contentType = res.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    const data = (await res.json()) as { message?: string } | undefined;
+    if (data?.message) {
+      return data.message;
+    }
+    return JSON.stringify(data);
+  }
+  return await res.text();
+}
+
+export function createMattermostClient(params: {
+  baseUrl: string;
+  botToken: string;
+  fetchImpl?: typeof fetch;
+}): MattermostClient {
+  const baseUrl = normalizeMattermostBaseUrl(params.baseUrl);
+  if (!baseUrl) {
+    throw new Error("Mattermost baseUrl is required");
+  }
+  const apiBaseUrl = `${baseUrl}/api/v4`;
+  const token = params.botToken.trim();
+  const fetchImpl = params.fetchImpl ?? fetch;
+
+  const request = async <T>(path: string, init?: RequestInit): Promise<T> => {
+    const url = buildMattermostApiUrl(baseUrl, path);
+    const headers = new Headers(init?.headers);
+    headers.set("Authorization", `Bearer ${token}`);
+    if (typeof init?.body === "string" && !headers.has("Content-Type")) {
+      headers.set("Content-Type", "application/json");
+    }
+    const res = await fetchImpl(url, { ...init, headers });
+    if (!res.ok) {
+      const detail = await readMattermostError(res);
+      throw new Error(
+        `Mattermost API ${res.status} ${res.statusText}: ${detail || "unknown error"}`,
+      );
+    }
+
+    if (res.status === 204) {
+      return undefined as T;
+    }
+
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+      return (await res.json()) as T;
+    }
+
+    return (await res.text()) as T;
+  };
+
+  return { baseUrl, apiBaseUrl, token, request };
+}
+
+export async function fetchMattermostMe(client: MattermostClient): Promise<MattermostUser> {
+  return await client.request<MattermostUser>("/users/me");
+}
+
+export async function fetchMattermostUser(
+  client: MattermostClient,
+  userId: string,
+): Promise<MattermostUser> {
+  return await client.request<MattermostUser>(`/users/${userId}`);
+}
+
+export async function fetchMattermostUserByUsername(
+  client: MattermostClient,
+  username: string,
+): Promise<MattermostUser> {
+  return await client.request<MattermostUser>(`/users/username/${encodeURIComponent(username)}`);
+}
+
+export async function fetchMattermostChannel(
+  client: MattermostClient,
+  channelId: string,
+): Promise<MattermostChannel> {
+  return await client.request<MattermostChannel>(`/channels/${channelId}`);
+}
+
+export async function sendMattermostTyping(
+  client: MattermostClient,
+  params: { channelId: string; parentId?: string },
+): Promise<void> {
+  const payload: Record<string, string> = {
+    channel_id: params.channelId,
+  };
+  const parentId = params.parentId?.trim();
+  if (parentId) {
+    payload.parent_id = parentId;
+  }
+  await client.request<Record<string, unknown>>("/users/me/typing", {
+    method: "POST",
+    body: JSON.stringify(payload),
+  });
+}
+
+export async function createMattermostDirectChannel(
+  client: MattermostClient,
+  userIds: string[],
+): Promise<MattermostChannel> {
+  return await client.request<MattermostChannel>("/channels/direct", {
+    method: "POST",
+    body: JSON.stringify(userIds),
+  });
+}
+
+export async function createMattermostPost(
+  client: MattermostClient,
+  params: {
+    channelId: string;
+    message: string;
+    rootId?: string;
+    fileIds?: string[];
+  },
+): Promise<MattermostPost> {
+  const payload: Record<string, string> = {
+    channel_id: params.channelId,
+    message: params.message,
+  };
+  if (params.rootId) {
+    payload.root_id = params.rootId;
+  }
+  if (params.fileIds?.length) {
+    (payload as Record<string, unknown>).file_ids = params.fileIds;
+  }
+  return await client.request<MattermostPost>("/posts", {
+    method: "POST",
+    body: JSON.stringify(payload),
+  });
+}
+
+export async function uploadMattermostFile(
+  client: MattermostClient,
+  params: {
+    channelId: string;
+    buffer: Buffer;
+    fileName: string;
+    contentType?: string;
+  },
+): Promise<MattermostFileInfo> {
+  const form = new FormData();
+  const fileName = params.fileName?.trim() || "upload";
+  const bytes = Uint8Array.from(params.buffer);
+  const blob = params.contentType
+    ? new Blob([bytes], { type: params.contentType })
+    : new Blob([bytes]);
+  form.append("files", blob, fileName);
+  form.append("channel_id", params.channelId);
+
+  const res = await fetch(`${client.apiBaseUrl}/files`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${client.token}`,
+    },
+    body: form,
+  });
+
+  if (!res.ok) {
+    const detail = await readMattermostError(res);
+    throw new Error(`Mattermost API ${res.status} ${res.statusText}: ${detail || "unknown error"}`);
+  }
+
+  const data = (await res.json()) as { file_infos?: MattermostFileInfo[] };
+  const info = data.file_infos?.[0];
+  if (!info?.id) {
+    throw new Error("Mattermost file upload failed");
+  }
+  return info;
+}

package/src/mattermost/index.ts

@@ -0,0 +1,9 @@
+export {
+  listEnabledMattermostAccounts,
+  listMattermostAccountIds,
+  resolveDefaultMattermostAccountId,
+  resolveMattermostAccount,
+} from "./accounts.js";
+export { monitorMattermostProvider } from "./monitor.js";
+export { probeMattermost } from "./probe.js";
+export { sendMessageMattermost } from "./send.js";

package/src/mattermost/monitor-helpers.ts

@@ -0,0 +1,93 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+export { createDedupeCache, rawDataToString } from "openclaw/plugin-sdk";
+
+export type ResponsePrefixContext = {
+  model?: string;
+  modelFull?: string;
+  provider?: string;
+  thinkingLevel?: string;
+  identityName?: string;
+};
+
+export function extractShortModelName(fullModel: string): string {
+  const slash = fullModel.lastIndexOf("/");
+  const modelPart = slash >= 0 ? fullModel.slice(slash + 1) : fullModel;
+  return modelPart.replace(/-\d{8}$/, "").replace(/-latest$/, "");
+}
+
+export function formatInboundFromLabel(params: {
+  isGroup: boolean;
+  groupLabel?: string;
+  groupId?: string;
+  directLabel: string;
+  directId?: string;
+  groupFallback?: string;
+}): string {
+  if (params.isGroup) {
+    const label = params.groupLabel?.trim() || params.groupFallback || "Group";
+    const id = params.groupId?.trim();
+    return id ? `${label} id:${id}` : label;
+  }
+
+  const directLabel = params.directLabel.trim();
+  const directId = params.directId?.trim();
+  if (!directId || directId === directLabel) {
+    return directLabel;
+  }
+  return `${directLabel} id:${directId}`;
+}
+
+function normalizeAgentId(value: string | undefined | null): string {
+  const trimmed = (value ?? "").trim();
+  if (!trimmed) {
+    return "main";
+  }
+  if (/^[a-z0-9][a-z0-9_-]{0,63}$/i.test(trimmed)) {
+    return trimmed;
+  }
+  return (
+    trimmed
+      .toLowerCase()
+      .replace(/[^a-z0-9_-]+/g, "-")
+      .replace(/^-+/, "")
+      .replace(/-+$/, "")
+      .slice(0, 64) || "main"
+  );
+}
+
+type AgentEntry = NonNullable<NonNullable<OpenClawConfig["agents"]>["list"]>[number];
+
+function listAgents(cfg: OpenClawConfig): AgentEntry[] {
+  const list = cfg.agents?.list;
+  if (!Array.isArray(list)) {
+    return [];
+  }
+  return list.filter((entry): entry is AgentEntry => Boolean(entry && typeof entry === "object"));
+}
+
+function resolveAgentEntry(cfg: OpenClawConfig, agentId: string): AgentEntry | undefined {
+  const id = normalizeAgentId(agentId);
+  return listAgents(cfg).find((entry) => normalizeAgentId(entry.id) === id);
+}
+
+export function resolveIdentityName(cfg: OpenClawConfig, agentId: string): string | undefined {
+  const entry = resolveAgentEntry(cfg, agentId);
+  return entry?.identity?.name?.trim() || undefined;
+}
+
+export function resolveThreadSessionKeys(params: {
+  baseSessionKey: string;
+  threadId?: string | null;
+  parentSessionKey?: string;
+  useSuffix?: boolean;
+}): { sessionKey: string; parentSessionKey?: string } {
+  const threadId = (params.threadId ?? "").trim();
+  if (!threadId) {
+    return { sessionKey: params.baseSessionKey, parentSessionKey: undefined };
+  }
+  const useSuffix = params.useSuffix ?? true;
+  const sessionKey = useSuffix
+    ? `${params.baseSessionKey}:thread:${threadId}`
+    : params.baseSessionKey;
+  return { sessionKey, parentSessionKey: params.parentSessionKey };
+}

package/src/mattermost/monitor-onchar.ts

@@ -0,0 +1,25 @@
+const DEFAULT_ONCHAR_PREFIXES = [">", "!"];
+
+export function resolveOncharPrefixes(prefixes: string[] | undefined): string[] {
+  const cleaned = prefixes?.map((entry) => entry.trim()).filter(Boolean) ?? DEFAULT_ONCHAR_PREFIXES;
+  return cleaned.length > 0 ? cleaned : DEFAULT_ONCHAR_PREFIXES;
+}
+
+export function stripOncharPrefix(
+  text: string,
+  prefixes: string[],
+): { triggered: boolean; stripped: string } {
+  const trimmed = text.trimStart();
+  for (const prefix of prefixes) {
+    if (!prefix) {
+      continue;
+    }
+    if (trimmed.startsWith(prefix)) {
+      return {
+        triggered: true,
+        stripped: trimmed.slice(prefix.length).trimStart(),
+      };
+    }
+  }
+  return { triggered: false, stripped: text };
+}

package/src/mattermost/monitor-websocket.test.ts

@@ -0,0 +1,232 @@
+import type { RuntimeEnv } from "openclaw/plugin-sdk";
+import { describe, expect, it, vi } from "vitest";
+import {
+  createMattermostConnectOnce,
+  type MattermostWebSocketLike,
+  WebSocketClosedBeforeOpenError,
+} from "./monitor-websocket.js";
+import { runWithReconnect } from "./reconnect.js";
+
+class FakeWebSocket implements MattermostWebSocketLike {
+  public readonly sent: string[] = [];
+  public closeCalls = 0;
+  public terminateCalls = 0;
+  private openListeners: Array<() => void> = [];
+  private messageListeners: Array<(data: Buffer) => void | Promise<void>> = [];
+  private closeListeners: Array<(code: number, reason: Buffer) => void> = [];
+  private errorListeners: Array<(err: unknown) => void> = [];
+
+  on(event: "open", listener: () => void): void;
+  on(event: "message", listener: (data: Buffer) => void | Promise<void>): void;
+  on(event: "close", listener: (code: number, reason: Buffer) => void): void;
+  on(event: "error", listener: (err: unknown) => void): void;
+  on(event: "open" | "message" | "close" | "error", listener: unknown): void {
+    if (event === "open") {
+      this.openListeners.push(listener as () => void);
+      return;
+    }
+    if (event === "message") {
+      this.messageListeners.push(listener as (data: Buffer) => void | Promise<void>);
+      return;
+    }
+    if (event === "close") {
+      this.closeListeners.push(listener as (code: number, reason: Buffer) => void);
+      return;
+    }
+    this.errorListeners.push(listener as (err: unknown) => void);
+  }
+
+  send(data: string): void {
+    this.sent.push(data);
+  }
+
+  close(): void {
+    this.closeCalls++;
+  }
+
+  terminate(): void {
+    this.terminateCalls++;
+  }
+
+  emitOpen(): void {
+    for (const listener of this.openListeners) {
+      listener();
+    }
+  }
+
+  emitMessage(data: Buffer): void {
+    for (const listener of this.messageListeners) {
+      void listener(data);
+    }
+  }
+
+  emitClose(code: number, reason = ""): void {
+    const buffer = Buffer.from(reason, "utf8");
+    for (const listener of this.closeListeners) {
+      listener(code, buffer);
+    }
+  }
+
+  emitError(err: unknown): void {
+    for (const listener of this.errorListeners) {
+      listener(err);
+    }
+  }
+}
+
+const testRuntime = (): RuntimeEnv =>
+  ({
+    log: vi.fn(),
+    error: vi.fn(),
+    exit: ((code: number): never => {
+      throw new Error(`exit ${code}`);
+    }) as RuntimeEnv["exit"],
+  }) as RuntimeEnv;
+
+describe("mattermost websocket monitor", () => {
+  it("rejects when websocket closes before open", async () => {
+    const socket = new FakeWebSocket();
+    const connectOnce = createMattermostConnectOnce({
+      wsUrl: "wss://example.invalid/api/v4/websocket",
+      botToken: "token",
+      runtime: testRuntime(),
+      nextSeq: () => 1,
+      onPosted: async () => {},
+      webSocketFactory: () => socket,
+    });
+
+    queueMicrotask(() => {
+      socket.emitClose(1006, "connection refused");
+    });
+
+    const failure = connectOnce();
+    await expect(failure).rejects.toBeInstanceOf(WebSocketClosedBeforeOpenError);
+    await expect(failure).rejects.toMatchObject({
+      message: "websocket closed before open (code 1006)",
+    });
+  });
+
+  it("retries when first attempt errors before open and next attempt succeeds", async () => {
+    const abort = new AbortController();
+    const reconnectDelays: number[] = [];
+    const onError = vi.fn();
+    const patches: Array<Record<string, unknown>> = [];
+    const sockets: FakeWebSocket[] = [];
+    let disconnects = 0;
+
+    const connectOnce = createMattermostConnectOnce({
+      wsUrl: "wss://example.invalid/api/v4/websocket",
+      botToken: "token",
+      runtime: testRuntime(),
+      nextSeq: (() => {
+        let seq = 1;
+        return () => seq++;
+      })(),
+      onPosted: async () => {},
+      abortSignal: abort.signal,
+      statusSink: (patch) => {
+        patches.push(patch as Record<string, unknown>);
+        if (patch.lastDisconnect) {
+          disconnects++;
+          if (disconnects >= 2) {
+            abort.abort();
+          }
+        }
+      },
+      webSocketFactory: () => {
+        const socket = new FakeWebSocket();
+        const attempt = sockets.length;
+        sockets.push(socket);
+        queueMicrotask(() => {
+          if (attempt === 0) {
+            socket.emitError(new Error("boom"));
+            socket.emitClose(1006, "connection refused");
+            return;
+          }
+          socket.emitOpen();
+          socket.emitClose(1000);
+        });
+        return socket;
+      },
+    });
+
+    await runWithReconnect(connectOnce, {
+      abortSignal: abort.signal,
+      initialDelayMs: 1,
+      onError,
+      onReconnect: (delay) => reconnectDelays.push(delay),
+    });
+
+    expect(sockets).toHaveLength(2);
+    expect(sockets[0].closeCalls).toBe(1);
+    expect(sockets[1].sent).toHaveLength(1);
+    expect(JSON.parse(sockets[1].sent[0])).toMatchObject({
+      action: "authentication_challenge",
+      data: { token: "token" },
+      seq: 1,
+    });
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(reconnectDelays).toEqual([1]);
+    expect(patches.some((patch) => patch.connected === true)).toBe(true);
+    expect(patches.filter((patch) => patch.connected === false)).toHaveLength(2);
+  });
+
+  it("dispatches reaction events to the reaction handler", async () => {
+    const socket = new FakeWebSocket();
+    const onPosted = vi.fn(async () => {});
+    const onReaction = vi.fn(async (payload) => payload);
+    const connectOnce = createMattermostConnectOnce({
+      wsUrl: "wss://example.invalid/api/v4/websocket",
+      botToken: "token",
+      runtime: testRuntime(),
+      nextSeq: () => 1,
+      onPosted,
+      onReaction,
+      webSocketFactory: () => socket,
+    });
+
+    const connected = connectOnce();
+    queueMicrotask(() => {
+      socket.emitOpen();
+      socket.emitMessage(
+        Buffer.from(
+          JSON.stringify({
+            event: "reaction_added",
+            data: {
+              reaction: JSON.stringify({
+                user_id: "user-1",
+                post_id: "post-1",
+                emoji_name: "thumbsup",
+              }),
+            },
+          }),
+        ),
+      );
+      socket.emitClose(1000);
+    });
+
+    await connected;
+
+    expect(onReaction).toHaveBeenCalledTimes(1);
+    expect(onPosted).not.toHaveBeenCalled();
+    const payload = onReaction.mock.calls[0]?.[0];
+    expect(payload).toMatchObject({
+      event: "reaction_added",
+      data: {
+        reaction: JSON.stringify({
+          user_id: "user-1",
+          post_id: "post-1",
+          emoji_name: "thumbsup",
+        }),
+      },
+    });
+    expect(payload.data?.reaction).toBe(
+      JSON.stringify({
+        user_id: "user-1",
+        post_id: "post-1",
+        emoji_name: "thumbsup",
+      }),
+    );
+    expect(payload.data?.reaction).toBeDefined();
+  });
+});