@badgerclaw/connect 1.0.0

package/src/matrix/actions/reactions.ts

@@ -0,0 +1,102 @@
+import { resolveMatrixRoomId } from "../send.js";
+import { resolveActionClient } from "./client.js";
+import { resolveMatrixActionLimit } from "./limits.js";
+import {
+  EventType,
+  RelationType,
+  type MatrixActionClientOpts,
+  type MatrixRawEvent,
+  type MatrixReactionSummary,
+  type ReactionEventContent,
+} from "./types.js";
+
+function getReactionsPath(roomId: string, messageId: string): string {
+  return `/_matrix/client/v1/rooms/${encodeURIComponent(roomId)}/relations/${encodeURIComponent(messageId)}/${RelationType.Annotation}/${EventType.Reaction}`;
+}
+
+async function listReactionEvents(
+  client: NonNullable<MatrixActionClientOpts["client"]>,
+  roomId: string,
+  messageId: string,
+  limit: number,
+): Promise<MatrixRawEvent[]> {
+  const res = (await client.doRequest("GET", getReactionsPath(roomId, messageId), {
+    dir: "b",
+    limit,
+  })) as { chunk: MatrixRawEvent[] };
+  return res.chunk;
+}
+
+export async function listMatrixReactions(
+  roomId: string,
+  messageId: string,
+  opts: MatrixActionClientOpts & { limit?: number } = {},
+): Promise<MatrixReactionSummary[]> {
+  const { client, stopOnDone } = await resolveActionClient(opts);
+  try {
+    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
+    const limit = resolveMatrixActionLimit(opts.limit, 100);
+    const chunk = await listReactionEvents(client, resolvedRoom, messageId, limit);
+    const summaries = new Map<string, MatrixReactionSummary>();
+    for (const event of chunk) {
+      const content = event.content as ReactionEventContent;
+      const key = content["m.relates_to"]?.key;
+      if (!key) {
+        continue;
+      }
+      const sender = event.sender ?? "";
+      const entry: MatrixReactionSummary = summaries.get(key) ?? {
+        key,
+        count: 0,
+        users: [],
+      };
+      entry.count += 1;
+      if (sender && !entry.users.includes(sender)) {
+        entry.users.push(sender);
+      }
+      summaries.set(key, entry);
+    }
+    return Array.from(summaries.values());
+  } finally {
+    if (stopOnDone) {
+      client.stop();
+    }
+  }
+}
+
+export async function removeMatrixReactions(
+  roomId: string,
+  messageId: string,
+  opts: MatrixActionClientOpts & { emoji?: string } = {},
+): Promise<{ removed: number }> {
+  const { client, stopOnDone } = await resolveActionClient(opts);
+  try {
+    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
+    const chunk = await listReactionEvents(client, resolvedRoom, messageId, 200);
+    const userId = await client.getUserId();
+    if (!userId) {
+      return { removed: 0 };
+    }
+    const targetEmoji = opts.emoji?.trim();
+    const toRemove = chunk
+      .filter((event) => event.sender === userId)
+      .filter((event) => {
+        if (!targetEmoji) {
+          return true;
+        }
+        const content = event.content as ReactionEventContent;
+        return content["m.relates_to"]?.key === targetEmoji;
+      })
+      .map((event) => event.event_id)
+      .filter((id): id is string => Boolean(id));
+    if (toRemove.length === 0) {
+      return { removed: 0 };
+    }
+    await Promise.all(toRemove.map((id) => client.redactEvent(resolvedRoom, id)));
+    return { removed: toRemove.length };
+  } finally {
+    if (stopOnDone) {
+      client.stop();
+    }
+  }
+}

package/src/matrix/actions/room.ts

@@ -0,0 +1,85 @@
+import { resolveMatrixRoomId } from "../send.js";
+import { resolveActionClient } from "./client.js";
+import { EventType, type MatrixActionClientOpts } from "./types.js";
+
+export async function getMatrixMemberInfo(
+  userId: string,
+  opts: MatrixActionClientOpts & { roomId?: string } = {},
+) {
+  const { client, stopOnDone } = await resolveActionClient(opts);
+  try {
+    const roomId = opts.roomId ? await resolveMatrixRoomId(client, opts.roomId) : undefined;
+    // @vector-im/matrix-bot-sdk uses getUserProfile
+    const profile = await client.getUserProfile(userId);
+    // Note: @vector-im/matrix-bot-sdk doesn't have getRoom().getMember() like matrix-js-sdk
+    // We'd need to fetch room state separately if needed
+    return {
+      userId,
+      profile: {
+        displayName: profile?.displayname ?? null,
+        avatarUrl: profile?.avatar_url ?? null,
+      },
+      membership: null, // Would need separate room state query
+      powerLevel: null, // Would need separate power levels state query
+      displayName: profile?.displayname ?? null,
+      roomId: roomId ?? null,
+    };
+  } finally {
+    if (stopOnDone) {
+      client.stop();
+    }
+  }
+}
+
+export async function getMatrixRoomInfo(roomId: string, opts: MatrixActionClientOpts = {}) {
+  const { client, stopOnDone } = await resolveActionClient(opts);
+  try {
+    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
+    // @vector-im/matrix-bot-sdk uses getRoomState for state events
+    let name: string | null = null;
+    let topic: string | null = null;
+    let canonicalAlias: string | null = null;
+    let memberCount: number | null = null;
+
+    try {
+      const nameState = await client.getRoomStateEvent(resolvedRoom, "m.room.name", "");
+      name = nameState?.name ?? null;
+    } catch {
+      // ignore
+    }
+
+    try {
+      const topicState = await client.getRoomStateEvent(resolvedRoom, EventType.RoomTopic, "");
+      topic = topicState?.topic ?? null;
+    } catch {
+      // ignore
+    }
+
+    try {
+      const aliasState = await client.getRoomStateEvent(resolvedRoom, "m.room.canonical_alias", "");
+      canonicalAlias = aliasState?.alias ?? null;
+    } catch {
+      // ignore
+    }
+
+    try {
+      const members = await client.getJoinedRoomMembers(resolvedRoom);
+      memberCount = members.length;
+    } catch {
+      // ignore
+    }
+
+    return {
+      roomId: resolvedRoom,
+      name,
+      topic,
+      canonicalAlias,
+      altAliases: [], // Would need separate query
+      memberCount,
+    };
+  } finally {
+    if (stopOnDone) {
+      client.stop();
+    }
+  }
+}

package/src/matrix/actions/summary.ts

@@ -0,0 +1,75 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+import {
+  EventType,
+  type MatrixMessageSummary,
+  type MatrixRawEvent,
+  type RoomMessageEventContent,
+  type RoomPinnedEventsEventContent,
+} from "./types.js";
+
+export function summarizeMatrixRawEvent(event: MatrixRawEvent): MatrixMessageSummary {
+  const content = event.content as RoomMessageEventContent;
+  const relates = content["m.relates_to"];
+  let relType: string | undefined;
+  let eventId: string | undefined;
+  if (relates) {
+    if ("rel_type" in relates) {
+      relType = relates.rel_type;
+      eventId = relates.event_id;
+    } else if ("m.in_reply_to" in relates) {
+      eventId = relates["m.in_reply_to"]?.event_id;
+    }
+  }
+  const relatesTo =
+    relType || eventId
+      ? {
+          relType,
+          eventId,
+        }
+      : undefined;
+  return {
+    eventId: event.event_id,
+    sender: event.sender,
+    body: content.body,
+    msgtype: content.msgtype,
+    timestamp: event.origin_server_ts,
+    relatesTo,
+  };
+}
+
+export async function readPinnedEvents(client: MatrixClient, roomId: string): Promise<string[]> {
+  try {
+    const content = (await client.getRoomStateEvent(
+      roomId,
+      EventType.RoomPinnedEvents,
+      "",
+    )) as RoomPinnedEventsEventContent;
+    const pinned = content.pinned;
+    return pinned.filter((id) => id.trim().length > 0);
+  } catch (err: unknown) {
+    const errObj = err as { statusCode?: number; body?: { errcode?: string } };
+    const httpStatus = errObj.statusCode;
+    const errcode = errObj.body?.errcode;
+    if (httpStatus === 404 || errcode === "M_NOT_FOUND") {
+      return [];
+    }
+    throw err;
+  }
+}
+
+export async function fetchEventSummary(
+  client: MatrixClient,
+  roomId: string,
+  eventId: string,
+): Promise<MatrixMessageSummary | null> {
+  try {
+    const raw = (await client.getEvent(roomId, eventId)) as unknown as MatrixRawEvent;
+    if (raw.unsigned?.redacted_because) {
+      return null;
+    }
+    return summarizeMatrixRawEvent(raw);
+  } catch {
+    // Event not found, redacted, or inaccessible - return null
+    return null;
+  }
+}

package/src/matrix/actions/types.ts

@@ -0,0 +1,85 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+
+export const MsgType = {
+  Text: "m.text",
+} as const;
+
+export const RelationType = {
+  Replace: "m.replace",
+  Annotation: "m.annotation",
+} as const;
+
+export const EventType = {
+  RoomMessage: "m.room.message",
+  RoomPinnedEvents: "m.room.pinned_events",
+  RoomTopic: "m.room.topic",
+  Reaction: "m.reaction",
+} as const;
+
+export type RoomMessageEventContent = {
+  msgtype: string;
+  body: string;
+  "m.new_content"?: RoomMessageEventContent;
+  "m.relates_to"?: {
+    rel_type?: string;
+    event_id?: string;
+    "m.in_reply_to"?: { event_id?: string };
+  };
+};
+
+export type ReactionEventContent = {
+  "m.relates_to": {
+    rel_type: string;
+    event_id: string;
+    key: string;
+  };
+};
+
+export type RoomPinnedEventsEventContent = {
+  pinned: string[];
+};
+
+export type RoomTopicEventContent = {
+  topic?: string;
+};
+
+export type MatrixRawEvent = {
+  event_id: string;
+  sender: string;
+  type: string;
+  origin_server_ts: number;
+  content: Record<string, unknown>;
+  unsigned?: {
+    redacted_because?: unknown;
+  };
+};
+
+export type MatrixActionClientOpts = {
+  client?: MatrixClient;
+  timeoutMs?: number;
+  accountId?: string | null;
+};
+
+export type MatrixMessageSummary = {
+  eventId?: string;
+  sender?: string;
+  body?: string;
+  msgtype?: string;
+  timestamp?: number;
+  relatesTo?: {
+    relType?: string;
+    eventId?: string;
+    key?: string;
+  };
+};
+
+export type MatrixReactionSummary = {
+  key: string;
+  count: number;
+  users: string[];
+};
+
+export type MatrixActionClient = {
+  client: MatrixClient;
+  stopOnDone: boolean;
+};

package/src/matrix/actions.ts

@@ -0,0 +1,15 @@
+export type {
+  MatrixActionClientOpts,
+  MatrixMessageSummary,
+  MatrixReactionSummary,
+} from "./actions/types.js";
+export {
+  sendMatrixMessage,
+  editMatrixMessage,
+  deleteMatrixMessage,
+  readMatrixMessages,
+} from "./actions/messages.js";
+export { listMatrixReactions, removeMatrixReactions } from "./actions/reactions.js";
+export { pinMatrixMessage, unpinMatrixMessage, listMatrixPins } from "./actions/pins.js";
+export { getMatrixMemberInfo, getMatrixRoomInfo } from "./actions/room.js";
+export { reactMatrixMessage } from "./send.js";

package/src/matrix/active-client.ts

@@ -0,0 +1,32 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+
+// Support multiple active clients for multi-account
+const activeClients = new Map<string, MatrixClient>();
+
+export function setActiveMatrixClient(
+  client: MatrixClient | null,
+  accountId?: string | null,
+): void {
+  const key = normalizeAccountId(accountId);
+  if (client) {
+    activeClients.set(key, client);
+  } else {
+    activeClients.delete(key);
+  }
+}
+
+export function getActiveMatrixClient(accountId?: string | null): MatrixClient | null {
+  const key = normalizeAccountId(accountId);
+  return activeClients.get(key) ?? null;
+}
+
+export function getAnyActiveMatrixClient(): MatrixClient | null {
+  // Return any available client (for backward compatibility)
+  const first = activeClients.values().next();
+  return first.done ? null : first.value;
+}
+
+export function clearAllActiveMatrixClients(): void {
+  activeClients.clear();
+}

package/src/matrix/client/config.ts

@@ -0,0 +1,245 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import { fetchWithSsrFGuard } from "openclaw/plugin-sdk/matrix";
+import { getMatrixRuntime } from "../../runtime.js";
+import {
+  normalizeResolvedSecretInputString,
+  normalizeSecretInputString,
+} from "../../secret-input.js";
+import type { CoreConfig } from "../../types.js";
+import { loadMatrixSdk } from "../sdk-runtime.js";
+import { ensureMatrixSdkLoggingConfigured } from "./logging.js";
+import type { MatrixAuth, MatrixResolvedConfig } from "./types.js";
+
+function clean(value: unknown, path: string): string {
+  return normalizeResolvedSecretInputString({ value, path }) ?? "";
+}
+
+/** Shallow-merge known nested config sub-objects so partial overrides inherit base values. */
+function deepMergeConfig<T extends Record<string, unknown>>(base: T, override: Partial<T>): T {
+  const merged = { ...base, ...override } as Record<string, unknown>;
+  // Merge known nested objects (dm, actions) so partial overrides keep base fields
+  for (const key of ["dm", "actions"] as const) {
+    const b = base[key];
+    const o = override[key];
+    if (typeof b === "object" && b !== null && typeof o === "object" && o !== null) {
+      merged[key] = { ...(b as Record<string, unknown>), ...(o as Record<string, unknown>) };
+    }
+  }
+  return merged as T;
+}
+
+/**
+ * Resolve Matrix config for a specific account, with fallback to top-level config.
+ * This supports both multi-account (channels.badgerclaw.accounts.*) and
+ * single-account (channels.badgerclaw.*) configurations.
+ */
+export function resolveMatrixConfigForAccount(
+  cfg: CoreConfig = getMatrixRuntime().config.loadConfig() as CoreConfig,
+  accountId?: string | null,
+  env: NodeJS.ProcessEnv = process.env,
+): MatrixResolvedConfig {
+  const normalizedAccountId = normalizeAccountId(accountId);
+  const matrixBase = cfg.channels?.badgerclaw ?? {};
+  const accounts = cfg.channels?.badgerclaw?.accounts;
+
+  // Try to get account-specific config first (direct lookup, then case-insensitive fallback)
+  let accountConfig = accounts?.[normalizedAccountId];
+  if (!accountConfig && accounts) {
+    for (const key of Object.keys(accounts)) {
+      if (normalizeAccountId(key) === normalizedAccountId) {
+        accountConfig = accounts[key];
+        break;
+      }
+    }
+  }
+
+  // Deep merge: account-specific values override top-level values, preserving
+  // nested object inheritance (dm, actions, groups) so partial overrides work.
+  const matrix = accountConfig ? deepMergeConfig(matrixBase, accountConfig) : matrixBase;
+
+  const homeserver =
+    clean(matrix.homeserver, "channels.badgerclaw.homeserver") ||
+    clean(env.MATRIX_HOMESERVER, "MATRIX_HOMESERVER");
+  const userId =
+    clean(matrix.userId, "channels.badgerclaw.userId") || clean(env.MATRIX_USER_ID, "MATRIX_USER_ID");
+  const accessToken =
+    clean(matrix.accessToken, "channels.badgerclaw.accessToken") ||
+    clean(env.MATRIX_ACCESS_TOKEN, "MATRIX_ACCESS_TOKEN") ||
+    undefined;
+  const password =
+    clean(matrix.password, "channels.badgerclaw.password") ||
+    clean(env.MATRIX_PASSWORD, "MATRIX_PASSWORD") ||
+    undefined;
+  const deviceName =
+    clean(matrix.deviceName, "channels.badgerclaw.deviceName") ||
+    clean(env.MATRIX_DEVICE_NAME, "MATRIX_DEVICE_NAME") ||
+    undefined;
+  const initialSyncLimit =
+    typeof matrix.initialSyncLimit === "number"
+      ? Math.max(0, Math.floor(matrix.initialSyncLimit))
+      : undefined;
+  const encryption = matrix.encryption ?? false;
+  return {
+    homeserver,
+    userId,
+    accessToken,
+    password,
+    deviceName,
+    initialSyncLimit,
+    encryption,
+  };
+}
+
+/**
+ * Single-account function for backward compatibility - resolves default account config.
+ */
+export function resolveMatrixConfig(
+  cfg: CoreConfig = getMatrixRuntime().config.loadConfig() as CoreConfig,
+  env: NodeJS.ProcessEnv = process.env,
+): MatrixResolvedConfig {
+  return resolveMatrixConfigForAccount(cfg, DEFAULT_ACCOUNT_ID, env);
+}
+
+export async function resolveMatrixAuth(params?: {
+  cfg?: CoreConfig;
+  env?: NodeJS.ProcessEnv;
+  accountId?: string | null;
+}): Promise<MatrixAuth> {
+  const cfg = params?.cfg ?? (getMatrixRuntime().config.loadConfig() as CoreConfig);
+  const env = params?.env ?? process.env;
+  const resolved = resolveMatrixConfigForAccount(cfg, params?.accountId, env);
+  if (!resolved.homeserver) {
+    throw new Error("BadgerClaw homeserver is required (matrix.homeserver)");
+  }
+
+  const {
+    loadMatrixCredentials,
+    saveMatrixCredentials,
+    credentialsMatchConfig,
+    touchMatrixCredentials,
+  } = await import("../credentials.js");
+
+  const accountId = params?.accountId;
+  const cached = loadMatrixCredentials(env, accountId);
+  const cachedCredentials =
+    cached &&
+    credentialsMatchConfig(cached, {
+      homeserver: resolved.homeserver,
+      userId: resolved.userId || "",
+    })
+      ? cached
+      : null;
+
+  // If we have an access token, we can fetch userId via whoami if not provided
+  if (resolved.accessToken) {
+    let userId = resolved.userId;
+    if (!userId) {
+      // Fetch userId from access token via whoami
+      ensureMatrixSdkLoggingConfigured();
+      const { MatrixClient } = loadMatrixSdk();
+      const tempClient = new MatrixClient(resolved.homeserver, resolved.accessToken);
+      const whoami = await tempClient.getUserId();
+      userId = whoami;
+      // Save the credentials with the fetched userId
+      saveMatrixCredentials(
+        {
+          homeserver: resolved.homeserver,
+          userId,
+          accessToken: resolved.accessToken,
+        },
+        env,
+        accountId,
+      );
+    } else if (cachedCredentials && cachedCredentials.accessToken === resolved.accessToken) {
+      touchMatrixCredentials(env, accountId);
+    }
+    return {
+      homeserver: resolved.homeserver,
+      userId,
+      accessToken: resolved.accessToken,
+      deviceName: resolved.deviceName,
+      initialSyncLimit: resolved.initialSyncLimit,
+      encryption: resolved.encryption,
+    };
+  }
+
+  if (cachedCredentials) {
+    touchMatrixCredentials(env, accountId);
+    return {
+      homeserver: cachedCredentials.homeserver,
+      userId: cachedCredentials.userId,
+      accessToken: cachedCredentials.accessToken,
+      deviceName: resolved.deviceName,
+      initialSyncLimit: resolved.initialSyncLimit,
+      encryption: resolved.encryption,
+    };
+  }
+
+  if (!resolved.userId) {
+    throw new Error("BadgerClaw userId is required when no access token is configured (matrix.userId)");
+  }
+
+  if (!resolved.password) {
+    throw new Error(
+      "BadgerClaw password is required when no access token is configured (matrix.password)",
+    );
+  }
+
+  // Login with password using HTTP API.
+  const { response: loginResponse, release: releaseLoginResponse } = await fetchWithSsrFGuard({
+    url: `${resolved.homeserver}/_matrix/client/v3/login`,
+    init: {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        type: "m.login.password",
+        identifier: { type: "m.id.user", user: resolved.userId },
+        password: resolved.password,
+        initial_device_display_name: resolved.deviceName ?? "OpenClaw Gateway",
+      }),
+    },
+    auditContext: "matrix.login",
+  });
+  const login = await (async () => {
+    try {
+      if (!loginResponse.ok) {
+        const errorText = await loginResponse.text();
+        throw new Error(`BadgerClaw login failed: ${errorText}`);
+      }
+      return (await loginResponse.json()) as {
+        access_token?: string;
+        user_id?: string;
+        device_id?: string;
+      };
+    } finally {
+      await releaseLoginResponse();
+    }
+  })();
+
+  const accessToken = login.access_token?.trim();
+  if (!accessToken) {
+    throw new Error("BadgerClaw login did not return an access token");
+  }
+
+  const auth: MatrixAuth = {
+    homeserver: resolved.homeserver,
+    userId: login.user_id ?? resolved.userId,
+    accessToken,
+    deviceName: resolved.deviceName,
+    initialSyncLimit: resolved.initialSyncLimit,
+    encryption: resolved.encryption,
+  };
+
+  saveMatrixCredentials(
+    {
+      homeserver: auth.homeserver,
+      userId: auth.userId,
+      accessToken: auth.accessToken,
+      deviceId: login.device_id,
+    },
+    env,
+    accountId,
+  );
+
+  return auth;
+}