@openclaw/matrix 2026.1.29

package/src/matrix/send.test.ts

@@ -0,0 +1,172 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+import { setMatrixRuntime } from "../runtime.js";
+
+vi.mock("@vector-im/matrix-bot-sdk", () => ({
+  ConsoleLogger: class {
+    trace = vi.fn();
+    debug = vi.fn();
+    info = vi.fn();
+    warn = vi.fn();
+    error = vi.fn();
+  },
+  LogService: {
+    setLogger: vi.fn(),
+  },
+  MatrixClient: vi.fn(),
+  SimpleFsStorageProvider: vi.fn(),
+  RustSdkCryptoStorageProvider: vi.fn(),
+}));
+
+const loadWebMediaMock = vi.fn().mockResolvedValue({
+  buffer: Buffer.from("media"),
+  fileName: "photo.png",
+  contentType: "image/png",
+  kind: "image",
+});
+const getImageMetadataMock = vi.fn().mockResolvedValue(null);
+const resizeToJpegMock = vi.fn();
+
+const runtimeStub = {
+  config: {
+    loadConfig: () => ({}),
+  },
+  media: {
+    loadWebMedia: (...args: unknown[]) => loadWebMediaMock(...args),
+    mediaKindFromMime: () => "image",
+    isVoiceCompatibleAudio: () => false,
+    getImageMetadata: (...args: unknown[]) => getImageMetadataMock(...args),
+    resizeToJpeg: (...args: unknown[]) => resizeToJpegMock(...args),
+  },
+  channel: {
+    text: {
+      resolveTextChunkLimit: () => 4000,
+      resolveChunkMode: () => "length",
+      chunkMarkdownText: (text: string) => (text ? [text] : []),
+      chunkMarkdownTextWithMode: (text: string) => (text ? [text] : []),
+      resolveMarkdownTableMode: () => "code",
+      convertMarkdownTables: (text: string) => text,
+    },
+  },
+} as unknown as PluginRuntime;
+
+let sendMessageMatrix: typeof import("./send.js").sendMessageMatrix;
+
+const makeClient = () => {
+  const sendMessage = vi.fn().mockResolvedValue("evt1");
+  const uploadContent = vi.fn().mockResolvedValue("mxc://example/file");
+  const client = {
+    sendMessage,
+    uploadContent,
+    getUserId: vi.fn().mockResolvedValue("@bot:example.org"),
+  } as unknown as import("@vector-im/matrix-bot-sdk").MatrixClient;
+  return { client, sendMessage, uploadContent };
+};
+
+describe("sendMessageMatrix media", () => {
+  beforeAll(async () => {
+    setMatrixRuntime(runtimeStub);
+    ({ sendMessageMatrix } = await import("./send.js"));
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    setMatrixRuntime(runtimeStub);
+  });
+
+  it("uploads media with url payloads", async () => {
+    const { client, sendMessage, uploadContent } = makeClient();
+
+    await sendMessageMatrix("room:!room:example", "caption", {
+      client,
+      mediaUrl: "file:///tmp/photo.png",
+    });
+
+    const uploadArg = uploadContent.mock.calls[0]?.[0];
+    expect(Buffer.isBuffer(uploadArg)).toBe(true);
+
+    const content = sendMessage.mock.calls[0]?.[1] as {
+      url?: string;
+      msgtype?: string;
+      format?: string;
+      formatted_body?: string;
+    };
+    expect(content.msgtype).toBe("m.image");
+    expect(content.format).toBe("org.matrix.custom.html");
+    expect(content.formatted_body).toContain("caption");
+    expect(content.url).toBe("mxc://example/file");
+  });
+
+  it("uploads encrypted media with file payloads", async () => {
+    const { client, sendMessage, uploadContent } = makeClient();
+    (client as { crypto?: object }).crypto = {
+      isRoomEncrypted: vi.fn().mockResolvedValue(true),
+      encryptMedia: vi.fn().mockResolvedValue({
+        buffer: Buffer.from("encrypted"),
+        file: {
+          key: {
+            kty: "oct",
+            key_ops: ["encrypt", "decrypt"],
+            alg: "A256CTR",
+            k: "secret",
+            ext: true,
+          },
+          iv: "iv",
+          hashes: { sha256: "hash" },
+          v: "v2",
+        },
+      }),
+    };
+
+    await sendMessageMatrix("room:!room:example", "caption", {
+      client,
+      mediaUrl: "file:///tmp/photo.png",
+    });
+
+    const uploadArg = uploadContent.mock.calls[0]?.[0] as Buffer | undefined;
+    expect(uploadArg?.toString()).toBe("encrypted");
+
+    const content = sendMessage.mock.calls[0]?.[1] as {
+      url?: string;
+      file?: { url?: string };
+    };
+    expect(content.url).toBeUndefined();
+    expect(content.file?.url).toBe("mxc://example/file");
+  });
+});
+
+describe("sendMessageMatrix threads", () => {
+  beforeAll(async () => {
+    setMatrixRuntime(runtimeStub);
+    ({ sendMessageMatrix } = await import("./send.js"));
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    setMatrixRuntime(runtimeStub);
+  });
+
+  it("includes thread relation metadata when threadId is set", async () => {
+    const { client, sendMessage } = makeClient();
+
+    await sendMessageMatrix("room:!room:example", "hello thread", {
+      client,
+      threadId: "$thread",
+    });
+
+    const content = sendMessage.mock.calls[0]?.[1] as {
+      "m.relates_to"?: {
+        rel_type?: string;
+        event_id?: string;
+        "m.in_reply_to"?: { event_id?: string };
+      };
+    };
+
+    expect(content["m.relates_to"]).toMatchObject({
+      rel_type: "m.thread",
+      event_id: "$thread",
+      "m.in_reply_to": { event_id: "$thread" },
+    });
+  });
+});

package/src/matrix/send.ts

@@ -0,0 +1,255 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+
+import type { PollInput } from "openclaw/plugin-sdk";
+import { getMatrixRuntime } from "../runtime.js";
+import { buildPollStartContent, M_POLL_START } from "./poll-types.js";
+import { resolveMatrixClient, resolveMediaMaxBytes } from "./send/client.js";
+import {
+  buildReplyRelation,
+  buildTextContent,
+  buildThreadRelation,
+  resolveMatrixMsgType,
+  resolveMatrixVoiceDecision,
+} from "./send/formatting.js";
+import {
+  buildMediaContent,
+  prepareImageInfo,
+  resolveMediaDurationMs,
+  uploadMediaMaybeEncrypted,
+} from "./send/media.js";
+import { normalizeThreadId, resolveMatrixRoomId } from "./send/targets.js";
+import {
+  EventType,
+  MsgType,
+  RelationType,
+  type MatrixOutboundContent,
+  type MatrixSendOpts,
+  type MatrixSendResult,
+  type ReactionEventContent,
+} from "./send/types.js";
+
+const MATRIX_TEXT_LIMIT = 4000;
+const getCore = () => getMatrixRuntime();
+
+export type { MatrixSendOpts, MatrixSendResult } from "./send/types.js";
+export { resolveMatrixRoomId } from "./send/targets.js";
+
+export async function sendMessageMatrix(
+  to: string,
+  message: string,
+  opts: MatrixSendOpts = {},
+): Promise<MatrixSendResult> {
+  const trimmedMessage = message?.trim() ?? "";
+  if (!trimmedMessage && !opts.mediaUrl) {
+    throw new Error("Matrix send requires text or media");
+  }
+  const { client, stopOnDone } = await resolveMatrixClient({
+    client: opts.client,
+    timeoutMs: opts.timeoutMs,
+  });
+  try {
+    const roomId = await resolveMatrixRoomId(client, to);
+    const cfg = getCore().config.loadConfig();
+    const tableMode = getCore().channel.text.resolveMarkdownTableMode({
+      cfg,
+      channel: "matrix",
+      accountId: opts.accountId,
+    });
+    const convertedMessage = getCore().channel.text.convertMarkdownTables(
+      trimmedMessage,
+      tableMode,
+    );
+    const textLimit = getCore().channel.text.resolveTextChunkLimit(cfg, "matrix");
+    const chunkLimit = Math.min(textLimit, MATRIX_TEXT_LIMIT);
+    const chunkMode = getCore().channel.text.resolveChunkMode(cfg, "matrix", opts.accountId);
+    const chunks = getCore().channel.text.chunkMarkdownTextWithMode(
+      convertedMessage,
+      chunkLimit,
+      chunkMode,
+    );
+    const threadId = normalizeThreadId(opts.threadId);
+    const relation = threadId
+      ? buildThreadRelation(threadId, opts.replyToId)
+      : buildReplyRelation(opts.replyToId);
+    const sendContent = async (content: MatrixOutboundContent) => {
+      // @vector-im/matrix-bot-sdk uses sendMessage differently
+      const eventId = await client.sendMessage(roomId, content);
+      return eventId;
+    };
+
+    let lastMessageId = "";
+    if (opts.mediaUrl) {
+      const maxBytes = resolveMediaMaxBytes();
+      const media = await getCore().media.loadWebMedia(opts.mediaUrl, maxBytes);
+      const uploaded = await uploadMediaMaybeEncrypted(client, roomId, media.buffer, {
+        contentType: media.contentType,
+        filename: media.fileName,
+      });
+      const durationMs = await resolveMediaDurationMs({
+        buffer: media.buffer,
+        contentType: media.contentType,
+        fileName: media.fileName,
+        kind: media.kind,
+      });
+      const baseMsgType = resolveMatrixMsgType(media.contentType, media.fileName);
+      const { useVoice } = resolveMatrixVoiceDecision({
+        wantsVoice: opts.audioAsVoice === true,
+        contentType: media.contentType,
+        fileName: media.fileName,
+      });
+      const msgtype = useVoice ? MsgType.Audio : baseMsgType;
+      const isImage = msgtype === MsgType.Image;
+      const imageInfo = isImage
+        ? await prepareImageInfo({ buffer: media.buffer, client })
+        : undefined;
+      const [firstChunk, ...rest] = chunks;
+      const body = useVoice ? "Voice message" : (firstChunk ?? media.fileName ?? "(file)");
+      const content = buildMediaContent({
+        msgtype,
+        body,
+        url: uploaded.url,
+        file: uploaded.file,
+        filename: media.fileName,
+        mimetype: media.contentType,
+        size: media.buffer.byteLength,
+        durationMs,
+        relation,
+        isVoice: useVoice,
+        imageInfo,
+      });
+      const eventId = await sendContent(content);
+      lastMessageId = eventId ?? lastMessageId;
+      const textChunks = useVoice ? chunks : rest;
+      const followupRelation = threadId ? relation : undefined;
+      for (const chunk of textChunks) {
+        const text = chunk.trim();
+        if (!text) continue;
+        const followup = buildTextContent(text, followupRelation);
+        const followupEventId = await sendContent(followup);
+        lastMessageId = followupEventId ?? lastMessageId;
+      }
+    } else {
+      for (const chunk of chunks.length ? chunks : [""]) {
+        const text = chunk.trim();
+        if (!text) continue;
+        const content = buildTextContent(text, relation);
+        const eventId = await sendContent(content);
+        lastMessageId = eventId ?? lastMessageId;
+      }
+    }
+
+    return {
+      messageId: lastMessageId || "unknown",
+      roomId,
+    };
+  } finally {
+    if (stopOnDone) {
+      client.stop();
+    }
+  }
+}
+
+export async function sendPollMatrix(
+  to: string,
+  poll: PollInput,
+  opts: MatrixSendOpts = {},
+): Promise<{ eventId: string; roomId: string }> {
+  if (!poll.question?.trim()) {
+    throw new Error("Matrix poll requires a question");
+  }
+  if (!poll.options?.length) {
+    throw new Error("Matrix poll requires options");
+  }
+  const { client, stopOnDone } = await resolveMatrixClient({
+    client: opts.client,
+    timeoutMs: opts.timeoutMs,
+  });
+
+  try {
+    const roomId = await resolveMatrixRoomId(client, to);
+    const pollContent = buildPollStartContent(poll);
+    const threadId = normalizeThreadId(opts.threadId);
+    const pollPayload = threadId
+      ? { ...pollContent, "m.relates_to": buildThreadRelation(threadId) }
+      : pollContent;
+    // @vector-im/matrix-bot-sdk sendEvent returns eventId string directly
+    const eventId = await client.sendEvent(roomId, M_POLL_START, pollPayload);
+
+    return {
+      eventId: eventId ?? "unknown",
+      roomId,
+    };
+  } finally {
+    if (stopOnDone) {
+      client.stop();
+    }
+  }
+}
+
+export async function sendTypingMatrix(
+  roomId: string,
+  typing: boolean,
+  timeoutMs?: number,
+  client?: MatrixClient,
+): Promise<void> {
+  const { client: resolved, stopOnDone } = await resolveMatrixClient({
+    client,
+    timeoutMs,
+  });
+  try {
+    const resolvedTimeoutMs = typeof timeoutMs === "number" ? timeoutMs : 30_000;
+    await resolved.setTyping(roomId, typing, resolvedTimeoutMs);
+  } finally {
+    if (stopOnDone) {
+      resolved.stop();
+    }
+  }
+}
+
+export async function sendReadReceiptMatrix(
+  roomId: string,
+  eventId: string,
+  client?: MatrixClient,
+): Promise<void> {
+  if (!eventId?.trim()) return;
+  const { client: resolved, stopOnDone } = await resolveMatrixClient({
+    client,
+  });
+  try {
+    const resolvedRoom = await resolveMatrixRoomId(resolved, roomId);
+    await resolved.sendReadReceipt(resolvedRoom, eventId.trim());
+  } finally {
+    if (stopOnDone) {
+      resolved.stop();
+    }
+  }
+}
+
+export async function reactMatrixMessage(
+  roomId: string,
+  messageId: string,
+  emoji: string,
+  client?: MatrixClient,
+): Promise<void> {
+  if (!emoji.trim()) {
+    throw new Error("Matrix reaction requires an emoji");
+  }
+  const { client: resolved, stopOnDone } = await resolveMatrixClient({
+    client,
+  });
+  try {
+    const resolvedRoom = await resolveMatrixRoomId(resolved, roomId);
+    const reaction: ReactionEventContent = {
+      "m.relates_to": {
+        rel_type: RelationType.Annotation,
+        event_id: messageId,
+        key: emoji,
+      },
+    };
+    await resolved.sendEvent(resolvedRoom, EventType.Reaction, reaction);
+  } finally {
+    if (stopOnDone) {
+      resolved.stop();
+    }
+  }
+}