@badgerclaw/connect 1.0.0

package/src/matrix/send.ts

@@ -0,0 +1,267 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+import type { PollInput } from "openclaw/plugin-sdk/matrix";
+import { getMatrixRuntime } from "../runtime.js";
+import { buildPollStartContent, M_POLL_START } from "./poll-types.js";
+import { enqueueSend } from "./send-queue.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("BadgerClaw send requires text or media");
+  }
+  const { client, stopOnDone } = await resolveMatrixClient({
+    client: opts.client,
+    timeoutMs: opts.timeoutMs,
+    accountId: opts.accountId,
+    cfg: opts.cfg,
+  });
+  const cfg = opts.cfg ?? getCore().config.loadConfig();
+  try {
+    const roomId = await resolveMatrixRoomId(client, to);
+    return await enqueueSend(roomId, async () => {
+      const tableMode = getCore().channel.text.resolveMarkdownTableMode({
+        cfg,
+        channel: "badgerclaw",
+        accountId: opts.accountId,
+      });
+      const convertedMessage = getCore().channel.text.convertMarkdownTables(
+        trimmedMessage,
+        tableMode,
+      );
+      const textLimit = getCore().channel.text.resolveTextChunkLimit(cfg, "badgerclaw");
+      const chunkLimit = Math.min(textLimit, MATRIX_TEXT_LIMIT);
+      const chunkMode = getCore().channel.text.resolveChunkMode(cfg, "badgerclaw", 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(opts.accountId, cfg);
+        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 ?? "unknown",
+        });
+        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("BadgerClaw poll requires a question");
+  }
+  if (!poll.options?.length) {
+    throw new Error("BadgerClaw poll requires options");
+  }
+  const { client, stopOnDone } = await resolveMatrixClient({
+    client: opts.client,
+    timeoutMs: opts.timeoutMs,
+    accountId: opts.accountId,
+    cfg: opts.cfg,
+  });
+
+  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("BadgerClaw 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();
+    }
+  }
+}

package/src/onboarding.ts

@@ -0,0 +1,331 @@
+import type { DmPolicy } from "openclaw/plugin-sdk/matrix";
+import {
+  addWildcardAllowFrom,
+  formatResolvedUnresolvedNote,
+  mergeAllowFromEntries,
+  promptChannelAccessConfig,
+  setTopLevelChannelGroupPolicy,
+  type ChannelOnboardingAdapter,
+  type ChannelOnboardingDmPolicy,
+  type WizardPrompter,
+} from "openclaw/plugin-sdk/matrix";
+import { redeemPairingCode } from "./connect.js";
+import { listMatrixDirectoryGroupsLive } from "./directory-live.js";
+import { resolveMatrixAccount } from "./matrix/accounts.js";
+import { ensureMatrixSdkInstalled, isMatrixSdkAvailable } from "./matrix/deps.js";
+import { resolveMatrixTargets } from "./resolve-targets.js";
+import type { CoreConfig } from "./types.js";
+
+const channel = "badgerclaw" as const;
+
+function setMatrixDmPolicy(cfg: CoreConfig, policy: DmPolicy) {
+  const allowFrom =
+    policy === "open" ? addWildcardAllowFrom(cfg.channels?.badgerclaw?.dm?.allowFrom) : undefined;
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      badgerclaw: {
+        ...cfg.channels?.badgerclaw,
+        dm: {
+          ...cfg.channels?.badgerclaw?.dm,
+          policy,
+          ...(allowFrom ? { allowFrom } : {}),
+        },
+      },
+    },
+  };
+}
+
+async function promptPairingCode(prompter: WizardPrompter): Promise<{
+  homeserver: string;
+  accessToken: string;
+  userId: string;
+  botName: string;
+} | null> {
+  await prompter.note(
+    "BadgerClaw connects your OpenClaw agent to encrypted chat rooms.\n\nTo get started:\n1. Create a bot in the BadgerClaw app (/bot create <name>)\n2. You will receive a pairing code (BCK-XXXX-XXXX)\n3. Enter it below",
+    "BadgerClaw setup",
+  );
+
+  while (true) {
+    const code = String(
+      await prompter.text({
+        message: "Pairing code",
+        validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+      }),
+    ).trim();
+
+    try {
+      const result = await redeemPairingCode(code);
+      return {
+        homeserver: result.homeserver,
+        accessToken: result.access_token,
+        userId: result.user_id,
+        botName: result.bot_name,
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      await prompter.note(`Pairing failed: ${message}\n\nPlease try again.`, "BadgerClaw setup");
+    }
+  }
+}
+
+async function promptMatrixAllowFrom(params: {
+  cfg: CoreConfig;
+  prompter: WizardPrompter;
+}): Promise<CoreConfig> {
+  const { cfg, prompter } = params;
+  const existingAllowFrom = cfg.channels?.badgerclaw?.dm?.allowFrom ?? [];
+  const account = resolveMatrixAccount({ cfg });
+  const canResolve = Boolean(account.configured);
+
+  const parseInput = (raw: string) =>
+    raw
+      .split(/[\n,;]+/g)
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+
+  const isFullUserId = (value: string) => value.startsWith("@") && value.includes(":");
+
+  while (true) {
+    const entry = await prompter.text({
+      message: "BadgerClaw allowFrom (full @user:server; display name only if unique)",
+      placeholder: "@user:server",
+      initialValue: existingAllowFrom[0] ? String(existingAllowFrom[0]) : undefined,
+      validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+    });
+    const parts = parseInput(String(entry));
+    const resolvedIds: string[] = [];
+    const pending: string[] = [];
+    const unresolved: string[] = [];
+    const unresolvedNotes: string[] = [];
+
+    for (const part of parts) {
+      if (isFullUserId(part)) {
+        resolvedIds.push(part);
+        continue;
+      }
+      if (!canResolve) {
+        unresolved.push(part);
+        continue;
+      }
+      pending.push(part);
+    }
+
+    if (pending.length > 0) {
+      const results = await resolveMatrixTargets({
+        cfg,
+        inputs: pending,
+        kind: "user",
+      }).catch(() => []);
+      for (const result of results) {
+        if (result?.resolved && result.id) {
+          resolvedIds.push(result.id);
+          continue;
+        }
+        if (result?.input) {
+          unresolved.push(result.input);
+          if (result.note) {
+            unresolvedNotes.push(`${result.input}: ${result.note}`);
+          }
+        }
+      }
+    }
+
+    if (unresolved.length > 0) {
+      const details = unresolvedNotes.length > 0 ? unresolvedNotes : unresolved;
+      await prompter.note(
+        `Could not resolve:\n${details.join("\n")}\nUse full @user:server IDs.`,
+        "BadgerClaw allowlist",
+      );
+      continue;
+    }
+
+    const unique = mergeAllowFromEntries(existingAllowFrom, resolvedIds);
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        badgerclaw: {
+          ...cfg.channels?.badgerclaw,
+          enabled: true,
+          dm: {
+            ...cfg.channels?.badgerclaw?.dm,
+            policy: "allowlist",
+            allowFrom: unique,
+          },
+        },
+      },
+    };
+  }
+}
+
+function setMatrixGroupPolicy(cfg: CoreConfig, groupPolicy: "open" | "allowlist" | "disabled") {
+  return setTopLevelChannelGroupPolicy({
+    cfg,
+    channel: "badgerclaw",
+    groupPolicy,
+    enabled: true,
+  }) as CoreConfig;
+}
+
+function setMatrixGroupRooms(cfg: CoreConfig, roomKeys: string[]) {
+  const groups = Object.fromEntries(roomKeys.map((key) => [key, { allow: true }]));
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      badgerclaw: {
+        ...cfg.channels?.badgerclaw,
+        enabled: true,
+        groups,
+      },
+    },
+  };
+}
+
+const dmPolicy: ChannelOnboardingDmPolicy = {
+  label: "BadgerClaw",
+  channel,
+  policyKey: "channels.badgerclaw.dm.policy",
+  allowFromKey: "channels.badgerclaw.dm.allowFrom",
+  getCurrent: (cfg) => (cfg as CoreConfig).channels?.badgerclaw?.dm?.policy ?? "pairing",
+  setPolicy: (cfg, policy) => setMatrixDmPolicy(cfg as CoreConfig, policy),
+  promptAllowFrom: promptMatrixAllowFrom,
+};
+
+export const badgerclawOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel,
+  getStatus: async ({ cfg }) => {
+    const account = resolveMatrixAccount({ cfg: cfg as CoreConfig });
+    const configured = account.configured;
+    const sdkReady = isMatrixSdkAvailable();
+    return {
+      channel,
+      configured,
+      statusLines: [
+        `BadgerClaw: ${configured ? "configured" : "needs homeserver + access token or password"}`,
+      ],
+      selectionHint: !sdkReady
+        ? "install @vector-im/matrix-bot-sdk"
+        : configured
+          ? "configured"
+          : "needs auth",
+    };
+  },
+  configure: async ({ cfg, runtime, prompter, forceAllowFrom }) => {
+    let next = cfg as CoreConfig;
+    await ensureMatrixSdkInstalled({
+      runtime,
+      confirm: async (message) =>
+        await prompter.confirm({
+          message,
+          initialValue: true,
+        }),
+    });
+
+    // Pairing code flow — the primary onboarding path
+    const pairing = await promptPairingCode(prompter);
+    if (pairing) {
+      next = {
+        ...next,
+        channels: {
+          ...next.channels,
+          badgerclaw: {
+            ...next.channels?.badgerclaw,
+            enabled: true,
+            homeserver: pairing.homeserver,
+            accessToken: pairing.accessToken,
+            userId: pairing.userId,
+            deviceName: pairing.botName || "OpenClaw Gateway",
+            encryption: true,
+            autoJoin: "always",
+            dm: {
+              ...next.channels?.badgerclaw?.dm,
+              policy: "open",
+              allowFrom: addWildcardAllowFrom(next.channels?.badgerclaw?.dm?.allowFrom),
+            },
+          },
+        },
+      };
+    }
+
+    if (forceAllowFrom) {
+      next = await promptMatrixAllowFrom({ cfg: next, prompter });
+    }
+
+    const existingGroups = next.channels?.badgerclaw?.groups ?? next.channels?.badgerclaw?.rooms;
+    const accessConfig = await promptChannelAccessConfig({
+      prompter,
+      label: "BadgerClaw rooms",
+      currentPolicy: next.channels?.badgerclaw?.groupPolicy ?? "allowlist",
+      currentEntries: Object.keys(existingGroups ?? {}),
+      placeholder: "!roomId:server, #alias:server, Project Room",
+      updatePrompt: Boolean(existingGroups),
+    });
+    if (accessConfig) {
+      if (accessConfig.policy !== "allowlist") {
+        next = setMatrixGroupPolicy(next, accessConfig.policy);
+      } else {
+        let roomKeys = accessConfig.entries;
+        if (accessConfig.entries.length > 0) {
+          try {
+            const resolvedIds: string[] = [];
+            const unresolved: string[] = [];
+            for (const entry of accessConfig.entries) {
+              const trimmed = entry.trim();
+              if (!trimmed) {
+                continue;
+              }
+              const cleaned = trimmed.replace(/^(room|channel):/i, "").trim();
+              if (cleaned.startsWith("!") && cleaned.includes(":")) {
+                resolvedIds.push(cleaned);
+                continue;
+              }
+              const matches = await listMatrixDirectoryGroupsLive({
+                cfg: next,
+                query: trimmed,
+                limit: 10,
+              });
+              const exact = matches.find(
+                (match) => (match.name ?? "").toLowerCase() === trimmed.toLowerCase(),
+              );
+              const best = exact ?? matches[0];
+              if (best?.id) {
+                resolvedIds.push(best.id);
+              } else {
+                unresolved.push(entry);
+              }
+            }
+            roomKeys = [...resolvedIds, ...unresolved.map((entry) => entry.trim()).filter(Boolean)];
+            const resolution = formatResolvedUnresolvedNote({
+              resolved: resolvedIds,
+              unresolved,
+            });
+            if (resolution) {
+              await prompter.note(resolution, "BadgerClaw rooms");
+            }
+          } catch (err) {
+            await prompter.note(
+              `Room lookup failed; keeping entries as typed. ${String(err)}`,
+              "BadgerClaw rooms",
+            );
+          }
+        }
+        next = setMatrixGroupPolicy(next, "allowlist");
+        next = setMatrixGroupRooms(next, roomKeys);
+      }
+    }
+
+    return { cfg: next };
+  },
+  dmPolicy,
+  disable: (cfg) => ({
+    ...(cfg as CoreConfig),
+    channels: {
+      ...(cfg as CoreConfig).channels,
+      badgerclaw: { ...(cfg as CoreConfig).channels?.badgerclaw, enabled: false },
+    },
+  }),
+};

package/src/outbound.ts

@@ -0,0 +1,58 @@
+import type { ChannelOutboundAdapter } from "openclaw/plugin-sdk/matrix";
+import { sendMessageMatrix, sendPollMatrix } from "./matrix/send.js";
+import { getMatrixRuntime } from "./runtime.js";
+
+export const matrixOutbound: ChannelOutboundAdapter = {
+  deliveryMode: "direct",
+  chunker: (text, limit) => getMatrixRuntime().channel.text.chunkMarkdownText(text, limit),
+  chunkerMode: "markdown",
+  textChunkLimit: 4000,
+  sendText: async ({ cfg, to, text, deps, replyToId, threadId, accountId }) => {
+    const send = deps?.sendMatrix ?? sendMessageMatrix;
+    const resolvedThreadId =
+      threadId !== undefined && threadId !== null ? String(threadId) : undefined;
+    const result = await send(to, text, {
+      cfg,
+      replyToId: replyToId ?? undefined,
+      threadId: resolvedThreadId,
+      accountId: accountId ?? undefined,
+    });
+    return {
+      channel: "badgerclaw",
+      messageId: result.messageId,
+      roomId: result.roomId,
+    };
+  },
+  sendMedia: async ({ cfg, to, text, mediaUrl, deps, replyToId, threadId, accountId }) => {
+    const send = deps?.sendMatrix ?? sendMessageMatrix;
+    const resolvedThreadId =
+      threadId !== undefined && threadId !== null ? String(threadId) : undefined;
+    const result = await send(to, text, {
+      cfg,
+      mediaUrl,
+      replyToId: replyToId ?? undefined,
+      threadId: resolvedThreadId,
+      accountId: accountId ?? undefined,
+    });
+    return {
+      channel: "badgerclaw",
+      messageId: result.messageId,
+      roomId: result.roomId,
+    };
+  },
+  sendPoll: async ({ cfg, to, poll, threadId, accountId }) => {
+    const resolvedThreadId =
+      threadId !== undefined && threadId !== null ? String(threadId) : undefined;
+    const result = await sendPollMatrix(to, poll, {
+      cfg,
+      threadId: resolvedThreadId,
+      accountId: accountId ?? undefined,
+    });
+    return {
+      channel: "badgerclaw",
+      messageId: result.eventId,
+      roomId: result.roomId,
+      pollId: result.eventId,
+    };
+  },
+};