@nanhara/hara 0.70.0 → 0.95.2

package/dist/gateway/matrix.js

@@ -0,0 +1,188 @@
+// Matrix adapter for `hara gateway` — client-server API with a /sync long-poll (built-in fetch, zero new dep;
+// no WebSocket). Mirrors the Telegram long-poll model and the Discord download-media/sendFile patterns. Creds
+// from HARA_MATRIX_HOMESERVER (e.g. https://matrix.org) + HARA_MATRIX_TOKEN (access token) + HARA_MATRIX_USER_ID
+// (the bot's own @user:server, for self-filtering). Same ChatAdapter shape as the others, so all cross-platform
+// gateway plumbing (send_file, system context, stuck-guard, image attach/describe) works unchanged.
+//
+// LIMITATION (v1): NO end-to-end encryption. Encrypted rooms (m.room.encrypted events) are skipped — only
+// plaintext rooms work. E2EE would need libolm + a crypto store (see hermes' matrix-nio adapter), which breaks
+// the zero-dep constraint. Invite this bot into UNENCRYPTED rooms only.
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+import { chunkText } from "./telegram.js";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const isImage = (name, mime) => (mime?.startsWith("image/") ?? false) || /\.(png|jpe?g|gif|webp)$/i.test(name);
+const mimeFromExt = (name) => {
+    const ext = name.toLowerCase().split(".").pop() ?? "";
+    const map = {
+        png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp",
+        mp4: "video/mp4", mp3: "audio/mpeg", ogg: "audio/ogg", pdf: "application/pdf", txt: "text/plain",
+    };
+    return map[ext] ?? "application/octet-stream";
+};
+/** Parse `mxc://server/mediaId` → its two parts (pure). null if not an mxc URL. */
+export function parseMxc(mxc) {
+    if (typeof mxc !== "string" || !mxc.startsWith("mxc://"))
+        return null;
+    const rest = mxc.slice(6); // strip "mxc://"
+    const slash = rest.indexOf("/");
+    if (slash < 0)
+        return null;
+    const server = rest.slice(0, slash);
+    const mediaId = rest.slice(slash + 1);
+    if (!server || !mediaId)
+        return null;
+    return { server, mediaId };
+}
+/** Extract an InboundMsg from a single Matrix timeline event (pure). Accepts m.room.message of msgtype m.text
+ *  (and friends carrying a body) plus m.image (→ marker text + the mxc url to download in start()). Ignores our
+ *  own messages and encrypted events. Returns the InboundMsg + the image's mxc url (null if none). null = skip. */
+export function parseMatrixEvent(event, selfUserId) {
+    if (!event || event.type !== "m.room.message")
+        return null; // encrypted (m.room.encrypted) / state events → skip
+    const sender = typeof event.sender === "string" ? event.sender : "";
+    const roomId = typeof event.__roomId === "string" ? event.__roomId : ""; // injected by start() (events carry no room id)
+    if (!sender || !roomId)
+        return null;
+    if (sender === selfUserId)
+        return null; // ignore our own messages
+    const content = event.content ?? {};
+    const msgtype = typeof content.msgtype === "string" ? content.msgtype : "";
+    const body = typeof content.body === "string" ? content.body : "";
+    let imageMxc = null;
+    let text = body;
+    if (msgtype === "m.image") {
+        imageMxc = typeof content.url === "string" && content.url.startsWith("mxc://") ? content.url : null;
+        text = body || "[图片]";
+    }
+    else if (!body) {
+        return null; // text-less non-image (sticker/location/reaction-as-message/etc.)
+    }
+    return {
+        msg: {
+            chatId: roomId,
+            userId: sender,
+            userName: sender,
+            text: text || "[图片]",
+        },
+        imageMxc,
+    };
+}
+/** Download a Matrix mxc:// media to a local path under ~/.hara/matrix/media (resolves via /_matrix/media/v3/download). */
+async function downloadMatrixMedia(homeserver, token, mxc) {
+    const parts = parseMxc(mxc);
+    if (!parts)
+        return null;
+    try {
+        const url = `${homeserver}/_matrix/media/v3/download/${encodeURIComponent(parts.server)}/${encodeURIComponent(parts.mediaId)}`;
+        const r = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
+        if (!r.ok)
+            return null;
+        const dir = join(homedir(), ".hara", "matrix", "media");
+        mkdirSync(dir, { recursive: true });
+        const path = join(dir, `mx_${Date.now()}_${parts.mediaId.slice(-12)}`);
+        writeFileSync(path, Buffer.from(await r.arrayBuffer()));
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+export function matrixAdapter(homeserver, token, selfUserId) {
+    const base = homeserver.replace(/\/+$/, ""); // trim trailing slashes
+    const auth = { Authorization: `Bearer ${token}` };
+    let txnSeq = Date.now(); // monotonically increasing txn id base (survives clock-ish across a process run)
+    const nextTxn = () => `hara${++txnSeq}`;
+    return {
+        name: "matrix",
+        async send(chatId, text) {
+            for (const part of chunkText(text || "(empty)", 4000)) {
+                const txn = nextTxn();
+                await fetch(`${base}/_matrix/client/v3/rooms/${encodeURIComponent(String(chatId))}/send/m.room.message/${txn}`, {
+                    method: "PUT",
+                    headers: { ...auth, "content-type": "application/json" },
+                    body: JSON.stringify({ msgtype: "m.text", body: part }),
+                }).catch(() => { });
+            }
+        },
+        async sendFile(chatId, filePath) {
+            const name = basename(filePath);
+            const mime = mimeFromExt(name);
+            try {
+                // 1) upload bytes → content_uri (mxc://)
+                const up = await fetch(`${base}/_matrix/media/v3/upload?filename=${encodeURIComponent(name)}`, {
+                    method: "POST",
+                    headers: { ...auth, "content-type": mime },
+                    body: readFileSync(filePath),
+                });
+                if (!up.ok)
+                    return;
+                const j = (await up.json());
+                const mxc = j?.content_uri;
+                if (!mxc)
+                    return;
+                // 2) send a referencing m.room.message — m.image for images, m.file otherwise
+                const msgtype = isImage(name, mime) ? "m.image" : "m.file";
+                const txn = nextTxn();
+                await fetch(`${base}/_matrix/client/v3/rooms/${encodeURIComponent(String(chatId))}/send/m.room.message/${txn}`, {
+                    method: "PUT",
+                    headers: { ...auth, "content-type": "application/json" },
+                    body: JSON.stringify({ msgtype, body: name, filename: name, url: mxc, info: { mimetype: mime } }),
+                }).catch(() => { });
+            }
+            catch {
+                /* upload/send failed — surfaced upstream as "no file delivered" */
+            }
+        },
+        async start(onMessage, signal) {
+            // Prime the cursor: a since-less, timeout=0 sync skips backlog so we only see messages from now on.
+            let since = "";
+            try {
+                const r = await fetch(`${base}/_matrix/client/v3/sync?timeout=0`, { headers: auth, signal });
+                if (r.ok) {
+                    const j = (await r.json());
+                    if (typeof j.next_batch === "string")
+                        since = j.next_batch;
+                }
+            }
+            catch {
+                if (signal.aborted)
+                    return;
+            }
+            while (!signal.aborted) {
+                try {
+                    const q = `timeout=30000${since ? `&since=${encodeURIComponent(since)}` : ""}`;
+                    const res = await fetch(`${base}/_matrix/client/v3/sync?${q}`, { headers: auth, signal });
+                    if (!res.ok) {
+                        await sleep(2000);
+                        continue;
+                    }
+                    const j = (await res.json());
+                    if (typeof j.next_batch === "string")
+                        since = j.next_batch;
+                    const join = j.rooms?.join ?? {};
+                    for (const [roomId, room] of Object.entries(join)) {
+                        for (const event of room?.timeline?.events ?? []) {
+                            event.__roomId = roomId; // events carry no room id in /sync — inject it for the pure parser
+                            const parsed = parseMatrixEvent(event, selfUserId);
+                            if (!parsed)
+                                continue;
+                            if (parsed.imageMxc) {
+                                const path = await downloadMatrixMedia(base, token, parsed.imageMxc);
+                                if (path)
+                                    parsed.msg.images = [path];
+                            }
+                            await onMessage(parsed.msg).catch(() => { });
+                        }
+                    }
+                }
+                catch {
+                    if (signal.aborted)
+                        break;
+                    await sleep(2000); // network blip → back off + retry
+                }
+            }
+        },
+    };
+}

package/dist/gateway/mattermost.js

@@ -0,0 +1,206 @@
+// Mattermost adapter for `hara gateway` — connects to a self-hosted (or cloud) Mattermost over the v4
+// WebSocket (Node's native global WebSocket, zero new dep on Node ≥ 22) for inbound events, and the v4 REST
+// API for outbound. Server from HARA_MATTERMOST_URL, token (bot or personal-access) from HARA_MATTERMOST_TOKEN;
+// allow users via HARA_GATEWAY_ALLOWED (Mattermost user ids). Same ChatAdapter shape as Telegram/Discord, so all
+// the cross-platform gateway plumbing (send_file, in-chat system context, stuck-guard, image attach/describe)
+// works unchanged. Auth is a WS "authentication_challenge" rather than an HTTP header.
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+import { chunkText } from "./telegram.js";
+const WSImpl = globalThis.WebSocket;
+const sleep = (ms, signal) => new Promise((r) => {
+    if (signal?.aborted)
+        return r();
+    const t = setTimeout(r, ms);
+    signal?.addEventListener?.("abort", () => { clearTimeout(t); r(); }, { once: true });
+});
+const isImage = (name, mime) => (mime?.startsWith("image/") ?? false) || /\.(png|jpe?g|gif|webp)$/i.test(name);
+/** Strip a trailing slash and any `/api/v4` suffix so we can rebuild paths cleanly (pure). */
+function normalizeBase(raw) {
+    return raw.trim().replace(/\/+$/, "").replace(/\/api\/v4$/i, "");
+}
+/** http(s):// base → wss(s):// websocket endpoint (pure). */
+function wsUrlFromBase(base) {
+    return normalizeBase(base).replace(/^http/i, "ws") + "/api/v4/websocket";
+}
+async function downloadMattermostFile(base, token, fileId, name) {
+    try {
+        const r = await fetch(`${normalizeBase(base)}/api/v4/files/${encodeURIComponent(fileId)}`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!r.ok)
+            return null;
+        const dir = join(homedir(), ".hara", "mattermost", "media");
+        mkdirSync(dir, { recursive: true });
+        const path = join(dir, `mm_${Date.now()}_${basename(name) || "file.bin"}`);
+        writeFileSync(path, Buffer.from(await r.arrayBuffer()));
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse a Mattermost "posted" event's post → InboundMsg + its image file ids (pure; download happens in
+ *  start()). The post is the already-parsed object (the event's data.post is a JSON string the caller decodes).
+ *  null = ignore (own post / system post / empty). */
+export function parseMattermostPost(post, selfUserId) {
+    if (!post?.channel_id || !post?.user_id)
+        return null;
+    if (post.user_id === selfUserId)
+        return null; // ignore our own posts
+    if (post.type)
+        return null; // system post (join/leave/etc.) — type "" is a normal user post
+    const fileIds = Array.isArray(post.file_ids) ? post.file_ids.map((f) => String(f)) : [];
+    // file_ids alone don't tell us the mime; the caller resolves per-file. Here we surface them all and let the
+    // download step filter to images. To stay pure we pass them through as candidate image ids.
+    const imageFileIds = fileIds;
+    const text = String(post.message ?? "");
+    if (!text && !imageFileIds.length)
+        return null;
+    return {
+        msg: {
+            chatId: String(post.channel_id),
+            userId: String(post.user_id),
+            userName: String(post.user_id), // enriched by start() from the event's sender_name when available
+            text: text || "[图片]",
+        },
+        imageFileIds,
+    };
+}
+export function mattermostAdapter(serverUrl, token) {
+    const base = normalizeBase(serverUrl);
+    const api = `${base}/api/v4`;
+    const auth = { Authorization: `Bearer ${token}` };
+    return {
+        name: "mattermost",
+        async send(chatId, text) {
+            for (const part of chunkText(text || "(empty)", 4000)) {
+                await fetch(`${api}/posts`, {
+                    method: "POST",
+                    headers: { ...auth, "content-type": "application/json" },
+                    body: JSON.stringify({ channel_id: chatId, message: part }),
+                }).catch(() => { });
+            }
+        },
+        async sendFile(chatId, filePath) {
+            // upload the file (multipart) → get a file_id, then create a post referencing it
+            const form = new FormData();
+            form.append("channel_id", String(chatId));
+            form.append("files", new Blob([readFileSync(filePath)]), basename(filePath));
+            const up = await fetch(`${api}/files`, { method: "POST", headers: auth, body: form }).catch(() => null);
+            if (!up || !up.ok)
+                return;
+            const j = (await up.json().catch(() => null));
+            const fileId = j?.file_infos?.[0]?.id;
+            if (!fileId)
+                return;
+            await fetch(`${api}/posts`, {
+                method: "POST",
+                headers: { ...auth, "content-type": "application/json" },
+                body: JSON.stringify({ channel_id: chatId, message: "", file_ids: [fileId] }),
+            }).catch(() => { });
+        },
+        async start(onMessage, signal) {
+            if (!WSImpl) {
+                console.error("hara gateway: Mattermost needs Node ≥ 22 (global WebSocket). Upgrade Node.");
+                return;
+            }
+            while (!signal.aborted) {
+                await connectOnce(base, token, onMessage, signal);
+                if (!signal.aborted)
+                    await sleep(3000, signal); // reconnect backoff
+            }
+        },
+    };
+}
+/** One WS connection: send authentication_challenge, then dispatch "posted" events. Resolves on close/abort;
+ *  the caller reconnects. v1 keeps it simple — fresh auth each time, no resume. The bot's own user id is
+ *  resolved via GET /users/me so we can drop our own echoes. */
+function connectOnce(base, token, onMessage, signal) {
+    return new Promise((resolve) => {
+        const ws = new WSImpl(wsUrlFromBase(base));
+        let seq = 1;
+        let selfId = "";
+        const stop = () => {
+            signal.removeEventListener("abort", stop);
+            try {
+                ws.close();
+            }
+            catch {
+                /* already closing */
+            }
+            resolve();
+        };
+        signal.addEventListener("abort", stop, { once: true });
+        ws.addEventListener("close", () => {
+            signal.removeEventListener("abort", stop);
+            resolve();
+        });
+        ws.addEventListener("error", () => { });
+        ws.addEventListener("open", async () => {
+            // resolve our own user id first so parseMattermostPost can ignore our echoes
+            try {
+                const me = await fetch(`${base}/api/v4/users/me`, { headers: { Authorization: `Bearer ${token}` } });
+                if (me.ok)
+                    selfId = String(((await me.json())?.id) ?? "");
+            }
+            catch {
+                /* best-effort; without it we just won't filter our own posts */
+            }
+            try {
+                ws.send(JSON.stringify({ seq: seq++, action: "authentication_challenge", data: { token } }));
+            }
+            catch {
+                /* socket gone */
+            }
+        });
+        ws.addEventListener("message", async (ev) => {
+            let p;
+            try {
+                p = JSON.parse(String(ev.data));
+            }
+            catch {
+                return;
+            }
+            if (p.event !== "posted")
+                return;
+            let post;
+            try {
+                post = JSON.parse(String(p.data?.post ?? ""));
+            }
+            catch {
+                return;
+            }
+            const parsed = parseMattermostPost(post, selfId);
+            if (!parsed)
+                return;
+            // enrich the display name from the event payload when the server includes it
+            const senderName = String(p.data?.sender_name ?? "").replace(/^@/, "");
+            if (senderName)
+                parsed.msg.userName = senderName;
+            for (const fid of parsed.imageFileIds) {
+                // resolve the file's mime/name, then download only images so the agent can SEE them
+                let name = "image";
+                let mime = "";
+                try {
+                    const info = await fetch(`${base}/api/v4/files/${encodeURIComponent(fid)}/info`, { headers: { Authorization: `Bearer ${token}` } });
+                    if (info.ok) {
+                        const ij = (await info.json());
+                        name = String(ij?.name ?? name);
+                        mime = String(ij?.mime_type ?? "");
+                    }
+                }
+                catch {
+                    /* fall back to extension sniff below */
+                }
+                if (!isImage(name, mime))
+                    continue;
+                const path = await downloadMattermostFile(base, token, fid, name);
+                if (path)
+                    (parsed.msg.images ??= []).push(path);
+            }
+            await onMessage(parsed.msg).catch(() => { });
+        });
+    });
+}